diff options
| -rw-r--r-- | FUTURES | 8 | ||||
| -rw-r--r-- | POSIX.STD | 19 | ||||
| -rw-r--r-- | TODO | 8 | ||||
| -rw-r--r-- | awklib/eg/prog/indirectcall.awk | 3 | ||||
| -rw-r--r-- | doc/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/awkcard.in | 9 | ||||
| -rw-r--r-- | doc/gawk.1 | 14 | ||||
| -rw-r--r-- | doc/gawk.info | 1125 | ||||
| -rw-r--r-- | doc/gawk.texi | 480 | ||||
| -rw-r--r-- | eval.c | 5 |
10 files changed, 833 insertions, 843 deletions
@@ -38,9 +38,9 @@ For 4.0 DONE: Add an FPAT variable and patsplit function where the regex describes the fields, not the separators. - Remove support for all unsupported systems. + DONE: Remove support for all unsupported systems. - Remove all old README* files. + DONE: Remove all old README* files. DONE: Remove --copyleft, leaving just --copyright. @@ -50,7 +50,7 @@ For 4.0 Indirect functions BEGINFILE, ENDFILE - Simplify awk.h. + DONE: Simplify awk.h. Consider moving var_value info into Node_var itself to reduce memory usage. @@ -65,7 +65,7 @@ For 4.0 Gnulib? - Move to git? + DONE: Move to git. Additional manual features: Remove all page breaks @@ -5,7 +5,7 @@ are permitted in any medium without royalty provided the copyright notice and this notice are preserved. -------------------------------------------------------------------------- -Fri Nov 19 11:59:56 IST 2010 +Wed Dec 1 21:51:31 IST 2010 ============================ This file documents several things related to the 2008 POSIX standard that I noted after reviewing it. @@ -26,9 +26,16 @@ that I noted after reviewing it. More discussion is provided in the node `POSIX Floating Point Problems' in gawk.texi. -3. String comparison with <, <= etc is supposed to take the local collating - sequence into account. Gawk currently doesn't. This is exacerbated - by the fact that the standard routines all want zero-terminated - strings to work on. +3. String comparison with <, <= etc is supposed to take the locale's collating + sequence into account. By default gawk doesn't do this. Rather, gawk + will do this only if --posix is in effect. - THIS SHOULD BE WORKED ON. +The following things aren't described by POSIX but ought to be: + +1. The value of $0 in an END rule + +2. The return value of a function that either does return with no value + or that falls off the end of the function body. + +3. What happens with substr() if start is <= 0, or greater than the length + of the string, or if length is <= 0. @@ -6,7 +6,8 @@ Paolo's code for checking for single char values in str2wstr(). #Fix os_close_on_exec to do read/modify/write of the fd flags. -Consider forcing [a-z] int abc...wxyz in regexes, no matter what the locale. +#Consider forcing [a-z] int abc...wxyz in regexes, no matter what the locale. +#Done by adding a warning. Add in gawk/mp @@ -28,14 +29,15 @@ xgawk features (@load, -l, others) Add tests for pgawk Add tests for patches in emails Add doc fix in email -# Update debugger chapter with new features +#Update debugger chapter with new features Add debugger commands to reference card #Remove obsolete directories #Remove all obsolete README files #Update bootstrap.sh and README.CVS types of files Review all FIXME and TODO comments -# Check on strftime %e with porters. +#Document arrays of arrays in awkcard and gawk.1. +#Check on strftime %e with porters. Code Review: array.c diff --git a/awklib/eg/prog/indirectcall.awk b/awklib/eg/prog/indirectcall.awk index 56843d5d..3ecb2887 100644 --- a/awklib/eg/prog/indirectcall.awk +++ b/awklib/eg/prog/indirectcall.awk @@ -11,7 +11,8 @@ function num_ge(left, right) { return ((left + 0) >= (right + 0)) } -# do_sort --- sort the data according to `compare' and return it as a string +# do_sort --- sort the data according to `compare' +# and return it as a string function do_sort(first, last, compare, data, i, retval) { diff --git a/doc/ChangeLog b/doc/ChangeLog index 871c9400..98414248 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +Wed Dec 1 21:39:15 2010 Arnold D. Robbins <arnold@skeeve.com> + + * awkcard.in, gawk.1: Document arrays of arrays. + * gawk.texi: General progress. + Mon Nov 8 22:24:21 2010 Arnold D. Robbins <arnold@skeeve.com> * gawk.1: Minor fix from Jari Aalto <jari.aalto@cante.net> diff --git a/doc/awkcard.in b/doc/awkcard.in index 9ff33a5d..af4c5955 100644 --- a/doc/awkcard.in +++ b/doc/awkcard.in @@ -686,7 +686,14 @@ Use the \*(FCdelete\fP statement to delete an element from an array. \*(CLSpecifying just the array name without a subscript in the \*(FCdelete\fP -statement deletes the entire contents of an array.\*(CX +statement deletes the entire contents of an array. +.sp .5 +\*(CB\*(GK provides true multidimensional arrays. +Such arrays need not be ``rectangular'' as in C or C++. For example: +.sp .5 +.nf + \*(FCa[1] = 5; a[2][1] = 6; a[2][2] = 7\*(FR\*(CX +.fi .EB "\s+2\f(HBARRAYS\*(FR\s0" .\" --- Expressions @@ -1168,6 +1168,20 @@ The .B delete statement may also be used to delete the entire contents of an array, just by specifying the array name without a subscript. +.PP +.I gawk +supports true multidimensional arrays. It does not require that +such arrays be ``rectangular'' as in C or C++. +For example: +.RS +.ft B +.nf +a[1] = 5 +a[2][1] = 6 +a[2][2] = 7 +.fi +.ft +.RE .SS Variable Typing And Conversion .PP Variables and fields diff --git a/doc/gawk.info b/doc/gawk.info index 4c2d6639..6dd1e2cc 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -9876,6 +9876,75 @@ with a pound sign (`#'): Sorting::. `asorti()' is a `gawk' extension; it is not available in compatibility mode (*note Options::). +`gensub(REGEXP, REPLACEMENT, HOW [, TARGET]) #' + Search the target string TARGET for matches of the regular + expression REGEXP. If HOW is a string beginning with `g' or `G', + then replace all matches of REGEXP with REPLACEMENT. Otherwise, + HOW is treated as a number indicating which match of REGEXP to + replace. If no TARGET is supplied, use `$0'. It returns the + modified string is returned as the result of the function and the + original target string is _not_ changed. + + `gensub()' is a general substitution function. It's purpose is to + provide more features than the standard `sub()' and `gsub()' + functions. + + `gensub()' provides an additional feature that is not available in + `sub()' or `gsub()': the ability to specify components of a regexp + in the replacement text. This is done by using parentheses in the + regexp to mark the components and then specifying `\N' in the + replacement text, where N is a digit from 1 to 9. For example: + + $ gawk ' + > BEGIN { + > a = "abc def" + > b = gensub(/(.+) (.+)/, "\\2 \\1", "g", a) + > print b + > }' + -| def abc + + As with `sub()', you must type two backslashes in order to get one + into the string. In the replacement text, the sequence `\0' + represents the entire matched text, as does the character `&'. + + The following example shows how you can use the third argument to + control which match of the regexp should be changed: + + $ echo a b c a b c | + > gawk '{ print gensub(/a/, "AA", 2) }' + -| a b c AA b c + + In this case, `$0' is used as the default target string. + `gensub()' returns the new string as its result, which is passed + directly to `print' for printing. + + If the HOW argument is a string that does not begin with `g' or + `G', or if it is a number that is less than or equal to zero, only + one substitution is performed. If HOW is zero, `gawk' issues a + warning message. + + If REGEXP does not match TARGET, `gensub()''s return value is the + original unchanged value of TARGET. + + `gensub()' is a `gawk' extension; it is not available in + compatibility mode (*note Options::). + +`gsub(REGEXP, REPLACEMENT [, TARGET])' + Search TARGET for _all_ of the longest, leftmost, _nonoverlapping_ + matching substrings it can find and replace them with REPLACEMENT. + The `g' in `gsub()' stands for "global," which means replace + everywhere. For example: + + { 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 search and alter (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 assignable. + `index(IN, FIND)' Search the string IN for the first occurrence of the string FIND, and return the position in characters where that occurrence begins @@ -10036,19 +10105,19 @@ with a pound sign (`#'): mode (*note Options::), it is not available. `split(STRING, ARRAY [, FIELDSEP [, SEPS ] ])' - This function divides STRING into pieces separated by FIELDSEP and - stores the pieces in ARRAY and the separator strings in the SEPS - 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 FIELDSEP is omitted, the value of `FS' is used. - `split()' returns the number of elements created. SEPS is a - `gawk' extension with `SEPS[I]' being the separator string between - `ARRAY[I]' and `ARRAY[I+1]'. If FIELDSEP is a single space then - any leading whitespace goes into `SEPS[0]' and any trailing - whitespace goes into `SEPS[N]' where N is the return value of - `split()' (that is, the number of elements in ARRAY). + Divide STRING into pieces separated by FIELDSEP and store the + pieces in ARRAY and the separator strings in the SEPS 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 + FIELDSEP is omitted, the value of `FS' is used. `split()' returns + the number of elements created. SEPS is a `gawk' extension with + `SEPS[I]' being the separator string between `ARRAY[I]' and + `ARRAY[I+1]'. If FIELDSEP is a single space then any leading + whitespace goes into `SEPS[0]' and any trailing whitespace goes + into `SEPS[N]' where N is the return value of `split()' (that is, + the number of elements in ARRAY). The `split()' function splits strings into pieces in a manner similar to the way input lines are split into fields. For example: @@ -10100,16 +10169,15 @@ with a pound sign (`#'): STRING. `sprintf(FORMAT, EXPRESSION1, ...)' - This returns (without printing) the string that `printf' would - have printed out with the same arguments (*note Printf::). For - example: + Return (without printing) the string that `printf' would have + printed out with the same arguments (*note Printf::). For example: pival = sprintf("pi = %.2f (approx.)", 22/7) assigns the string `"pi = 3.14 (approx.)"' to the variable `pival'. `strtonum(STR) #' - Examines STR and returns its numeric value. If STR begins with a + Examine STR and return its numeric value. If STR begins with a leading `0', `strtonum()' assumes that STR is an octal number. If STR begins with a leading `0x' or `0X', `strtonum()' assumes that STR is a hexadecimal number. For example: @@ -10129,11 +10197,11 @@ with a pound sign (`#'): compatibility mode (*note Options::). `sub(REGEXP, REPLACEMENT [, TARGET])' - The `sub()' function alters the value of TARGET. It searches this - value, which is treated as a string, for the leftmost, longest - substring matched by the regular expression REGEXP. Then the - entire string is changed by replacing the matched text with - REPLACEMENT. The modified string becomes the new value of TARGET. + It searches TARGET, which is treated as a string, for the + leftmost, longest substring matched by the regular expression + REGEXP. Modify the entire string by replacing the matched text + with REPLACEMENT. The modified string becomes the new value of + TARGET. The REGEXP argument may be either a regexp constant (`/.../') or a string constant (`"..."'). In the latter case, the string is @@ -10187,7 +10255,7 @@ with a pound sign (`#'): { sub(/\|/, "\\&"); print } As mentioned, the third argument to `sub()' must be a variable, - field or array reference. Some versions of `awk' allow the third + field or array element. Some versions of `awk' allow the third argument to be an expression that is not an lvalue. In such a case, `sub()' still searches for the pattern and returns zero or one, but the result of the substitution (if any) is thrown away @@ -10204,80 +10272,13 @@ with a pound sign (`#'): into a string, and then the value of that string is treated as the regexp to match. -`gsub(REGEXP, REPLACEMENT [, TARGET])' - This is similar to the `sub()' function, except that `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: - - { 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 search and alter (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 assignable. - -`gensub(REGEXP, REPLACEMENT, HOW [, TARGET]) #' - `gensub()' is a general substitution function. Like `sub()' and - `gsub()', it searches the target string TARGET for matches of the - regular expression REGEXP. Unlike `sub()' and `gsub()', the - modified string is returned as the result of the function and the - original target string is _not_ changed. If HOW is a string - beginning with `g' or `G', then it replaces all matches of REGEXP - with REPLACEMENT. Otherwise, HOW is treated as a number that - indicates which match of REGEXP to replace. If no TARGET is - supplied, `$0' is used. - - `gensub()' provides an additional feature that is not available in - `sub()' or `gsub()': the ability to specify components of a regexp - in the replacement text. This is done by using parentheses in the - regexp to mark the components and then specifying `\N' in the - replacement text, where N is a digit from 1 to 9. For example: - - $ gawk ' - > BEGIN { - > a = "abc def" - > b = gensub(/(.+) (.+)/, "\\2 \\1", "g", a) - > print b - > }' - -| def abc - - As with `sub()', you must type two backslashes in order to get one - into the string. In the replacement text, the sequence `\0' - represents the entire matched text, as does the character `&'. - - The following example shows how you can use the third argument to - control which match of the regexp should be changed: - - $ echo a b c a b c | - > gawk '{ print gensub(/a/, "AA", 2) }' - -| a b c AA b c - - In this case, `$0' is used as the default target string. - `gensub()' returns the new string as its result, which is passed - directly to `print' for printing. - - If the HOW argument is a string that does not begin with `g' or - `G', or if it is a number that is less than or equal to zero, only - one substitution is performed. If HOW is zero, `gawk' issues a - warning message. - - If REGEXP does not match TARGET, `gensub()''s return value is the - original unchanged value of TARGET. - - `gensub()' is a `gawk' extension; it is not available in - compatibility mode (*note Options::). - `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 + Return a LENGTH-character-long substring of STRING, starting at + character number START. The first character of a string is character number one.(3) For example, `substr("washington", 5, 3)' returns `"ing"'. - If LENGTH is not present, this function returns the whole suffix of + If LENGTH is not present, `substr()' returns the whole suffix of STRING that begins at character number START. For example, `substr("washington", 5)' returns `"ington"'. The whole suffix is also returned if LENGTH is greater than the number of characters @@ -10314,14 +10315,14 @@ with a pound sign (`#'): string = substr(string, 1, 2) "CDE" substr(string, 6) `tolower(STRING)' - This returns a copy of STRING, with each uppercase character in - the string replaced with its corresponding lowercase character. + Return a copy of STRING, with each uppercase character in the + string replaced with its corresponding lowercase 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 lowercase character in - the string replaced with its corresponding uppercase character. + Return a copy of STRING, with each lowercase character in the + string replaced with its corresponding uppercase character. Nonalphabetic characters are left unchanged. For example, `toupper("MiXeD cAsE 123")' returns `"MIXED CASE 123"'. @@ -10380,7 +10381,8 @@ is illustrated in *note table-sub-escapes::. `\\\\\\&' `\\\&' a literal `\\&' `\\q' `\q' a literal `\q' -Table 8.1: Historical Escape Sequence Processing for sub and gsub +Table 8.1: Historical Escape Sequence Processing for `sub()' and +`gsub()' This table shows both the lexical-level processing, where an odd number of backslashes becomes an even number at the runtime level, as well as @@ -10391,66 +10393,10 @@ backslashes entered at the lexical level.) The problem with the historical approach is that there is no way to get a literal `\' followed by the matched text. - The 1992 POSIX standard attempted to fix this problem. That standard -says that `sub()' and `gsub()' look for either a `\' or an `&' after -the `\'. If either one follows a `\', that character is output -literally. The interpretation of `\' and `&' then becomes as shown in -*note table-sub-posix-92::. - - You type `sub()' sees `sub()' generates - ------- --------- -------------- - `&' `&' the matched text - `\\&' `\&' a literal `&' - `\\\\&' `\\&' a literal `\', then the matched text - `\\\\\\&' `\\\&' a literal `\&' - -Table 8.2: 1992 POSIX Rules for sub and gsub Escape Sequence Processing - -This appears to solve the problem. Unfortunately, the phrasing of the -standard is unusual. It says, in effect, that `\' turns off the special -meaning of any following character, but for anything other than `\' and -`&', such special meaning is undefined. This wording leads to two -problems: - - * Backslashes must now be doubled in the REPLACEMENT string, breaking - historical `awk' programs. - - * To make sure that an `awk' program is portable, _every_ character - in the REPLACEMENT string must be preceded with a backslash.(1) - - Because of the problems just listed, in 1996, the `gawk' maintainer -submitted proposed text for a revised standard that reverts to rules -that correspond more closely to the original existing practice. The -proposed rules have special cases that make it possible to produce a -`\' preceding the matched text. This is shown in *note -table-sub-proposed::. - - You type `sub()' sees `sub()' generates - ------- --------- -------------- - `\\\\\\&' `\\\&' a literal `\&' - `\\\\&' `\\&' a literal `\', followed by the matched text - `\\&' `\&' a literal `&' - `\\q' `\q' a literal `\q' - `\\\\' `\\' `\\' - -Table 8.3: Proposed rules for sub and backslash - - In a nutshell, at the runtime level, there are now three special -sequences of characters (`\\\&', `\\&' and `\&') whereas historically -there was only one. However, as in the historical case, any `\' that -is not part of one of these three sequences is not special and appears -in the output literally. - - `gawk' 3.0 and 3.1 follow these proposed POSIX rules for `sub()' and -`gsub()'. The POSIX standard took much longer to be revised than was -expected in 1996. The 2001 standard does not follow the above rules. -Instead, the rules there are somewhat simpler. The results are similar -except for one case. - - The 2001 POSIX rules state that `\&' in the replacement string -produces a literal `&', `\\' produces a literal `\', and `\' followed -by anything else is not special; the `\' is placed straight into the -output. These rules are presented in *note table-posix-2001-sub::. + The POSIX rules state that `\&' in the replacement string produces a +literal `&', `\\' produces a literal `\', and `\' followed by anything +else is not special; the `\' is placed straight into the output. These +rules are presented in *note table-posix-sub::. You type `sub()' sees `sub()' generates ------- --------- -------------- @@ -10460,17 +10406,9 @@ output. These rules are presented in *note table-posix-2001-sub::. `\\q' `\q' a literal `\q' `\\\\' `\\' `\' -Table 8.4: POSIX 2001 rules for sub +Table 8.2: POSIX rules for `sub()' - The only case where the difference is noticeable is the last one: -`\\\\' is seen as `\\' and produces `\' instead of `\\'. - - Starting with version 3.1.4, `gawk' followed the POSIX rules when -`--posix' is specified (*note Options::). Otherwise, it continued to -follow the 1996 proposed rules, since that had been its behavior for -many seven years. - - As of version 4.0, `gawk' uses the POSIX 2001 rules. + `gawk' follows the POSIX rules. The rules for `gensub()' are considerably simpler. At the runtime level, whenever `gawk' sees a `\', if the following character is a @@ -10488,7 +10426,7 @@ the `\' does not, as shown in *note table-gensub-escapes::. `\\\\\\&' `\\\&' a literal `\&' `\\q' `\q' a literal `q' -Table 8.5: Escape Sequence Processing for gensub +Table 8.3: Escape Sequence Processing for `gensub()' Because of the complexity of the lexical and runtime level processing and the special cases for `sub()' and `gsub()', we recommend the use of @@ -10506,10 +10444,6 @@ functions. For example: Although this makes a certain amount of sense, it can be surprising. - ---------- Footnotes ---------- - - (1) This consequence was certainly unintended. - File: gawk.info, Node: I/O Functions, Next: Time Functions, Prev: String Functions, Up: Built-in @@ -10540,7 +10474,7 @@ parameters are enclosed in square brackets ([ ]): redirecting output to a pipe or coprocess. Many utility programs "buffer" their output; i.e., they save - information to write to a disk file or terminal in memory until + information to write to a disk file or the screen in memory until there is enough for it to be worthwhile to send the data to the output device. This is often more efficient than writing every little bit of information as soon as it is ready. However, @@ -10574,10 +10508,8 @@ parameters are enclosed in square brackets ([ ]): case, `fflush()' returns -1, as well. `system(COMMAND)' - Executes operating-system commands and then returns to the `awk' - program. The `system()' function executes the command given by - the string COMMAND. It returns the status returned by the command - that was executed as its value. + Execute the operating-system command COMMAND and then return to + the `awk' program. It returns COMMAND's exit status as its value. For example, if the following fragment of code is put in your `awk' program: @@ -10599,13 +10531,13 @@ parameters are enclosed in square brackets ([ ]): close("/bin/sh") However, if your `awk' program is interactive, `system()' is - useful for cranking up large self-contained programs, such as a - shell or an editor. Some operating systems cannot implement the + useful for running large self-contained programs, such as a shell + or an editor. Some operating systems cannot implement the `system()' function. `system()' causes a fatal error if it is not supported. NOTE: When `--sandbox' is specified, the `system()' function - is disabled. + is disabled (*note Options::). Advanced Notes: Interactive Versus Noninteractive Buffering @@ -10686,18 +10618,19 @@ would see the latter (undesirable) output. ---------- Footnotes ---------- (1) A program is interactive if the standard output is connected to -a terminal device. +a terminal device. On modern systems, this means your keyboard and +screen. File: gawk.info, Node: Time Functions, Next: Bitwise Functions, Prev: I/O Functions, Up: Built-in -8.1.5 Using `gawk''s Timestamp Functions ----------------------------------------- +8.1.5 Time Functions +-------------------- `awk' programs are commonly used to process log files containing timestamp information, indicating when a particular log record was written. Many programs log their timestamp in the form returned by the -`time' system call, which is the number of seconds since a particular +`time()' system call, which is the number of seconds since a particular epoch. On POSIX-compliant systems, it is the number of seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds.(1) All known POSIX-compliant systems support timestamps from 0 through 2^31 - 1, @@ -10711,17 +10644,11 @@ with timestamps. They are `gawk' extensions; they are not specified in the POSIX standard, nor are they in any other known version of `awk'.(2) Optional parameters are enclosed in square brackets ([ ]): -`systime()' - This function returns the current time as the number of seconds - since the system epoch. On POSIX systems, this is the number of - seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds. - It may be a different number on other systems. - `mktime(DATESPEC)' - This function turns DATESPEC into a timestamp in the same form as - is returned by `systime()'. It is similar to the function of the - same name in ISO C. The argument, DATESPEC, is a string of the - form `"YYYY MM DD HH MM SS [DST]"'. The string consists of six or + Turn DATESPEC into a timestamp in the same form as is returned by + `systime()'. It is similar to the function of the same name in + ISO C. The argument, DATESPEC, is a string of the form + `"YYYY MM DD HH MM SS [DST]"'. The string consists of six or seven numbers representing, respectively, the full year including century, the month from 1 to 12, the day of the month from 1 to 31, the hour of the day from 0 to 23, the minute from 0 to 59, the @@ -10741,19 +10668,24 @@ Optional parameters are enclosed in square brackets ([ ]): time is out of range, `mktime()' returns -1. `strftime([FORMAT [, TIMESTAMP [, UTC-FLAG]]])' - This function returns a string. It is similar to the function of - the same name in ISO C. The time specified by TIMESTAMP is used to - produce a string, based on the contents of the FORMAT string. If - UTC-FLAG is present and is either non-zero or non-null, the value - is formatted as UTC (Coordinated Universal Time, formerly GMT or - Greenwich Mean Time). Otherwise, the value is formatted for the - local time zone. The TIMESTAMP is in the same format as the value - returned by the `systime()' function. If no TIMESTAMP argument is - supplied, `gawk' uses the current time of day as the timestamp. - If no FORMAT argument is supplied, `strftime()' uses - `"%a %b %d %H:%M:%S %Z %Y"'. This format string produces output - that is (almost) equivalent to that of the `date' utility. - (Versions of `gawk' prior to 3.0 require the FORMAT argument.) + Format the time specified by TIMESTAMP based on the contents of + the FORMAT string and return the result. It is similar to the + function of the same name in ISO C. If UTC-FLAG is present and is + either non-zero or non-null, the value is formatted as UTC + (Coordinated Universal Time, formerly GMT or Greenwich Mean Time). + Otherwise, the value is formatted for the local time zone. The + TIMESTAMP is in the same format as the value returned by the + `systime()' function. If no TIMESTAMP argument is supplied, + `gawk' uses the current time of day as the timestamp. If no + FORMAT argument is supplied, `strftime()' uses + `"%a %b %e %H:%M:%S %Z %Y"'. This format string produces output + that is equivalent to that of the `date' utility. + +`systime()' + Return the current time as the number of seconds since the system + epoch. On POSIX systems, this is the number of seconds since + 1970-01-01 00:00:00 UTC, not counting leap seconds. It may be a + different number on other systems. The `systime()' function allows you to compare a timestamp from a log file with the current time of day. In particular, it is easy to @@ -10810,12 +10742,12 @@ the following date format specifications: format. `%g' - The year modulo 100 of the ISO week number, as a decimal number - (00-99). For example, January 1, 1993 is in week 53 of 1992. - Thus, the year of its ISO week number is 1992, even though its - year is 1993. Similarly, December 31, 1973 is in week 1 of 1974. - Thus, the year of its ISO week number is 1974, even though its - year is 1973. + The year modulo 100 of the ISO 8601 week number, as a decimal + number (00-99). For example, January 1, 1993 is in week 53 of + 1992. Thus, the year of its ISO 8601 week number is 1992, even + though its year is 1993. Similarly, December 31, 1973 is in week + 1 of 1974. Thus, the year of its ISO week number is 1974, even + though its year is 1973. `%G' The full year of the ISO week number, as a decimal number. @@ -10895,7 +10827,7 @@ the following date format specifications: The year modulo 100 as a decimal number (00-99). `%Y' - The full year as a decimal number (e.g., 1995). + The full year as a decimal number (e.g., 2011). `%z' The timezone offset in a +HHMM format (e.g., the format necessary @@ -10924,11 +10856,11 @@ in Europe, however, it is abbreviated "4.9.91." Thus, the `%x' specification in a `"US"' locale might produce `9/4/91', while in a `"EUROPE"' locale, it might produce `4.9.91'. The ISO C standard defines a default `"C"' locale, which is an environment that is typical -of what most C programmers are used to. +of what many C programmers are used to. For systems that are not yet fully standards-compliant, `gawk' supplies a copy of `strftime()' from the GNU C Library. It supports -all of the just listed format specifications. If that version is used +all of the just-listed format specifications. If that version is used to compile `gawk' (*note Installation::), then the following additional format specifications are available: @@ -10947,15 +10879,15 @@ format specifications are available: Additionally, the alternate representations are recognized but their normal representations are used. - This example is an `awk' implementation of the POSIX `date' utility. -Normally, the `date' utility prints the current date and time of day in -a well-known format. However, if you provide an argument to it that -begins with a `+', `date' copies nonformat specifier characters to the -standard output and interprets the current time according to the format -specifiers in the string. For example: + The following example is an `awk' implementation of the POSIX `date' +utility. Normally, the `date' utility prints the current date and time +of day in a well-known format. However, if you provide an argument to +it that begins with a `+', `date' copies nonformat specifier characters +to the standard output and interprets the current time according to the +format specifiers in the string. For example: $ date '+Today is %A, %B %d, %Y.' - -| Today is Thursday, September 14, 2000. + -| Today is Wednesday, December 01, 2010. Here is the `gawk' version of the `date' utility. It has a shell "wrapper" to handle the `-u' option, which requires that `date' run as @@ -10997,8 +10929,8 @@ shell scripts. (3) Occasionally there are minutes in a year with a leap second, which is why the seconds can go up to 60. - (4) As this is a recent standard, not every system's `strftime()' -necessarily supports all of the conversions listed here. + (4) Unfortunately, not every system's `strftime()' necessarily +supports all of the conversions listed here. (5) If you don't understand any of this, don't worry about it; these facilities are meant to make it easier to "internationalize" programs. @@ -11013,8 +10945,8 @@ does not appear in the returned string or appears literally. File: gawk.info, Node: Bitwise Functions, Next: I18N Functions, Prev: Time Functions, Up: Built-in -8.1.6 Bit-Manipulation Functions of `gawk' ------------------------------------------- +8.1.6 Bit-Manipulation Functions +-------------------------------- I can explain it for you, but I can't understand it for you. Anonymous @@ -11033,7 +10965,7 @@ table-bitwise-ops::. 0 | 0 0 | 0 1 | 0 1 1 | 0 1 | 1 1 | 1 0 -Table 8.6: Bitwise Operations +Table 8.4: Bitwise Operations As you can see, the result of an AND operation is 1 only when _both_ bits are 1. The result of an OR operation is 1 if _either_ bit is 1. @@ -11049,15 +10981,23 @@ again with `10111001' and shift it left by three bits, you end up with `11001000'. `gawk' provides built-in functions that implement the bitwise operations just described. They are: -`and(V1, V2)' Returns the bitwise AND of the values provided by V1 - and V2. -`or(V1, V2)' Returns the bitwise OR of the values provided by V1 - and V2. -`xor(V1, V2)' Returns the bitwise XOR of the values provided by V1 - and V2. -`compl(VAL)' Returns the bitwise complement of VAL. -`lshift(VAL, COUNT)' Returns the value of VAL, shifted left by COUNT bits. -`rshift(VAL, COUNT)' Returns the value of VAL, shifted right by COUNT bits. +`and(V1, V2)' + Return the bitwise AND of the values provided by V1 and V2. + +`compl(VAL)' + Return the bitwise complement of VAL. + +`lshift(VAL, COUNT)' + Return the value of VAL, shifted left by COUNT bits. + +`or(V1, V2)' + Return the bitwise OR of the values provided by V1 and V2. + +`rshift(VAL, COUNT)' + Return the value of VAL, shifted right by COUNT bits. + +`xor(V1, V2)' + Return the bitwise XOR of the values provided by V1 and V2. For all of these functions, first the double-precision floating-point value is converted to the widest C unsigned integer @@ -11109,7 +11049,7 @@ This program produces the following output when run: -| lshift(0x99, 2) = 0x264 = 0000001001100100 -| rshift(0x99, 2) = 0x26 = 00100110 - The `bits2str' function turns a binary number into a string. The + The `bits2str()' function turns a binary number into a string. The number `1' represents a binary value where the rightmost bit is set to 1. Using this mask, the function repeatedly checks the rightmost bit. ANDing the mask with the value indicates whether the rightmost bit is 1 @@ -11135,8 +11075,8 @@ have the left side fill with 1's. Caveat emptor. File: gawk.info, Node: I18N Functions, Prev: Bitwise Functions, Up: Built-in -8.1.7 Using `gawk''s String-Translation Functions -------------------------------------------------- +8.1.7 String-Translation Functions +---------------------------------- `gawk' provides facilities for internationalizing `awk' programs. These include the functions described in the following list. The @@ -11144,30 +11084,30 @@ descriptions here are purposely brief. *Note Internationalization::, for the full story. Optional parameters are enclosed in square brackets ([ ]): -`dcgettext(STRING [, DOMAIN [, CATEGORY]])' - This function returns the translation of STRING in text domain - DOMAIN for locale category CATEGORY. The default value for DOMAIN - is the current value of `TEXTDOMAIN'. The default value for - CATEGORY is `"LC_MESSAGES"'. - -`dcngettext(STRING1, STRING2, NUMBER [, DOMAIN [, CATEGORY]])' - This function returns the plural form used for NUMBER of the - translation of STRING1 and STRING2 in text domain DOMAIN for - locale category CATEGORY. STRING1 is the English singular variant - of a message, and STRING2 the English plural variant of the same - message. The default value for DOMAIN is the current value of - `TEXTDOMAIN'. The default value for CATEGORY is `"LC_MESSAGES"'. - `bindtextdomain(DIRECTORY [, DOMAIN])' - This function allows you to specify the directory in which `gawk' - will look for message translation files, in case they will not or - cannot be placed in the "standard" locations (e.g., during - testing). It returns the directory in which DOMAIN is "bound." + Set the directory in which `gawk' will look for message + translation files, in case they will not or cannot be placed in + the "standard" locations (e.g., during testing). It returns the + directory in which DOMAIN is "bound." The default DOMAIN is the value of `TEXTDOMAIN'. If DIRECTORY is the null string (`""'), then `bindtextdomain()' returns the current binding for the given DOMAIN. +`dcgettext(STRING [, DOMAIN [, CATEGORY]])' + Return the translation of STRING in text domain DOMAIN for locale + category CATEGORY. The default value for DOMAIN is the current + value of `TEXTDOMAIN'. The default value for CATEGORY is + `"LC_MESSAGES"'. + +`dcngettext(STRING1, STRING2, NUMBER [, DOMAIN [, CATEGORY]])' + Return the plural form used for NUMBER of the translation of + STRING1 and STRING2 in text domain DOMAIN for locale category + CATEGORY. STRING1 is the English singular variant of a message, + and STRING2 the English plural variant of the same message. The + default value for DOMAIN is the current value of `TEXTDOMAIN'. + The default value for CATEGORY is `"LC_MESSAGES"'. + File: gawk.info, Node: User-defined, Next: Indirect Calls, Prev: Built-in, Up: Functions @@ -11201,10 +11141,9 @@ There is no need to put the definition of a function before all uses of the function. This is because `awk' reads the entire program before starting to execute any of it. - The definition of a function named NAME looks like this: *FIXME: -NEXT ED:* put [ ] around parameter list. + The definition of a function named NAME looks like this: - function NAME(PARAMETER-LIST) + function NAME([PARAMETER-LIST]) { BODY-OF-FUNCTION } @@ -11222,9 +11161,10 @@ call. The local variables are initialized to the empty string. A function cannot have two parameters with the same name, nor may it have a parameter with the same name as the function itself. - According to the POSIX standard, function parameters cannot have the -same name as one of the special built-in variables (*note Built-in -Variables::. Not all versions of `awk' enforce this restriction. + In addition, according to the POSIX standard, function parameters +cannot have the same name as one of the special built-in variables +(*note Built-in Variables::. Not all versions of `awk' enforce this +restriction. The BODY-OF-FUNCTION consists of `awk' statements. It is the most important part of the definition, because it says what the function @@ -11279,19 +11219,22 @@ of the variable `func' with the return value of the function `foo'. If the resulting string is non-null, the action is executed. This is probably not what is desired. (`awk' accepts this input as syntactically valid, because functions may be used before they are -defined in `awk' programs.) *FIXME: NEXT ED:* This won't actually run, -since foo() is undefined ... +defined in `awk' programs.(1)) To ensure that your `awk' programs are portable, always use the keyword `function' when defining a function. + ---------- Footnotes ---------- + + (1) This program won't actually run, since `foo()' is undefined. + File: gawk.info, Node: Function Example, Next: Function Caveats, Prev: Definition Syntax, Up: User-defined 8.2.2 Function Definition Examples ---------------------------------- -Here is an example of a user-defined function, called `myprint', that +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) @@ -11305,7 +11248,7 @@ To illustrate, here is an `awk' rule that uses our `myprint' function: This program prints, in our special format, all the third fields that contain a positive number in our input. Therefore, when given the -following: +following input: 1.2 3.4 5.6 7.8 9.10 11.12 -13.14 15.16 @@ -11352,10 +11295,10 @@ way: > gawk --source '{ print rev($0, length($0)) }' -f rev.awk -| !cinaP t'noD - The C `ctime' function takes a timestamp and returns it in a string, -formatted in a well-known fashion. The following example uses the -built-in `strftime()' function (*note Time Functions::) to create an -`awk' version of `ctime': + The C `ctime()' function takes a timestamp and returns it in a +string, formatted in a well-known fashion. The following example uses +the built-in `strftime()' function (*note Time Functions::) to create +an `awk' version of `ctime()': # ctime.awk # @@ -11382,9 +11325,9 @@ the function. A function call consists of the function name followed by the arguments in parentheses. `awk' expressions are what you write in the call for the arguments. Each time the call is executed, these -expressions are evaluated, and the values are the actual arguments. For -example, here is a call to `foo' with three arguments (the first being -a string concatenation): +expressions are evaluated, and the values become the actual arguments. +For example, here is a call to `foo()' with three arguments (the first +being a string concatenation): foo(x y, "lose", 4 * z) @@ -11404,11 +11347,11 @@ example, if you write the following code: foo = "bar" z = myfunc(foo) -then you should not think of the argument to `myfunc' as being "the +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. Thus, if `myfunc' -does this: +`"bar"'. If the function `myfunc()' alters the values of its local +variables, this has no effect on any other variables. Thus, if +`myfunc()' does this: function myfunc(str) { @@ -11418,15 +11361,15 @@ does this: } to change its first argument variable `str', it does _not_ change the -value of `foo' in the caller. The role of `foo' in calling `myfunc' +value of `foo' in the caller. The role of `foo' in calling `myfunc()' ended when its value (`"bar"') was computed. If `str' also exists -outside of `myfunc', the function body cannot alter this outer value, -because it is shadowed during the execution of `myfunc' and cannot be +outside of `myfunc()', the function body cannot alter this outer value, +because it 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 "call by +manipulation by the function. This is usually termed "call by reference". Changes made to an array parameter inside the body of a function _are_ visible outside that function. @@ -11462,7 +11405,7 @@ actually tries to call the function. For example: # note that `foo' is not defined Because the `if' statement will never be true, it is not really a -problem that `foo' has not been defined. Usually, though, it is a +problem that `foo()' has not been defined. Usually, though, it is a problem if a program calls an undefined function. If `--lint' is specified (*note Options::), `gawk' reports calls to @@ -11485,19 +11428,24 @@ the `awk' program. It looks like this: return [EXPRESSION] - The EXPRESSION part is optional. If it is omitted, then the returned -value is undefined, and therefore, unpredictable. + The EXPRESSION part is optional. Due most likely to an oversight, +POSIX does not define what the return value is if you omit the +EXPRESSION. Technically speaking, this make the returned value +undefined, and therefore, unpredictable. In practice, though, all +versions of `awk' simply return the null string, which acts like zero +if used in a numeric context. 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 body, then the function returns an unpredictable value. `awk' -does _not_ warn you if you use the return value of such a function. +function body, then technically, the function returns an unpredictable +value. In practice, it returns the empty string. `awk' does _not_ +warn you if you use the return value of such a function. Sometimes, you want to write a function for what it does, not for what it returns. Such a function corresponds to a `void' function in C -or to a `procedure' in Pascal. Thus, it may be appropriate to not -return any value; simply bear in mind that if you use the return value -of such a function, you do so at your own risk. +or to a `procedure' in Ada. Thus, it may be appropriate to not return +any value; simply bear in mind that you should not be using the return +value of such a function. The following is an example of a user-defined function that returns a value for the largest number among the elements of an array: @@ -11511,16 +11459,16 @@ a value for the largest number among the elements of an array: return ret } -You call `maxelt' with one argument, which is an array name. The local -variables `i' and `ret' are not intended to be arguments; while there -is nothing to stop you from passing more than one argument to `maxelt', -the results would be strange. The extra space before `i' in the -function parameter list indicates that `i' and `ret' are not supposed -to be arguments. You should follow this convention when defining -functions. +You call `maxelt()' with one argument, which is an array name. The +local variables `i' and `ret' are not intended to be arguments; while +there is nothing to stop you from passing more than one argument to +`maxelt()', the results would be strange. The extra space before `i' +in the function parameter list indicates that `i' and `ret' are not +supposed to be arguments. You should follow this convention when +defining functions. - The following program uses the `maxelt' function. It loads an -array, calls `maxelt', and then reports the maximum number in that + The following program uses the `maxelt()' function. It loads an +array, calls `maxelt()', and then reports the maximum number in that array: function maxelt(vec, i, ret) @@ -11550,7 +11498,7 @@ array: -6 467 998 1101 99385 11 0 225 -the program reports (predictably) that `99385' is the largest number in +the program reports (predictably) that 99,385 is the largest value in the array. @@ -11717,7 +11665,7 @@ to force it to be a string value.) may think at first. The C and C++ languages provide "function pointers," which are a mechanism for calling a function chosen at runtime. One of the most well-known uses of this ablity is the C -`qsort' function, which sorts an array using the well-known "quick +`qsort()' function, which sorts an array using the well-known "quick sort" algorithm (see the Wikipedia article (http://en.wikipedia.org/wiki/Quick_sort) for more information). To use this function, you supply a pointer to a comparison function. This @@ -11754,10 +11702,10 @@ mechanism allows you to sort arbitrary data in an arbitrary fashion. data[j] = temp } - The `quicksort' function receives the `data' array, the starting and -ending indices to sort (`left' and `right'), and the name of a function -that performs a "less than" comparison. It then implements the quick -sort algorithm. + The `quicksort()' function receives the `data' array, the starting +and ending indices to sort (`left' and `right'), and the name of a +function that performs a "less than" comparison. It then implements +the quick sort algorithm. To make use of the sorting function, we return to our previous example. The first thing to do is write some comparison functions: @@ -11776,7 +11724,7 @@ example. The first thing to do is write some comparison functions: return ((left + 0) >= (right + 0)) } - The `num_ge' function is needed to perform a descending sort; when + The `num_ge()' function is needed to perform a descending sort; when used to perform a "less than" test, it actually does the opposite (greater than or equal to), which yields data sorted in descending order. @@ -11786,7 +11734,8 @@ starting and ending field numbers and the comparison function. It builds an array with the data and calls `quicksort' appropriately, and then formats the results as a single string: - # do_sort --- sort the data according to `compare' and return it as a string + # do_sort --- sort the data according to `compare' + # and return it as a string function do_sort(first, last, compare, data, i, retval) { @@ -11805,7 +11754,7 @@ then formats the results as a single string: return retval } - Finally, the two sorting functions call `do_sort', passing in the + Finally, the two sorting functions call `do_sort()', passing in the names of the two comparison functions: # sort --- sort the data in ascending order and return it as a string @@ -11859,7 +11808,7 @@ indirectly. (Other than, perhaps, the mathematical functions, there is not a lot of reason to try to call the built-in functions indirectly.) `gawk' does its best to make indirect function calls efficient. For -example: +example, in the following case: for (i = 1; i <= n; i++) @the_func() @@ -24287,7 +24236,7 @@ Index * * (asterisk), * operator, as regexp operator: Regexp Operators. (line 86) * * (asterisk), * operator, null strings, matching: Gory Details. - (line 159) + (line 96) * * (asterisk), ** operator <1>: Options. (line 208) * * (asterisk), ** operator <2>: Precedence. (line 49) * * (asterisk), ** operator: Arithmetic Ops. (line 81) @@ -24343,7 +24292,7 @@ Index * --profile option: Profiling. (line 15) * --re-interval option: Options. (line 228) * --sandbox option: Options. (line 235) -* --sandbox option, disabling system function: I/O Functions. (line 88) +* --sandbox option, disabling system function: I/O Functions. (line 86) * --sandbox option, input redirection with getline: Getline. (line 19) * --sandbox option, output redirection with print, printf: Redirection. (line 6) @@ -24509,7 +24458,7 @@ Index * adding, features to gawk: Adding Code. (line 6) * adding, fields: Changing Fields. (line 53) * adding, functions to gawk: Dynamic Extensions. (line 10) -* advanced features, buffering: I/O Functions. (line 101) +* advanced features, buffering: I/O Functions. (line 99) * advanced features, close() function: Close Files And Pipes. (line 131) * advanced features, constants, values of: Nondecimal-numbers. @@ -24526,7 +24475,7 @@ Index (line 23) * advanced features, network connections, See Also networks, connections: Advanced Features. (line 6) -* advanced features, null strings, matching: Gory Details. (line 159) +* advanced features, null strings, matching: Gory Details. (line 96) * advanced features, operators, precedence: Increment Ops. (line 61) * advanced features, piping into sh: Redirection. (line 143) * advanced features, regexp constants: Assignment Ops. (line 148) @@ -24616,7 +24565,7 @@ Index * asterisk (*), * operator, as regexp operator: Regexp Operators. (line 86) * asterisk (*), * operator, null strings, matching: Gory Details. - (line 159) + (line 96) * asterisk (*), ** operator <1>: Options. (line 208) * asterisk (*), ** operator <2>: Precedence. (line 49) * asterisk (*), ** operator: Arithmetic Ops. (line 81) @@ -24772,12 +24721,12 @@ Index * binary input/output: User-modified. (line 10) * bindtextdomain() function (C library): Explaining gettext. (line 47) * bindtextdomain() function (gawk) <1>: Programmer i18n. (line 45) -* bindtextdomain() function (gawk): I18N Functions. (line 26) +* bindtextdomain() function (gawk): I18N Functions. (line 12) * bindtextdomain() function (gawk), portability and: I18N Portability. (line 33) * BINMODE variable <1>: PC Using. (line 40) * BINMODE variable: User-modified. (line 10) -* bits2str user-defined function: Bitwise Functions. (line 60) +* bits2str user-defined function: Bitwise Functions. (line 68) * bitwise, complement: Bitwise Functions. (line 25) * bitwise, operations: Bitwise Functions. (line 6) * bitwise, shift: Bitwise Functions. (line 32) @@ -24805,8 +24754,8 @@ Index * Buening, Andreas <2>: Contributors. (line 84) * Buening, Andreas: Acknowledgments. (line 59) * buffering, input/output <1>: Two-way I/O. (line 71) -* buffering, input/output: I/O Functions. (line 133) -* buffering, interactive vs. noninteractive: I/O Functions. (line 101) +* buffering, input/output: I/O Functions. (line 131) +* buffering, interactive vs. noninteractive: I/O Functions. (line 99) * buffers, flushing: I/O Functions. (line 29) * buffers, operators for: GNU Regexp Operators. (line 48) @@ -24831,7 +24780,7 @@ Index * caret (^), in character lists: Character Lists. (line 16) * case keyword: Switch Statement. (line 6) * case sensitivity, array indices and: Array Intro. (line 92) -* case sensitivity, converting case: String Functions. (line 493) +* case sensitivity, converting case: String Functions. (line 494) * case sensitivity, example programs: Library Functions. (line 43) * case sensitivity, gawk: Case-sensitivity. (line 26) * case sensitivity, regexps and <1>: User-modified. (line 82) @@ -24918,7 +24867,7 @@ Index * compatibility mode (gawk), specifying: Options. (line 75) * compiled programs <1>: Glossary. (line 155) * compiled programs: Basic High Level. (line 15) -* compl() function (gawk): Bitwise Functions. (line 43) +* compl() function (gawk): Bitwise Functions. (line 42) * complement, bitwise: Bitwise Functions. (line 25) * compound statements, control statements and: Statements. (line 10) * concatenating: Concatenation. (line 9) @@ -24936,12 +24885,12 @@ Index * constants, types of: Constants. (line 6) * continue statement: Continue Statement. (line 6) * control statements: Statements. (line 6) -* converting, case: String Functions. (line 493) -* converting, dates to timestamps: Time Functions. (line 72) +* converting, case: String Functions. (line 494) +* converting, dates to timestamps: Time Functions. (line 71) * converting, during subscripting: Numeric Array Subscripts. (line 31) * converting, numbers: Conversion. (line 6) -* converting, numbers, to strings: Bitwise Functions. (line 99) +* converting, numbers, to strings: Bitwise Functions. (line 107) * converting, strings to numbers: Conversion. (line 6) * CONVFMT variable <1>: User-modified. (line 28) * CONVFMT variable: Conversion. (line 29) @@ -24957,7 +24906,7 @@ Index * csh utility: Statements/Lines. (line 44) * csh utility, POSIXLY_CORRECT environment variable: Options. (line 300) * csh utility, |& operator, comparison with: Two-way I/O. (line 44) -* ctime user-defined function: Function Example. (line 72) +* ctime() user-defined function: Function Example. (line 72) * currency symbols, localization: Explaining gettext. (line 99) * custom.h file: Configuration Philosophy. (line 29) @@ -24993,7 +24942,7 @@ Index (line 20) * dark corner, input files: Records. (line 98) * dark corner, invoking awk: Command Line. (line 16) -* dark corner, length() function: String Functions. (line 84) +* dark corner, length() function: String Functions. (line 153) * dark corner, multiline records: Multiple Line. (line 35) * dark corner, NF variable, decrementing: Changing Fields. (line 107) * dark corner, OFMT variable: OFMT. (line 27) @@ -25003,7 +24952,7 @@ Index (line 148) * dark corner, regexp constants, as arguments to user-defined functions: Using Constant Regexps. (line 43) -* dark corner, split() function: String Functions. (line 261) +* dark corner, split() function: String Functions. (line 330) * dark corner, strings, storing: Records. (line 188) * dark corner, value of ARGV[0]: Auto-set. (line 35) * data, fixed-width: Constant Size. (line 9) @@ -25011,18 +24960,18 @@ Index * database, group, reading: Group Functions. (line 6) * database, users, reading: Passwd Functions. (line 6) * date utility, GNU: Time Functions. (line 17) -* date utility, POSIX: Time Functions. (line 259) -* dates, converting to timestamps: Time Functions. (line 72) +* date utility, POSIX: Time Functions. (line 258) +* dates, converting to timestamps: Time Functions. (line 71) * dates, information related to, localization: Explaining gettext. (line 111) * Davies, Stephen <1>: Contributors. (line 69) * Davies, Stephen: Acknowledgments. (line 59) * dcgettext() function (gawk) <1>: Programmer i18n. (line 19) -* dcgettext() function (gawk): I18N Functions. (line 12) +* dcgettext() function (gawk): I18N Functions. (line 22) * dcgettext() function (gawk), portability and: I18N Portability. (line 33) * dcngettext() function (gawk) <1>: Programmer i18n. (line 35) -* dcngettext() function (gawk): I18N Functions. (line 18) +* dcngettext() function (gawk): I18N Functions. (line 28) * dcngettext() function (gawk), portability and: I18N Portability. (line 33) * deadlocks: Two-way I/O. (line 71) @@ -25135,7 +25084,7 @@ Index * deleting elements in arrays: Delete. (line 6) * deleting entire arrays: Delete. (line 39) * dgawk: Debugger. (line 6) -* differences between gawk and awk: String Functions. (line 98) +* differences between gawk and awk: String Functions. (line 167) * differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV. (line 88) * differences in awk and gawk, ARGIND variable: Auto-set. (line 40) @@ -25175,7 +25124,7 @@ Index (line 34) * differences in awk and gawk, LINT variable: User-modified. (line 98) * differences in awk and gawk, match() function: String Functions. - (line 161) + (line 230) * differences in awk and gawk, next/nextfile statements: Nextfile Statement. (line 6) * differences in awk and gawk, print/printf statements: Format Modifiers. @@ -25191,11 +25140,11 @@ Index * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. - (line 249) + (line 318) * differences in awk and gawk, strings: Scalar Constants. (line 20) * differences in awk and gawk, strings, storing: Records. (line 184) * differences in awk and gawk, strtonum() function (gawk): String Functions. - (line 288) + (line 356) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. (line 153) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. @@ -25457,7 +25406,7 @@ Index (line 57) * format specifiers, printf statement: Control Letters. (line 6) * format specifiers, strftime() function (gawk): Time Functions. - (line 85) + (line 84) * format strings: Basic Printf. (line 15) * formats, numeric output: OFMT. (line 6) * formatting output: Printf. (line 6) @@ -25524,7 +25473,7 @@ Index * functions, library, rounding numbers: Round Function. (line 6) * functions, library, user database, reading: Passwd Functions. (line 6) -* functions, names of <1>: Definition Syntax. (line 21) +* functions, names of <1>: Definition Syntax. (line 20) * functions, names of: Arrays. (line 18) * functions, recursive: Definition Syntax. (line 73) * functions, return values, setting: Internals. (line 136) @@ -25613,7 +25562,7 @@ Index (line 63) * General Public License (GPL): Glossary. (line 295) * General Public License, See GPL: Manual History. (line 11) -* gensub() function (gawk) <1>: String Functions. (line 401) +* gensub() function (gawk) <1>: String Functions. (line 57) * gensub() function (gawk): Using Constant Regexps. (line 43) * gensub() function (gawk), escape processing: Gory Details. (line 6) @@ -25681,10 +25630,10 @@ Index * group database, reading: Group Functions. (line 6) * group file: Group Functions. (line 6) * groups, information about: Group Functions. (line 6) -* gsub() function <1>: String Functions. (line 385) +* gsub() function <1>: String Functions. (line 110) * gsub() function: Using Constant Regexps. (line 43) -* gsub() function, arguments of: String Functions. (line 366) +* gsub() function, arguments of: String Functions. (line 434) * gsub() function, escape processing: Gory Details. (line 6) * h debugger command (alias for help): Miscellaneous Dgawk Commands. (line 71) @@ -25735,7 +25684,7 @@ Index * in operator, arrays and: Reference to Elements. (line 37) * increment operators: Increment Ops. (line 6) -* index() function: String Functions. (line 57) +* index() function: String Functions. (line 126) * indexing arrays: Array Intro. (line 50) * indirect function calls: Indirect Calls. (line 6) * info debugger command: Dgawk Info. (line 12) @@ -25842,7 +25791,7 @@ Index (line 11) * left shift, bitwise: Bitwise Functions. (line 32) * leftmost longest match: Multiple Line. (line 26) -* length() function: String Functions. (line 68) +* length() function: String Functions. (line 137) * Lesser General Public License (LGPL): Glossary. (line 373) * LGPL (Lesser General Public License): Glossary. (line 373) * libraries of awk functions: Library Functions. (line 6) @@ -25926,13 +25875,13 @@ Index (line 6) * marked strings, extracting: String Extraction. (line 6) * Marx, Groucho: Increment Ops. (line 61) -* match() function: String Functions. (line 108) +* match() function: String Functions. (line 177) * match() function, RSTART/RLENGTH variables: String Functions. - (line 125) + (line 194) * matching, expressions, See comparison expressions: Typing and Comparison. (line 9) * matching, leftmost longest: Multiple Line. (line 26) -* matching, null strings: Gory Details. (line 159) +* matching, null strings: Gory Details. (line 96) * mawk program: Other Versions. (line 34) * McPhee, Patrick: Contributors. (line 92) * memory, releasing: Internals. (line 92) @@ -25944,7 +25893,7 @@ Index * message object files, specifying directory of: Explaining gettext. (line 51) * metacharacters, escape sequences for: Escape Sequences. (line 132) -* mktime() function (gawk): Time Functions. (line 30) +* mktime() function (gawk): Time Functions. (line 24) * modifiers, in format specifiers: Format Modifiers. (line 6) * monetary information, localization: Explaining gettext. (line 99) * msgfmt utility: I18N Example. (line 62) @@ -25953,10 +25902,10 @@ Index * names, arrays/variables <1>: Library Names. (line 6) * names, arrays/variables: Arrays. (line 18) * names, functions <1>: Library Names. (line 6) -* names, functions: Definition Syntax. (line 21) +* names, functions: Definition Syntax. (line 20) * namespace issues <1>: Library Names. (line 6) * namespace issues: Arrays. (line 18) -* namespace issues, functions: Definition Syntax. (line 21) +* namespace issues, functions: Definition Syntax. (line 20) * nargs internal variable: Internals. (line 46) * nawk utility: Names. (line 17) * negative zero: Unexpected Results. (line 28) @@ -26012,7 +25961,7 @@ Index * null strings, as array subscripts: Uninitialized Subscripts. (line 43) * null strings, converting numbers to strings: Conversion. (line 21) -* null strings, matching: Gory Details. (line 159) +* null strings, matching: Gory Details. (line 96) * null strings, quoting and: Quoting. (line 62) * number sign (#), #! (executable scripts): Executable Scripts. (line 6) @@ -26026,7 +25975,7 @@ Index * numbers, Cliff random: Cliff Random Function. (line 6) * numbers, converting: Conversion. (line 6) -* numbers, converting, to strings <1>: Bitwise Functions. (line 99) +* numbers, converting, to strings <1>: Bitwise Functions. (line 107) * numbers, converting, to strings: User-modified. (line 28) * numbers, floating-point: Basic Data Typing. (line 21) * numbers, floating-point, AWKNUM internal type: Internals. (line 19) @@ -26099,7 +26048,7 @@ Index * options, printing list of: Options. (line 136) * OR bitwise operation: Bitwise Functions. (line 6) * or Boolean-logic operator: Boolean Ops. (line 6) -* or() function (gawk): Bitwise Functions. (line 39) +* or() function (gawk): Bitwise Functions. (line 48) * ord user-defined function: Ordinal Functions. (line 16) * order of evaluation, concatenation: Concatenation. (line 42) * ORS variable <1>: User-modified. (line 129) @@ -26125,7 +26074,7 @@ Index * parentheses (): Regexp Operators. (line 78) * parentheses (), pgawk program: Profiling. (line 144) * password file: Passwd Functions. (line 16) -* patsplit() function: String Functions. (line 195) +* patsplit() function: String Functions. (line 264) * patterns: Patterns and Actions. (line 6) * patterns, comparison expressions as: Expression Patterns. (line 14) @@ -26178,11 +26127,11 @@ Index * portability, deleting array elements: Delete. (line 51) * portability, example programs: Library Functions. (line 31) * portability, fflush() function and: I/O Functions. (line 29) -* portability, functions, defining: Definition Syntax. (line 94) +* portability, functions, defining: Definition Syntax. (line 93) * portability, gawk: New Ports. (line 6) * portability, gettext library and: Explaining gettext. (line 10) * portability, internationalization and: I18N Portability. (line 6) -* portability, length() function: String Functions. (line 77) +* portability, length() function: String Functions. (line 146) * portability, new awk vs. old awk: Conversion. (line 54) * portability, next statement in user-defined functions: Function Caveats. (line 99) @@ -26190,7 +26139,7 @@ Index * portability, operators: Increment Ops. (line 61) * portability, operators, not in POSIX awk: Precedence. (line 98) * portability, POSIXLY_CORRECT environment variable: Options. (line 305) -* portability, substr() function: String Functions. (line 483) +* portability, substr() function: String Functions. (line 484) * portable object files <1>: Translator i18n. (line 6) * portable object files: Explaining gettext. (line 36) * portable object files, converting to message object files: I18N Example. @@ -26218,14 +26167,13 @@ Index (line 29) * POSIX awk, continue statement and: Continue Statement. (line 43) * POSIX awk, CONVFMT variable and: User-modified. (line 28) -* POSIX awk, date utility and: Time Functions. (line 259) +* POSIX awk, date utility and: Time Functions. (line 258) * POSIX awk, field separators and <1>: Field Splitting Summary. (line 41) * POSIX awk, field separators and: Fields. (line 6) * POSIX awk, FS variable and: User-modified. (line 66) * POSIX awk, function keyword in: Definition Syntax. (line 78) -* POSIX awk, functions and, gsub()/sub(): Gory Details. (line 53) -* POSIX awk, functions and, length(): String Functions. (line 77) +* POSIX awk, functions and, length(): String Functions. (line 146) * POSIX awk, GNU long options and: Options. (line 15) * POSIX awk, interval expressions in: Regexp Operators. (line 134) * POSIX awk, next/nextfile statements and: Next Statement. (line 45) @@ -26296,7 +26244,7 @@ Index * programming conventions, ARGC/ARGV variables: Auto-set. (line 31) * programming conventions, exit statement: Exit Statement. (line 36) * programming conventions, function parameters: Return Statement. - (line 39) + (line 44) * programming conventions, functions, calling: Calling Built-in. (line 10) * programming conventions, functions, writing: Definition Syntax. @@ -26429,7 +26377,7 @@ Index * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 71) * RLENGTH variable: Auto-set. (line 171) -* RLENGTH variable, match() function and: String Functions. (line 125) +* RLENGTH variable, match() function and: String Functions. (line 194) * Robbins, Arnold <1>: Future Extensions. (line 6) * Robbins, Arnold <2>: Bugs. (line 29) * Robbins, Arnold <3>: Contributors. (line 95) @@ -26453,9 +26401,9 @@ Index * RS variable <1>: User-modified. (line 134) * RS variable: Records. (line 20) * RS variable, multiline records and: Multiple Line. (line 17) -* rshift() function (gawk): Bitwise Functions. (line 46) +* rshift() function (gawk): Bitwise Functions. (line 51) * RSTART variable: Auto-set. (line 177) -* RSTART variable, match() function and: String Functions. (line 125) +* RSTART variable, match() function and: String Functions. (line 194) * RT variable <1>: Auto-set. (line 184) * RT variable <2>: Multiple Line. (line 129) * RT variable: Records. (line 112) @@ -26477,7 +26425,7 @@ Index * search paths, for source files <1>: VMS Running. (line 28) * search paths, for source files <2>: Igawk Program. (line 358) * search paths, for source files: AWKPATH Variable. (line 6) -* searching: String Functions. (line 57) +* searching: String Functions. (line 126) * searching, files for regular expressions: Egrep Program. (line 6) * searching, for words: Dupword Program. (line 6) * sed utility <1>: Glossary. (line 12) @@ -26557,10 +26505,10 @@ Index * sparse arrays: Array Intro. (line 71) * Spencer, Henry: Glossary. (line 12) * split utility: Split Program. (line 6) -* split() function: String Functions. (line 216) +* split() function: String Functions. (line 285) * split() function, array elements, deleting: Delete. (line 56) * split.awk program: Split Program. (line 30) -* sprintf() function <1>: String Functions. (line 280) +* sprintf() function <1>: String Functions. (line 349) * sprintf() function: OFMT. (line 15) * sprintf() function, OFMT variable and: User-modified. (line 124) * sprintf() function, print/printf statements and: Round Function. @@ -26588,7 +26536,7 @@ Index * stream editors <1>: Simple Sed. (line 6) * stream editors: Field Splitting Summary. (line 47) -* strftime() function (gawk): Time Functions. (line 53) +* strftime() function (gawk): Time Functions. (line 47) * string constants: Scalar Constants. (line 15) * string constants, vs. regexp constants: Computed Regexps. (line 38) * string extraction (internationalization): String Extraction. @@ -26597,7 +26545,7 @@ Index * string-matching operators: Regexp Usage. (line 19) * strings: Internals. (line 77) * strings, converting: Conversion. (line 6) -* strings, converting, numbers to <1>: Bitwise Functions. (line 99) +* strings, converting, numbers to <1>: Bitwise Functions. (line 107) * strings, converting, numbers to: User-modified. (line 28) * strings, empty, See null strings: Records. (line 102) * strings, extracting: String Extraction. (line 6) @@ -26608,14 +26556,14 @@ Index * strings, null: Regexp Field Splitting. (line 43) * strings, numeric: Variable Typing. (line 6) -* strings, splitting: String Functions. (line 235) -* strtonum() function (gawk): String Functions. (line 288) +* strings, splitting: String Functions. (line 304) +* strtonum() function (gawk): String Functions. (line 356) * strtonum() function (gawk), --non-decimal-data option and: Nondecimal Data. (line 36) -* sub() function <1>: String Functions. (line 309) +* sub() function <1>: String Functions. (line 377) * sub() function: Using Constant Regexps. (line 43) -* sub() function, arguments of: String Functions. (line 366) +* sub() function, arguments of: String Functions. (line 434) * sub() function, escape processing: Gory Details. (line 6) * subscript separators: User-modified. (line 147) * subscripts in arrays, multidimensional: Multi-dimensional. (line 10) @@ -26628,13 +26576,13 @@ Index * SUBSEP variable: User-modified. (line 147) * SUBSEP variable, multidimensional arrays: Multi-dimensional. (line 16) -* substr() function: String Functions. (line 452) +* substr() function: String Functions. (line 453) * Sumner, Andrew: Other Versions. (line 81) * switch statement: Switch Statement. (line 6) * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. (line 148) * system() function: I/O Functions. (line 64) -* systime() function (gawk): Time Functions. (line 24) +* systime() function (gawk): Time Functions. (line 61) * t debugger command (alias for tbreak): Breakpoint Control. (line 83) * tandem: Tandem Installation. (line 6) * tbreak debugger command: Breakpoint Control. (line 83) @@ -26644,7 +26592,7 @@ Index * tee utility: Tee Program. (line 6) * tee.awk program: Tee Program. (line 26) * terminating records: Records. (line 112) -* testbits.awk program: Bitwise Functions. (line 60) +* testbits.awk program: Bitwise Functions. (line 68) * Texinfo <1>: Adding Code. (line 99) * Texinfo <2>: Distribution contents. (line 68) @@ -26677,11 +26625,11 @@ Index (line 6) * time, retrieving: Time Functions. (line 17) * timestamps: Time Functions. (line 6) -* timestamps, converting dates to: Time Functions. (line 72) +* timestamps, converting dates to: Time Functions. (line 71) * timestamps, formatted: Gettimeofday Function. (line 6) -* tolower() function: String Functions. (line 494) -* toupper() function: String Functions. (line 500) +* tolower() function: String Functions. (line 495) +* toupper() function: String Functions. (line 501) * tr utility: Translate Program. (line 6) * trace debugger command: Miscellaneous Dgawk Commands. (line 113) @@ -26706,8 +26654,9 @@ Index * troubleshooting, gawk, fatal errors, function arguments: Calling Built-in. (line 16) * troubleshooting, getline function: File Checking. (line 24) -* troubleshooting, gsub()/sub() functions: String Functions. (line 376) -* troubleshooting, match() function: String Functions. (line 190) +* troubleshooting, gsub()/sub() functions: String Functions. (line 444) +* troubleshooting, match() function: String Functions. (line 259) +* troubleshooting, patsplit() function: String Functions. (line 281) * troubleshooting, print statement, omitting commas: Print Examples. (line 31) * troubleshooting, printing: Redirection. (line 118) @@ -26716,8 +26665,8 @@ Index * troubleshooting, regexp constants vs. string constants: Computed Regexps. (line 38) * troubleshooting, string concatenation: Concatenation. (line 27) -* troubleshooting, substr() function: String Functions. (line 470) -* troubleshooting, system() function: I/O Functions. (line 88) +* troubleshooting, substr() function: String Functions. (line 471) +* troubleshooting, system() function: I/O Functions. (line 86) * troubleshooting, typographical errors, global variables: Options. (line 92) * true, logical: Truth Values. (line 6) @@ -26844,7 +26793,7 @@ Index * xgettext utility: String Extraction. (line 13) * XML: Internals. (line 162) * XOR bitwise operation: Bitwise Functions. (line 6) -* xor() function (gawk): Bitwise Functions. (line 41) +* xor() function (gawk): Bitwise Functions. (line 54) * Zaretskii, Eli <1>: Bugs. (line 69) * Zaretskii, Eli: Acknowledgments. (line 59) * zero, negative vs. positive: Unexpected Results. (line 28) @@ -27071,211 +27020,209 @@ Ref: Numeric Functions-Footnote-1412135 Ref: Numeric Functions-Footnote-2412471 Ref: Numeric Functions-Footnote-3412519 Node: String Functions412788 -Ref: String Functions-Footnote-1434686 -Ref: String Functions-Footnote-2434815 -Ref: String Functions-Footnote-3435063 -Node: Gory Details435150 -Ref: table-sub-escapes436807 -Ref: table-sub-posix-92438153 -Ref: table-sub-proposed439496 -Ref: table-posix-2001-sub440856 -Ref: table-gensub-escapes442131 -Ref: Gory Details-Footnote-1443334 -Node: I/O Functions443385 -Ref: I/O Functions-Footnote-1450173 -Node: Time Functions450264 -Ref: Time Functions-Footnote-1461076 -Ref: Time Functions-Footnote-2461144 -Ref: Time Functions-Footnote-3461302 -Ref: Time Functions-Footnote-4461413 -Ref: Time Functions-Footnote-5461540 -Ref: Time Functions-Footnote-6461767 -Node: Bitwise Functions462033 -Ref: table-bitwise-ops462611 -Ref: Bitwise Functions-Footnote-1466851 -Node: I18N Functions467035 -Node: User-defined468758 -Node: Definition Syntax469562 -Node: Function Example474260 -Node: Function Caveats476842 -Node: Return Statement480767 -Node: Dynamic Typing483424 -Node: Indirect Calls484161 -Node: Internationalization493796 -Node: I18N and L10N495215 -Node: Explaining gettext495899 -Ref: Explaining gettext-Footnote-1500810 -Ref: Explaining gettext-Footnote-2501049 -Node: Programmer i18n501218 -Node: Translator i18n505453 -Node: String Extraction506244 -Ref: String Extraction-Footnote-1507201 -Node: Printf Ordering507327 -Ref: Printf Ordering-Footnote-1510107 -Node: I18N Portability510171 -Ref: I18N Portability-Footnote-1512616 -Node: I18N Example512679 -Ref: I18N Example-Footnote-1515299 -Node: Gawk I18N515371 -Node: Advanced Features515949 -Node: Nondecimal Data517264 -Node: Two-way I/O518825 -Ref: Two-way I/O-Footnote-1524308 -Node: TCP/IP Networking524385 -Node: Profiling527175 -Node: Invoking Gawk534636 -Node: Command Line535943 -Node: Options536728 -Ref: Options-Footnote-1549816 -Node: Other Arguments549841 -Node: AWKPATH Variable552522 -Ref: AWKPATH Variable-Footnote-1555297 -Node: Exit Status555557 -Node: Include Files556229 -Node: Obsolete559830 -Node: Undocumented560631 -Node: Known Bugs560893 -Node: Library Functions561495 -Ref: Library Functions-Footnote-1564476 -Node: Library Names564647 -Ref: Library Names-Footnote-1568120 -Ref: Library Names-Footnote-2568339 -Node: General Functions568425 -Node: Nextfile Function569488 -Node: Strtonum Function573852 -Node: Assert Function576793 -Node: Round Function580097 -Node: Cliff Random Function581637 -Node: Ordinal Functions582652 -Ref: Ordinal Functions-Footnote-1585712 -Node: Join Function585928 -Ref: Join Function-Footnote-1587690 -Node: Gettimeofday Function587890 -Node: Data File Management591601 -Node: Filetrans Function592233 -Node: Rewind Function595659 -Node: File Checking597105 -Node: Empty Files598135 -Node: Ignoring Assigns600360 -Node: Getopt Function601908 -Ref: Getopt Function-Footnote-1613190 -Node: Passwd Functions613393 -Ref: Passwd Functions-Footnote-1622371 -Node: Group Functions622459 -Node: Sample Programs630556 -Node: Running Examples631225 -Node: Clones631953 -Node: Cut Program633085 -Node: Egrep Program642844 -Ref: Egrep Program-Footnote-1650594 -Node: Id Program650704 -Node: Split Program654311 -Node: Tee Program657779 -Node: Uniq Program660522 -Node: Wc Program667889 -Ref: Wc Program-Footnote-1672133 -Node: Miscellaneous Programs672329 -Node: Dupword Program673449 -Node: Alarm Program675480 -Node: Translate Program680022 -Ref: Translate Program-Footnote-1684401 -Ref: Translate Program-Footnote-2684638 -Node: Labels Program684772 -Ref: Labels Program-Footnote-1688063 -Node: Word Sorting688147 -Node: History Sorting692494 -Node: Extract Program694332 -Node: Simple Sed701690 -Node: Igawk Program704747 -Ref: Igawk Program-Footnote-1719478 -Ref: Igawk Program-Footnote-2719679 -Node: Signature Program719817 -Node: Debugger720897 -Node: Debugging721773 -Node: Debugging Concepts722087 -Node: Debugging Terms723940 -Node: Awk Debugging726488 -Node: Sample dgawk session727380 -Node: dgawk invocation727872 -Node: Finding The Bug729056 -Node: List of Debugger Commands735571 -Node: Breakpoint Control736886 -Node: Dgawk Execution Control740096 -Node: Viewing And Changing Data743445 -Node: Dgawk Stack746741 -Node: Dgawk Info748202 -Node: Miscellaneous Dgawk Commands752140 -Node: Readline Support757856 -Node: Dgawk Limitations758672 -Node: Language History760844 -Node: V7/SVR3.1762221 -Node: SVR4764516 -Node: POSIX765961 -Node: BTL767673 -Node: POSIX/GNU769363 -Node: Contributors779027 -Node: Installation782632 -Node: Gawk Distribution783603 -Node: Getting784087 -Node: Extracting784913 -Node: Distribution contents786301 -Node: Unix Installation791374 -Node: Quick Installation791965 -Node: Additional Configuration Options793667 -Node: Configuration Philosophy795430 -Node: Non-Unix Installation797794 -Node: PC Installation798259 -Node: PC Binary Installation799565 -Node: PC Compiling801408 -Node: PC Dynamic805913 -Node: PC Using808276 -Node: Cygwin812824 -Node: MSYS813808 -Node: VMS Installation814314 -Node: VMS Compilation814918 -Node: VMS Installation Details816495 -Node: VMS Running818125 -Node: VMS POSIX819722 -Node: VMS Old Gawk821020 -Node: Unsupported821489 -Node: Atari Installation821951 -Node: Atari Compiling823238 -Node: Atari Using825127 -Node: BeOS Installation827974 -Node: Tandem Installation829119 -Node: Bugs830798 -Node: Other Versions834630 -Node: Notes839852 -Node: Compatibility Mode840544 -Node: Additions841327 -Node: Adding Code842077 -Node: New Ports848129 -Node: Dynamic Extensions852261 -Node: Internals853642 -Node: Plugin License864047 -Node: Sample Library864681 -Node: Internal File Description865345 -Node: Internal File Ops869040 -Ref: Internal File Ops-Footnote-1873916 -Node: Using Internal File Ops874064 -Node: Future Extensions876089 -Node: Basic Concepts880126 -Node: Basic High Level880883 -Ref: Basic High Level-Footnote-1884999 -Node: Basic Data Typing885193 -Node: Floating Point Issues889630 -Node: String Conversion Precision890713 -Ref: String Conversion Precision-Footnote-1892407 -Node: Unexpected Results892516 -Node: POSIX Floating Point Problems894342 -Ref: POSIX Floating Point Problems-Footnote-1898041 -Node: Glossary898079 -Node: Copying921847 -Node: GNU Free Documentation License959404 -Node: next-edition984548 -Node: unresolved984900 -Node: revision985400 -Node: consistency985823 -Node: Index989176 +Ref: String Functions-Footnote-1434587 +Ref: String Functions-Footnote-2434716 +Ref: String Functions-Footnote-3434964 +Node: Gory Details435051 +Ref: table-sub-escapes436708 +Ref: table-posix-sub438022 +Ref: table-gensub-escapes438922 +Node: I/O Functions440093 +Ref: I/O Functions-Footnote-1446790 +Node: Time Functions446937 +Ref: Time Functions-Footnote-1457593 +Ref: Time Functions-Footnote-2457661 +Ref: Time Functions-Footnote-3457819 +Ref: Time Functions-Footnote-4457930 +Ref: Time Functions-Footnote-5458042 +Ref: Time Functions-Footnote-6458269 +Node: Bitwise Functions458535 +Ref: table-bitwise-ops459093 +Ref: Bitwise Functions-Footnote-1463253 +Node: I18N Functions463437 +Node: User-defined465067 +Node: Definition Syntax465871 +Ref: Definition Syntax-Footnote-1470501 +Node: Function Example470570 +Node: Function Caveats473164 +Node: Return Statement477107 +Node: Dynamic Typing480049 +Node: Indirect Calls480786 +Node: Internationalization490471 +Node: I18N and L10N491890 +Node: Explaining gettext492574 +Ref: Explaining gettext-Footnote-1497485 +Ref: Explaining gettext-Footnote-2497724 +Node: Programmer i18n497893 +Node: Translator i18n502128 +Node: String Extraction502919 +Ref: String Extraction-Footnote-1503876 +Node: Printf Ordering504002 +Ref: Printf Ordering-Footnote-1506782 +Node: I18N Portability506846 +Ref: I18N Portability-Footnote-1509291 +Node: I18N Example509354 +Ref: I18N Example-Footnote-1511974 +Node: Gawk I18N512046 +Node: Advanced Features512624 +Node: Nondecimal Data513939 +Node: Two-way I/O515500 +Ref: Two-way I/O-Footnote-1520983 +Node: TCP/IP Networking521060 +Node: Profiling523850 +Node: Invoking Gawk531311 +Node: Command Line532618 +Node: Options533403 +Ref: Options-Footnote-1546491 +Node: Other Arguments546516 +Node: AWKPATH Variable549197 +Ref: AWKPATH Variable-Footnote-1551972 +Node: Exit Status552232 +Node: Include Files552904 +Node: Obsolete556505 +Node: Undocumented557306 +Node: Known Bugs557568 +Node: Library Functions558170 +Ref: Library Functions-Footnote-1561151 +Node: Library Names561322 +Ref: Library Names-Footnote-1564795 +Ref: Library Names-Footnote-2565014 +Node: General Functions565100 +Node: Nextfile Function566163 +Node: Strtonum Function570527 +Node: Assert Function573468 +Node: Round Function576772 +Node: Cliff Random Function578312 +Node: Ordinal Functions579327 +Ref: Ordinal Functions-Footnote-1582387 +Node: Join Function582603 +Ref: Join Function-Footnote-1584365 +Node: Gettimeofday Function584565 +Node: Data File Management588276 +Node: Filetrans Function588908 +Node: Rewind Function592334 +Node: File Checking593780 +Node: Empty Files594810 +Node: Ignoring Assigns597035 +Node: Getopt Function598583 +Ref: Getopt Function-Footnote-1609865 +Node: Passwd Functions610068 +Ref: Passwd Functions-Footnote-1619046 +Node: Group Functions619134 +Node: Sample Programs627231 +Node: Running Examples627900 +Node: Clones628628 +Node: Cut Program629760 +Node: Egrep Program639519 +Ref: Egrep Program-Footnote-1647269 +Node: Id Program647379 +Node: Split Program650986 +Node: Tee Program654454 +Node: Uniq Program657197 +Node: Wc Program664564 +Ref: Wc Program-Footnote-1668808 +Node: Miscellaneous Programs669004 +Node: Dupword Program670124 +Node: Alarm Program672155 +Node: Translate Program676697 +Ref: Translate Program-Footnote-1681076 +Ref: Translate Program-Footnote-2681313 +Node: Labels Program681447 +Ref: Labels Program-Footnote-1684738 +Node: Word Sorting684822 +Node: History Sorting689169 +Node: Extract Program691007 +Node: Simple Sed698365 +Node: Igawk Program701422 +Ref: Igawk Program-Footnote-1716153 +Ref: Igawk Program-Footnote-2716354 +Node: Signature Program716492 +Node: Debugger717572 +Node: Debugging718448 +Node: Debugging Concepts718762 +Node: Debugging Terms720615 +Node: Awk Debugging723163 +Node: Sample dgawk session724055 +Node: dgawk invocation724547 +Node: Finding The Bug725731 +Node: List of Debugger Commands732246 +Node: Breakpoint Control733561 +Node: Dgawk Execution Control736771 +Node: Viewing And Changing Data740120 +Node: Dgawk Stack743416 +Node: Dgawk Info744877 +Node: Miscellaneous Dgawk Commands748815 +Node: Readline Support754531 +Node: Dgawk Limitations755347 +Node: Language History757519 +Node: V7/SVR3.1758896 +Node: SVR4761191 +Node: POSIX762636 +Node: BTL764348 +Node: POSIX/GNU766038 +Node: Contributors775702 +Node: Installation779307 +Node: Gawk Distribution780278 +Node: Getting780762 +Node: Extracting781588 +Node: Distribution contents782976 +Node: Unix Installation788049 +Node: Quick Installation788640 +Node: Additional Configuration Options790342 +Node: Configuration Philosophy792105 +Node: Non-Unix Installation794469 +Node: PC Installation794934 +Node: PC Binary Installation796240 +Node: PC Compiling798083 +Node: PC Dynamic802588 +Node: PC Using804951 +Node: Cygwin809499 +Node: MSYS810483 +Node: VMS Installation810989 +Node: VMS Compilation811593 +Node: VMS Installation Details813170 +Node: VMS Running814800 +Node: VMS POSIX816397 +Node: VMS Old Gawk817695 +Node: Unsupported818164 +Node: Atari Installation818626 +Node: Atari Compiling819913 +Node: Atari Using821802 +Node: BeOS Installation824649 +Node: Tandem Installation825794 +Node: Bugs827473 +Node: Other Versions831305 +Node: Notes836527 +Node: Compatibility Mode837219 +Node: Additions838002 +Node: Adding Code838752 +Node: New Ports844804 +Node: Dynamic Extensions848936 +Node: Internals850317 +Node: Plugin License860722 +Node: Sample Library861356 +Node: Internal File Description862020 +Node: Internal File Ops865715 +Ref: Internal File Ops-Footnote-1870591 +Node: Using Internal File Ops870739 +Node: Future Extensions872764 +Node: Basic Concepts876801 +Node: Basic High Level877558 +Ref: Basic High Level-Footnote-1881674 +Node: Basic Data Typing881868 +Node: Floating Point Issues886305 +Node: String Conversion Precision887388 +Ref: String Conversion Precision-Footnote-1889082 +Node: Unexpected Results889191 +Node: POSIX Floating Point Problems891017 +Ref: POSIX Floating Point Problems-Footnote-1894716 +Node: Glossary894754 +Node: Copying918522 +Node: GNU Free Documentation License956079 +Node: next-edition981223 +Node: unresolved981575 +Node: revision982075 +Node: consistency982498 +Node: Index985851 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 9318f312..f669ab12 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -2,6 +2,7 @@ @ignore TODO: Globally add () after built in and awk function names. + Go through CAUTION, NOTE, @strong, @quotation, etc. DONE: @end ignore @c %**start of header (This is for running Texinfo on a region.) @@ -13078,10 +13079,9 @@ sequences of random numbers. @subsection String-Manipulation Functions The functions in this @value{SECTION} look at or change the text of one or more -strings. -Optional parameters are enclosed in square brackets@w{ ([ ]).} -Those functions that are -specific to @command{gawk} are marked with a pound sign@w{ (@samp{#}):} +strings. Optional parameters are enclosed in square brackets@w{ ([ ]).} +Those functions that are specific to @command{gawk} are marked with a +pound sign@w{ (@samp{#}):} @menu * Gory Details:: More than you want to know about @samp{\} and @@ -13097,8 +13097,7 @@ Return the number of elements in the array @var{source}. @command{gawk} sorts the contents of @var{source} using the normal rules for comparing values (in particular, @code{IGNORECASE} affects the sorting) -and replaces -the indices +and replaces the indices of the sorted values of @var{source} with sequential integers starting with one. If the optional array @var{dest} is specified, then @var{source} is duplicated into @var{dest}. @var{dest} is then @@ -13145,6 +13144,91 @@ The @code{asorti()} function is described in more detail in @code{asorti()} is a @command{gawk} extension; it is not available in compatibility mode (@pxref{Options}). +@item gensub(@var{regexp}, @var{replacement}, @var{how} @r{[}, @var{target}@r{]}) # +@cindex @code{gensub()} function (@command{gawk}) +Search the target string @var{target} for matches of the regular +expression @var{regexp}. If @var{how} is a string beginning with +@samp{g} or @samp{G}, then replace all matches of @var{regexp} with +@var{replacement}. Otherwise, @var{how} is treated as a number indicating +which match of @var{regexp} to replace. If no @var{target} is supplied, +use @code{$0}. It returns the modified string is returned as the result +of the function and the original target string is @emph{not} changed. + +@code{gensub()} is a general substitution function. It's purpose is +to provide more features than the standard @code{sub()} and @code{gsub()} +functions. + +@code{gensub()} provides an additional feature that is not available +in @code{sub()} or @code{gsub()}: the ability to specify components of a +regexp in the replacement text. This is done by using parentheses in +the regexp to mark the components and then specifying @samp{\@var{N}} +in the replacement text, where @var{N} is a digit from 1 to 9. +For example: + +@example +$ @kbd{gawk '} +> @kbd{BEGIN @{} +> @kbd{a = "abc def"} +> @kbd{b = gensub(/(.+) (.+)/, "\\2 \\1", "g", a)} +> @kbd{print b} +> @kbd{@}'} +@print{} def abc +@end example + +@noindent +As with @code{sub()}, you must type two backslashes in order +to get one into the string. +In the replacement text, the sequence @samp{\0} represents the entire +matched text, as does the character @samp{&}. + +The following example shows how you can use the third argument to control +which match of the regexp should be changed: + +@example +$ @kbd{echo a b c a b c |} +> @kbd{gawk '@{ print gensub(/a/, "AA", 2) @}'} +@print{} a b c AA b c +@end example + +In this case, @code{$0} is used as the default target string. +@code{gensub()} returns the new string as its result, which is +passed directly to @code{print} for printing. + +@c @cindex automatic warnings +@c @cindex warnings, automatic +If the @var{how} argument is a string that does not begin with @samp{g} or +@samp{G}, or if it is a number that is less than or equal to zero, only one +substitution is performed. If @var{how} is zero, @command{gawk} issues +a warning message. + +If @var{regexp} does not match @var{target}, @code{gensub()}'s return value +is the original unchanged value of @var{target}. + +@code{gensub()} is a @command{gawk} extension; it is not available +in compatibility mode (@pxref{Options}). + +@item gsub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]}) +@cindex @code{gsub()} function +Search @var{target} for +@emph{all} of the longest, leftmost, @emph{nonoverlapping} matching +substrings it can find and replace them with @var{replacement}. +The @samp{g} in @code{gsub()} stands for +``global,'' which means replace everywhere. For example: + +@example +@{ gsub(/Britain/, "United Kingdom"); print @} +@end example + +@noindent +replaces all occurrences of the string @samp{Britain} with @samp{United +Kingdom} for all input records. + +The @code{gsub()} function returns the number of substitutions made. If +the variable to search and alter (@var{target}) is +omitted, then the entire input record (@code{$0}) is used. +As in @code{sub()}, the characters @samp{&} and @samp{\} are special, +and the third argument must be assignable. + @item index(@var{in}, @var{find}) @cindex @code{index()} function @cindex searching @@ -13205,7 +13289,6 @@ If @option{--lint} has been specified on the command line, @command{gawk} issues a warning about this. - @cindex differences between @command{gawk} and @command{awk} With @command{gawk} and several other @command{awk} implementations, when supplied an array argument, the @code{length()} function returns the number of elements @@ -13357,6 +13440,7 @@ manner similar to the way input lines are split into fields using @code{FPAT}. Before splitting the string, @code{patsplit()} deletes any previously existing elements in the arrays @var{array} and @var{seps}. +@cindex troubleshooting, @code{patsplit()} function The @code{patsplit()} function is a @command{gawk} extension. In compatibility mode (@pxref{Options}), @@ -13364,8 +13448,8 @@ it is not available. @item split(@var{string}, @var{array} @r{[}, @var{fieldsep} @r{[}, @var{seps} @r{]} @r{]}) @cindex @code{split()} function -This function divides @var{string} into pieces separated by @var{fieldsep} -and stores the pieces in @var{array} and the separator strings in the +Divide @var{string} into pieces separated by @var{fieldsep} +and store the pieces in @var{array} and the separator strings in the @var{seps} array. The first piece is stored in @code{@var{array}[1]}, the second piece in @code{@var{array}[2]}, and so forth. The string value of the third argument, @var{fieldsep}, is @@ -13448,7 +13532,7 @@ If @var{string} does not match @var{fieldsep} at all (but is not null), @item sprintf(@var{format}, @var{expression1}, @dots{}) @cindex @code{sprintf()} function -This returns (without printing) the string that @code{printf} would +Return (without printing) the string that @code{printf} would have printed out with the same arguments (@pxref{Printf}). For example: @@ -13463,7 +13547,7 @@ assigns the string @w{@code{"pi = 3.14 (approx.)"}} to the variable @code{pival} @cindex differences in @command{awk} and @command{gawk}, @code{strtonum()} function (@command{gawk}) @cindex @code{strtonum()} function (@command{gawk}) @item strtonum(@var{str}) # -Examines @var{str} and returns its numeric value. If @var{str} +Examine @var{str} and return its numeric value. If @var{str} begins with a leading @samp{0}, @code{strtonum()} assumes that @var{str} is an octal number. If @var{str} begins with a leading @samp{0x} or @samp{0X}, @code{strtonum()} assumes that @var{str} is a hexadecimal number. @@ -13490,11 +13574,10 @@ in compatibility mode (@pxref{Options}). @item sub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]}) @cindex @code{sub()} function -The @code{sub()} function alters the value of @var{target}. -It searches this value, which is treated as a string, for the +It searches @var{target}, which is treated as a string, for the leftmost, longest substring matched by the regular expression @var{regexp}. -Then the entire string is -changed by replacing the matched text with @var{replacement}. +Modify the entire string +by replacing the matched text with @var{replacement}. The modified string becomes the new value of @var{target}. The @var{regexp} argument may be either a regexp constant @@ -13569,7 +13652,7 @@ an @samp{&}: @cindex @code{sub()} function, arguments of @cindex @code{gsub()} function, arguments of As mentioned, the third argument to @code{sub()} must -be a variable, field or array reference. +be a variable, field or array element. Some versions of @command{awk} allow the third argument to be an expression that is not an lvalue. In such a case, @code{sub()} still searches for the pattern and returns zero or one, but the result of @@ -13591,97 +13674,15 @@ will not run. Finally, if the @var{regexp} is not a regexp constant, it is converted into a string, and then the value of that string is treated as the regexp to match. -@item gsub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]}) -@cindex @code{gsub()} function -This is similar to the @code{sub()} function, except that @code{gsub()} replaces -@emph{all} of the longest, leftmost, @emph{nonoverlapping} matching -substrings it can find. The @samp{g} in @code{gsub()} stands for -``global,'' which means replace everywhere. For example: - -@example -@{ gsub(/Britain/, "United Kingdom"); print @} -@end example - -@noindent -replaces all occurrences of the string @samp{Britain} with @samp{United -Kingdom} for all input records. - -The @code{gsub()} function returns the number of substitutions made. If -the variable to search and alter (@var{target}) is -omitted, then the entire input record (@code{$0}) is used. -As in @code{sub()}, the characters @samp{&} and @samp{\} are special, -and the third argument must be assignable. - -@item gensub(@var{regexp}, @var{replacement}, @var{how} @r{[}, @var{target}@r{]}) # -@cindex @code{gensub()} function (@command{gawk}) -@code{gensub()} is a general substitution function. Like @code{sub()} and -@code{gsub()}, it searches the target string @var{target} for matches of -the regular expression @var{regexp}. Unlike @code{sub()} and @code{gsub()}, -the modified string is returned as the result of the function and the -original target string is @emph{not} changed. If @var{how} is a string -beginning with @samp{g} or @samp{G}, then it replaces all matches of -@var{regexp} with @var{replacement}. Otherwise, @var{how} is treated -as a number that indicates which match of @var{regexp} to replace. If -no @var{target} is supplied, @code{$0} is used. - -@code{gensub()} provides an additional feature that is not available -in @code{sub()} or @code{gsub()}: the ability to specify components of a -regexp in the replacement text. This is done by using parentheses in -the regexp to mark the components and then specifying @samp{\@var{N}} -in the replacement text, where @var{N} is a digit from 1 to 9. -For example: - -@example -$ @kbd{gawk '} -> @kbd{BEGIN @{} -> @kbd{a = "abc def"} -> @kbd{b = gensub(/(.+) (.+)/, "\\2 \\1", "g", a)} -> @kbd{print b} -> @kbd{@}'} -@print{} def abc -@end example - -@noindent -As with @code{sub()}, you must type two backslashes in order -to get one into the string. -In the replacement text, the sequence @samp{\0} represents the entire -matched text, as does the character @samp{&}. - -The following example shows how you can use the third argument to control -which match of the regexp should be changed: - -@example -$ @kbd{echo a b c a b c |} -> @kbd{gawk '@{ print gensub(/a/, "AA", 2) @}'} -@print{} a b c AA b c -@end example - -In this case, @code{$0} is used as the default target string. -@code{gensub()} returns the new string as its result, which is -passed directly to @code{print} for printing. - -@c @cindex automatic warnings -@c @cindex warnings, automatic -If the @var{how} argument is a string that does not begin with @samp{g} or -@samp{G}, or if it is a number that is less than or equal to zero, only one -substitution is performed. If @var{how} is zero, @command{gawk} issues -a warning message. - -If @var{regexp} does not match @var{target}, @code{gensub()}'s return value -is the original unchanged value of @var{target}. - -@code{gensub()} is a @command{gawk} extension; it is not available -in compatibility mode (@pxref{Options}). - @item substr(@var{string}, @var{start} @r{[}, @var{length}@r{]}) @cindex @code{substr()} function -This returns a @var{length}-character-long substring of @var{string}, +Return a @var{length}-character-long substring of @var{string}, starting at character number @var{start}. The first character of a string is character number one.@footnote{This is different from C and C++, in which the first character is number zero.} For example, @code{substr("washington", 5, 3)} returns @code{"ing"}. -If @var{length} is not present, this function returns the whole suffix of +If @var{length} is not present, @code{substr()} returns the whole suffix of @var{string} that begins at character number @var{start}. For example, @code{substr("washington", 5)} returns @code{"ington"}. The whole suffix is also returned @@ -13733,14 +13734,14 @@ string = substr(string, 1, 2) "CDE" substr(string, 6) @cindex converting, case @item tolower(@var{string}) @cindex @code{tolower()} function -This returns a copy of @var{string}, with each uppercase character +Return a copy of @var{string}, with each uppercase character in the string replaced with its corresponding lowercase character. Nonalphabetic characters are left unchanged. For example, @code{tolower("MiXeD cAsE 123")} returns @code{"mixed case 123"}. @item toupper(@var{string}) @cindex @code{toupper()} function -This returns a copy of @var{string}, with each lowercase character +Return a copy of @var{string}, with each lowercase character in the string replaced with its corresponding uppercase character. Nonalphabetic characters are left unchanged. For example, @code{toupper("MiXeD cAsE 123")} returns @code{"MIXED CASE 123"}. @@ -13787,7 +13788,7 @@ through unchanged. This is illustrated in @ref{table-sub-escapes}. @c Thank to Karl Berry for help with the TeX stuff. @float Table,table-sub-escapes -@caption{Historical Escape Sequence Processing for sub and gsub} +@caption{Historical Escape Sequence Processing for @code{sub()} and @code{gsub()}} @tex \vbox{\bigskip % This table has lots of &'s and \'s, so unspecialize them. @@ -13846,6 +13847,8 @@ case of even numbers of backslashes entered at the lexical level.) The problem with the historical approach is that there is no way to get a literal @samp{\} followed by the matched text. +@c We can omit this historical stuff now +@ignore @c @cindex @command{awk} language, POSIX version @cindex POSIX @command{awk}, functions and, @code{gsub()}/@code{sub()} The 1992 POSIX standard attempted to fix this problem. That standard @@ -13979,14 +13982,15 @@ in the output literally. The POSIX standard took much longer to be revised than was expected in 1996. The 2001 standard does not follow the above rules. Instead, the rules there are somewhat simpler. The results are similar except for one case. +@end ignore -The 2001 POSIX rules state that @samp{\&} in the replacement string produces +The POSIX rules state that @samp{\&} in the replacement string produces a literal @samp{&}, @samp{\\} produces a literal @samp{\}, and @samp{\} followed by anything else is not special; the @samp{\} is placed straight into the output. -These rules are presented in @ref{table-posix-2001-sub}. +These rules are presented in @ref{table-posix-sub}. -@float Table,table-posix-2001-sub -@caption{POSIX 2001 rules for sub} +@float Table,table-posix-sub +@caption{POSIX rules for @code{sub()}} @tex \vbox{\bigskip % This table has lots of &'s and \'s, so unspecialize them. @@ -14029,6 +14033,7 @@ These rules are presented in @ref{table-posix-2001-sub}. @end ifnottex @end float +@ignore The only case where the difference is noticeable is the last one: @samp{\\\\} is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. @@ -14036,8 +14041,9 @@ Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, it continued to follow the 1996 proposed rules, since that had been its behavior for many seven years. +@end ignore -As of @value{PVERSION} 4.0, @command{gawk} uses the POSIX 2001 rules. +@command{gawk} follows the POSIX rules. The rules for @code{gensub()} are considerably simpler. At the runtime level, whenever @command{gawk} sees a @samp{\}, if the following character @@ -14048,7 +14054,7 @@ appears in the generated text and the @samp{\} does not, as shown in @ref{table-gensub-escapes}. @float Table,table-gensub-escapes -@caption{Escape Sequence Processing for gensub} +@caption{Escape Sequence Processing for @code{gensub()}} @tex \vbox{\bigskip % This table has lots of &'s and \'s, so unspecialize them. @@ -14112,7 +14118,7 @@ This is particularly important for the @code{sub()}, @code{gsub()}, and @code{gensub()} functions. For example: @example -$ echo abc | awk '@{ gsub(/m*/, "X"); print @}' +$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'} @print{} XaXbXcX @end example @@ -14154,7 +14160,7 @@ a pipe or coprocess. @cindex buffers, flushing @cindex output, buffering Many utility programs @dfn{buffer} their output; i.e., they save information -to write to a disk file or terminal in memory until there is enough +to write to a disk file or the screen in memory until there is enough for it to be worthwhile to send the data to the output device. This is often more efficient than writing every little bit of information as soon as it is ready. However, sometimes @@ -14196,11 +14202,9 @@ In such a case, @code{fflush()} returns @minus{}1, as well. @item system(@var{command}) @cindex @code{system()} function @cindex interacting with other programs -Executes operating-system -commands and then returns to the @command{awk} program. The @code{system()} -function executes the command given by the string @var{command}. -It returns the status returned by the command that was executed as -its value. +Execute the operating-system +command @var{command} and then return to the @command{awk} program. +It returns @var{command}'s exit status as its value. For example, if the following fragment of code is put in your @command{awk} program: @@ -14229,13 +14233,14 @@ close("/bin/sh") @cindex troubleshooting, @code{system()} function @cindex @code{--sandbox} option, disabling @command{system} function However, if your @command{awk} -program is interactive, @code{system()} is useful for cranking up large +program is interactive, @code{system()} is useful for running large self-contained programs, such as a shell or an editor. Some operating systems cannot implement the @code{system()} function. @code{system()} causes a fatal error if it is not supported. @quotation NOTE -When @option{--sandbox} is specified, the @code{system()} function is disabled. +When @option{--sandbox} is specified, the @code{system()} function is disabled +(@pxref{Options}). @end quotation @end table @@ -14248,8 +14253,8 @@ When @option{--sandbox} is specified, the @code{system()} function is disabled. As a side point, buffering issues can be even more confusing, depending upon whether your program is @dfn{interactive}, i.e., communicating with a user sitting at a keyboard.@footnote{A program is interactive -if the standard output is connected -to a terminal device.} +if the standard output is connected to a terminal device. On modern +systems, this means your keyboard and screen.} @c Thanks to Walter.Mecky@dresdnerbank.de for this example, and for @c motivating me to write this section. @@ -14259,10 +14264,10 @@ a full buffer, which may be many lines of output. Here is an example of the difference: @example -$ awk '@{ print $1 + $2 @}' -1 1 +$ @kbd{awk '@{ print $1 + $2 @}'} +@kbd{1 1} @print{} 2 -2 3 +@kbd{2 3} @print{} 5 @kbd{@value{CTL}-d} @end example @@ -14272,9 +14277,9 @@ Each line of output is printed immediately. Compare that behavior with this example: @example -$ awk '@{ print $1 + $2 @}' | cat -1 1 -2 3 +$ @kbd{awk '@{ print $1 + $2 @}' | cat} +@kbd{1 1} +@kbd{2 3} @kbd{@value{CTL}-d} @print{} 2 @print{} 5 @@ -14343,7 +14348,7 @@ If @command{awk} did not flush its buffers before calling @code{system()}, you would see the latter (undesirable) output. @node Time Functions -@subsection Using @command{gawk}'s Timestamp Functions +@subsection Time Functions @c STARTOFRANGE tst @cindex timestamps @@ -14357,7 +14362,7 @@ you would see the latter (undesirable) output. @code{awk} programs are commonly used to process log files containing timestamp information, indicating when a particular log record was written. Many programs log their timestamp -in the form returned by the @code{time} system call, which is the +in the form returned by the @code{time()} system call, which is the number of seconds since a particular epoch. On POSIX-compliant systems, it is the number of seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds.@footnote{@xref{Glossary}, @@ -14380,18 +14385,9 @@ for simple time-related operations in shell scripts.} Optional parameters are enclosed in square brackets ([ ]): @table @code -@item systime() -@cindex @code{systime()} function (@command{gawk}) -@cindex timestamps -This function returns the current time as the number of seconds since -the system epoch. On POSIX systems, this is the number of seconds -since 1970-01-01 00:00:00 UTC, not counting leap seconds. -It may be a different number on -other systems. - @item mktime(@var{datespec}) @cindex @code{mktime()} function (@command{gawk}) -This function turns @var{datespec} into a timestamp in the same form +Turn @var{datespec} into a timestamp in the same form as is returned by @code{systime()}. It is similar to the function of the same name in ISO C. The argument, @var{datespec}, is a string of the form @w{@code{"@var{YYYY} @var{MM} @var{DD} @var{HH} @var{MM} @var{SS} [@var{DST}]"}}. @@ -14419,9 +14415,9 @@ is out of range, @code{mktime()} returns @minus{}1. @item strftime(@r{[}@var{format} @r{[}, @var{timestamp} @r{[}, @var{utc-flag}@r{]]]}) @c STARTOFRANGE strf @cindex @code{strftime()} function (@command{gawk}) -This function returns a string. It is similar to the function of the -same name in ISO C. The time specified by @var{timestamp} is used to -produce a string, based on the contents of the @var{format} string. +Format the time specified by @var{timestamp} +based on the contents of the @var{format} string and return the result. +It is similar to the function of the same name in ISO C. If @var{utc-flag} is present and is either non-zero or non-null, the value is formatted as UTC (Coordinated Universal Time, formerly GMT or Greenwich Mean Time). Otherwise, the value is formatted for the local time zone. @@ -14429,9 +14425,16 @@ The @var{timestamp} is in the same format as the value returned by the @code{systime()} function. If no @var{timestamp} argument is supplied, @command{gawk} uses the current time of day as the timestamp. If no @var{format} argument is supplied, @code{strftime()} uses -@code{@w{"%a %b %d %H:%M:%S %Z %Y"}}. This format string produces -output that is (almost) equivalent to that of the @command{date} utility. -(Versions of @command{gawk} prior to 3.0 require the @var{format} argument.) +@code{@w{"%a %b %e %H:%M:%S %Z %Y"}}. This format string produces +output that is equivalent to that of the @command{date} utility. + +@item systime() +@cindex @code{systime()} function (@command{gawk}) +@cindex timestamps +Return the current time as the number of seconds since +the system epoch. On POSIX systems, this is the number of seconds +since 1970-01-01 00:00:00 UTC, not counting leap seconds. +It may be a different number on other systems. @end table The @code{systime()} function allows you to compare a timestamp from a @@ -14456,8 +14459,8 @@ returned string, while substituting date and time values for format specifications in the @var{format} string. @cindex format specifiers, @code{strftime()} function (@command{gawk}) -@code{strftime()} is guaranteed by the 1999 ISO C standard@footnote{As this -is a recent standard, not every system's @code{strftime()} necessarily +@code{strftime()} is guaranteed by the 1999 ISO C standard@footnote{Unfortunately, +not every system's @code{strftime()} necessarily supports all of the conversions listed here.} to support the following date format specifications: @@ -14496,9 +14499,9 @@ Equivalent to specifying @samp{%Y-%m-%d}. This is the ISO 8601 date format. @item %g -The year modulo 100 of the ISO week number, as a decimal number (00--99). +The year modulo 100 of the ISO 8601 week number, as a decimal number (00--99). For example, January 1, 1993 is in week 53 of 1992. Thus, the year -of its ISO week number is 1992, even though its year is 1993. +of its ISO 8601 week number is 1992, even though its year is 1993. Similarly, December 31, 1973 is in week 1 of 1974. Thus, the year of its ISO week number is 1974, even though its year is 1973. @@ -14581,7 +14584,7 @@ The locale's ``appropriate'' time representation. The year modulo 100 as a decimal number (00--99). @item %Y -The full year as a decimal number (e.g., 1995). +The full year as a decimal number (e.g., 2011). @c @cindex RFC 822 @c @cindex RFC 1036 @@ -14623,13 +14626,13 @@ In many countries in Europe, however, it is abbreviated ``4.9.91.'' Thus, the @samp{%x} specification in a @code{"US"} locale might produce @samp{9/4/91}, while in a @code{"EUROPE"} locale, it might produce @samp{4.9.91}. The ISO C standard defines a default @code{"C"} -locale, which is an environment that is typical of what most C programmers +locale, which is an environment that is typical of what many C programmers are used to. For systems that are not yet fully standards-compliant, @command{gawk} supplies a copy of @code{strftime()} from the GNU C Library. -It supports all of the just listed format specifications. +It supports all of the just-listed format specifications. If that version is used to compile @command{gawk} (@pxref{Installation}), then the following additional format specifications are available: @@ -14668,7 +14671,7 @@ normal representations are used. @cindex @code{date} utility, POSIX @cindex POSIX @command{awk}, @code{date} utility and -This example is an @command{awk} implementation of the POSIX +The following example is an @command{awk} implementation of the POSIX @command{date} utility. Normally, the @command{date} utility prints the current date and time of day in a well-known format. However, if you provide an argument to it that begins with a @samp{+}, @command{date} @@ -14678,7 +14681,7 @@ the string. For example: @example $ date '+Today is %A, %B %d, %Y.' -@print{} Today is Thursday, September 14, 2000. +@print{} Today is Wednesday, December 01, 2010. @end example Here is the @command{gawk} version of the @command{date} utility. @@ -14718,7 +14721,7 @@ gawk 'BEGIN @{ @c ENDOFRANGE gawtst @node Bitwise Functions -@subsection Bit-Manipulation Functions of @command{gawk} +@subsection Bit-Manipulation Functions @c STARTOFRANGE bit @cindex bitwise, operations @c STARTOFRANGE and @@ -14880,31 +14883,31 @@ with @samp{11001000}. bitwise operations just described. They are: @cindex @command{gawk}, bitwise operations in -@multitable {@code{rshift(@var{val}, @var{count})}} {Return the value of @var{val}, shifted right by @var{count} bits.} +@table @code @cindex @code{and()} function (@command{gawk}) -@item @code{and(@var{v1}, @var{v2})} -@tab Returns the bitwise AND of the values provided by @var{v1} and @var{v2}. - -@cindex @code{or()} function (@command{gawk}) -@item @code{or(@var{v1}, @var{v2})} -@tab Returns the bitwise OR of the values provided by @var{v1} and @var{v2}. - -@cindex @code{xor()} function (@command{gawk}) -@item @code{xor(@var{v1}, @var{v2})} -@tab Returns the bitwise XOR of the values provided by @var{v1} and @var{v2}. +@item and(@var{v1}, @var{v2}) +Return the bitwise AND of the values provided by @var{v1} and @var{v2}. @cindex @code{compl()} function (@command{gawk}) -@item @code{compl(@var{val})} -@tab Returns the bitwise complement of @var{val}. +@item compl(@var{val}) +Return the bitwise complement of @var{val}. @cindex @code{lshift()} function (@command{gawk}) -@item @code{lshift(@var{val}, @var{count})} -@tab Returns the value of @var{val}, shifted left by @var{count} bits. +@item lshift(@var{val}, @var{count}) +Return the value of @var{val}, shifted left by @var{count} bits. + +@cindex @code{or()} function (@command{gawk}) +@item or(@var{v1}, @var{v2}) +Return the bitwise OR of the values provided by @var{v1} and @var{v2}. @cindex @code{rshift()} function (@command{gawk}) -@item @code{rshift(@var{val}, @var{count})} -@tab Returns the value of @var{val}, shifted right by @var{count} bits. -@end multitable +@item rshift(@var{val}, @var{count}) +Return the value of @var{val}, shifted right by @var{count} bits. + +@cindex @code{xor()} function (@command{gawk}) +@item xor(@var{v1}, @var{v2}) +Return the bitwise XOR of the values provided by @var{v1} and @var{v2}. +@end table For all of these functions, first the double-precision floating-point value is converted to the widest C unsigned integer type, then the bitwise operation is @@ -14913,13 +14916,12 @@ leading nonzero bits are removed one by one until it can be represented exactly. The result is then converted back into a C @code{double}. (If you don't understand this paragraph, don't worry about it.) -Here is a user-defined function -(@pxref{User-defined}) +Here is a user-defined function (@pxref{User-defined}) that illustrates the use of these functions: @cindex @code{bits2str} user-defined function @cindex @code{testbits.awk} program -@smallexample +@example @group @c file eg/lib/bits2str.awk # bits2str --- turn a byte into readable 1's and 0's @@ -14975,25 +14977,25 @@ BEGIN @{ printf "rshift(0x99, 2) = %#x = %s\n", shift, bits2str(shift) @} @c endfile -@end smallexample +@end example @noindent This program produces the following output when run: -@smallexample -$ gawk -f testbits.awk +@example +$ @kbd{gawk -f testbits.awk} @print{} 123 = 01111011 @print{} 0123 = 01010011 @print{} 0x99 = 10011001 @print{} compl(0x99) = 0xffffff66 = 11111111111111111111111101100110 @print{} lshift(0x99, 2) = 0x264 = 0000001001100100 @print{} rshift(0x99, 2) = 0x26 = 00100110 -@end smallexample +@end example @cindex numbers, converting, to strings @cindex strings, converting, numbers to @cindex converting, numbers, to strings -The @code{bits2str} function turns a binary number into a string. +The @code{bits2str()} function turns a binary number into a string. The number @code{1} represents a binary value where the rightmost bit is set to 1. Using this mask, the function repeatedly checks the rightmost bit. @@ -15020,7 +15022,7 @@ results of the @code{compl()}, @code{lshift()}, and @code{rshift()} functions. @c ENDOFRANGE opbit @node I18N Functions -@subsection Using @command{gawk}'s String-Translation Functions +@subsection String-Translation Functions @cindex @command{gawk}, string-translation functions @cindex functions, string-translation @cindex internationalization @@ -15034,35 +15036,35 @@ for the full story. Optional parameters are enclosed in square brackets ([ ]): @table @code +@cindex @code{bindtextdomain()} function (@command{gawk}) +@item bindtextdomain(@var{directory} @r{[}, @var{domain}@r{]}) +Set the directory in which +@command{gawk} will look for message translation files, in case they +will not or cannot be placed in the ``standard'' locations +(e.g., during testing). +It returns the directory in which @var{domain} is ``bound.'' + +The default @var{domain} is the value of @code{TEXTDOMAIN}. +If @var{directory} is the null string (@code{""}), then +@code{bindtextdomain()} returns the current binding for the +given @var{domain}. + @cindex @code{dcgettext()} function (@command{gawk}) @item dcgettext(@var{string} @r{[}, @var{domain} @r{[}, @var{category}@r{]]}) -This function returns the translation of @var{string} in +Return the translation of @var{string} in text domain @var{domain} for locale category @var{category}. The default value for @var{domain} is the current value of @code{TEXTDOMAIN}. The default value for @var{category} is @code{"LC_MESSAGES"}. @cindex @code{dcngettext()} function (@command{gawk}) @item dcngettext(@var{string1}, @var{string2}, @var{number} @r{[}, @var{domain} @r{[}, @var{category}@r{]]}) -This function returns the plural form used for @var{number} of the +Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @var{domain} for locale category @var{category}. @var{string1} is the English singular variant of a message, and @var{string2} the English plural variant of the same message. The default value for @var{domain} is the current value of @code{TEXTDOMAIN}. The default value for @var{category} is @code{"LC_MESSAGES"}. - -@cindex @code{bindtextdomain()} function (@command{gawk}) -@item bindtextdomain(@var{directory} @r{[}, @var{domain}@r{]}) -This function allows you to specify the directory in which -@command{gawk} will look for message translation files, in case they -will not or cannot be placed in the ``standard'' locations -(e.g., during testing). -It returns the directory in which @var{domain} is ``bound.'' - -The default @var{domain} is the value of @code{TEXTDOMAIN}. -If @var{directory} is the null string (@code{""}), then -@code{bindtextdomain()} returns the current binding for the -given @var{domain}. @end table @c ENDOFRANGE funcbi @c ENDOFRANGE bifunc @@ -15102,10 +15104,9 @@ before all uses of the function. This is because @command{awk} reads the entire program before starting to execute any of it. The definition of a function named @var{name} looks like this: -@strong{FIXME: NEXT ED:} put [ ] around parameter list. @example -function @var{name}(@var{parameter-list}) +function @var{name}(@r{[}@var{parameter-list}@r{]}) @{ @var{body-of-function} @} @@ -15128,7 +15129,7 @@ the call. The local variables are initialized to the empty string. A function cannot have two parameters with the same name, nor may it have a parameter with the same name as the function itself. -According to the POSIX standard, function parameters cannot have the same +In addition, according to the POSIX standard, function parameters cannot have the same name as one of the special built-in variables (@pxref{Built-in Variables}. Not all versions of @command{awk} enforce this restriction. @@ -15198,8 +15199,8 @@ of the variable @samp{func} with the return value of the function @samp{foo}. If the resulting string is non-null, the action is executed. This is probably not what is desired. (@command{awk} accepts this input as syntactically valid, because functions may be used before they are defined -in @command{awk} programs.) -@strong{FIXME: NEXT ED:} This won't actually run, since foo() is undefined ... +in @command{awk} programs.@footnote{This program won't actually run, +since @code{foo()} is undefined.}) @cindex portability, functions@comma{} defining To ensure that your @command{awk} programs are portable, always use the @@ -15208,7 +15209,7 @@ keyword @code{function} when defining a function. @node Function Example @subsection Function Definition Examples -Here is an example of a user-defined function, called @code{myprint}, that +Here is an example of a user-defined function, called @code{myprint()}, that takes a number and prints it in a specific format: @example @@ -15228,7 +15229,7 @@ $3 > 0 @{ myprint($3) @} @noindent This program prints, in our special format, all the third fields that -contain a positive number in our input. Therefore, when given the following: +contain a positive number in our input. Therefore, when given the following input: @example 1.2 3.4 5.6 7.8 @@ -15284,18 +15285,18 @@ If this function is in a file named @file{rev.awk}, it can be tested this way: @example -$ echo "Don't Panic!" | -> gawk --source '@{ print rev($0, length($0)) @}' -f rev.awk +$ @kbd{echo "Don't Panic!" |} +> @kbd{gawk --source '@{ print rev($0, length($0)) @}' -f rev.awk} @print{} !cinaP t'noD @end example -The C @code{ctime} function takes a timestamp and returns it in a string, +The C @code{ctime()} function takes a timestamp and returns it in a string, formatted in a well-known fashion. The following example uses the built-in @code{strftime()} function (@pxref{Time Functions}) -to create an @command{awk} version of @code{ctime}: +to create an @command{awk} version of @code{ctime()}: -@cindex @code{ctime} user-defined function +@cindex @code{ctime()} user-defined function @example @c file eg/lib/ctime.awk # ctime.awk @@ -15325,8 +15326,8 @@ the function. A function call consists of the function name followed by the arguments in parentheses. @command{awk} expressions are what you write in the call for the arguments. Each time the call is executed, these -expressions are evaluated, and the values are the actual arguments. For -example, here is a call to @code{foo} with three arguments (the first +expressions are evaluated, and the values become the actual arguments. For +example, here is a call to @code{foo()} with three arguments (the first being a string concatenation): @example @@ -15353,11 +15354,11 @@ z = myfunc(foo) @end example @noindent -then you should not think of the argument to @code{myfunc} as being +then you should not think of the argument to @code{myfunc()} as being ``the variable @code{foo}.'' Instead, think of the argument as the string value @code{"bar"}. -If the function @code{myfunc} alters the values of its local variables, -this has no effect on any other variables. Thus, if @code{myfunc} +If the function @code{myfunc()} alters the values of its local variables, +this has no effect on any other variables. Thus, if @code{myfunc()} does this: @example @@ -15372,17 +15373,17 @@ function myfunc(str) @noindent to change its first argument variable @code{str}, it does @emph{not} change the value of @code{foo} in the caller. The role of @code{foo} in -calling @code{myfunc} ended when its value (@code{"bar"}) was computed. -If @code{str} also exists outside of @code{myfunc}, the function body +calling @code{myfunc()} ended when its value (@code{"bar"}) was computed. +If @code{str} also exists outside of @code{myfunc()}, the function body cannot alter this outer value, because it is shadowed during the -execution of @code{myfunc} and cannot be seen or changed from there. +execution of @code{myfunc()} and cannot be seen or changed from there. @cindex call by reference @cindex arrays, as parameters to functions @cindex functions, arrays as parameters to However, when arrays are the parameters to functions, they are @emph{not} copied. Instead, the array itself is made available for direct manipulation -by the function. This is usually called @dfn{call by reference}. +by the function. This is usually termed @dfn{call by reference}. Changes made to an array parameter inside the body of a function @emph{are} visible outside that function. @@ -15429,7 +15430,7 @@ function bar() @{ @dots{} @} @noindent Because the @samp{if} statement will never be true, it is not really a -problem that @code{foo} has not been defined. Usually, though, it is a +problem that @code{foo()} has not been defined. Usually, though, it is a problem if a program calls an undefined function. @cindex lint checking, undefined functions @@ -15458,19 +15459,24 @@ program. It looks like this: return @r{[}@var{expression}@r{]} @end example -The @var{expression} part is optional. If it is omitted, then the returned -value is undefined, and therefore, unpredictable. +The @var{expression} part is optional. +Due most likely to an oversight, POSIX does not define what the return +value is if you omit the @var{expression}. Technically speaking, this +make the returned value undefined, and therefore, unpredictable. +In practice, though, all versions of @command{awk} simply return the +null string, which acts like zero if used in a numeric context. A @code{return} statement with no value expression is assumed at the end of every function definition. So if control reaches the end of the function -body, then the function returns an unpredictable value. @command{awk} +body, then technically, the function returns an unpredictable value. +In practice, it returns the empty string. @command{awk} does @emph{not} warn you if you use the return value of such a function. Sometimes, you want to write a function for what it does, not for what it returns. Such a function corresponds to a @code{void} function -in C or to a @code{procedure} in Pascal. Thus, it may be appropriate to not -return any value; simply bear in mind that if you use the return -value of such a function, you do so at your own risk. +in C or to a @code{procedure} in Ada. Thus, it may be appropriate to not +return any value; simply bear in mind that you should not be using the +return value of such a function. The following is an example of a user-defined function that returns a value for the largest number among the elements of an array: @@ -15488,16 +15494,16 @@ function maxelt(vec, i, ret) @cindex programming conventions, function parameters @noindent -You call @code{maxelt} with one argument, which is an array name. The local +You call @code{maxelt()} with one argument, which is an array name. The local variables @code{i} and @code{ret} are not intended to be arguments; while there is nothing to stop you from passing more than one argument -to @code{maxelt}, the results would be strange. The extra space before +to @code{maxelt()}, the results would be strange. The extra space before @code{i} in the function parameter list indicates that @code{i} and @code{ret} are not supposed to be arguments. You should follow this convention when defining functions. -The following program uses the @code{maxelt} function. It loads an -array, calls @code{maxelt}, and then reports the maximum number in that +The following program uses the @code{maxelt()} function. It loads an +array, calls @code{maxelt()}, and then reports the maximum number in that array: @example @@ -15532,7 +15538,7 @@ Given the following input: @end example @noindent -the program reports (predictably) that @code{99385} is the largest number +the program reports (predictably) that 99,385 is the largest value in the array. @node Dynamic Typing @@ -15621,7 +15627,7 @@ variable as the name of the function to call. The syntax is similar to that of a regular function call: an identifier immediately followed by a left parenthesis, any arguments, and then -a closing right parenthesis, with the addition of a leading @code{@@} +a closing right parenthesis, with the addition of a leading @samp{@@} character: @example @@ -15730,7 +15736,7 @@ $ @kbd{gawk -f indirectcall.awk class_data1} The ability to use indirect function calls is more powerful than you may think at first. The C and C++ languages provide ``function pointers,'' which are a mechanism for calling a function chosen at runtime. One of the most -well-known uses of this ablity is the C @code{qsort} function, which sorts +well-known uses of this ablity is the C @code{qsort()} function, which sorts an array using the well-known ``quick sort'' algorithm (see @uref{http://en.wikipedia.org/wiki/Quick_sort, the Wikipedia article} for more information). To use this function, you supply a pointer to a comparison @@ -15789,7 +15795,7 @@ function quicksort_swap(data, i, j, temp) @c endfile @end example -The @code{quicksort} function receives the @code{data} array, the starting and ending +The @code{quicksort()} function receives the @code{data} array, the starting and ending indices to sort (@code{left} and @code{right}), and the name of a function that performs a ``less than'' comparison. It then implements the quick sort algorithm. @@ -15814,7 +15820,7 @@ function num_ge(left, right) @c endfile @end example -The @code{num_ge} function is needed to perform a descending sort; when used +The @code{num_ge()} function is needed to perform a descending sort; when used to perform a ``less than'' test, it actually does the opposite (greater than or equal to), which yields data sorted in descending order. @@ -15825,7 +15831,8 @@ results as a single string: @example @c file eg/prog/indirectcall.awk -# do_sort --- sort the data according to `compare' and return it as a string +# do_sort --- sort the data according to `compare' +# and return it as a string function do_sort(first, last, compare, data, i, retval) @{ @@ -15846,7 +15853,7 @@ function do_sort(first, last, compare, data, i, retval) @c endfile @end example -Finally, the two sorting functions call @code{do_sort}, passing in the +Finally, the two sorting functions call @code{do_sort()}, passing in the names of the two comparison functions: @example @@ -15907,7 +15914,8 @@ you can generally write ``wrapper'' functions which call the built-in ones, and be called indirectly. (Other than, perhaps, the mathematical functions, there is not a lot of reason to try to call the built-in functions indirectly.) -@command{gawk} does its best to make indirect function calls efficient. For example: +@command{gawk} does its best to make indirect function calls efficient. +For example, in the following case: @example for (i = 1; i <= n; i++) @@ -2436,9 +2436,8 @@ match_re: if (t1->stlen > 0) { /* retrieve function definition node */ f = pc->func_body; - if (f != NULL - && STREQ(f->vname, t1->stptr) /* indirect var hasn't been reassigned */ - ) + if (f != NULL && STREQ(f->vname, t1->stptr)) + /* indirect var hasn't been reassigned */ goto func_call; f = lookup(t1->stptr); } |