Fresh Fish 6

home *** CD-ROM | disk | FTP | other *** search

/ Fresh Fish 6 / FreshFish_September1994.bin / bbs / gnu / gawk-2.15.5-src.lha / GNU / src / amiga / gawk-2.15.5 / gawk.info-5 < prev next >

Wrap

GNU Info File | 1994-06-13 | 47.7 KB | 1,257 lines

This is Info file gawk.info, produced by Makeinfo-1.55 from the input file /gnu/src/amiga/gawk-2.15.5/gawk.texi. This file documents `awk', a program that you can use to select particular records in a file and perform operations upon them. This is Edition 0.15 of `The GAWK Manual', for the 2.15 version of the GNU implementation of AWK. Copyright (C) 1989, 1991, 1992, 1993 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 Statement, Next: Break Statement, Prev: Do Statement, 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 all the powers of 2 between 1 and 100: for (i = 1; i <= 100; i *= 2) print i Any of the three expressions in the parentheses following the `for' may be omitted if there is nothing to be done there. Thus, `for (;x > 0;)' is equivalent to `while (x > 0)'. If the CONDITION is omitted, it is treated as TRUE, effectively yielding an "infinite loop" (i.e., a loop that will never terminate). 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 The `continue' Statement: Continue Statement.) 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. There is an alternate version of the `for' loop, for iterating over all the indices of an array: for (i in array) DO SOMETHING WITH array[i] *Note Arrays in `awk': Arrays, for more information on this version of the `for' 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. File: gawk.info, Node: Break Statement, Next: Continue Statement, Prev: For Statement, 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 integer, 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 which stops the entire `awk' program. *Note The `exit' Statement: Exit Statement.) 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 Statement, Next: Next Statement, Prev: Break Statement, 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 one of the input records contains the string `ignore', this example skips the print statement for that record, and continues back to the first statement in the loop. This is not a practical example of `continue', since it would be just as easy to write the loop like this: for (x in names) if (names[x] !~ /ignore/) print names[x] The `continue' statement in a `for' loop directs `awk' to skip the rest of the body of the loop, and resume execution with the increment-expression of the `for' statement. 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. Contrast the `for' loop above with the `while' loop: awk 'BEGIN { x = 0 while (x <= 20) { if (x == 5) continue printf ("%d ", x) x++ } print "" }' This program loops forever once `x' gets to 5. As described above, the `continue' statement has no meaning when used outside the body of a loop. However, although it was never documented, historical implementations of `awk' have treated the `continue' statement outside of a loop as if it were a `next' statement (*note The `next' Statement: Next Statement.). By default, `gawk' silently supports this usage. However, if `-W posix' has been specified on the command line (*note Invoking `awk': Command Line.), it will be treated as an error, since the POSIX standard specifies that `continue' should only be used inside the body of a loop. File: gawk.info, Node: Next Statement, Next: Next File Statement, Prev: Continue Statement, 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 Explicit Input with `getline': 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 highest level, `awk' program execution is a loop that reads an input record and then tests each rule's 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 this implicit 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 this rule near the beginning of the program: NF != 4 { printf("line %d skipped: doesn't have 4 fields", FNR) > "/dev/stderr" next } so that the following rules will not see the bad record. The error message is redirected to the standard error output stream, as error messages should be. *Note Standard I/O Streams: Special Files. According to the POSIX standard, the behavior is undefined if the `next' statement is used in a `BEGIN' or `END' rule. `gawk' will treat it as a syntax error. If the `next' statement causes the end of the input to be reached, then the code in the `END' rules, if any, will be executed. *Note `BEGIN' and `END' Special Patterns: BEGIN/END. File: gawk.info, Node: Next File Statement, Next: Exit Statement, Prev: Next Statement, Up: Statements The `next file' Statement ========================= The `next file' statement is similar to the `next' statement. However, instead of abandoning processing of the current record, the `next file' statement instructs `awk' to stop processing the current data file. Upon execution of the `next file' statement, `FILENAME' is updated to the name of the next data file listed on the command line, `FNR' is reset to 1, and processing starts over with the first rule in the progam. *Note Built-in Variables::. If the `next file' statement causes the end of the input to be reached, then the code in the `END' rules, if any, will be executed. *Note `BEGIN' and `END' Special Patterns: BEGIN/END. The `next file' statement is a `gawk' extension; it is not (currently) available in any other `awk' implementation. You can simulate its behavior by creating a library file named `nextfile.awk', with the following contents. (This sample program uses user-defined functions, a feature that has not been presented yet. *Note User-defined Functions: User-defined, for more information.) # nextfile --- function to skip remaining records in current file # this should be read in before the "main" awk program function nextfile() { _abandon_ = FILENAME; next } _abandon_ == FILENAME && FNR > 1 { next } _abandon_ == FILENAME && FNR == 1 { _abandon_ = "" } The `nextfile' function simply sets a "private" variable(1) to the name of the current data file, and then retrieves the next record. Since this file is read before the main `awk' program, the rules that follows the function definition will be executed before the rules in the main program. The first rule continues to skip records as long as the name of the input file has not changed, and this is not the first record in the file. This rule is sufficient most of the time. But what if the *same* data file is named twice in a row on the command line? This rule would not process the data file the second time. The second rule catches this case: If the data file name is what was being skipped, but `FNR' is 1, then this is the second time the file is being processed, and it should not be skipped. The `next file' statement would be useful if you have many data files to process, and due to the nature of the data, you expect that you would not want to process every record in the file. In order to move on to the next data file, you would have to continue scanning the unwanted records (as described above). The `next file' statement accomplishes this much more efficiently. ---------- Footnotes ---------- (1) Since all variables in `awk' are global, this program uses the common practice of prefixing the variable name with an underscore. In fact, it also suffixes the variable name with an underscore, as extra insurance against using a variable name that might be used in some other library file. File: gawk.info, Node: Exit Statement, Prev: Next File Statement, 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 are read. However, if an `END' rule is present, it is executed (*note `BEGIN' and `END' Special Patterns: 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 of 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 do not 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" > "/dev/stderr" exit 4 } } File: gawk.info, Node: Arrays, Next: Built-in, Prev: Statements, Up: Top Arrays in `awk' *************** An "array" is a table of values, called "elements". The elements of an array are distinguished by their indices. "Indices" may be either numbers or strings. Each array has a name, which looks like a variable name, but must not be in use as a variable name in the same `awk' program. * Menu: * Array Intro:: Introduction to Arrays * Reference to Elements:: How to examine one element of an array. * Assigning Elements:: How to change an element of an array. * Array Example:: Basic Example of an Array * 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. * Numeric Array Subscripts:: How to use numbers as subscripts in `awk'. * Multi-dimensional:: Emulating multi-dimensional arrays in `awk'. * Multi-scanning:: Scanning multi-dimensional arrays. File: gawk.info, Node: Array Intro, Next: Reference to Elements, Prev: Arrays, Up: Arrays Introduction to Arrays ====================== The `awk' language has one-dimensional "arrays" for storing groups of related strings or numbers. Every `awk' array must have a name. Array names have the same syntax as variable names; any valid variable name would also be a valid array name. But you cannot use one name in both ways (as an array and as a variable) in one `awk' program. Arrays in `awk' superficially resemble arrays in other programming languages; but there are fundamental differences. In `awk', you don't need to specify the size of an array before you start to use it. Additionally, any number or string in `awk' 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 contains. 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. 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 is irrelevant. One advantage of an associative array is that new pairs can be added at any time. For example, suppose we add to the above 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 1-4 and 10, but doesn't have elements 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 numeric 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, that array's indices are consecutive integers starting at 1. (*Note Built-in Functions for String Manipulation: String Functions.) 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 The `delete' Statement: 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[INDEX]' exists, and 0 (false) if it does not exist. For example, to test whether the array `frequencies' contains the index `"2"', you could write this statement: 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 do that except to scan all the elements.) Also, this *does not* create `frequencies["2"]', while the following (incorrect) alternative would do so: 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 gets confused if it encounters repeated numbers, gaps, or lines that don't begin with a number. { if ($1 > max) max = $1 arr[$1] = $0 } END { for (x = 1; x <= max; x++) print arr[x] } The first 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 second 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 If a line number is repeated, the last line with a given number overrides the others. Gaps in the line numbers can be handled with an easy improvement to the program's `END' rule: END { for (x = 1; x <= max; x++) if (x in arr) print arr[x] } 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 executes 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 Functions: 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 = 1; i <= NF; i++) used[$i] = 1 } # Find number of distinct words more than 10 characters long. END { 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: Numeric Array Subscripts, 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] You can not refer to an array element after it has been deleted; it is as if you had never referred to it and had never given it any value. You can no longer obtain any value the element once had. Here is an example of deleting elements in an array: for (i in frequencies) delete frequencies[i] This example removes all the elements from the array `frequencies'. If you delete an element, a subsequent `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" It is not an error to delete an element which does not exist. File: gawk.info, Node: Numeric Array Subscripts, Next: Multi-dimensional, Prev: Delete, Up: Arrays Using Numbers to Subscript Arrays ================================= An important aspect of arrays to remember is that array subscripts are *always* strings. If you use a numeric value as a subscript, it will be converted to a string value before it is used for subscripting (*note Conversion of Strings and Numbers: Conversion.). This means that the value of the `CONVFMT' can potentially affect how your program accesses elements of an array. For example: a = b = 12.153 data[a] = 1 CONVFMT = "%2.2f" if (b in data) printf "%s is in data", b else printf "%s is not in data", b should print `12.15 is not in data'. The first statement gives both `a' and `b' the same numeric value. Assigning to `data[a]' first gives `a' the string value `"12.153"' (using the default conversion value of `CONVFMT', `"%.6g"'), and then assigns 1 to `data["12.153"]'. The program then changes the value of `CONVFMT'. The test `(b in data)' forces `b' to be converted to a string, this time `"12.15"', since the value of `CONVFMT' only allows two significant digits. This test fails, since `"12.15"' is a different string from `"12.153"'. According to the rules for conversions (*note Conversion of Strings and Numbers: Conversion.), integer values are always converted to strings as integers, no matter what the value of `CONVFMT' may happen to be. So the usual case of for (i = 1; i <= maxsub; i++) do something with array[i] will work, no matter what the value of `CONVFMT'. Like many things in `awk', the majority of the time things work as you would expect them to work. But it is useful to have a precise knowledge of the actual rules, since sometimes they can have a subtle effect on your programs. File: gawk.info, Node: Multi-dimensional, Next: Multi-scanning, Prev: Numeric Array Subscripts, 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 of Strings and Numbers: 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 built-in variable `SUBSEP'. For example, suppose we evaluate the expression `foo[5,12]="value"' when the value of `SUBSEP' is `"@"'. The numbers 5 and 12 are converted to strings and concatenated with an `@' between them, yielding `"5@12"'; thus, the array element `foo["5@12"]' is 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 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' were `"@"'; then `foo["a@b", "c"]' and `foo["a", "b@c"]' would be indistinguishable because both would actually be stored as `foo["a@b@c"]'. Because `SUBSEP' is `"\034"', such confusion can arise only when an index contains the character with ASCII code 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 '{ 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 all Elements of an Array: Scanning an Array.) with the `split' built-in function (*note Built-in Functions for String Manipulation: 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 is 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 that are always available for your `awk' program to call. This chapter defines all the built-in functions in `awk'; 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 Functions: User-defined.) * Menu: * Calling Built-in:: How to call built-in functions. * 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. * Time Functions:: Functions for dealing with time stamps. File: gawk.info, Node: Calling Built-in, Next: Numeric Functions, Prev: Built-in, Up: Built-in Calling Built-in Functions ========================== To call a built-in function, write the name of the function followed by arguments in parentheses. For example, `atan2(y + z, 1)' is a call to the function `atan2', with two arguments. Whitespace is ignored between the built-in function name and the open-parenthesis, but we recommend that you avoid using whitespace there. User-defined functions do not permit whitespace in this way, and you will find it easier to avoid mistakes by following a simple convention which always works: no whitespace after a function name. Each built-in function accepts a certain number of arguments. 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. 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 = sqrt(i++) the variable `i' is set to 5 before `sqrt' is called with a value of 4 for its actual parameter. File: gawk.info, Node: Numeric Functions, Next: String Functions, Prev: Calling Built-in, Up: Built-in Numeric Built-in Functions ========================== Here is a full list of built-in functions that work with numbers: `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. Thus, `sqrt(4)' is 2. `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' 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 greater than 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. Note that this program will print a new random number for each input record. 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:* `rand' starts generating numbers from the same point, or "seed", each time you run `awk'. This means that a 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' 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 ========================================== The functions in this section look at or change the text of one or more strings. `index(IN, FIND)' This searches the string IN for the first occurrence of the string FIND, and returns the position in characters 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. (Remember that string indices in `awk' start at 1.) `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. By contrast, `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. If no argument is supplied, `length' returns the length of `$0'. In older versions of `awk', you could call the `length' function without any parentheses. Doing so is marked as "deprecated" in the POSIX standard. This means that while you can do this in your programs, it is a feature that can eventually be removed from a future version of the standard. Therefore, for maximal portability of your `awk' programs you should always supply the parentheses. `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 built-in variable `RSTART' to the index. It also sets the built-in variable `RLENGTH' to the length in characters 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 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 created by Melvin. `split(STRING, ARRAY, FIELDSEP)' This divides STRING into pieces separated by FIELDSEP, 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, FIELDSEP, is a regexp describing where to split STRING (much as `FS' can be a regexp describing where to split input records). If the FIELDSEP 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. As with input field-splitting, when the value of FIELDSEP is `" "', leading and trailing whitespace is ignored, and the elements are separated by runs of whitespace. `sprintf(FORMAT, EXPRESSION1,...)' This returns (without printing) the string that `printf' would have printed out with the same arguments (*note Using `printf' Statements for Fancier Printing: Printf.). For example: sprintf("pi = %.2f (approx.)", 22/7) returns the string `"pi = 3.14 (approx.)"'. `sub(REGEXP, REPLACEMENT, TARGET)' The `sub' function alters the value of TARGET. 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. The modified string becomes the new value of TARGET. This function is peculiar because TARGET 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). If the special character `&' appears in REPLACEMENT, it 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 }' changes the first occurrence of `candidate' to `candidate and his wife' on each input line. Here is another example: awk 'BEGIN { str = "daabaaa" sub(/a*/, "c&c", str) print str }' prints `dcaacbaaa'. This show how `&' can represent a non-constant string, and also illustrates the "leftmost, longest" rule. The effect of this special character (`&') can be turned off by putting a backslash before it in the string. As usual, to insert one backslash in the string, you must write two backslashes. Therefore, write `\\&' in a string constant to include a literal `&' in the replacement. For example, here is how to replace the first `|' on each line with an `&': awk '{ sub(/\|/, "\\&"); print }' *Note:* as mentioned above, the third argument to `sub' must be an lvalue. Some versions of `awk' allow the third argument to be an expression which is not an lvalue. In such a case, `sub' would still search for the pattern and return 0 or 1, but the result of the substitution (if any) would be thrown away because there is no place to put it. Such versions of `awk' accept expressions like this: sub(/USA/, "United States", "the USA and Canada") But that is considered erroneous in `gawk'. `gsub(REGEXP, REPLACEMENT, TARGET)' This is similar to the `sub' function, except `gsub' replaces *all* of the longest, leftmost, *nonoverlapping* 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, is omitted, then the entire input record, `$0', is used. As in `sub', the characters `&' and `\' are special, and the third argument must be an lvalue. `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"'. This is also the case if LENGTH is greater than the number of characters remaining in the string, counting from character number START. `tolower(STRING)' This returns a copy of STRING, with each upper-case character in the string replaced with its corresponding lower-case character. Nonalphabetic characters are left unchanged. For example, `tolower("MiXeD cAsE 123")' returns `"mixed case 123"'. `toupper(STRING)' This returns a copy of STRING, with each lower-case character in the string replaced with its corresponding upper-case character. Nonalphabetic characters are left unchanged. For example, `toupper("MiXeD cAsE 123")' returns `"MIXED CASE 123"'.