diff options
| -rw-r--r-- | doc/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/gawk.info | 934 | ||||
| -rw-r--r-- | doc/gawk.texi | 178 | ||||
| -rw-r--r-- | doc/gawktexi.in | 178 |
4 files changed, 642 insertions, 653 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 854cad6d..9b77b107 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2013-12-12 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Fix the presentation of asort() and asorti(). + Thanks to Andy Schorr for pointing out the problems. + 2013-11-28 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Update quotations to use @author, fix a few diff --git a/doc/gawk.info b/doc/gawk.info index 24f08018..42228cae 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -10439,42 +10439,45 @@ available: default `awk' behavior. `"@ind_str_asc"' - Order by indices compared as strings; this is the most basic sort. - (Internally, array indices are always strings, so with `a[2*5] = 1' - the index is `"10"' rather than numeric 10.) + Order by indices in ascending order compared as strings; this is + the most basic sort. (Internally, array indices are always + strings, so with `a[2*5] = 1' the index is `"10"' rather than + numeric 10.) `"@ind_num_asc"' - Order by indices but force them to be treated as numbers in the - process. Any index with a non-numeric value will end up - positioned as if it were zero. + Order by indices in ascending order but force them to be treated + as numbers in the process. Any index with a non-numeric value + will end up positioned as if it were zero. `"@val_type_asc"' - Order by element values rather than indices. Ordering is by the - type assigned to the element (*note Typing and Comparison::). All - numeric values come before all string values, which in turn come - before all subarrays. (Subarrays have not been described yet; - *note Arrays of Arrays::). + Order by element values in ascending order (rather than by + indices). Ordering is by the type assigned to the element (*note + Typing and Comparison::). All numeric values come before all + string values, which in turn come before all subarrays. + (Subarrays have not been described yet; *note Arrays of Arrays::.) `"@val_str_asc"' - Order by element values rather than by indices. Scalar values are - compared as strings. Subarrays, if present, come out last. + Order by element values in ascending order (rather than by + indices). Scalar values are compared as strings. Subarrays, if + present, come out last. `"@val_num_asc"' - Order by element values rather than by indices. Scalar values are - compared as numbers. Subarrays, if present, come out last. When - numeric values are equal, the string values are used to provide an - ordering: this guarantees consistent results across different - versions of the C `qsort()' function,(1) which `gawk' uses - internally to perform the sorting. + Order by element values in ascending order (rather than by + indices). Scalar values are compared as numbers. Subarrays, if + present, come out last. When numeric values are equal, the string + values are used to provide an ordering: this guarantees consistent + results across different versions of the C `qsort()' function,(1) + which `gawk' uses internally to perform the sorting. `"@ind_str_desc"' - Reverse order from the most basic sort. + String indices ordered from high to low. `"@ind_num_desc"' Numeric indices ordered from high to low. `"@val_type_desc"' - Element values, based on type, in descending order. + Element values, based on type, ordered from high to low. + Subarrays, if present, come out first. `"@val_str_desc"' Element values, treated as strings, ordered from high to low. @@ -11187,13 +11190,15 @@ File: gawk.info, Node: String Functions, Next: I/O Functions, Prev: Numeric F ----------------------------------- The functions in this minor node look at or change the text of one or -more strings. `gawk' understands locales (*note Locales::), and does -all string processing in terms of _characters_, not _bytes_. This -distinction is particularly important to understand for locales where -one character may be represented by multiple bytes. Thus, for example, -`length()' returns the number of characters in a string, and not the -number of bytes used to represent those characters, Similarly, -`index()' works with character indices, and not byte indices. +more strings. + + `gawk' understands locales (*note Locales::), and does all string +processing in terms of _characters_, not _bytes_. This distinction is +particularly important to understand for locales where one character +may be represented by multiple bytes. Thus, for example, `length()' +returns the number of characters in a string, and not the number of +bytes used to represent those characters. Similarly, `index()' works +with character indices, and not byte indices. In the following list, optional parameters are enclosed in square brackets ([ ]). Several functions perform string substitution; the @@ -11209,26 +11214,26 @@ pound sign (`#'): `gensub()'. `asort(SOURCE [, DEST [, HOW ] ]) #' - Return the number of elements in the array SOURCE. `gawk' sorts - the contents of SOURCE and replaces the indices of the sorted - values of SOURCE with sequential integers starting with one. If - the optional array DEST is specified, then SOURCE is duplicated - into DEST. DEST is then sorted, leaving the indices of SOURCE - unchanged. The optional third argument HOW is a string which - controls the rule for comparing values, and the sort direction. A - single space is required between the comparison mode, `string' or - `number', and the direction specification, `ascending' or - `descending'. You can omit direction and/or mode in which case it - will default to `ascending' and `string', respectively. An empty - string "" is the same as the default `"ascending string"' for the - value of HOW. If the `source' array contains subarrays as values, - they will come out last(first) in the `dest' array for - `ascending'(`descending') order specification. The value of - `IGNORECASE' affects the sorting. The third argument can also be - a user-defined function name in which case the value returned by - the function is used to order the array elements before - constructing the result array. *Note Array Sorting Functions::, - for more information. +`asorti(SOURCE [, DEST [, HOW ] ]) #' + These two functions are similar in behavior, so they are described + together. + + NOTE: The following description ignores the third argument, + HOW, since it requires understanding features that we have + not discussed yet. Thus, the discussion here is a deliberate + simplification. (We do provide all the details later on: + *Note Array Sorting Functions::, for the full story.) + + Both functions return the number of elements in the array SOURCE. + For `asort()', `gawk' sorts the values of SOURCE and replaces the + indices of the sorted values of SOURCE with sequential integers + starting with one. If the optional array DEST is specified, then + SOURCE is duplicated into DEST. DEST is then sorted, leaving the + indices of SOURCE unchanged. + + When comparing strings, `IGNORECASE' affects the sorting. If the + SOURCE array contains subarrays as values (*note Arrays of + Arrays::), they will come last, after all scalar values. For example, if the contents of `a' are as follows: @@ -11246,23 +11251,16 @@ pound sign (`#'): a[2] = "de" a[3] = "sac" - In order to reverse the direction of the sorted results in the - above example, `asort()' can be called with three arguments as - follows: - - asort(a, a, "descending") - - The `asort()' function is described in more detail in *note Array - Sorting Functions::. `asort()' is a `gawk' extension; it is not - available in compatibility mode (*note Options::). + The `asorti()' function works similarly to `asort()', however, the + _indices_ are sorted, instead of the values. Thus, in the previous + example, starting with the same initial set of indices and values + in `a', calling `asorti(a)' would yield: -`asorti(SOURCE [, DEST [, HOW ] ]) #' - Return the number of elements in the array SOURCE. It works - similarly to `asort()', however, the _indices_ are sorted, instead - of the values. (Here too, `IGNORECASE' affects the sorting.) + a[1] = "first" + a[2] = "last" + a[3] = "middle" - The `asorti()' function is described in more detail in *note Array - Sorting Functions::. `asorti()' is a `gawk' extension; it is not + `asort()' and `asorti()' are `gawk' extensions; they are not available in compatibility mode (*note Options::). `gensub(REGEXP, REPLACEMENT, HOW [, TARGET]) #' @@ -18226,7 +18224,7 @@ seemingly ordered data: function cmp_randomize(i1, v1, i2, v2) { - # random order + # random order (caution: this may never terminate!) return (2 - 4 * rand()) } @@ -18240,7 +18238,7 @@ elements with otherwise equal values is to include the indices in the comparison rules. Note that doing this may make the loop traversal less efficient, so consider it only if necessary. The following comparison functions force a deterministic order, and are based on the -fact that the indices of two elements are never equal: +fact that the (string) indices of two elements are never equal: function cmp_numeric(i1, v1, i2, v2) { @@ -18299,9 +18297,9 @@ functions (*note String Functions::) for sorting arrays. For example: After the call to `asort()', the array `data' is indexed from 1 to some number N, the total number of elements in `data'. (This count is `asort()''s return value.) `data[1]' <= `data[2]' <= `data[3]', and so -on. The comparison is based on the type of the elements (*note Typing -and Comparison::). All numeric values come before all string values, -which in turn come before all subarrays. +on. The default comparison is based on the type of the elements (*note +Typing and Comparison::). All numeric values come before all string +values, which in turn come before all subarrays. An important side effect of calling `asort()' is that _the array's original indices are irrevocably lost_. As this isn't always @@ -18316,21 +18314,11 @@ desirable, `asort()' accepts a second argument: and then sorts `dest', destroying its indices. However, the `source' array is not affected. - `asort()' accepts a third string argument to control comparison of -array elements. As with `PROCINFO["sorted_in"]', this argument may be -one of the predefined names that `gawk' provides (*note Controlling -Scanning::), or the name of a user-defined function (*note Controlling -Array Traversal::). - - NOTE: In all cases, the sorted element values consist of the - original array's element values. The ability to control - comparison merely affects the way in which they are sorted. - Often, what's needed is to sort on the values of the _indices_ instead of the values of the elements. To do that, use the `asorti()' -function. The interface is identical to that of `asort()', except that -the index values are used for sorting, and become the values of the -result array: +function. The interface and behavior are identical to that of +`asort()', except that the index values are used for sorting, and +become the values of the result array: { source[$0] = some_func($0) } @@ -18345,32 +18333,41 @@ result array: } } - Similar to `asort()', in all cases, the sorted element values -consist of the original array's indices. The ability to control -comparison merely affects the way in which they are sorted. - - Sorting the array by replacing the indices provides maximal -flexibility. To traverse the elements in decreasing order, use a loop -that goes from N down to 1, either over the elements or over the -indices.(1) - - Copying array indices and elements isn't expensive in terms of -memory. Internally, `gawk' maintains "reference counts" to data. For -example, when `asort()' copies the first array to the second one, there -is only one copy of the original array elements' data, even though both -arrays use the values. + So far, so good. Now it starts to get interesting. Both `asort()' +and `asorti()' accept a third string argument to control comparison of +array elements. In *note String Functions::, we ignored this third +argument; however, the time has now come to describe how this argument +affects these two functions. + + Basically, the third argument specifies how the array is to be +sorted. There are two possibilities. As with `PROCINFO["sorted_in"]', +this argument may be one of the predefined names that `gawk' provides +(*note Controlling Scanning::), or it may be the name of a user-defined +function (*note Controlling Array Traversal::). + + In the latter case, _the function can compare elements in any way it +chooses_, taking into account just the indices, just the values, or +both. This is extremely powerful. + + Once the array is sorted, `asort()' takes the _values_ in their +final order, and uses them to fill in the result array, whereas +`asorti()' takes the _indices_ in their final order, and uses them to +fill in the result array. + + NOTE: Copying array indices and elements isn't expensive in terms + of memory. Internally, `gawk' maintains "reference counts" to + data. For example, when `asort()' copies the first array to the + second one, there is only one copy of the original array elements' + data, even though both arrays use the values. Because `IGNORECASE' affects string comparisons, the value of `IGNORECASE' also affects sorting for both `asort()' and `asorti()'. Note also that the locale's sorting order does _not_ come into play; -comparisons are based on character values only.(2) Caveat Emptor. +comparisons are based on character values only.(1) Caveat Emptor. ---------- Footnotes ---------- - (1) You may also use one of the predefined sorting names that sorts -in decreasing order. - - (2) This is true because locale-based comparison occurs only when in + (1) This is true because locale-based comparison occurs only when in POSIX compatibility mode, and since `asort()' and `asorti()' are `gawk' extensions, they are not available in that case. @@ -29712,7 +29709,7 @@ Index * arrays, elements, order of: Scanning an Array. (line 48) * arrays, elements, referencing: Reference to Elements. (line 6) -* arrays, elements, retrieving number of: String Functions. (line 29) +* arrays, elements, retrieving number of: String Functions. (line 32) * arrays, for statement and: Scanning an Array. (line 20) * arrays, IGNORECASE variable and: Array Intro. (line 91) * arrays, indexing: Array Intro. (line 49) @@ -29724,7 +29721,7 @@ Index * arrays, sorting: Array Sorting Functions. (line 6) * arrays, sorting, IGNORECASE variable and: Array Sorting Functions. - (line 81) + (line 83) * arrays, sparse: Array Intro. (line 70) * arrays, subscripts: Numeric Array Subscripts. (line 6) @@ -29736,10 +29733,14 @@ Index * ASCII: Ordinal Functions. (line 45) * asort() function (gawk) <1>: Array Sorting Functions. (line 6) -* asort() function (gawk): String Functions. (line 29) +* asort() function (gawk): String Functions. (line 32) * asort() function (gawk), arrays, sorting: Array Sorting Functions. (line 6) -* asorti() function (gawk): String Functions. (line 77) +* asorti() function (gawk) <1>: Array Sorting Functions. + (line 6) +* asorti() function (gawk): String Functions. (line 32) +* asorti() function (gawk), arrays, sorting: Array Sorting Functions. + (line 6) * assert() function (C library): Assert Function. (line 6) * assert() user-defined function: Assert Function. (line 28) * assertions: Assert Function. (line 6) @@ -29981,7 +29982,7 @@ Index * caret (^), regexp operator: Regexp Operators. (line 22) * case keyword: Switch Statement. (line 6) * case sensitivity, array indices and: Array Intro. (line 91) -* case sensitivity, converting case: String Functions. (line 524) +* case sensitivity, converting case: String Functions. (line 519) * case sensitivity, example programs: Library Functions. (line 53) * case sensitivity, gawk: Case-sensitivity. (line 26) * case sensitivity, regexps and <1>: User-modified. (line 82) @@ -30058,7 +30059,7 @@ Index * common extensions, delete to delete entire arrays: Delete. (line 39) * common extensions, func keyword: Definition Syntax. (line 83) * common extensions, length() applied to an array: String Functions. - (line 198) + (line 193) * common extensions, RS as a regexp: Records. (line 120) * common extensions, single character fields: Single Character Fields. (line 6) @@ -30103,7 +30104,7 @@ Index (line 6) * continue statement: Continue Statement. (line 6) * control statements: Statements. (line 6) -* converting, case: String Functions. (line 524) +* converting, case: String Functions. (line 519) * converting, dates to timestamps: Time Functions. (line 75) * converting, during subscripting: Numeric Array Subscripts. (line 31) @@ -30163,7 +30164,7 @@ Index (line 20) * dark corner, input files: Records. (line 103) * dark corner, invoking awk: Command Line. (line 16) -* dark corner, length() function: String Functions. (line 184) +* dark corner, length() function: String Functions. (line 179) * dark corner, locale's decimal point character: Conversion. (line 77) * dark corner, multiline records: Multiple Line. (line 35) * dark corner, NF variable, decrementing: Changing Fields. (line 107) @@ -30174,7 +30175,7 @@ Index (line 147) * dark corner, regexp constants, as arguments to user-defined functions: Using Constant Regexps. (line 43) -* dark corner, split() function: String Functions. (line 363) +* dark corner, split() function: String Functions. (line 358) * dark corner, strings, storing: Records. (line 195) * dark corner, value of ARGV[0]: Auto-set. (line 35) * data, fixed-width: Constant Size. (line 9) @@ -30306,7 +30307,7 @@ Index * deleting elements in arrays: Delete. (line 6) * deleting entire arrays: Delete. (line 39) * Demaille, Akim: Acknowledgments. (line 60) -* differences between gawk and awk: String Functions. (line 198) +* differences between gawk and awk: String Functions. (line 193) * differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV. (line 88) * differences in awk and gawk, ARGIND variable: Auto-set. (line 40) @@ -30351,7 +30352,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 261) + (line 256) * differences in awk and gawk, print/printf statements: Format Modifiers. (line 13) * differences in awk and gawk, PROCINFO array: Auto-set. (line 133) @@ -30365,11 +30366,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 351) + (line 346) * differences in awk and gawk, strings: Scalar Constants. (line 20) * differences in awk and gawk, strings, storing: Records. (line 191) * differences in awk and gawk, strtonum() function (gawk): String Functions. - (line 406) + (line 401) * differences in awk and gawk, SYMTAB variable: Auto-set. (line 274) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. (line 162) @@ -30511,7 +30512,7 @@ Index * extensions, common, delete to delete entire arrays: Delete. (line 39) * extensions, common, func keyword: Definition Syntax. (line 83) * extensions, common, length() applied to an array: String Functions. - (line 198) + (line 193) * extensions, common, RS as a regexp: Records. (line 120) * extensions, common, single character fields: Single Character Fields. (line 6) @@ -30775,8 +30776,8 @@ Index * gawk, function arguments and: Calling Built-in. (line 16) * gawk, hexadecimal numbers and: Nondecimal-numbers. (line 42) * gawk, IGNORECASE variable in <1>: Array Sorting Functions. - (line 81) -* gawk, IGNORECASE variable in <2>: String Functions. (line 29) + (line 83) +* gawk, IGNORECASE variable in <2>: String Functions. (line 32) * gawk, IGNORECASE variable in <3>: Array Intro. (line 91) * gawk, IGNORECASE variable in <4>: User-modified. (line 82) * gawk, IGNORECASE variable in: Case-sensitivity. (line 26) @@ -30830,7 +30831,7 @@ Index * gawkextlib project: gawkextlib. (line 6) * General Public License (GPL): Glossary. (line 314) * General Public License, See GPL: Manual History. (line 11) -* gensub() function (gawk) <1>: String Functions. (line 86) +* gensub() function (gawk) <1>: String Functions. (line 81) * gensub() function (gawk): Using Constant Regexps. (line 43) * gensub() function (gawk), escape processing: Gory Details. (line 6) @@ -30897,10 +30898,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 139) +* gsub() function <1>: String Functions. (line 134) * gsub() function: Using Constant Regexps. (line 43) -* gsub() function, arguments of: String Functions. (line 464) +* gsub() function, arguments of: String Functions. (line 459) * gsub() function, escape processing: Gory Details. (line 6) * h debugger command (alias for help): Miscellaneous Debugger Commands. (line 66) @@ -30935,13 +30936,13 @@ Index * igawk.sh program: Igawk Program. (line 124) * ignore debugger command: Breakpoint Control. (line 87) * IGNORECASE variable <1>: Array Sorting Functions. - (line 81) -* IGNORECASE variable <2>: String Functions. (line 29) + (line 83) +* IGNORECASE variable <2>: String Functions. (line 32) * IGNORECASE variable <3>: Array Intro. (line 91) * IGNORECASE variable <4>: User-modified. (line 82) * IGNORECASE variable: Case-sensitivity. (line 26) * IGNORECASE variable, array sorting and: Array Sorting Functions. - (line 81) + (line 83) * IGNORECASE variable, array subscripts and: Array Intro. (line 91) * IGNORECASE variable, in example programs: Library Functions. (line 53) @@ -30960,7 +30961,7 @@ Index * in operator: Comparison Operators. (line 11) * increment operators: Increment Ops. (line 6) -* index() function: String Functions. (line 155) +* index() function: String Functions. (line 150) * indexing arrays: Array Intro. (line 49) * indirect function calls: Indirect Calls. (line 6) * infinite precision: Arbitrary Precision Arithmetic. @@ -31072,7 +31073,7 @@ Index (line 11) * left shift, bitwise: Bitwise Functions. (line 32) * leftmost longest match: Multiple Line. (line 26) -* length() function: String Functions. (line 168) +* length() function: String Functions. (line 163) * Lesser General Public License (LGPL): Glossary. (line 405) * LGPL (Lesser General Public License): Glossary. (line 405) * libmawk: Other Versions. (line 120) @@ -31154,9 +31155,9 @@ Index (line 6) * marked strings, extracting: String Extraction. (line 6) * Marx, Groucho: Increment Ops. (line 60) -* match() function: String Functions. (line 208) +* match() function: String Functions. (line 203) * match() function, RSTART/RLENGTH variables: String Functions. - (line 225) + (line 220) * matching, expressions, See comparison expressions: Typing and Comparison. (line 9) * matching, leftmost longest: Multiple Line. (line 26) @@ -31349,7 +31350,7 @@ Index * parentheses () <1>: Profiling. (line 138) * parentheses (): Regexp Operators. (line 79) * password file: Passwd Functions. (line 16) -* patsplit() function (gawk): String Functions. (line 295) +* patsplit() function (gawk): String Functions. (line 290) * patterns: Patterns and Actions. (line 6) * patterns, comparison expressions as: Expression Patterns. (line 14) @@ -31402,7 +31403,7 @@ Index * 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 177) +* portability, length() function: String Functions. (line 172) * portability, new awk vs. old awk: Conversion. (line 55) * portability, next statement in user-defined functions: Pass By Value/Reference. (line 91) @@ -31410,7 +31411,7 @@ Index * portability, operators: Increment Ops. (line 60) * portability, operators, not in POSIX awk: Precedence. (line 98) * portability, POSIXLY_CORRECT environment variable: Options. (line 353) -* portability, substr() function: String Functions. (line 514) +* portability, substr() function: String Functions. (line 509) * 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. @@ -31447,7 +31448,7 @@ Index * POSIX awk, FS variable and: User-modified. (line 66) * POSIX awk, function keyword in: Definition Syntax. (line 83) * POSIX awk, functions and, gsub()/sub(): Gory Details. (line 54) -* POSIX awk, functions and, length(): String Functions. (line 177) +* POSIX awk, functions and, length(): String Functions. (line 172) * POSIX awk, GNU long options and: Options. (line 15) * POSIX awk, interval expressions in: Regexp Operators. (line 135) * POSIX awk, next/nextfile statements and: Next Statement. (line 45) @@ -31597,7 +31598,7 @@ Index * redirection of input: Getline/File. (line 6) * redirection of output: Redirection. (line 6) * reference counting, sorting arrays: Array Sorting Functions. - (line 75) + (line 77) * regexp constants <1>: Comparison Operators. (line 103) * regexp constants <2>: Regexp Constants. (line 6) @@ -31666,7 +31667,7 @@ Index * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 55) * RLENGTH variable: Auto-set. (line 253) -* RLENGTH variable, match() function and: String Functions. (line 225) +* RLENGTH variable, match() function and: String Functions. (line 220) * Robbins, Arnold <1>: Future Extensions. (line 6) * Robbins, Arnold <2>: Bugs. (line 32) * Robbins, Arnold <3>: Contributors. (line 130) @@ -31693,7 +31694,7 @@ Index * RS variable, multiline records and: Multiple Line. (line 17) * rshift() function (gawk): Bitwise Functions. (line 52) * RSTART variable: Auto-set. (line 259) -* RSTART variable, match() function and: String Functions. (line 225) +* RSTART variable, match() function and: String Functions. (line 220) * RT variable <1>: Auto-set. (line 266) * RT variable <2>: Getline/Variable/File. (line 10) @@ -31723,7 +31724,7 @@ Index * search paths, for source files <2>: PC Using. (line 11) * search paths, for source files <3>: Igawk Program. (line 368) * search paths, for source files: AWKPATH Variable. (line 6) -* searching: String Functions. (line 155) +* searching: String Functions. (line 150) * searching, files for regular expressions: Egrep Program. (line 6) * searching, for words: Dupword Program. (line 6) * sed utility <1>: Glossary. (line 12) @@ -31848,10 +31849,10 @@ Index * sparse arrays: Array Intro. (line 70) * Spencer, Henry: Glossary. (line 12) * split utility: Split Program. (line 6) -* split() function: String Functions. (line 317) +* split() function: String Functions. (line 312) * split() function, array elements, deleting: Delete. (line 61) * split.awk program: Split Program. (line 30) -* sprintf() function <1>: String Functions. (line 382) +* sprintf() function <1>: String Functions. (line 377) * sprintf() function: OFMT. (line 15) * sprintf() function, OFMT variable and: User-modified. (line 124) * sprintf() function, print/printf statements and: Round Function. @@ -31897,14 +31898,14 @@ Index * strings, null: Regexp Field Splitting. (line 43) * strings, numeric: Variable Typing. (line 6) -* strings, splitting: String Functions. (line 337) -* strtonum() function (gawk): String Functions. (line 389) +* strings, splitting: String Functions. (line 332) +* strtonum() function (gawk): String Functions. (line 384) * strtonum() function (gawk), --non-decimal-data option and: Nondecimal Data. (line 36) -* sub() function <1>: String Functions. (line 410) +* sub() function <1>: String Functions. (line 405) * sub() function: Using Constant Regexps. (line 43) -* sub() function, arguments of: String Functions. (line 464) +* sub() function, arguments of: String Functions. (line 459) * sub() function, escape processing: Gory Details. (line 6) * subscript separators: User-modified. (line 156) * subscripts in arrays, multidimensional: Multidimensional. (line 10) @@ -31916,7 +31917,7 @@ Index (line 6) * SUBSEP variable: User-modified. (line 156) * SUBSEP variable, multidimensional arrays: Multidimensional. (line 16) -* substr() function: String Functions. (line 483) +* substr() function: String Functions. (line 478) * Sumner, Andrew: Other Versions. (line 64) * switch statement: Switch Statement. (line 6) * SYMTAB array: Auto-set. (line 274) @@ -31971,8 +31972,8 @@ Index * timestamps, converting dates to: Time Functions. (line 75) * timestamps, formatted: Getlocaltime Function. (line 6) -* tolower() function: String Functions. (line 525) -* toupper() function: String Functions. (line 531) +* tolower() function: String Functions. (line 520) +* toupper() function: String Functions. (line 526) * tr utility: Translate Program. (line 6) * trace debugger command: Miscellaneous Debugger Commands. (line 108) @@ -31995,9 +31996,9 @@ Index * troubleshooting, gawk, fatal errors, function arguments: Calling Built-in. (line 16) * troubleshooting, getline function: File Checking. (line 25) -* troubleshooting, gsub()/sub() functions: String Functions. (line 474) -* troubleshooting, match() function: String Functions. (line 290) -* troubleshooting, patsplit() function: String Functions. (line 313) +* troubleshooting, gsub()/sub() functions: String Functions. (line 469) +* troubleshooting, match() function: String Functions. (line 285) +* troubleshooting, patsplit() function: String Functions. (line 308) * troubleshooting, print statement, omitting commas: Print Examples. (line 31) * troubleshooting, printing: Redirection. (line 118) @@ -32006,7 +32007,7 @@ Index * troubleshooting, regexp constants vs. string constants: Computed Regexps. (line 38) * troubleshooting, string concatenation: Concatenation. (line 26) -* troubleshooting, substr() function: String Functions. (line 501) +* troubleshooting, substr() function: String Functions. (line 496) * troubleshooting, system() function: I/O Functions. (line 94) * troubleshooting, typographical errors, global variables: Options. (line 112) @@ -32371,325 +32372,324 @@ Node: Assigning Elements439178 Node: Array Example439669 Node: Scanning an Array441401 Node: Controlling Scanning443715 -Ref: Controlling Scanning-Footnote-1448638 -Node: Delete448954 -Ref: Delete-Footnote-1451719 -Node: Numeric Array Subscripts451776 -Node: Uninitialized Subscripts453959 -Node: Multidimensional455586 -Node: Multiscanning458678 -Node: Arrays of Arrays460267 -Node: Functions464907 -Node: Built-in465726 -Node: Calling Built-in466804 -Node: Numeric Functions468792 -Ref: Numeric Functions-Footnote-1472624 -Ref: Numeric Functions-Footnote-2472981 -Ref: Numeric Functions-Footnote-3473029 -Node: String Functions473298 -Ref: String Functions-Footnote-1496856 -Ref: String Functions-Footnote-2496985 -Ref: String Functions-Footnote-3497233 -Node: Gory Details497320 -Ref: table-sub-escapes498999 -Ref: table-sub-posix-92500353 -Ref: table-sub-proposed501704 -Ref: table-posix-sub503058 -Ref: table-gensub-escapes504603 -Ref: Gory Details-Footnote-1505779 -Ref: Gory Details-Footnote-2505830 -Node: I/O Functions505981 -Ref: I/O Functions-Footnote-1512966 -Node: Time Functions513113 -Ref: Time Functions-Footnote-1524046 -Ref: Time Functions-Footnote-2524114 -Ref: Time Functions-Footnote-3524272 -Ref: Time Functions-Footnote-4524383 -Ref: Time Functions-Footnote-5524495 -Ref: Time Functions-Footnote-6524722 -Node: Bitwise Functions524988 -Ref: table-bitwise-ops525550 -Ref: Bitwise Functions-Footnote-1529771 -Node: Type Functions529955 -Node: I18N Functions531106 -Node: User-defined532733 -Node: Definition Syntax533537 -Ref: Definition Syntax-Footnote-1538447 -Node: Function Example538516 -Node: Function Caveats541110 -Node: Calling A Function541531 -Node: Variable Scope542646 -Node: Pass By Value/Reference545609 -Node: Return Statement549117 -Node: Dynamic Typing552098 -Node: Indirect Calls553029 -Node: Library Functions562714 -Ref: Library Functions-Footnote-1566227 -Ref: Library Functions-Footnote-2566370 -Node: Library Names566541 -Ref: Library Names-Footnote-1570012 -Ref: Library Names-Footnote-2570232 -Node: General Functions570318 -Node: Strtonum Function571346 -Node: Assert Function574276 -Node: Round Function577602 -Node: Cliff Random Function579145 -Node: Ordinal Functions580161 -Ref: Ordinal Functions-Footnote-1583231 -Ref: Ordinal Functions-Footnote-2583483 -Node: Join Function583692 -Ref: Join Function-Footnote-1585463 -Node: Getlocaltime Function585663 -Node: Readfile Function589404 -Node: Data File Management591243 -Node: Filetrans Function591875 -Node: Rewind Function595944 -Node: File Checking597331 -Node: Empty Files598425 -Node: Ignoring Assigns600655 -Node: Getopt Function602208 -Ref: Getopt Function-Footnote-1613511 -Node: Passwd Functions613714 -Ref: Passwd Functions-Footnote-1622689 -Node: Group Functions622777 -Node: Walking Arrays630861 -Node: Sample Programs632998 -Node: Running Examples633672 -Node: Clones634400 -Node: Cut Program635624 -Node: Egrep Program645469 -Ref: Egrep Program-Footnote-1653242 -Node: Id Program653352 -Node: Split Program656968 -Ref: Split Program-Footnote-1660487 -Node: Tee Program660615 -Node: Uniq Program663418 -Node: Wc Program670847 -Ref: Wc Program-Footnote-1675113 -Ref: Wc Program-Footnote-2675313 -Node: Miscellaneous Programs675405 -Node: Dupword Program676593 -Node: Alarm Program678624 -Node: Translate Program683377 -Ref: Translate Program-Footnote-1687764 -Ref: Translate Program-Footnote-2688012 -Node: Labels Program688146 -Ref: Labels Program-Footnote-1691517 -Node: Word Sorting691601 -Node: History Sorting695485 -Node: Extract Program697324 -Ref: Extract Program-Footnote-1704827 -Node: Simple Sed704955 -Node: Igawk Program708017 -Ref: Igawk Program-Footnote-1723174 -Ref: Igawk Program-Footnote-2723375 -Node: Anagram Program723513 -Node: Signature Program726581 -Node: Advanced Features727681 -Node: Nondecimal Data729567 -Node: Array Sorting731150 -Node: Controlling Array Traversal731847 -Node: Array Sorting Functions740085 -Ref: Array Sorting Functions-Footnote-1743759 -Ref: Array Sorting Functions-Footnote-2743852 -Node: Two-way I/O744046 -Ref: Two-way I/O-Footnote-1749478 -Node: TCP/IP Networking749548 -Node: Profiling752392 -Node: Internationalization759889 -Node: I18N and L10N761314 -Node: Explaining gettext762000 -Ref: Explaining gettext-Footnote-1767068 -Ref: Explaining gettext-Footnote-2767252 -Node: Programmer i18n767417 -Node: Translator i18n771619 -Node: String Extraction772412 -Ref: String Extraction-Footnote-1773373 -Node: Printf Ordering773459 -Ref: Printf Ordering-Footnote-1776243 -Node: I18N Portability776307 -Ref: I18N Portability-Footnote-1778756 -Node: I18N Example778819 -Ref: I18N Example-Footnote-1781457 -Node: Gawk I18N781529 -Node: Debugger782150 -Node: Debugging783121 -Node: Debugging Concepts783554 -Node: Debugging Terms785410 -Node: Awk Debugging788007 -Node: Sample Debugging Session788899 -Node: Debugger Invocation789419 -Node: Finding The Bug790751 -Node: List of Debugger Commands797239 -Node: Breakpoint Control798573 -Node: Debugger Execution Control802237 -Node: Viewing And Changing Data805597 -Node: Execution Stack808953 -Node: Debugger Info810420 -Node: Miscellaneous Debugger Commands814402 -Node: Readline Support819578 -Node: Limitations820409 -Node: Arbitrary Precision Arithmetic822661 -Ref: Arbitrary Precision Arithmetic-Footnote-1824310 -Node: General Arithmetic824458 -Node: Floating Point Issues826178 -Node: String Conversion Precision827059 -Ref: String Conversion Precision-Footnote-1828764 -Node: Unexpected Results828873 -Node: POSIX Floating Point Problems831026 -Ref: POSIX Floating Point Problems-Footnote-1834851 -Node: Integer Programming834889 -Node: Floating-point Programming836628 -Ref: Floating-point Programming-Footnote-1842959 -Ref: Floating-point Programming-Footnote-2843229 -Node: Floating-point Representation843493 -Node: Floating-point Context844658 -Ref: table-ieee-formats845497 -Node: Rounding Mode846881 -Ref: table-rounding-modes847360 -Ref: Rounding Mode-Footnote-1850375 -Node: Gawk and MPFR850554 -Node: Arbitrary Precision Floats851809 -Ref: Arbitrary Precision Floats-Footnote-1854252 -Node: Setting Precision854568 -Ref: table-predefined-precision-strings855254 -Node: Setting Rounding Mode857399 -Ref: table-gawk-rounding-modes857803 -Node: Floating-point Constants858990 -Node: Changing Precision860419 -Ref: Changing Precision-Footnote-1861816 -Node: Exact Arithmetic861990 -Node: Arbitrary Precision Integers865128 -Ref: Arbitrary Precision Integers-Footnote-1868146 -Node: Dynamic Extensions868293 -Node: Extension Intro869751 -Node: Plugin License871016 -Node: Extension Mechanism Outline871701 -Ref: load-extension872118 -Ref: load-new-function873596 -Ref: call-new-function874591 -Node: Extension API Description876606 -Node: Extension API Functions Introduction877819 -Node: General Data Types882685 -Ref: General Data Types-Footnote-1888284 -Node: Requesting Values888583 -Ref: table-value-types-returned889314 -Node: Constructor Functions890268 -Node: Registration Functions893288 -Node: Extension Functions893973 -Node: Exit Callback Functions896198 -Node: Extension Version String897447 -Node: Input Parsers898097 -Node: Output Wrappers907854 -Node: Two-way processors912364 -Node: Printing Messages914572 -Ref: Printing Messages-Footnote-1915649 -Node: Updating `ERRNO'915801 -Node: Accessing Parameters916540 -Node: Symbol Table Access917770 -Node: Symbol table by name918282 -Node: Symbol table by cookie920029 -Ref: Symbol table by cookie-Footnote-1924159 -Node: Cached values924222 -Ref: Cached values-Footnote-1927671 -Node: Array Manipulation927762 -Ref: Array Manipulation-Footnote-1928860 -Node: Array Data Types928899 -Ref: Array Data Types-Footnote-1931602 -Node: Array Functions931694 -Node: Flattening Arrays935460 -Node: Creating Arrays942312 -Node: Extension API Variables947037 -Node: Extension Versioning947673 -Node: Extension API Informational Variables949574 -Node: Extension API Boilerplate950660 -Node: Finding Extensions954464 -Node: Extension Example955024 -Node: Internal File Description955754 -Node: Internal File Ops959845 -Ref: Internal File Ops-Footnote-1971353 -Node: Using Internal File Ops971493 -Ref: Using Internal File Ops-Footnote-1973846 -Node: Extension Samples974112 -Node: Extension Sample File Functions975636 -Node: Extension Sample Fnmatch984121 -Node: Extension Sample Fork985847 -Node: Extension Sample Inplace987065 -Node: Extension Sample Ord988843 -Node: Extension Sample Readdir989679 -Node: Extension Sample Revout991211 -Node: Extension Sample Rev2way991804 -Node: Extension Sample Read write array992494 -Node: Extension Sample Readfile994377 -Node: Extension Sample API Tests995195 -Node: Extension Sample Time995720 -Node: gawkextlib997084 -Node: Language History999844 -Node: V7/SVR3.11001366 -Node: SVR41003686 -Node: POSIX1005128 -Node: BTL1006514 -Node: POSIX/GNU1007248 -Node: Common Extensions1012783 -Node: Ranges and Locales1014089 -Ref: Ranges and Locales-Footnote-11018707 -Ref: Ranges and Locales-Footnote-21018734 -Ref: Ranges and Locales-Footnote-31018994 -Node: Contributors1019215 -Node: Installation1024290 -Node: Gawk Distribution1025184 -Node: Getting1025668 -Node: Extracting1026494 -Node: Distribution contents1028186 -Node: Unix Installation1033706 -Node: Quick Installation1034323 -Node: Additional Configuration Options1036767 -Node: Configuration Philosophy1038244 -Node: Non-Unix Installation1040598 -Node: PC Installation1041056 -Node: PC Binary Installation1042355 -Node: PC Compiling1044203 -Node: PC Testing1047147 -Node: PC Using1048323 -Node: Cygwin1052508 -Node: MSYS1053508 -Node: VMS Installation1054022 -Node: VMS Compilation1054625 -Ref: VMS Compilation-Footnote-11055632 -Node: VMS Installation Details1055690 -Node: VMS Running1057325 -Node: VMS Old Gawk1058932 -Node: Bugs1059406 -Node: Other Versions1063262 -Node: Notes1069346 -Node: Compatibility Mode1070146 -Node: Additions1070929 -Node: Accessing The Source1071856 -Node: Adding Code1073296 -Node: New Ports1079341 -Node: Derived Files1083476 -Ref: Derived Files-Footnote-11088797 -Ref: Derived Files-Footnote-21088831 -Ref: Derived Files-Footnote-31089431 -Node: Future Extensions1089529 -Node: Implementation Limitations1090106 -Node: Extension Design1091358 -Node: Old Extension Problems1092512 -Ref: Old Extension Problems-Footnote-11094020 -Node: Extension New Mechanism Goals1094077 -Ref: Extension New Mechanism Goals-Footnote-11097442 -Node: Extension Other Design Decisions1097628 -Node: Extension Future Growth1099734 -Node: Old Extension Mechanism1100570 -Node: Basic Concepts1102310 -Node: Basic High Level1102991 -Ref: figure-general-flow1103262 -Ref: figure-process-flow1103861 -Ref: Basic High Level-Footnote-11107090 -Node: Basic Data Typing1107275 -Node: Glossary1110630 -Node: Copying1136092 -Node: GNU Free Documentation License1173649 -Node: Index1198786 +Ref: Controlling Scanning-Footnote-1448802 +Node: Delete449118 +Ref: Delete-Footnote-1451883 +Node: Numeric Array Subscripts451940 +Node: Uninitialized Subscripts454123 +Node: Multidimensional455750 +Node: Multiscanning458842 +Node: Arrays of Arrays460431 +Node: Functions465071 +Node: Built-in465890 +Node: Calling Built-in466968 +Node: Numeric Functions468956 +Ref: Numeric Functions-Footnote-1472788 +Ref: Numeric Functions-Footnote-2473145 +Ref: Numeric Functions-Footnote-3473193 +Node: String Functions473462 +Ref: String Functions-Footnote-1496382 +Ref: String Functions-Footnote-2496511 +Ref: String Functions-Footnote-3496759 +Node: Gory Details496846 +Ref: table-sub-escapes498525 +Ref: table-sub-posix-92499879 +Ref: table-sub-proposed501230 +Ref: table-posix-sub502584 +Ref: table-gensub-escapes504129 +Ref: Gory Details-Footnote-1505305 +Ref: Gory Details-Footnote-2505356 +Node: I/O Functions505507 +Ref: I/O Functions-Footnote-1512492 +Node: Time Functions512639 +Ref: Time Functions-Footnote-1523572 +Ref: Time Functions-Footnote-2523640 +Ref: Time Functions-Footnote-3523798 +Ref: Time Functions-Footnote-4523909 +Ref: Time Functions-Footnote-5524021 +Ref: Time Functions-Footnote-6524248 +Node: Bitwise Functions524514 +Ref: table-bitwise-ops525076 +Ref: Bitwise Functions-Footnote-1529297 +Node: Type Functions529481 +Node: I18N Functions530632 +Node: User-defined532259 +Node: Definition Syntax533063 +Ref: Definition Syntax-Footnote-1537973 +Node: Function Example538042 +Node: Function Caveats540636 +Node: Calling A Function541057 +Node: Variable Scope542172 +Node: Pass By Value/Reference545135 +Node: Return Statement548643 +Node: Dynamic Typing551624 +Node: Indirect Calls552555 +Node: Library Functions562240 +Ref: Library Functions-Footnote-1565753 +Ref: Library Functions-Footnote-2565896 +Node: Library Names566067 +Ref: Library Names-Footnote-1569538 +Ref: Library Names-Footnote-2569758 +Node: General Functions569844 +Node: Strtonum Function570872 +Node: Assert Function573802 +Node: Round Function577128 +Node: Cliff Random Function578671 +Node: Ordinal Functions579687 +Ref: Ordinal Functions-Footnote-1582757 +Ref: Ordinal Functions-Footnote-2583009 +Node: Join Function583218 +Ref: Join Function-Footnote-1584989 +Node: Getlocaltime Function585189 +Node: Readfile Function588930 +Node: Data File Management590769 +Node: Filetrans Function591401 +Node: Rewind Function595470 +Node: File Checking596857 +Node: Empty Files597951 +Node: Ignoring Assigns600181 +Node: Getopt Function601734 +Ref: Getopt Function-Footnote-1613037 +Node: Passwd Functions613240 +Ref: Passwd Functions-Footnote-1622215 +Node: Group Functions622303 +Node: Walking Arrays630387 +Node: Sample Programs632524 +Node: Running Examples633198 +Node: Clones633926 +Node: Cut Program635150 +Node: Egrep Program644995 +Ref: Egrep Program-Footnote-1652768 +Node: Id Program652878 +Node: Split Program656494 +Ref: Split Program-Footnote-1660013 +Node: Tee Program660141 +Node: Uniq Program662944 +Node: Wc Program670373 +Ref: Wc Program-Footnote-1674639 +Ref: Wc Program-Footnote-2674839 +Node: Miscellaneous Programs674931 +Node: Dupword Program676119 +Node: Alarm Program678150 +Node: Translate Program682903 +Ref: Translate Program-Footnote-1687290 +Ref: Translate Program-Footnote-2687538 +Node: Labels Program687672 +Ref: Labels Program-Footnote-1691043 +Node: Word Sorting691127 +Node: History Sorting695011 +Node: Extract Program696850 +Ref: Extract Program-Footnote-1704353 +Node: Simple Sed704481 +Node: Igawk Program707543 +Ref: Igawk Program-Footnote-1722700 +Ref: Igawk Program-Footnote-2722901 +Node: Anagram Program723039 +Node: Signature Program726107 +Node: Advanced Features727207 +Node: Nondecimal Data729093 +Node: Array Sorting730676 +Node: Controlling Array Traversal731373 +Node: Array Sorting Functions739657 +Ref: Array Sorting Functions-Footnote-1743526 +Node: Two-way I/O743720 +Ref: Two-way I/O-Footnote-1749152 +Node: TCP/IP Networking749222 +Node: Profiling752066 +Node: Internationalization759563 +Node: I18N and L10N760988 +Node: Explaining gettext761674 +Ref: Explaining gettext-Footnote-1766742 +Ref: Explaining gettext-Footnote-2766926 +Node: Programmer i18n767091 +Node: Translator i18n771293 +Node: String Extraction772086 +Ref: String Extraction-Footnote-1773047 +Node: Printf Ordering773133 +Ref: Printf Ordering-Footnote-1775917 +Node: I18N Portability775981 +Ref: I18N Portability-Footnote-1778430 +Node: I18N Example778493 +Ref: I18N Example-Footnote-1781131 +Node: Gawk I18N781203 +Node: Debugger781824 +Node: Debugging782795 +Node: Debugging Concepts783228 +Node: Debugging Terms785084 +Node: Awk Debugging787681 +Node: Sample Debugging Session788573 +Node: Debugger Invocation789093 +Node: Finding The Bug790425 +Node: List of Debugger Commands796913 +Node: Breakpoint Control798247 +Node: Debugger Execution Control801911 +Node: Viewing And Changing Data805271 +Node: Execution Stack808627 +Node: Debugger Info810094 +Node: Miscellaneous Debugger Commands814076 +Node: Readline Support819252 +Node: Limitations820083 +Node: Arbitrary Precision Arithmetic822335 +Ref: Arbitrary Precision Arithmetic-Footnote-1823984 +Node: General Arithmetic824132 +Node: Floating Point Issues825852 +Node: String Conversion Precision826733 +Ref: String Conversion Precision-Footnote-1828438 +Node: Unexpected Results828547 +Node: POSIX Floating Point Problems830700 +Ref: POSIX Floating Point Problems-Footnote-1834525 +Node: Integer Programming834563 +Node: Floating-point Programming836302 +Ref: Floating-point Programming-Footnote-1842633 +Ref: Floating-point Programming-Footnote-2842903 +Node: Floating-point Representation843167 +Node: Floating-point Context844332 +Ref: table-ieee-formats845171 +Node: Rounding Mode846555 +Ref: table-rounding-modes847034 +Ref: Rounding Mode-Footnote-1850049 +Node: Gawk and MPFR850228 +Node: Arbitrary Precision Floats851483 +Ref: Arbitrary Precision Floats-Footnote-1853926 +Node: Setting Precision854242 +Ref: table-predefined-precision-strings854928 +Node: Setting Rounding Mode857073 +Ref: table-gawk-rounding-modes857477 +Node: Floating-point Constants858664 +Node: Changing Precision860093 +Ref: Changing Precision-Footnote-1861490 +Node: Exact Arithmetic861664 +Node: Arbitrary Precision Integers864802 +Ref: Arbitrary Precision Integers-Footnote-1867820 +Node: Dynamic Extensions867967 +Node: Extension Intro869425 +Node: Plugin License870690 +Node: Extension Mechanism Outline871375 +Ref: load-extension871792 +Ref: load-new-function873270 +Ref: call-new-function874265 +Node: Extension API Description876280 +Node: Extension API Functions Introduction877493 +Node: General Data Types882359 +Ref: General Data Types-Footnote-1887958 +Node: Requesting Values888257 +Ref: table-value-types-returned888988 +Node: Constructor Functions889942 +Node: Registration Functions892962 +Node: Extension Functions893647 +Node: Exit Callback Functions895872 +Node: Extension Version String897121 +Node: Input Parsers897771 +Node: Output Wrappers907528 +Node: Two-way processors912038 +Node: Printing Messages914246 +Ref: Printing Messages-Footnote-1915323 +Node: Updating `ERRNO'915475 +Node: Accessing Parameters916214 +Node: Symbol Table Access917444 +Node: Symbol table by name917956 +Node: Symbol table by cookie919703 +Ref: Symbol table by cookie-Footnote-1923833 +Node: Cached values923896 +Ref: Cached values-Footnote-1927345 +Node: Array Manipulation927436 +Ref: Array Manipulation-Footnote-1928534 +Node: Array Data Types928573 +Ref: Array Data Types-Footnote-1931276 +Node: Array Functions931368 +Node: Flattening Arrays935134 +Node: Creating Arrays941986 +Node: Extension API Variables946711 +Node: Extension Versioning947347 +Node: Extension API Informational Variables949248 +Node: Extension API Boilerplate950334 +Node: Finding Extensions954138 +Node: Extension Example954698 +Node: Internal File Description955428 +Node: Internal File Ops959519 +Ref: Internal File Ops-Footnote-1971027 +Node: Using Internal File Ops971167 +Ref: Using Internal File Ops-Footnote-1973520 +Node: Extension Samples973786 +Node: Extension Sample File Functions975310 +Node: Extension Sample Fnmatch983795 +Node: Extension Sample Fork985521 +Node: Extension Sample Inplace986739 +Node: Extension Sample Ord988517 +Node: Extension Sample Readdir989353 +Node: Extension Sample Revout990885 +Node: Extension Sample Rev2way991478 +Node: Extension Sample Read write array992168 +Node: Extension Sample Readfile994051 +Node: Extension Sample API Tests994869 +Node: Extension Sample Time995394 +Node: gawkextlib996758 +Node: Language History999518 +Node: V7/SVR3.11001040 +Node: SVR41003360 +Node: POSIX1004802 +Node: BTL1006188 +Node: POSIX/GNU1006922 +Node: Common Extensions1012457 +Node: Ranges and Locales1013763 +Ref: Ranges and Locales-Footnote-11018381 +Ref: Ranges and Locales-Footnote-21018408 +Ref: Ranges and Locales-Footnote-31018668 +Node: Contributors1018889 +Node: Installation1023964 +Node: Gawk Distribution1024858 +Node: Getting1025342 +Node: Extracting1026168 +Node: Distribution contents1027860 +Node: Unix Installation1033380 +Node: Quick Installation1033997 +Node: Additional Configuration Options1036441 +Node: Configuration Philosophy1037918 +Node: Non-Unix Installation1040272 +Node: PC Installation1040730 +Node: PC Binary Installation1042029 +Node: PC Compiling1043877 +Node: PC Testing1046821 +Node: PC Using1047997 +Node: Cygwin1052182 +Node: MSYS1053182 +Node: VMS Installation1053696 +Node: VMS Compilation1054299 +Ref: VMS Compilation-Footnote-11055306 +Node: VMS Installation Details1055364 +Node: VMS Running1056999 +Node: VMS Old Gawk1058606 +Node: Bugs1059080 +Node: Other Versions1062936 +Node: Notes1069020 +Node: Compatibility Mode1069820 +Node: Additions1070603 +Node: Accessing The Source1071530 +Node: Adding Code1072970 +Node: New Ports1079015 +Node: Derived Files1083150 +Ref: Derived Files-Footnote-11088471 +Ref: Derived Files-Footnote-21088505 +Ref: Derived Files-Footnote-31089105 +Node: Future Extensions1089203 +Node: Implementation Limitations1089780 +Node: Extension Design1091032 +Node: Old Extension Problems1092186 +Ref: Old Extension Problems-Footnote-11093694 +Node: Extension New Mechanism Goals1093751 +Ref: Extension New Mechanism Goals-Footnote-11097116 +Node: Extension Other Design Decisions1097302 +Node: Extension Future Growth1099408 +Node: Old Extension Mechanism1100244 +Node: Basic Concepts1101984 +Node: Basic High Level1102665 +Ref: figure-general-flow1102936 +Ref: figure-process-flow1103535 +Ref: Basic High Level-Footnote-11106764 +Node: Basic Data Typing1106949 +Node: Glossary1110304 +Node: Copying1135766 +Node: GNU Free Documentation License1173323 +Node: Index1198460 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 10486cea..80638e46 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -14675,29 +14675,29 @@ Array elements are processed in arbitrary order, which is the default @command{awk} behavior. @item "@@ind_str_asc" -Order by indices compared as strings; this is the most basic sort. +Order by indices in ascending order compared as strings; this is the most basic sort. (Internally, array indices are always strings, so with @samp{a[2*5] = 1} the index is @code{"10"} rather than numeric 10.) @item "@@ind_num_asc" -Order by indices but force them to be treated as numbers in the process. +Order by indices in ascending order but force them to be treated as numbers in the process. Any index with a non-numeric value will end up positioned as if it were zero. @item "@@val_type_asc" -Order by element values rather than indices. +Order by element values in ascending order (rather than by indices). Ordering is by the type assigned to the element (@pxref{Typing and Comparison}). All numeric values come before all string values, which in turn come before all subarrays. (Subarrays have not been described yet; -@pxref{Arrays of Arrays}). +@pxref{Arrays of Arrays}.) @item "@@val_str_asc" -Order by element values rather than by indices. Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as strings. Subarrays, if present, come out last. @item "@@val_num_asc" -Order by element values rather than by indices. Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as numbers. Subarrays, if present, come out last. When numeric values are equal, the string values are used to provide an ordering: this guarantees consistent results across different @@ -14710,13 +14710,14 @@ across different environments.} which @command{gawk} uses internally to perform the sorting. @item "@@ind_str_desc" -Reverse order from the most basic sort. +String indices ordered from high to low. @item "@@ind_num_desc" Numeric indices ordered from high to low. @item "@@val_type_desc" -Element values, based on type, in descending order. +Element values, based on type, ordered from high to low. +Subarrays, if present, come out first. @item "@@val_str_desc" Element values, treated as strings, ordered from high to low. @@ -15573,15 +15574,16 @@ sequences of random numbers. @node String Functions @subsection String-Manipulation Functions -The functions in this @value{SECTION} look at or change the text of one or more -strings. -@code{gawk} understands locales (@pxref{Locales}), and does all string processing in terms of -@emph{characters}, not @emph{bytes}. This distinction is particularly important -to understand for locales where one character -may be represented by multiple bytes. Thus, for example, @code{length()} -returns the number of characters in a string, and not the number of bytes -used to represent those characters, Similarly, @code{index()} works with -character indices, and not byte indices. +The functions in this @value{SECTION} look at or change the text of one +or more strings. + +@code{gawk} understands locales (@pxref{Locales}), and does all +string processing in terms of @emph{characters}, not @emph{bytes}. +This distinction is particularly important to understand for locales +where one character may be represented by multiple bytes. Thus, for +example, @code{length()} returns the number of characters in a string, +and not the number of bytes used to represent those characters. Similarly, +@code{index()} works with character indices, and not byte indices. In the following list, optional parameters are enclosed in square brackets@w{ ([ ]).} Several functions perform string substitution; the full discussion is @@ -15598,30 +15600,32 @@ pound sign@w{ (@samp{#}):} @table @code @item asort(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # +@itemx asorti(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # +@cindex @code{asorti()} function (@command{gawk}) @cindex arrays, elements, retrieving number of @cindex @code{asort()} function (@command{gawk}) @cindex @command{gawk}, @code{IGNORECASE} variable in @cindex @code{IGNORECASE} variable -Return the number of elements in the array @var{source}. -@command{gawk} sorts the contents of @var{source} -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 -sorted, leaving the indices of @var{source} unchanged. The optional third -argument @var{how} is a string which controls the rule for comparing values, -and the sort direction. A single space is required between the -comparison mode, @samp{string} or @samp{number}, and the direction specification, -@samp{ascending} or @samp{descending}. You can omit direction and/or mode -in which case it will default to @samp{ascending} and @samp{string}, respectively. -An empty string "" is the same as the default @code{"ascending string"} -for the value of @var{how}. If the @samp{source} array contains subarrays as values, -they will come out last(first) in the @samp{dest} array for @samp{ascending}(@samp{descending}) -order specification. The value of @code{IGNORECASE} affects the sorting. -The third argument can also be a user-defined function name in which case -the value returned by the function is used to order the array elements -before constructing the result array. -@xref{Array Sorting Functions}, for more information. +These two functions are similar in behavior, so they are described +together. + +@quotation NOTE +The following description ignores the third argument, @var{how}, since it +requires understanding features that we have not discussed yet. Thus, +the discussion here is a deliberate simplification. (We do provide all +the details later on: @xref{Array Sorting Functions}, for the full story.) +@end quotation + +Both functions return the number of elements in the array @var{source}. +For @command{asort()}, @command{gawk} sorts the values of @var{source} +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 sorted, leaving the indices of @var{source} unchanged. + +When comparing strings, @code{IGNORECASE} affects the sorting. If the +@var{source} array contains subarrays as values (@pxref{Arrays of +Arrays}), they will come last, after all scalar values. For example, if the contents of @code{a} are as follows: @@ -15647,29 +15651,19 @@ a[2] = "de" a[3] = "sac" @end example -In order to reverse the direction of the sorted results in the above example, -@code{asort()} can be called with three arguments as follows: +The @code{asorti()} function works similarly to @code{asort()}, however, +the @emph{indices} are sorted, instead of the values. Thus, in the +previous example, starting with the same initial set of indices and +values in @code{a}, calling @samp{asorti(a)} would yield: @example -asort(a, a, "descending") +a[1] = "first" +a[2] = "last" +a[3] = "middle" @end example -The @code{asort()} function is described in more detail in -@ref{Array Sorting Functions}. -@code{asort()} is a @command{gawk} extension; it is not available -in compatibility mode (@pxref{Options}). - -@item asorti(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # -@cindex @code{asorti()} function (@command{gawk}) -Return the number of elements in the array @var{source}. -It works similarly to @code{asort()}, however, the @emph{indices} -are sorted, instead of the values. (Here too, -@code{IGNORECASE} affects the sorting.) - -The @code{asorti()} function is described in more detail in -@ref{Array Sorting Functions}. -@code{asorti()} is a @command{gawk} extension; it is not available -in compatibility mode (@pxref{Options}). +@code{asort()} and @code{asorti()} are @command{gawk} extensions; they +are 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}) @@ -25243,7 +25237,7 @@ ordered data: @example function cmp_randomize(i1, v1, i2, v2) @{ - # random order + # random order (caution: this may never terminate!) return (2 - 4 * rand()) @} @end example @@ -25258,7 +25252,7 @@ with otherwise equal values is to include the indices in the comparison rules. Note that doing this may make the loop traversal less efficient, so consider it only if necessary. The following comparison functions force a deterministic order, and are based on the fact that the -indices of two elements are never equal: +(string) indices of two elements are never equal: @example function cmp_numeric(i1, v1, i2, v2) @@ -25317,15 +25311,14 @@ sorted array traversal is not the default. @cindex arrays, sorting @cindex @code{asort()} function (@command{gawk}) @cindex @code{asort()} function (@command{gawk}), arrays@comma{} sorting +@cindex @code{asorti()} function (@command{gawk}) +@cindex @code{asorti()} function (@command{gawk}), arrays@comma{} sorting @cindex sort function, arrays, sorting -In most @command{awk} implementations, sorting an array requires -writing a @code{sort()} function. -While this can be educational for exploring different sorting algorithms, -usually that's not the point of the program. -@command{gawk} provides the built-in @code{asort()} -and @code{asorti()} functions -(@pxref{String Functions}) -for sorting arrays. For example: +In most @command{awk} implementations, sorting an array requires writing +a @code{sort()} function. While this can be educational for exploring +different sorting algorithms, usually that's not the point of the program. +@command{gawk} provides the built-in @code{asort()} and @code{asorti()} +functions (@pxref{String Functions}) for sorting arrays. For example: @example @var{populate the array} data @@ -25338,7 +25331,7 @@ After the call to @code{asort()}, the array @code{data} is indexed from 1 to some number @var{n}, the total number of elements in @code{data}. (This count is @code{asort()}'s return value.) @code{data[1]} @value{LEQ} @code{data[2]} @value{LEQ} @code{data[3]}, and so on. -The comparison is based on the type of the elements +The default comparison is based on the type of the elements (@pxref{Typing and Comparison}). All numeric values come before all string values, which in turn come before all subarrays. @@ -25360,24 +25353,11 @@ In this case, @command{gawk} copies the @code{source} array into the @code{dest} array and then sorts @code{dest}, destroying its indices. However, the @code{source} array is not affected. -@code{asort()} accepts a third string argument to control comparison of -array elements. As with @code{PROCINFO["sorted_in"]}, this argument -may be one of the predefined names that @command{gawk} provides -(@pxref{Controlling Scanning}), or the name of a user-defined function -(@pxref{Controlling Array Traversal}). - -@quotation NOTE -In all cases, the sorted element values consist of the original -array's element values. The ability to control comparison merely -affects the way in which they are sorted. -@end quotation - Often, what's needed is to sort on the values of the @emph{indices} -instead of the values of the elements. -To do that, use the -@code{asorti()} function. The interface is identical to that of -@code{asort()}, except that the index values are used for sorting, and -become the values of the result array: +instead of the values of the elements. To do that, use the +@code{asorti()} function. The interface and behavior are identical to +that of @code{asort()}, except that the index values are used for sorting, +and become the values of the result array: @example @{ source[$0] = some_func($0) @} @@ -25394,23 +25374,35 @@ END @{ @} @end example -Similar to @code{asort()}, -in all cases, the sorted element values consist of the original -array's indices. The ability to control comparison merely -affects the way in which they are sorted. +So far, so good. Now it starts to get interesting. Both @code{asort()} +and @code{asorti()} accept a third string argument to control comparison +of array elements. In @ref{String Functions}, we ignored this third +argument; however, the time has now come to describe how this argument +affects these two functions. + +Basically, the third argument specifies how the array is to be sorted. +There are two possibilities. As with @code{PROCINFO["sorted_in"]}, +this argument may be one of the predefined names that @command{gawk} +provides (@pxref{Controlling Scanning}), or it may be the name of a +user-defined function (@pxref{Controlling Array Traversal}). + +In the latter case, @emph{the function can compare elements in any way +it chooses}, taking into account just the indices, just the values, +or both. This is extremely powerful. -Sorting the array by replacing the indices provides maximal flexibility. -To traverse the elements in decreasing order, use a loop that goes from -@var{n} down to 1, either over the elements or over the indices.@footnote{You -may also use one of the predefined sorting names that sorts in -decreasing order.} +Once the array is sorted, @code{asort()} takes the @emph{values} in +their final order, and uses them to fill in the result array, whereas +@code{asorti()} takes the @emph{indices} in their final order, and uses +them to fill in the result array. @cindex reference counting, sorting arrays +@quotation NOTE Copying array indices and elements isn't expensive in terms of memory. Internally, @command{gawk} maintains @dfn{reference counts} to data. For example, when @code{asort()} copies the first array to the second one, there is only one copy of the original array elements' data, even though both arrays use the values. +@end quotation @c Document It And Call It A Feature. Sigh. @cindex @command{gawk}, @code{IGNORECASE} variable in diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 771ef1c4..f385107b 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -14014,29 +14014,29 @@ Array elements are processed in arbitrary order, which is the default @command{awk} behavior. @item "@@ind_str_asc" -Order by indices compared as strings; this is the most basic sort. +Order by indices in ascending order compared as strings; this is the most basic sort. (Internally, array indices are always strings, so with @samp{a[2*5] = 1} the index is @code{"10"} rather than numeric 10.) @item "@@ind_num_asc" -Order by indices but force them to be treated as numbers in the process. +Order by indices in ascending order but force them to be treated as numbers in the process. Any index with a non-numeric value will end up positioned as if it were zero. @item "@@val_type_asc" -Order by element values rather than indices. +Order by element values in ascending order (rather than by indices). Ordering is by the type assigned to the element (@pxref{Typing and Comparison}). All numeric values come before all string values, which in turn come before all subarrays. (Subarrays have not been described yet; -@pxref{Arrays of Arrays}). +@pxref{Arrays of Arrays}.) @item "@@val_str_asc" -Order by element values rather than by indices. Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as strings. Subarrays, if present, come out last. @item "@@val_num_asc" -Order by element values rather than by indices. Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as numbers. Subarrays, if present, come out last. When numeric values are equal, the string values are used to provide an ordering: this guarantees consistent results across different @@ -14049,13 +14049,14 @@ across different environments.} which @command{gawk} uses internally to perform the sorting. @item "@@ind_str_desc" -Reverse order from the most basic sort. +String indices ordered from high to low. @item "@@ind_num_desc" Numeric indices ordered from high to low. @item "@@val_type_desc" -Element values, based on type, in descending order. +Element values, based on type, ordered from high to low. +Subarrays, if present, come out first. @item "@@val_str_desc" Element values, treated as strings, ordered from high to low. @@ -14912,15 +14913,16 @@ sequences of random numbers. @node String Functions @subsection String-Manipulation Functions -The functions in this @value{SECTION} look at or change the text of one or more -strings. -@code{gawk} understands locales (@pxref{Locales}), and does all string processing in terms of -@emph{characters}, not @emph{bytes}. This distinction is particularly important -to understand for locales where one character -may be represented by multiple bytes. Thus, for example, @code{length()} -returns the number of characters in a string, and not the number of bytes -used to represent those characters, Similarly, @code{index()} works with -character indices, and not byte indices. +The functions in this @value{SECTION} look at or change the text of one +or more strings. + +@code{gawk} understands locales (@pxref{Locales}), and does all +string processing in terms of @emph{characters}, not @emph{bytes}. +This distinction is particularly important to understand for locales +where one character may be represented by multiple bytes. Thus, for +example, @code{length()} returns the number of characters in a string, +and not the number of bytes used to represent those characters. Similarly, +@code{index()} works with character indices, and not byte indices. In the following list, optional parameters are enclosed in square brackets@w{ ([ ]).} Several functions perform string substitution; the full discussion is @@ -14937,30 +14939,32 @@ pound sign@w{ (@samp{#}):} @table @code @item asort(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # +@itemx asorti(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # +@cindex @code{asorti()} function (@command{gawk}) @cindex arrays, elements, retrieving number of @cindex @code{asort()} function (@command{gawk}) @cindex @command{gawk}, @code{IGNORECASE} variable in @cindex @code{IGNORECASE} variable -Return the number of elements in the array @var{source}. -@command{gawk} sorts the contents of @var{source} -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 -sorted, leaving the indices of @var{source} unchanged. The optional third -argument @var{how} is a string which controls the rule for comparing values, -and the sort direction. A single space is required between the -comparison mode, @samp{string} or @samp{number}, and the direction specification, -@samp{ascending} or @samp{descending}. You can omit direction and/or mode -in which case it will default to @samp{ascending} and @samp{string}, respectively. -An empty string "" is the same as the default @code{"ascending string"} -for the value of @var{how}. If the @samp{source} array contains subarrays as values, -they will come out last(first) in the @samp{dest} array for @samp{ascending}(@samp{descending}) -order specification. The value of @code{IGNORECASE} affects the sorting. -The third argument can also be a user-defined function name in which case -the value returned by the function is used to order the array elements -before constructing the result array. -@xref{Array Sorting Functions}, for more information. +These two functions are similar in behavior, so they are described +together. + +@quotation NOTE +The following description ignores the third argument, @var{how}, since it +requires understanding features that we have not discussed yet. Thus, +the discussion here is a deliberate simplification. (We do provide all +the details later on: @xref{Array Sorting Functions}, for the full story.) +@end quotation + +Both functions return the number of elements in the array @var{source}. +For @command{asort()}, @command{gawk} sorts the values of @var{source} +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 sorted, leaving the indices of @var{source} unchanged. + +When comparing strings, @code{IGNORECASE} affects the sorting. If the +@var{source} array contains subarrays as values (@pxref{Arrays of +Arrays}), they will come last, after all scalar values. For example, if the contents of @code{a} are as follows: @@ -14986,29 +14990,19 @@ a[2] = "de" a[3] = "sac" @end example -In order to reverse the direction of the sorted results in the above example, -@code{asort()} can be called with three arguments as follows: +The @code{asorti()} function works similarly to @code{asort()}, however, +the @emph{indices} are sorted, instead of the values. Thus, in the +previous example, starting with the same initial set of indices and +values in @code{a}, calling @samp{asorti(a)} would yield: @example -asort(a, a, "descending") +a[1] = "first" +a[2] = "last" +a[3] = "middle" @end example -The @code{asort()} function is described in more detail in -@ref{Array Sorting Functions}. -@code{asort()} is a @command{gawk} extension; it is not available -in compatibility mode (@pxref{Options}). - -@item asorti(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # -@cindex @code{asorti()} function (@command{gawk}) -Return the number of elements in the array @var{source}. -It works similarly to @code{asort()}, however, the @emph{indices} -are sorted, instead of the values. (Here too, -@code{IGNORECASE} affects the sorting.) - -The @code{asorti()} function is described in more detail in -@ref{Array Sorting Functions}. -@code{asorti()} is a @command{gawk} extension; it is not available -in compatibility mode (@pxref{Options}). +@code{asort()} and @code{asorti()} are @command{gawk} extensions; they +are 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}) @@ -24392,7 +24386,7 @@ ordered data: @example function cmp_randomize(i1, v1, i2, v2) @{ - # random order + # random order (caution: this may never terminate!) return (2 - 4 * rand()) @} @end example @@ -24407,7 +24401,7 @@ with otherwise equal values is to include the indices in the comparison rules. Note that doing this may make the loop traversal less efficient, so consider it only if necessary. The following comparison functions force a deterministic order, and are based on the fact that the -indices of two elements are never equal: +(string) indices of two elements are never equal: @example function cmp_numeric(i1, v1, i2, v2) @@ -24466,15 +24460,14 @@ sorted array traversal is not the default. @cindex arrays, sorting @cindex @code{asort()} function (@command{gawk}) @cindex @code{asort()} function (@command{gawk}), arrays@comma{} sorting +@cindex @code{asorti()} function (@command{gawk}) +@cindex @code{asorti()} function (@command{gawk}), arrays@comma{} sorting @cindex sort function, arrays, sorting -In most @command{awk} implementations, sorting an array requires -writing a @code{sort()} function. -While this can be educational for exploring different sorting algorithms, -usually that's not the point of the program. -@command{gawk} provides the built-in @code{asort()} -and @code{asorti()} functions -(@pxref{String Functions}) -for sorting arrays. For example: +In most @command{awk} implementations, sorting an array requires writing +a @code{sort()} function. While this can be educational for exploring +different sorting algorithms, usually that's not the point of the program. +@command{gawk} provides the built-in @code{asort()} and @code{asorti()} +functions (@pxref{String Functions}) for sorting arrays. For example: @example @var{populate the array} data @@ -24487,7 +24480,7 @@ After the call to @code{asort()}, the array @code{data} is indexed from 1 to some number @var{n}, the total number of elements in @code{data}. (This count is @code{asort()}'s return value.) @code{data[1]} @value{LEQ} @code{data[2]} @value{LEQ} @code{data[3]}, and so on. -The comparison is based on the type of the elements +The default comparison is based on the type of the elements (@pxref{Typing and Comparison}). All numeric values come before all string values, which in turn come before all subarrays. @@ -24509,24 +24502,11 @@ In this case, @command{gawk} copies the @code{source} array into the @code{dest} array and then sorts @code{dest}, destroying its indices. However, the @code{source} array is not affected. -@code{asort()} accepts a third string argument to control comparison of -array elements. As with @code{PROCINFO["sorted_in"]}, this argument -may be one of the predefined names that @command{gawk} provides -(@pxref{Controlling Scanning}), or the name of a user-defined function -(@pxref{Controlling Array Traversal}). - -@quotation NOTE -In all cases, the sorted element values consist of the original -array's element values. The ability to control comparison merely -affects the way in which they are sorted. -@end quotation - Often, what's needed is to sort on the values of the @emph{indices} -instead of the values of the elements. -To do that, use the -@code{asorti()} function. The interface is identical to that of -@code{asort()}, except that the index values are used for sorting, and -become the values of the result array: +instead of the values of the elements. To do that, use the +@code{asorti()} function. The interface and behavior are identical to +that of @code{asort()}, except that the index values are used for sorting, +and become the values of the result array: @example @{ source[$0] = some_func($0) @} @@ -24543,23 +24523,35 @@ END @{ @} @end example -Similar to @code{asort()}, -in all cases, the sorted element values consist of the original -array's indices. The ability to control comparison merely -affects the way in which they are sorted. +So far, so good. Now it starts to get interesting. Both @code{asort()} +and @code{asorti()} accept a third string argument to control comparison +of array elements. In @ref{String Functions}, we ignored this third +argument; however, the time has now come to describe how this argument +affects these two functions. + +Basically, the third argument specifies how the array is to be sorted. +There are two possibilities. As with @code{PROCINFO["sorted_in"]}, +this argument may be one of the predefined names that @command{gawk} +provides (@pxref{Controlling Scanning}), or it may be the name of a +user-defined function (@pxref{Controlling Array Traversal}). + +In the latter case, @emph{the function can compare elements in any way +it chooses}, taking into account just the indices, just the values, +or both. This is extremely powerful. -Sorting the array by replacing the indices provides maximal flexibility. -To traverse the elements in decreasing order, use a loop that goes from -@var{n} down to 1, either over the elements or over the indices.@footnote{You -may also use one of the predefined sorting names that sorts in -decreasing order.} +Once the array is sorted, @code{asort()} takes the @emph{values} in +their final order, and uses them to fill in the result array, whereas +@code{asorti()} takes the @emph{indices} in their final order, and uses +them to fill in the result array. @cindex reference counting, sorting arrays +@quotation NOTE Copying array indices and elements isn't expensive in terms of memory. Internally, @command{gawk} maintains @dfn{reference counts} to data. For example, when @code{asort()} copies the first array to the second one, there is only one copy of the original array elements' data, even though both arrays use the values. +@end quotation @c Document It And Call It A Feature. Sigh. @cindex @command{gawk}, @code{IGNORECASE} variable in |