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 da5ad1ad..810e329b 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 4e31aa3b..fd2813ab 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -10448,42 +10448,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. @@ -11196,13 +11199,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 @@ -11218,26 +11223,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: @@ -11255,23 +11260,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]) #' @@ -18235,7 +18233,7 @@ seemingly ordered data: function cmp_randomize(i1, v1, i2, v2) { - # random order + # random order (caution: this may never terminate!) return (2 - 4 * rand()) } @@ -18249,7 +18247,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) { @@ -18308,9 +18306,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 @@ -18325,21 +18323,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) } @@ -18354,32 +18342,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. @@ -29721,7 +29718,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) @@ -29733,7 +29730,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) @@ -29745,10 +29742,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) @@ -29990,7 +29991,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) @@ -30067,7 +30068,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) @@ -30112,7 +30113,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) @@ -30172,7 +30173,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) @@ -30183,7 +30184,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) @@ -30315,7 +30316,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) @@ -30360,7 +30361,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 142) @@ -30374,11 +30375,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 283) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. (line 162) @@ -30520,7 +30521,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) @@ -30784,8 +30785,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) @@ -30839,7 +30840,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) @@ -30906,10 +30907,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) @@ -30944,13 +30945,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) @@ -30969,7 +30970,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. @@ -31081,7 +31082,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) @@ -31163,9 +31164,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) @@ -31358,7 +31359,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) @@ -31411,7 +31412,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) @@ -31419,7 +31420,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. @@ -31456,7 +31457,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) @@ -31606,7 +31607,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) @@ -31675,7 +31676,7 @@ Index * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 55) * RLENGTH variable: Auto-set. (line 262) -* 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) @@ -31702,7 +31703,7 @@ Index * RS variable, multiline records and: Multiple Line. (line 17) * rshift() function (gawk): Bitwise Functions. (line 52) * RSTART variable: Auto-set. (line 268) -* RSTART variable, match() function and: String Functions. (line 225) +* RSTART variable, match() function and: String Functions. (line 220) * RT variable <1>: Auto-set. (line 275) * RT variable <2>: Getline/Variable/File. (line 10) @@ -31732,7 +31733,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) @@ -31857,10 +31858,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. @@ -31906,14 +31907,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) @@ -31925,7 +31926,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 283) @@ -31980,8 +31981,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) @@ -32004,9 +32005,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) @@ -32015,7 +32016,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) @@ -32380,325 +32381,324 @@ Node: Assigning Elements439570 Node: Array Example440061 Node: Scanning an Array441793 Node: Controlling Scanning444107 -Ref: Controlling Scanning-Footnote-1449030 -Node: Delete449346 -Ref: Delete-Footnote-1452111 -Node: Numeric Array Subscripts452168 -Node: Uninitialized Subscripts454351 -Node: Multidimensional455978 -Node: Multiscanning459070 -Node: Arrays of Arrays460659 -Node: Functions465299 -Node: Built-in466118 -Node: Calling Built-in467196 -Node: Numeric Functions469184 -Ref: Numeric Functions-Footnote-1473016 -Ref: Numeric Functions-Footnote-2473373 -Ref: Numeric Functions-Footnote-3473421 -Node: String Functions473690 -Ref: String Functions-Footnote-1497248 -Ref: String Functions-Footnote-2497377 -Ref: String Functions-Footnote-3497625 -Node: Gory Details497712 -Ref: table-sub-escapes499391 -Ref: table-sub-posix-92500745 -Ref: table-sub-proposed502096 -Ref: table-posix-sub503450 -Ref: table-gensub-escapes504995 -Ref: Gory Details-Footnote-1506171 -Ref: Gory Details-Footnote-2506222 -Node: I/O Functions506373 -Ref: I/O Functions-Footnote-1513358 -Node: Time Functions513505 -Ref: Time Functions-Footnote-1524438 -Ref: Time Functions-Footnote-2524506 -Ref: Time Functions-Footnote-3524664 -Ref: Time Functions-Footnote-4524775 -Ref: Time Functions-Footnote-5524887 -Ref: Time Functions-Footnote-6525114 -Node: Bitwise Functions525380 -Ref: table-bitwise-ops525942 -Ref: Bitwise Functions-Footnote-1530163 -Node: Type Functions530347 -Node: I18N Functions531498 -Node: User-defined533125 -Node: Definition Syntax533929 -Ref: Definition Syntax-Footnote-1538839 -Node: Function Example538908 -Node: Function Caveats541502 -Node: Calling A Function541923 -Node: Variable Scope543038 -Node: Pass By Value/Reference546001 -Node: Return Statement549509 -Node: Dynamic Typing552490 -Node: Indirect Calls553421 -Node: Library Functions563106 -Ref: Library Functions-Footnote-1566619 -Ref: Library Functions-Footnote-2566762 -Node: Library Names566933 -Ref: Library Names-Footnote-1570404 -Ref: Library Names-Footnote-2570624 -Node: General Functions570710 -Node: Strtonum Function571738 -Node: Assert Function574668 -Node: Round Function577994 -Node: Cliff Random Function579537 -Node: Ordinal Functions580553 -Ref: Ordinal Functions-Footnote-1583623 -Ref: Ordinal Functions-Footnote-2583875 -Node: Join Function584084 -Ref: Join Function-Footnote-1585855 -Node: Getlocaltime Function586055 -Node: Readfile Function589796 -Node: Data File Management591635 -Node: Filetrans Function592267 -Node: Rewind Function596336 -Node: File Checking597723 -Node: Empty Files598817 -Node: Ignoring Assigns601047 -Node: Getopt Function602600 -Ref: Getopt Function-Footnote-1613903 -Node: Passwd Functions614106 -Ref: Passwd Functions-Footnote-1623081 -Node: Group Functions623169 -Node: Walking Arrays631253 -Node: Sample Programs633390 -Node: Running Examples634064 -Node: Clones634792 -Node: Cut Program636016 -Node: Egrep Program645861 -Ref: Egrep Program-Footnote-1653634 -Node: Id Program653744 -Node: Split Program657360 -Ref: Split Program-Footnote-1660879 -Node: Tee Program661007 -Node: Uniq Program663810 -Node: Wc Program671239 -Ref: Wc Program-Footnote-1675505 -Ref: Wc Program-Footnote-2675705 -Node: Miscellaneous Programs675797 -Node: Dupword Program676985 -Node: Alarm Program679016 -Node: Translate Program683769 -Ref: Translate Program-Footnote-1688156 -Ref: Translate Program-Footnote-2688404 -Node: Labels Program688538 -Ref: Labels Program-Footnote-1691909 -Node: Word Sorting691993 -Node: History Sorting695877 -Node: Extract Program697716 -Ref: Extract Program-Footnote-1705219 -Node: Simple Sed705347 -Node: Igawk Program708409 -Ref: Igawk Program-Footnote-1723566 -Ref: Igawk Program-Footnote-2723767 -Node: Anagram Program723905 -Node: Signature Program726973 -Node: Advanced Features728073 -Node: Nondecimal Data729959 -Node: Array Sorting731542 -Node: Controlling Array Traversal732239 -Node: Array Sorting Functions740477 -Ref: Array Sorting Functions-Footnote-1744151 -Ref: Array Sorting Functions-Footnote-2744244 -Node: Two-way I/O744438 -Ref: Two-way I/O-Footnote-1749870 -Node: TCP/IP Networking749940 -Node: Profiling752784 -Node: Internationalization760281 -Node: I18N and L10N761706 -Node: Explaining gettext762392 -Ref: Explaining gettext-Footnote-1767460 -Ref: Explaining gettext-Footnote-2767644 -Node: Programmer i18n767809 -Node: Translator i18n772011 -Node: String Extraction772804 -Ref: String Extraction-Footnote-1773765 -Node: Printf Ordering773851 -Ref: Printf Ordering-Footnote-1776635 -Node: I18N Portability776699 -Ref: I18N Portability-Footnote-1779148 -Node: I18N Example779211 -Ref: I18N Example-Footnote-1781849 -Node: Gawk I18N781921 -Node: Debugger782542 -Node: Debugging783513 -Node: Debugging Concepts783946 -Node: Debugging Terms785802 -Node: Awk Debugging788399 -Node: Sample Debugging Session789291 -Node: Debugger Invocation789811 -Node: Finding The Bug791143 -Node: List of Debugger Commands797631 -Node: Breakpoint Control798965 -Node: Debugger Execution Control802629 -Node: Viewing And Changing Data805989 -Node: Execution Stack809345 -Node: Debugger Info810812 -Node: Miscellaneous Debugger Commands814794 -Node: Readline Support819970 -Node: Limitations820801 -Node: Arbitrary Precision Arithmetic823053 -Ref: Arbitrary Precision Arithmetic-Footnote-1824702 -Node: General Arithmetic824850 -Node: Floating Point Issues826570 -Node: String Conversion Precision827451 -Ref: String Conversion Precision-Footnote-1829156 -Node: Unexpected Results829265 -Node: POSIX Floating Point Problems831418 -Ref: POSIX Floating Point Problems-Footnote-1835243 -Node: Integer Programming835281 -Node: Floating-point Programming837020 -Ref: Floating-point Programming-Footnote-1843351 -Ref: Floating-point Programming-Footnote-2843621 -Node: Floating-point Representation843885 -Node: Floating-point Context845050 -Ref: table-ieee-formats845889 -Node: Rounding Mode847273 -Ref: table-rounding-modes847752 -Ref: Rounding Mode-Footnote-1850767 -Node: Gawk and MPFR850946 -Node: Arbitrary Precision Floats852201 -Ref: Arbitrary Precision Floats-Footnote-1854644 -Node: Setting Precision854960 -Ref: table-predefined-precision-strings855646 -Node: Setting Rounding Mode857791 -Ref: table-gawk-rounding-modes858195 -Node: Floating-point Constants859382 -Node: Changing Precision860811 -Ref: Changing Precision-Footnote-1862208 -Node: Exact Arithmetic862382 -Node: Arbitrary Precision Integers865520 -Ref: Arbitrary Precision Integers-Footnote-1868538 -Node: Dynamic Extensions868685 -Node: Extension Intro870143 -Node: Plugin License871408 -Node: Extension Mechanism Outline872093 -Ref: load-extension872510 -Ref: load-new-function873988 -Ref: call-new-function874983 -Node: Extension API Description876998 -Node: Extension API Functions Introduction878211 -Node: General Data Types883077 -Ref: General Data Types-Footnote-1888676 -Node: Requesting Values888975 -Ref: table-value-types-returned889706 -Node: Constructor Functions890660 -Node: Registration Functions893680 -Node: Extension Functions894365 -Node: Exit Callback Functions896590 -Node: Extension Version String897839 -Node: Input Parsers898489 -Node: Output Wrappers908246 -Node: Two-way processors912756 -Node: Printing Messages914964 -Ref: Printing Messages-Footnote-1916041 -Node: Updating `ERRNO'916193 -Node: Accessing Parameters916932 -Node: Symbol Table Access918162 -Node: Symbol table by name918674 -Node: Symbol table by cookie920421 -Ref: Symbol table by cookie-Footnote-1924551 -Node: Cached values924614 -Ref: Cached values-Footnote-1928063 -Node: Array Manipulation928154 -Ref: Array Manipulation-Footnote-1929252 -Node: Array Data Types929291 -Ref: Array Data Types-Footnote-1931994 -Node: Array Functions932086 -Node: Flattening Arrays935852 -Node: Creating Arrays942704 -Node: Extension API Variables947429 -Node: Extension Versioning948065 -Node: Extension API Informational Variables949966 -Node: Extension API Boilerplate951052 -Node: Finding Extensions954856 -Node: Extension Example955416 -Node: Internal File Description956146 -Node: Internal File Ops960237 -Ref: Internal File Ops-Footnote-1971745 -Node: Using Internal File Ops971885 -Ref: Using Internal File Ops-Footnote-1974238 -Node: Extension Samples974504 -Node: Extension Sample File Functions976028 -Node: Extension Sample Fnmatch984513 -Node: Extension Sample Fork986239 -Node: Extension Sample Inplace987457 -Node: Extension Sample Ord989235 -Node: Extension Sample Readdir990071 -Node: Extension Sample Revout991603 -Node: Extension Sample Rev2way992196 -Node: Extension Sample Read write array992886 -Node: Extension Sample Readfile994769 -Node: Extension Sample API Tests995587 -Node: Extension Sample Time996112 -Node: gawkextlib997476 -Node: Language History1000236 -Node: V7/SVR3.11001758 -Node: SVR41004078 -Node: POSIX1005520 -Node: BTL1006906 -Node: POSIX/GNU1007640 -Node: Common Extensions1013175 -Node: Ranges and Locales1014481 -Ref: Ranges and Locales-Footnote-11019099 -Ref: Ranges and Locales-Footnote-21019126 -Ref: Ranges and Locales-Footnote-31019386 -Node: Contributors1019607 -Node: Installation1024682 -Node: Gawk Distribution1025576 -Node: Getting1026060 -Node: Extracting1026886 -Node: Distribution contents1028578 -Node: Unix Installation1034098 -Node: Quick Installation1034715 -Node: Additional Configuration Options1037159 -Node: Configuration Philosophy1038636 -Node: Non-Unix Installation1040990 -Node: PC Installation1041448 -Node: PC Binary Installation1042747 -Node: PC Compiling1044595 -Node: PC Testing1047539 -Node: PC Using1048715 -Node: Cygwin1052900 -Node: MSYS1053900 -Node: VMS Installation1054414 -Node: VMS Compilation1055017 -Ref: VMS Compilation-Footnote-11056024 -Node: VMS Installation Details1056082 -Node: VMS Running1057717 -Node: VMS Old Gawk1059324 -Node: Bugs1059798 -Node: Other Versions1063654 -Node: Notes1069738 -Node: Compatibility Mode1070538 -Node: Additions1071321 -Node: Accessing The Source1072248 -Node: Adding Code1073688 -Node: New Ports1079733 -Node: Derived Files1083868 -Ref: Derived Files-Footnote-11089189 -Ref: Derived Files-Footnote-21089223 -Ref: Derived Files-Footnote-31089823 -Node: Future Extensions1089921 -Node: Implementation Limitations1090498 -Node: Extension Design1091750 -Node: Old Extension Problems1092904 -Ref: Old Extension Problems-Footnote-11094412 -Node: Extension New Mechanism Goals1094469 -Ref: Extension New Mechanism Goals-Footnote-11097834 -Node: Extension Other Design Decisions1098020 -Node: Extension Future Growth1100126 -Node: Old Extension Mechanism1100962 -Node: Basic Concepts1102702 -Node: Basic High Level1103383 -Ref: figure-general-flow1103654 -Ref: figure-process-flow1104253 -Ref: Basic High Level-Footnote-11107482 -Node: Basic Data Typing1107667 -Node: Glossary1111022 -Node: Copying1136484 -Node: GNU Free Documentation License1174041 -Node: Index1199178 +Ref: Controlling Scanning-Footnote-1449194 +Node: Delete449510 +Ref: Delete-Footnote-1452275 +Node: Numeric Array Subscripts452332 +Node: Uninitialized Subscripts454515 +Node: Multidimensional456142 +Node: Multiscanning459234 +Node: Arrays of Arrays460823 +Node: Functions465463 +Node: Built-in466282 +Node: Calling Built-in467360 +Node: Numeric Functions469348 +Ref: Numeric Functions-Footnote-1473180 +Ref: Numeric Functions-Footnote-2473537 +Ref: Numeric Functions-Footnote-3473585 +Node: String Functions473854 +Ref: String Functions-Footnote-1496774 +Ref: String Functions-Footnote-2496903 +Ref: String Functions-Footnote-3497151 +Node: Gory Details497238 +Ref: table-sub-escapes498917 +Ref: table-sub-posix-92500271 +Ref: table-sub-proposed501622 +Ref: table-posix-sub502976 +Ref: table-gensub-escapes504521 +Ref: Gory Details-Footnote-1505697 +Ref: Gory Details-Footnote-2505748 +Node: I/O Functions505899 +Ref: I/O Functions-Footnote-1512884 +Node: Time Functions513031 +Ref: Time Functions-Footnote-1523964 +Ref: Time Functions-Footnote-2524032 +Ref: Time Functions-Footnote-3524190 +Ref: Time Functions-Footnote-4524301 +Ref: Time Functions-Footnote-5524413 +Ref: Time Functions-Footnote-6524640 +Node: Bitwise Functions524906 +Ref: table-bitwise-ops525468 +Ref: Bitwise Functions-Footnote-1529689 +Node: Type Functions529873 +Node: I18N Functions531024 +Node: User-defined532651 +Node: Definition Syntax533455 +Ref: Definition Syntax-Footnote-1538365 +Node: Function Example538434 +Node: Function Caveats541028 +Node: Calling A Function541449 +Node: Variable Scope542564 +Node: Pass By Value/Reference545527 +Node: Return Statement549035 +Node: Dynamic Typing552016 +Node: Indirect Calls552947 +Node: Library Functions562632 +Ref: Library Functions-Footnote-1566145 +Ref: Library Functions-Footnote-2566288 +Node: Library Names566459 +Ref: Library Names-Footnote-1569930 +Ref: Library Names-Footnote-2570150 +Node: General Functions570236 +Node: Strtonum Function571264 +Node: Assert Function574194 +Node: Round Function577520 +Node: Cliff Random Function579063 +Node: Ordinal Functions580079 +Ref: Ordinal Functions-Footnote-1583149 +Ref: Ordinal Functions-Footnote-2583401 +Node: Join Function583610 +Ref: Join Function-Footnote-1585381 +Node: Getlocaltime Function585581 +Node: Readfile Function589322 +Node: Data File Management591161 +Node: Filetrans Function591793 +Node: Rewind Function595862 +Node: File Checking597249 +Node: Empty Files598343 +Node: Ignoring Assigns600573 +Node: Getopt Function602126 +Ref: Getopt Function-Footnote-1613429 +Node: Passwd Functions613632 +Ref: Passwd Functions-Footnote-1622607 +Node: Group Functions622695 +Node: Walking Arrays630779 +Node: Sample Programs632916 +Node: Running Examples633590 +Node: Clones634318 +Node: Cut Program635542 +Node: Egrep Program645387 +Ref: Egrep Program-Footnote-1653160 +Node: Id Program653270 +Node: Split Program656886 +Ref: Split Program-Footnote-1660405 +Node: Tee Program660533 +Node: Uniq Program663336 +Node: Wc Program670765 +Ref: Wc Program-Footnote-1675031 +Ref: Wc Program-Footnote-2675231 +Node: Miscellaneous Programs675323 +Node: Dupword Program676511 +Node: Alarm Program678542 +Node: Translate Program683295 +Ref: Translate Program-Footnote-1687682 +Ref: Translate Program-Footnote-2687930 +Node: Labels Program688064 +Ref: Labels Program-Footnote-1691435 +Node: Word Sorting691519 +Node: History Sorting695403 +Node: Extract Program697242 +Ref: Extract Program-Footnote-1704745 +Node: Simple Sed704873 +Node: Igawk Program707935 +Ref: Igawk Program-Footnote-1723092 +Ref: Igawk Program-Footnote-2723293 +Node: Anagram Program723431 +Node: Signature Program726499 +Node: Advanced Features727599 +Node: Nondecimal Data729485 +Node: Array Sorting731068 +Node: Controlling Array Traversal731765 +Node: Array Sorting Functions740049 +Ref: Array Sorting Functions-Footnote-1743918 +Node: Two-way I/O744112 +Ref: Two-way I/O-Footnote-1749544 +Node: TCP/IP Networking749614 +Node: Profiling752458 +Node: Internationalization759955 +Node: I18N and L10N761380 +Node: Explaining gettext762066 +Ref: Explaining gettext-Footnote-1767134 +Ref: Explaining gettext-Footnote-2767318 +Node: Programmer i18n767483 +Node: Translator i18n771685 +Node: String Extraction772478 +Ref: String Extraction-Footnote-1773439 +Node: Printf Ordering773525 +Ref: Printf Ordering-Footnote-1776309 +Node: I18N Portability776373 +Ref: I18N Portability-Footnote-1778822 +Node: I18N Example778885 +Ref: I18N Example-Footnote-1781523 +Node: Gawk I18N781595 +Node: Debugger782216 +Node: Debugging783187 +Node: Debugging Concepts783620 +Node: Debugging Terms785476 +Node: Awk Debugging788073 +Node: Sample Debugging Session788965 +Node: Debugger Invocation789485 +Node: Finding The Bug790817 +Node: List of Debugger Commands797305 +Node: Breakpoint Control798639 +Node: Debugger Execution Control802303 +Node: Viewing And Changing Data805663 +Node: Execution Stack809019 +Node: Debugger Info810486 +Node: Miscellaneous Debugger Commands814468 +Node: Readline Support819644 +Node: Limitations820475 +Node: Arbitrary Precision Arithmetic822727 +Ref: Arbitrary Precision Arithmetic-Footnote-1824376 +Node: General Arithmetic824524 +Node: Floating Point Issues826244 +Node: String Conversion Precision827125 +Ref: String Conversion Precision-Footnote-1828830 +Node: Unexpected Results828939 +Node: POSIX Floating Point Problems831092 +Ref: POSIX Floating Point Problems-Footnote-1834917 +Node: Integer Programming834955 +Node: Floating-point Programming836694 +Ref: Floating-point Programming-Footnote-1843025 +Ref: Floating-point Programming-Footnote-2843295 +Node: Floating-point Representation843559 +Node: Floating-point Context844724 +Ref: table-ieee-formats845563 +Node: Rounding Mode846947 +Ref: table-rounding-modes847426 +Ref: Rounding Mode-Footnote-1850441 +Node: Gawk and MPFR850620 +Node: Arbitrary Precision Floats851875 +Ref: Arbitrary Precision Floats-Footnote-1854318 +Node: Setting Precision854634 +Ref: table-predefined-precision-strings855320 +Node: Setting Rounding Mode857465 +Ref: table-gawk-rounding-modes857869 +Node: Floating-point Constants859056 +Node: Changing Precision860485 +Ref: Changing Precision-Footnote-1861882 +Node: Exact Arithmetic862056 +Node: Arbitrary Precision Integers865194 +Ref: Arbitrary Precision Integers-Footnote-1868212 +Node: Dynamic Extensions868359 +Node: Extension Intro869817 +Node: Plugin License871082 +Node: Extension Mechanism Outline871767 +Ref: load-extension872184 +Ref: load-new-function873662 +Ref: call-new-function874657 +Node: Extension API Description876672 +Node: Extension API Functions Introduction877885 +Node: General Data Types882751 +Ref: General Data Types-Footnote-1888350 +Node: Requesting Values888649 +Ref: table-value-types-returned889380 +Node: Constructor Functions890334 +Node: Registration Functions893354 +Node: Extension Functions894039 +Node: Exit Callback Functions896264 +Node: Extension Version String897513 +Node: Input Parsers898163 +Node: Output Wrappers907920 +Node: Two-way processors912430 +Node: Printing Messages914638 +Ref: Printing Messages-Footnote-1915715 +Node: Updating `ERRNO'915867 +Node: Accessing Parameters916606 +Node: Symbol Table Access917836 +Node: Symbol table by name918348 +Node: Symbol table by cookie920095 +Ref: Symbol table by cookie-Footnote-1924225 +Node: Cached values924288 +Ref: Cached values-Footnote-1927737 +Node: Array Manipulation927828 +Ref: Array Manipulation-Footnote-1928926 +Node: Array Data Types928965 +Ref: Array Data Types-Footnote-1931668 +Node: Array Functions931760 +Node: Flattening Arrays935526 +Node: Creating Arrays942378 +Node: Extension API Variables947103 +Node: Extension Versioning947739 +Node: Extension API Informational Variables949640 +Node: Extension API Boilerplate950726 +Node: Finding Extensions954530 +Node: Extension Example955090 +Node: Internal File Description955820 +Node: Internal File Ops959911 +Ref: Internal File Ops-Footnote-1971419 +Node: Using Internal File Ops971559 +Ref: Using Internal File Ops-Footnote-1973912 +Node: Extension Samples974178 +Node: Extension Sample File Functions975702 +Node: Extension Sample Fnmatch984187 +Node: Extension Sample Fork985913 +Node: Extension Sample Inplace987131 +Node: Extension Sample Ord988909 +Node: Extension Sample Readdir989745 +Node: Extension Sample Revout991277 +Node: Extension Sample Rev2way991870 +Node: Extension Sample Read write array992560 +Node: Extension Sample Readfile994443 +Node: Extension Sample API Tests995261 +Node: Extension Sample Time995786 +Node: gawkextlib997150 +Node: Language History999910 +Node: V7/SVR3.11001432 +Node: SVR41003752 +Node: POSIX1005194 +Node: BTL1006580 +Node: POSIX/GNU1007314 +Node: Common Extensions1012849 +Node: Ranges and Locales1014155 +Ref: Ranges and Locales-Footnote-11018773 +Ref: Ranges and Locales-Footnote-21018800 +Ref: Ranges and Locales-Footnote-31019060 +Node: Contributors1019281 +Node: Installation1024356 +Node: Gawk Distribution1025250 +Node: Getting1025734 +Node: Extracting1026560 +Node: Distribution contents1028252 +Node: Unix Installation1033772 +Node: Quick Installation1034389 +Node: Additional Configuration Options1036833 +Node: Configuration Philosophy1038310 +Node: Non-Unix Installation1040664 +Node: PC Installation1041122 +Node: PC Binary Installation1042421 +Node: PC Compiling1044269 +Node: PC Testing1047213 +Node: PC Using1048389 +Node: Cygwin1052574 +Node: MSYS1053574 +Node: VMS Installation1054088 +Node: VMS Compilation1054691 +Ref: VMS Compilation-Footnote-11055698 +Node: VMS Installation Details1055756 +Node: VMS Running1057391 +Node: VMS Old Gawk1058998 +Node: Bugs1059472 +Node: Other Versions1063328 +Node: Notes1069412 +Node: Compatibility Mode1070212 +Node: Additions1070995 +Node: Accessing The Source1071922 +Node: Adding Code1073362 +Node: New Ports1079407 +Node: Derived Files1083542 +Ref: Derived Files-Footnote-11088863 +Ref: Derived Files-Footnote-21088897 +Ref: Derived Files-Footnote-31089497 +Node: Future Extensions1089595 +Node: Implementation Limitations1090172 +Node: Extension Design1091424 +Node: Old Extension Problems1092578 +Ref: Old Extension Problems-Footnote-11094086 +Node: Extension New Mechanism Goals1094143 +Ref: Extension New Mechanism Goals-Footnote-11097508 +Node: Extension Other Design Decisions1097694 +Node: Extension Future Growth1099800 +Node: Old Extension Mechanism1100636 +Node: Basic Concepts1102376 +Node: Basic High Level1103057 +Ref: figure-general-flow1103328 +Ref: figure-process-flow1103927 +Ref: Basic High Level-Footnote-11107156 +Node: Basic Data Typing1107341 +Node: Glossary1110696 +Node: Copying1136158 +Node: GNU Free Documentation License1173715 +Node: Index1198852 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index ca07e753..b736116e 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -14683,29 +14683,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 @@ -14718,13 +14718,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. @@ -15581,15 +15582,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 @@ -15606,30 +15608,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: @@ -15655,29 +15659,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}) @@ -25251,7 +25245,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 @@ -25266,7 +25260,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) @@ -25325,15 +25319,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 @@ -25346,7 +25339,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. @@ -25368,24 +25361,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) @} @@ -25402,23 +25382,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 839f22d7..8f24b61c 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -14022,29 +14022,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 @@ -14057,13 +14057,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. @@ -14920,15 +14921,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 @@ -14945,30 +14947,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: @@ -14994,29 +14998,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}) @@ -24400,7 +24394,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 @@ -24415,7 +24409,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) @@ -24474,15 +24468,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 @@ -24495,7 +24488,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. @@ -24517,24 +24510,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) @} @@ -24551,23 +24531,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 |