diff options
Diffstat (limited to 'gawk-info-4')
| -rw-r--r-- | gawk-info-4 | 1400 |
1 files changed, 1400 insertions, 0 deletions
diff --git a/gawk-info-4 b/gawk-info-4 new file mode 100644 index 00000000..c8e9b7ee --- /dev/null +++ b/gawk-info-4 @@ -0,0 +1,1400 @@ +Info file gawk-info, produced by Makeinfo, -*- Text -*- from input +file gawk.texinfo. + +This file documents `awk', a program that you can use to select +particular records in a file and perform operations upon them. + +Copyright (C) 1989 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + + +File: gawk-info, Node: For, Next: Break, Prev: Do, Up: Statements + +The `for' Statement +=================== + +The `for' statement makes it more convenient to count iterations of a +loop. The general form of the `for' statement looks like this: + + for (INITIALIZATION; CONDITION; INCREMENT) + BODY + +This statement starts by executing INITIALIZATION. Then, as long as +CONDITION is true, it repeatedly executes BODY and then INCREMENT. +Typically INITIALIZATION sets a variable to either zero or one, +INCREMENT adds 1 to it, and CONDITION compares it against the desired +number of iterations. + +Here is an example of a `for' statement: + + awk '{ for (i = 1; i <= 3; i++) + print $i + }' + +This prints the first three fields of each input record, one field +per line. + +In the `for' statement, BODY stands for any statement, but +INITIALIZATION, CONDITION and INCREMENT are just expressions. You +cannot set more than one variable in the INITIALIZATION part unless +you use a multiple assignment statement such as `x = y = 0', which is +possible only if all the initial values are equal. (But you can +initialize additional variables by writing their assignments as +separate statements preceding the `for' loop.) + +The same is true of the INCREMENT part; to increment additional +variables, you must write separate statements at the end of the loop. +The C compound expression, using C's comma operator, would be useful +in this context, but it is not supported in `awk'. + +Most often, INCREMENT is an increment expression, as in the example +above. But this is not required; it can be any expression whatever. +For example, this statement prints odd numbers from 1 to 100: + + # print odd numbers from 1 to 100 + for (i = 1; i <= 100; i += 2) + print i + +Any of the three expressions following `for' may be omitted if you +don't want it to do anything. Thus, `for (;x > 0;)' is equivalent to +`while (x > 0)'. If the CONDITION part is empty, it is treated as +TRUE, effectively yielding an infinite loop. + +In most cases, a `for' loop is an abbreviation for a `while' loop, as +shown here: + + INITIALIZATION + while (CONDITION) { + BODY + INCREMENT + } + +(The only exception is when the `continue' statement (*note +Continue::.) is used inside the loop; changing a `for' statement to a +`while' statement in this way can change the effect of the `continue' +statement inside the loop.) + +The `awk' language has a `for' statement in addition to a `while' +statement because often a `for' loop is both less work to type and +more natural to think of. Counting the number of iterations is very +common in loops. It can be easier to think of this counting as part +of looping rather than as something to do inside the loop. + +The next section has more complicated examples of `for' loops. + +There is an alternate version of the `for' loop, for iterating over +all the indices of an array: + + for (i in array) + PROCESS array[i] + +*Note Arrays::, for more information on this version of the `for' loop. + + + +File: gawk-info, Node: Break, Next: Continue, Prev: For, Up: Statements + +The `break' Statement +===================== + +The `break' statement jumps out of the innermost `for', `while', or +`do'--`while' loop that encloses it. The following example finds the +smallest divisor of any number, and also identifies prime numbers: + + awk '# find smallest divisor of num + { num = $1 + for (div = 2; div*div <= num; div++) + if (num % div == 0) + break + if (num % div == 0) + printf "Smallest divisor of %d is %d\n", num, div + else + printf "%d is prime\n", num }' + +When the remainder is zero in the first `if' statement, `awk' +immediately "breaks" out of the containing `for' loop. This means +that `awk' proceeds immediately to the statement following the loop +and continues processing. (This is very different from the `exit' +statement (*note Exit::.) which stops the entire `awk' program.) + +Here is another program equivalent to the previous one. It +illustrates how the CONDITION of a `for' or `while' could just as +well be replaced with a `break' inside an `if': + + awk '# find smallest divisor of num + { num = $1 + for (div = 2; ; div++) { + if (num % div == 0) { + printf "Smallest divisor of %d is %d\n", num, div + break + } + if (div*div > num) { + printf "%d is prime\n", num + break + } + } + }' + + + +File: gawk-info, Node: Continue, Next: Next, Prev: Break, Up: Statements + +The `continue' Statement +======================== + +The `continue' statement, like `break', is used only inside `for', +`while', and `do'--`while' loops. It skips over the rest of the loop +body, causing the next cycle around the loop to begin immediately. +Contrast this with `break', which jumps out of the loop altogether. +Here is an example: + + # print names that don't contain the string "ignore" + + # first, save the text of each line + { names[NR] = $0 } + + # print what we're interested in + END { + for (x in names) { + if (names[x] ~ /ignore/) + continue + print names[x] + } + } + +If any of the input records contain the string `ignore', this example +skips the print statement and continues back to the first statement +in the loop. + +This isn't a practical example of `continue', since it would be just +as easy to write the loop like this: + + for (x in names) + if (x !~ /ignore/) + print x + +The `continue' statement causes `awk' to skip the rest of what is +inside a `for' loop, but it resumes execution with the increment part +of the `for' loop. The following program illustrates this fact: + + awk 'BEGIN { + for (x = 0; x <= 20; x++) { + if (x == 5) + continue + printf ("%d ", x) + } + print "" + }' + +This program prints all the numbers from 0 to 20, except for 5, for +which the `printf' is skipped. Since the increment `x++' is not +skipped, `x' does not remain stuck at 5. + + + +File: gawk-info, Node: Next, Next: Exit, Prev: Continue, Up: Statements + +The `next' Statement +==================== + +The `next' statement forces `awk' to immediately stop processing the +current record and go on to the next record. This means that no +further rules are executed for the current record. The rest of the +current rule's action is not executed either. + +Contrast this with the effect of the `getline' function (*note +Getline::.). That too causes `awk' to read the next record +immediately, but it does not alter the flow of control in any way. +So the rest of the current action executes with a new input record. + +At the grossest level, `awk' program execution is a loop that reads +an input record and then tests each rule pattern against it. If you +think of this loop as a `for' statement whose body contains the +rules, then the `next' statement is analogous to a `continue' +statement: it skips to the end of the body of the loop, and executes +the increment (which reads another record). + +For example, if your `awk' program works only on records with four +fields, and you don't want it to fail when given bad input, you might +use the following rule near the beginning of the program: + + NF != 4 { + printf ("line %d skipped: doesn't have 4 fields", FNR) > "/dev/tty" + next + } + +so that the following rules will not see the bad record. The error +message is redirected to `/dev/tty' (the terminal), so that it won't +get lost amid the rest of the program's regular output. + + + +File: gawk-info, Node: Exit, Prev: Next, Up: Statements + +The `exit' Statement +==================== + +The `exit' statement causes `awk' to immediately stop executing the +current rule and to stop processing input; any remaining input is +ignored. + +If an `exit' statement is executed from a `BEGIN' rule the program +stops processing everything immediately. No input records will be +read. However, if an `END' rule is present, it will be executed +(*note BEGIN/END::.). + +If `exit' is used as part of an `END' rule, it causes the program to +stop immediately. + +An `exit' statement that is part an ordinary rule (that is, not part +of a `BEGIN' or `END' rule) stops the execution of any further +automatic rules, but the `END' rule is executed if there is one. If +you don't want the `END' rule to do its job in this case, you can set +a variable to nonzero before the `exit' statement, and check that +variable in the `END' rule. + +If an argument is supplied to `exit', its value is used as the exit +status code for the `awk' process. If no argument is supplied, +`exit' returns status zero (success). + +For example, let's say you've discovered an error condition you +really don't know how to handle. Conventionally, programs report +this by exiting with a nonzero status. Your `awk' program can do +this using an `exit' statement with a nonzero argument. Here's an +example of this: + + BEGIN { + if (("date" | getline date_now) < 0) { + print "Can't get system date" + exit 4 + } + } + + + +File: gawk-info, Node: Arrays, Next: Built-in, Prev: Statements, Up: Top + +Actions: Using Arrays in `awk' +****************************** + +An "array" is a table of various values, called "elements". The +elements of an array are distinguished by their "indices". Names of +arrays in `awk' are strings of alphanumeric characters and +underscores, just like regular variables. + +You cannot use the same identifier as both a variable and as an array +name in one `awk' program. + +* Menu: + +* Intro: Array Intro. Basic facts abou arrays in `awk'. +* Reference to Elements:: How to examine one element of an array. +* Assigning Elements:: How to change an element of an array. +* Example: Array Example. Sample program explained. + +* Scanning an Array:: A variation of the `for' statement. It loops + through the indices of an array's existing elements. + +* Delete:: The `delete' statement removes an element from an array. + +* Multi-dimensional:: Emulating multi--dimensional arrays in `awk'. +* Multi-scanning:: Scanning multi--dimensional arrays. + + + +File: gawk-info, Node: Array Intro, Next: Reference to Elements, Up: Arrays + +Introduction to Arrays +====================== + +The `awk' language has one--dimensional "arrays" for storing groups +of related strings or numbers. Each array must have a name; valid +array names are the same as valid variable names, and they do +conflict with variable names: you can't have both an array and a +variable with the same name at any point in an `awk' program. + +Arrays in `awk' superficially resemble arrays in other programming +languages; but there are fundamental differences. In `awk', you +don't need to declare the size of an array before you start to use it. +What's more, in `awk' any number or even a string may be used as an +array index. + +In most other languages, you have to "declare" an array and specify +how many elements or components it has. In such languages, the +declaration causes a contiguous block of memory to be allocated for +that many elements. An index in the array must be a positive +integer; for example, the index 0 specifies the first element in the +array, which is actually stored at the beginning of the block of +memory. Index 1 specifies the second element, which is stored in +memory right after the first element, and so on. It is impossible to +add more elements to the array, because it has room for only as many +elements as you declared. (Some languages have arrays whose first +index is 1, others require that you specify both the first and last +index when you declare the array. In such a language, an array could +be indexed, for example, from -3 to 17.) A contiguous array of four +elements might look like this, conceptually, if the element values +are 8, `"foo"', `""' and 30: + + +--------+--------+-------+--------+ + | 8 | "foo" | "" | 30 | value + +--------+--------+-------+--------+ + 0 1 2 3 index + +Only the values are stored; the indices are implicit from the order +of the values. 8 is the value at index 0, because 8 appears in the +position with 0 elements before it. + +Arrays in `awk' are different: they are "associative". This means +that each array is a collection of pairs: an index, and its +corresponding array element value: + + Element 4 Value 30 + Element 2 Value "foo" + Element 1 Value 8 + Element 3 Value "" + +We have shown the pairs in jumbled order because their order doesn't +mean anything. + +One advantage of an associative array is that new pairs can be added +at any time. For example, suppose we add to that array a tenth +element whose value is `"number ten"'. The result is this: + + Element 10 Value "number ten" + Element 4 Value 30 + Element 2 Value "foo" + Element 1 Value 8 + Element 3 Value "" + +Now the array is "sparse" (i.e. some indices are missing): it has +elements number 4 and 10, but doesn't have an element 5, 6, 7, 8, or 9. + +Another consequence of associative arrays is that the indices don't +have to be positive integers. Any number, or even a string, can be +an index. For example, here is an array which translates words from +English into French: + + Element "dog" Value "chien" + Element "cat" Value "chat" + Element "one" Value "un" + Element 1 Value "un" + +Here we decided to translate the number 1 in both spelled--out and +numeral form--thus illustrating that a single array can have both +numbers and strings as indices. + +When `awk' creates an array for you, e.g. with the `split' built--in +function (*note String Functions::.), that array's indices start at +the number one. + + + +File: gawk-info, Node: Reference to Elements, Next: Assigning Elements, Prev: Array Intro, Up: Arrays + +Referring to an Array Element +============================= + +The principal way of using an array is to refer to one of its elements. +An array reference is an expression which looks like this: + + ARRAY[INDEX] + +Here ARRAY is the name of an array. The expression INDEX is the +index of the element of the array that you want. The value of the +array reference is the current value of that array element. + +For example, `foo[4.3]' is an expression for the element of array +`foo' at index 4.3. + +If you refer to an array element that has no recorded value, the +value of the reference is `""', the null string. This includes +elements to which you have not assigned any value, and elements that +have been deleted (*note Delete::.). Such a reference automatically +creates that array element, with the null string as its value. (In +some cases, this is unfortunate, because it might waste memory inside +`awk'). + +You can find out if an element exists in an array at a certain index +with the expression: + + INDEX in ARRAY + +This expression tests whether or not the particular index exists, +without the side effect of creating that element if it is not present. +The expression has the value 1 (true) if `ARRAY[SUBSCRIPT]' exists, +and 0 (false) if it does not exist. + +For example, to find out whether the array `frequencies' contains the +subscript `"2"', you would ask: + + if ("2" in frequencies) print "Subscript \"2\" is present." + +Note that this is *not* a test of whether or not the array +`frequencies' contains an element whose *value* is `"2"'. (There is +no way to that except to scan all the elements.) Also, this *does +not* create `frequencies["2"]', while the following (incorrect) +alternative would: + + if (frequencies["2"] != "") print "Subscript \"2\" is present." + + + +File: gawk-info, Node: Assigning Elements, Next: Array Example, Prev: Reference to Elements, Up: Arrays + +Assigning Array Elements +======================== + +Array elements are lvalues: they can be assigned values just like +`awk' variables: + + ARRAY[SUBSCRIPT] = VALUE + +Here ARRAY is the name of your array. The expression SUBSCRIPT is +the index of the element of the array that you want to assign a +value. The expression VALUE is the value you are assigning to that +element of the array. + + + +File: gawk-info, Node: Array Example, Next: Scanning an Array, Prev: Assigning Elements, Up: Arrays + +Basic Example of an Array +========================= + +The following program takes a list of lines, each beginning with a +line number, and prints them out in order of line number. The line +numbers are not in order, however, when they are first read: they +are scrambled. This program sorts the lines by making an array using +the line numbers as subscripts. It then prints out the lines in +sorted order of their numbers. It is a very simple program, and will +get confused if it encounters repeated numbers, gaps, or lines that +don't begin with a number. + + BEGIN { + max=0 + } + + { + if ($1 > max) + max = $1 + arr[$1] = $0 + } + + END { + for (x = 1; x <= max; x++) + print arr[x] + } + +The first rule just initializes the variable `max'. (This is not +strictly necessary, since an uninitialized variable has the null +string as its value, and the null string is effectively zero when +used in a context where a number is required.) + +The second rule keeps track of the largest line number seen so far; +it also stores each line into the array `arr', at an index that is +the line's number. + +The third rule runs after all the input has been read, to print out +all the lines. + +When this program is run with the following input: + + 5 I am the Five man + 2 Who are you? The new number two! + 4 . . . And four on the floor + 1 Who is number one? + 3 I three you. + + its output is this: + + 1 Who is number one? + 2 Who are you? The new number two! + 3 I three you. + 4 . . . And four on the floor + 5 I am the Five man + + + +File: gawk-info, Node: Scanning an Array, Next: Delete, Prev: Array Example, Up: Arrays + +Scanning All Elements of an Array +================================= + +In programs that use arrays, often you need a loop that will execute +once for each element of an array. In other languages, where arrays +are contiguous and indices are limited to positive integers, this is +easy: the largest index is one less than the length of the array, and +you can find all the valid indices by counting from zero up to that +value. This technique won't do the job in `awk', since any number or +string may be an array index. So `awk' has a special kind of `for' +statement for scanning an array: + + for (VAR in ARRAY) + BODY + +This loop executes BODY once for each different value that your +program has previously used as an index in ARRAY, with the variable +VAR set to that index. + +Here is a program that uses this form of the `for' statement. The +first rule scans the input records and notes which words appear (at +least once) in the input, by storing a 1 into the array `used' with +the word as index. The second rule scans the elements of `used' to +find all the distinct words that appear in the input. It prints each +word that is more than 10 characters long, and also prints the number +of such words. *Note Built-in::, for more information on the +built--in function `length'. + + # Record a 1 for each word that is used at least once. + { + for (i = 0; i < NF; i++) + used[$i] = 1 + } + + # Find number of distinct words more than 10 characters long. + END { + num_long_words = 0 + for (x in used) + if (length(x) > 10) { + ++num_long_words + print x + } + print num_long_words, "words longer than 10 characters" + } + +*Note Sample Program::, for a more detailed example of this type. + +The order in which elements of the array are accessed by this +statement is determined by the internal arrangement of the array +elements within `awk' and cannot be controlled or changed. This can +lead to problems if new elements are added to ARRAY by statements in +BODY; you cannot predict whether or not the `for' loop will reach +them. Similarly, changing VAR inside the loop can produce strange +results. It is best to avoid such things. + + + +File: gawk-info, Node: Delete, Next: Multi-dimensional, Prev: Scanning an Array, Up: Arrays + +The `delete' Statement +====================== + +You can remove an individual element of an array using the `delete' +statement: + + delete ARRAY[INDEX] + +When an array element is deleted, it is as if you had never referred +to it and had never given it any value. Any value the element +formerly had can no longer be obtained. + +Here is an example of deleting elements in an array: + + awk '{ for (i in frequencies) + delete frequencies[i] + }' + +This example removes all the elements from the array `frequencies'. + +If you delete an element, the `for' statement to scan the array will +not report that element, and the `in' operator to check for the +presence of that element will return 0: + + delete foo[4] + if (4 in foo) + print "This will never be printed" + + + +File: gawk-info, Node: Multi-dimensional, Next: Multi-scanning, Prev: Delete, Up: Arrays + +Multi--dimensional arrays +========================= + +A multi--dimensional array is an array in which an element is +identified by a sequence of indices, not a single index. For +example, a two--dimensional array requires two indices. The usual +way (in most languages, including `awk') to refer to an element of a +two--dimensional array named `grid' is with `grid[x,y]'. + +Multi--dimensional arrays are supported in `awk' through +concatenation of indices into one string. What happens is that `awk' +converts the indices into strings (*note Conversion::.) and +concatenates them together, with a separator between them. This +creates a single string that describes the values of the separate +indices. The combined string is used as a single index into an +ordinary, one--dimensional array. The separator used is the value of +the special variable `SUBSEP'. + +For example, suppose the value of `SUBSEP' is `","' and the +expression `foo[5,12]="value"' is executed. The numbers 5 and 12 +will be concatenated with a comma between them, yielding `"5,12"'; +thus, the array element `foo["5,12"]' will be set to `"value"'. + +Once the element's value is stored, `awk' has no record of whether it +was stored with a single index or a sequence of indices. The two +expressions `foo[5,12]' and `foo[5 SUBSEP 12]' always have the same +value. + +The default value of `SUBSEP' is not a comma; it is the string +`"\034"', which contains a nonprinting character that is unlikely to +appear in an `awk' program or in the input data. + +The usefulness of choosing an unlikely character comes from the fact +that index values that contain a string matching `SUBSEP' lead to +combined strings that are ambiguous. Suppose that `SUBSEP' is a +comma; then `foo["a,b", "c"]' and `foo["a", "b,c"]' will be +indistinguishable because both are actually stored as `foo["a,b,c"]'. +Because `SUBSEP' is `"\034"', such confusion can actually happen only +when an index contains the character `"\034"', which is a rare event. + +You can test whether a particular index--sequence exists in a +``multi--dimensional'' array with the same operator `in' used for +single dimensional arrays. Instead of a single index as the +left--hand operand, write the whole sequence of indices, separated by +commas, in parentheses: + + (SUBSCRIPT1, SUBSCRIPT2, ...) in ARRAY + +The following example treats its input as a two--dimensional array of +fields; it rotates this array 90 degrees clockwise and prints the +result. It assumes that all lines have the same number of elements. + + awk 'BEGIN { + max_nf = max_nr = 0 + } + + { + if (max_nf < NF) + max_nf = NF + max_nr = NR + for (x = 1; x <= NF; x++) + vector[x, NR] = $x + } + + END { + for (x = 1; x <= max_nf; x++) { + for (y = max_nr; y >= 1; --y) + printf("%s ", vector[x, y]) + printf("\n") + } + }' + +When given the input: + + 1 2 3 4 5 6 + 2 3 4 5 6 1 + 3 4 5 6 1 2 + 4 5 6 1 2 3 + +it produces: + + 4 3 2 1 + 5 4 3 2 + 6 5 4 3 + 1 6 5 4 + 2 1 6 5 + 3 2 1 6 + + + +File: gawk-info, Node: Multi-scanning, Prev: Multi-dimensional, Up: Arrays + +Scanning Multi--dimensional Arrays +================================== + +There is no special `for' statement for scanning a +``multi--dimensional'' array; there cannot be one, because in truth +there are no multi--dimensional arrays or elements; there is only a +multi--dimensional *way of accessing* an array. + +However, if your program has an array that is always accessed as +multi--dimensional, you can get the effect of scanning it by +combining the scanning `for' statement (*note Scanning an Array::.) +with the `split' built--in function (*note String Functions::.). It +works like this: + + for (combined in ARRAY) { + split (combined, separate, SUBSEP) + ... + } + +This finds each concatenated, combined index in the array, and splits +it into the individual indices by breaking it apart where the value +of `SUBSEP' appears. The split--out indices become the elements of +the array `separate'. + +Thus, suppose you have previously stored in `ARRAY[1, "foo"]'; then +an element with index `"1\034foo"' exists in ARRAY. (Recall that the +default value of `SUBSEP' contains the character with code 034.) +Sooner or later the `for' statement will find that index and do an +iteration with `combined' set to `"1\034foo"'. Then the `split' +function will be called as follows: + + split ("1\034foo", separate, "\034") + +The result of this is to set `separate[1]' to 1 and `separate[2]' to +`"foo"'. Presto, the original sequence of separate indices has been +recovered. + + + +File: gawk-info, Node: Built-in, Next: User-defined, Prev: Arrays, Up: Top + +Built--in functions +******************* + +"Built--in" functions are functions always available for your `awk' +program to call. This chapter defines all the built--in functions +that exist; some of them are mentioned in other sections, but they +are summarized here for your convenience. (You can also define new +functions yourself. *Note User-defined::.) + +In most cases, any extra arguments given to built--in functions are +ignored. The defaults for omitted arguments vary from function to +function and are described under the individual functions. + +The name of a built--in function need not be followed immediately by +the opening left parenthesis of the arguments; whitespace is allowed. +However, it is wise to write no space there, since user--defined +functions do not allow space. + +When a function is called, expressions that create the function's +actual parameters are evaluated completely before the function call +is performed. For example, in the code fragment: + + i = 4 + j = myfunc(i++) + +the variable `i' will be set to 5 before `myfunc' is called with a +value of 4 for its actual parameter. + +* Menu: + +* Numeric Functions:: Functions that work with numbers, + including `int', `sin' and `rand'. + +* String Functions:: Functions for string manipulation, + such as `split', `match', and `sprintf'. + +* I/O Functions:: Functions for files and shell commands + + + +File: gawk-info, Node: Numeric Functions, Next: String Functions, Up: Built-in + +Numeric Built--in Functions +=========================== + +The general syntax of the numeric built--in functions is the same for +each. Here is an example of that syntax: + + awk '# Read input records containing a pair of points: x0, y0, x1, y1. + # Print the points and the distance between them. + { printf "%f %f %f %f %f\n", $1, $2, $3, $4, + sqrt(($2-$1) * ($2-$1) + ($4-$3) * ($4-$3)) }' + +This calculates the square root of a calculation that uses the values +of the fields. It then prints the first four fields of the input +record and the result of the square root calculation. + +Here is the full list of numeric built--in functions: + +`int(X)' + This gives you the integer part of X, truncated toward 0. This + produces the nearest integer to X, located between X and 0. + + For example, `int(3)' is 3, `int(3.9)' is 3, `int(-3.9)' is -3, + and `int(-3)' is -3 as well. + +`sqrt(X)' + This gives you the positive square root of X. It reports an + error if X is negative. + +`exp(X)' + This gives you the exponential of X, or reports an error if X is + out of range. The range of values X can have depends on your + machine's floating point representation. + +`log(X)' + This gives you the natural logarithm of X, if X is positive; + otherwise, it reports an error. + +`sin(X)' + This gives you the sine of X, with X in radians. + +`cos(X)' + This gives you the cosine of X, with X in radians. + +`atan2(Y, X)' + This gives you the arctangent of Y/X, with both in radians. + +`rand()' + This gives you a random number. The values of `rand()' are + uniformly--distributed between 0 and 1. The value is never 0 + and never 1. + + Often you want random integers instead. Here is a user--defined + function you can use to obtain a random nonnegative integer less + than N: + + function randint(n) { + return int(n * rand()) + } + + The multiplication produces a random real number at least 0, and + less than N. We then make it an integer (using `int') between 0 + and `N-1'. + + Here is an example where a similar function is used to produce + random integers between 1 and N: + + awk ' + # Function to roll a simulated die. + function roll(n) { return 1 + int(rand() * n) } + + # Roll 3 six--sided dice and print total number of points. + { + printf("%d points\n", roll(6)+roll(6)+roll(6)) + }' + + *Note* that `rand()' starts generating numbers from the same + point, or "seed", each time you run `awk'. This means that the + same program will produce the same results each time you run it. + The numbers are random within one `awk' run, but predictable + from run to run. This is convenient for debugging, but if you + want a program to do different things each time it is used, you + must change the seed to a value that will be different in each + run. To do this, use `srand'. + +`srand(X)' + The function `srand(X)' sets the starting point, or "seed", for + generating random numbers to the value X. + + Each seed value leads to a particular sequence of ``random'' + numbers. Thus, if you set the seed to the same value a second + time, you will get the same sequence of ``random'' numbers again. + + If you omit the argument X, as in `srand()', then the current + date and time of day are used for a seed. This is the way to + get random numbers that are truly unpredictable. + + The return value of `srand()' is the previous seed. This makes + it easy to keep track of the seeds for use in consistently + reproducing sequences of random numbers. + + + +File: gawk-info, Node: String Functions, Next: I/O Functions, Prev: Numeric Functions, Up: Built-in + +Built--in Functions for String Manipulation +=========================================== + +`index(IN, FIND)' + This searches the string IN for the first occurrence of the + string FIND, and returns the position where that occurrence + begins in the string IN. For example: + + awk 'BEGIN { print index("peanut", "an") }' + + prints `3'. If FIND is not found, `index' returns 0. + +`length(STRING)' + This gives you the number of characters in STRING. If STRING is + a number, the length of the digit string representing that + number is returned. For example, `length("abcde")' is 5. + Whereas, `length(15 * 35)' works out to 3. How? Well, 15 * 35 + = 525, and 525 is then converted to the string `"525"', which + has three characters. + +`match(STRING, REGEXP)' + The `match' function searches the string, STRING, for the + longest, leftmost substring matched by the regular expression, + REGEXP. It returns the character position, or "index", of where + that substring begins (1, if it starts at the beginning of + STRING). If no match if found, it returns 0. + + The `match' function sets the special variable `RSTART' to the + index. It also sets the special variable `RLENGTH' to the + length of the matched substring. If no match is found, `RSTART' + is set to 0, and `RLENGTH' to -1. + + For example: + + awk '{ + if ($1 == "FIND") + regex = $2 + else { + where = match($0, regex) + if (where) + print "Match of", regex, "found at", where, "in", $0 + } + }' + + This program looks for lines that match the regular expression + stored in the variable `regex'. This regular expression can be + changed. If the first word on a line is `FIND', `regex' is + changed to be the second word on that line. Therefore, given: + + FIND fo*bar + My program was a foobar + But none of it would doobar + FIND Melvin + JF+KM + This line is property of The Reality Engineering Co. + This file was created by Melvin. + + `awk' prints: + + Match of fo*bar found at 18 in My program was a foobar + Match of Melvin found at 26 in This file was created by Melvin. + +`split(STRING, ARRAY, FIELD_SEPARATOR)' + This divides STRING up into pieces separated by FIELD_SEPARATOR, + and stores the pieces in ARRAY. The first piece is stored in + `ARRAY[1]', the second piece in `ARRAY[2]', and so forth. The + string value of the third argument, FIELD_SEPARATOR, is used as + a regexp to search for to find the places to split STRING. If + the FIELD_SEPARATOR is omitted, the value of `FS' is used. + `split' returns the number of elements created. + + The `split' function, then, splits strings into pieces in a + manner similar to the way input lines are split into fields. + For example: + + split("auto-da-fe", a, "-") + + splits the string `auto-da-fe' into three fields using `-' as + the separator. It sets the contents of the array `a' as follows: + + a[1] = "auto" + a[2] = "da" + a[3] = "fe" + + The value returned by this call to `split' is 3. + +`sprintf(FORMAT, EXPRESSION1,...)' + This returns (without printing) the string that `printf' would + have printed out with the same arguments (*note Printf::.). For + example: + + sprintf("pi = %.2f (approx.)", 22/7) + + returns the string `"pi = 3.14 (approx.)"'. + +`sub(REGEXP, REPLACEMENT_STRING, TARGET_VARIABLE)' + The `sub' function alters the value of TARGET_VARIABLE. It + searches this value, which should be a string, for the leftmost + substring matched by the regular expression, REGEXP, extending + this match as far as possible. Then the entire string is + changed by replacing the matched text with REPLACEMENT_STRING. + The modified string becomes the new value of TARGET_VARIABLE. + + This function is peculiar because TARGET_VARIABLE is not simply + used to compute a value, and not just any expression will do: it + must be a variable, field or array reference, so that `sub' can + store a modified value there. If this argument is omitted, then + the default is to use and alter `$0'. + + For example: + + str = "water, water, everywhere" + sub(/at/, "ith", str) + + sets `str' to `"wither, water, everywhere"', by replacing the + leftmost, longest occurrence of `at' with `ith'. + + The `sub' function returns the number of substitutions made + (either one or zero). + + The special character, `&', in the replacement string, + REPLACEMENT_STRING, stands for the precise substring that was + matched by REGEXP. (If the regexp can match more than one + string, then this precise substring may vary.) For example: + + awk '{ sub(/candidate/, "& and his wife"); print }' + + will change the first occurrence of ``candidate'' to ``candidate + and his wife'' on each input line. + + The effect of this special character can be turned off by + preceding it with a backslash (`\&'). To include a backslash in + the replacement string, it too must be preceded with a (second) + backslash. + + Note: if you use `sub' with a third argument that is not a + variable, field or array element reference, then it will still + search for the pattern and return 0 or 1, but the modified + string is thrown away because there is no place to put it. For + example: + + sub(/USA/, "United States", "the USA and Canada") + + will indeed produce a string `"the United States and Canada"', + but there will be no way to use that string! + +`gsub(REGEXP, REPLACEMENT_STRING, TARGET_VARIABLE)' + This is similar to the `sub' function, except `gsub' replaces + *all* of the longest, leftmost, *non--overlapping* matching + substrings it can find. The ``g'' in `gsub' stands for + "global", which means replace *everywhere*. For example: + + awk '{ gsub(/Britain/, "United Kingdom"); print }' + + replaces all occurrences of the string `Britain' with `United + Kingdom' for all input records. + + The `gsub' function returns the number of substitutions made. + If the variable to be searched and altered, TARGET_VARIABLE, is + omitted, then the entire input record, `$0', is used. + + The characters `&' and `\' are special in `gsub' as they are in + `sub' (see immediately above). + +`substr(STRING, START, LENGTH)' + This returns a LENGTH--character--long substring of STRING, + starting at character number START. The first character of a + string is character number one. For example, + `substr("washington", 5, 3)' returns `"ing"'. + + If LENGTH is not present, this function returns the whole suffix + of STRING that begins at character number START. For example, + `substr("washington", 5)' returns `"ington"'. + + + +File: gawk-info, Node: I/O Functions, Prev: String Functions, Up: Built-in + +Built--in Functions for I/O to Files and Commands +================================================= + +`close(FILENAME)' + Close the file FILENAME. The argument may alternatively be a + shell command that was used for redirecting to or from a pipe; + then the pipe is closed. + + *Note Close Input::, regarding closing input files and pipes. + *Note Close Output::, regarding closing output files and pipes. + +`system(COMMAND)' + The system function allows the user to execute operating system + commands and then return to the `awk' program. The `system' + function executes the command given by the string value of + COMMAND. It returns, as its value, the status returned by the + command that was executed. This is known as returning the "exit + status". + + For example, if the following fragment of code is put in your + `awk' program: + + END { + system("mail -s 'awk run done' operator < /dev/null") + } + + the system operator will be sent mail when the `awk' program + finishes processing input and begins its end--of--input + processing. + + Note that much the same result can be obtained by redirecting + `print' or `printf' into a pipe. However, if your `awk' program + is interactive, this function is useful for cranking up large + self--contained programs, such as a shell or an editor. + + + +File: gawk-info, Node: User-defined, Next: Special, Prev: Built-in, Up: Top + +User--defined Functions +*********************** + +Complicated `awk' programs can often be simplified by defining your +own functions. User--defined functions can be called just like +built--in ones (*note Function Calls::.), but it is up to you to +define them--to tell `awk' what they should do. + +* Menu: + +* Definition Syntax:: How to write definitions and what they mean. +* Function Example:: An example function definition and what it does. +* Function Caveats:: Things to watch out for. +* Return Statement:: Specifying the value a function returns. + + + +File: gawk-info, Node: Definition Syntax, Next: Function Example, Up: User-defined + +Syntax of Function Definitions +============================== + +The definition of a function named NAME looks like this: + + function NAME (PARAMETER-LIST) { + BODY-OF-FUNCTION + } + +A valid function name is like a valid variable name: a sequence of +letters, digits and underscores, not starting with a digit. + +Such function definitions can appear anywhere between the rules of +the `awk' program. The general format of an `awk' program, then, is +now modified to include sequences of rules *and* user--defined +function definitions. + +The function definition need not precede all the uses of the function. +This is because `awk' reads the entire program before starting to +execute any of it. + +The PARAMETER-LIST is a list of the function's "local" variable +names, separated by commas. Within the body of the function, local +variables refer to arguments with which the function is called. If +the function is called with fewer arguments than it has local +variables, this is not an error; the extra local variables are simply +set as the null string. + +The local variable values hide or "shadow" any variables of the same +names used in the rest of the program. The shadowed variables are +not accessible in the function definition, because there is no way to +name them while their names have been taken away for the local +variables. All other variables used in the `awk' program can be +referenced or set normally in the function definition. + +The local variables last only as long as the function is executing. +Once the function finishes, the shadowed variables come back. + +The BODY-OF-FUNCTION part of the definition is the most important +part, because this is what says what the function should actually *do*. +The local variables exist to give the body a way to talk about the +arguments. + +Functions may be "recursive", i.e., they can call themselves, either +directly, or indirectly (via calling a second function that calls the +first again). + +The keyword `function' may also be written `func'. + + + +File: gawk-info, Node: Function Example, Next: Function Caveats, Prev: Definition Syntax, Up: User-defined + +Function Definition Example +=========================== + +Here is an example of a user--defined function, called `myprint', +that takes a number and prints it in a specific format. + + function myprint(num) + { + printf "%6.3g\n", num + } + +To illustrate, let's use the following `awk' rule to use, or "call", +our `myprint' function: + + $3 > 0 { myprint($3) }' + +This program prints, in our special format, all the third fields that +contain a positive number in our input. Therefore, when given: + + 1.2 3.4 5.6 7.8 + 9.10 11.12 13.14 15.16 + 17.18 19.20 21.22 23.24 + +this program, using our function to format the results, will print: + + 5.6 + 13.1 + 21.2 + +Here is a rather contrived example of a recursive function. It +prints a string backwards: + + function rev (str, len) { + if (len == 0) { + printf "\n" + return + } + printf "%c", substr(str, len, 1) + rev(str, len - 1) + } + + + +File: gawk-info, Node: Function Caveats, Next: Return Statement, Prev: Function Example, Up: User-defined + +Caveats of Function Calling +=========================== + +*Note* that there cannot be any blanks between the function name and +the left parenthesis of the argument list, when calling a function. +This is so `awk' can tell you are not trying to concatenate the value +of a variable with the value of an expression inside the parentheses. + +When a function is called, it is given a *copy* of the values of its +arguments. This is called "passing by value". The caller may use a +variable as the expression for the argument, but the called function +does not know this: all it knows is what value the argument had. For +example, if you write this code: + + foo = "bar" + z = myfunc(foo) + +then you should not think of the argument to `myfunc' as being ``the +variable `foo'''. Instead, think of the argument as the string +value, `"bar"'. + +If the function `myfunc' alters the values of its local variables, +this has no effect on any other variables. In particular, if +`myfunc' does this: + + function myfunc (win) { + print win + win = "zzz" + print win + } + +to change its first argument variable `win', this *does not* change +the value of `foo' in the caller. The role of `foo' in calling +`myfunc' ended when its value, `"bar"', was computed. If `win' also +exists outside of `myfunc', this definition will not change it--that +value is shadowed during the execution of `myfunc' and cannot be seen +or changed from there. + +However, when arrays are the parameters to functions, they are *not* +copied. Instead, the array itself is made available for direct +manipulation by the function. This is usually called "passing by +reference". Changes made to an array parameter inside the body of a +function *are* visible outside that function. *This can be very +dangerous if you don't watch what you are doing.* For example: + + function changeit (array, ind, nvalue) { + array[ind] = nvalue + } + + BEGIN { + a[1] = 1 ; a[2] = 2 ; a[3] = 3 + changeit(a, 2, "two") + printf "a[1] = %s, a[2] = %s, a[3] = %s\n", a[1], a[2], a[3] + } + +will print `a[1] = 1, a[2] = two, a[3] = 3', because the call to +`changeit' stores `"two"' in the second element of `a'. + + + +File: gawk-info, Node: Return Statement, Prev: Function Caveats, Up: User-defined + +The `return' statement +====================== + +The body of a user--defined function can contain a `return' statement. +This statement returns control to the rest of the `awk' program. It +can also be used to return a value for use in the rest of the `awk' +program. It looks like: + + `return EXPRESSION' + +The EXPRESSION part is optional. If it is omitted, then the returned +value is undefined and, therefore, unpredictable. + +A `return' statement with no value expression is assumed at the end +of every function definition. So if control reaches the end of the +function definition, then the function returns an unpredictable value. + +Here is an example of a user--defined function that returns a value +for the largest number among the elements of an array: + + function maxelt (vec, i, ret) { + for (i in vec) { + if (ret == "" || vec[i] > ret) + ret = vec[i] + } + return ret + } + +You call `maxelt' with one argument, an array name. The local +variables `i' and `ret' are not intended to be arguments; while there +is nothing to stop you from passing two or three arguments to +`maxelt', the results would be strange. + +When writing a function definition, it is conventional to separate +the parameters from the local variables with extra spaces, as shown +above in the definition of `maxelt'. + +Here is a program that uses, or calls, our `maxelt' function. This +program loads an array, calls `maxelt', and then reports the maximum +number in that array: + + awk ' + function maxelt (vec, i, ret) { + for (i in vec) { + if (ret == "" || vec[i] > ret) + ret = vec[i] + } + return ret + } + + # Load all fields of each record into nums. + { + for(i = 1; i <= NF; i++) + nums[NR, i] = $i + } + + END { + print maxelt(nums) + }' + +Given the following input: + + 1 5 23 8 16 + 44 3 5 2 8 26 + 256 291 1396 2962 100 + -6 467 998 1101 + 99385 11 0 225 + +our program tells us (predictably) that: + + 99385 + +is the largest number in our array. + + + +File: gawk-info, Node: Special, Next: Sample Program, Prev: User-defined, Up: Top + +Special Variables +***************** + +Most `awk' variables are available for you to use for your own +purposes; they will never change except when your program assigns +them, and will never affect anything except when your program +examines them. + +A few variables have special meanings. Some of them `awk' examines +automatically, so that they enable you to tell `awk' how to do +certain things. Others are set automatically by `awk', so that they +carry information from the internal workings of `awk' to your program. + +Most of these variables are also documented in the chapters where +their areas of activity are described. + +* Menu: + +* User-modified:: Special variables that you change to control `awk'. + +* Auto-set:: Special variables where `awk' gives you information. + +
\ No newline at end of file |