diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/gawk.1 | 23 | ||||
| -rw-r--r-- | doc/gawk.info | 682 | ||||
| -rw-r--r-- | doc/gawk.texi | 112 |
3 files changed, 448 insertions, 369 deletions
@@ -1089,10 +1089,12 @@ loops. Supported values are \fB"ascending index string"\fR, \fB"ascending index number"\fR, -\fB"ascending value"\fR, +\fB"ascending value string"\fR, +\fB"ascending value number"\fR, \fB"descending index string"\fR, \fB"descending index number"\fR, -\fB"descending value"\fR, and +\fB"descending value string"\fR, +\fB"descending value number"\fR, and \fB"unsorted"\fR. The order specification words can be truncated, or omitted (provided that at least one is present), or given in any order. @@ -2439,7 +2441,7 @@ number generator. has the following built-in string functions: .PP .TP "\w'\fBsprintf(\^\fIfmt\fB\^, \fIexpr-list\^\fB)\fR'u+1n" -\fBasort(\fIs \fR[\fB, \fId\fR]\fB)\fR +\fBasort(\fIs \fR[\fB, \fId\fR [\fB, \fIhow\fR] ]\fB)\fR Return the number of elements in the source array .IR s . @@ -2466,9 +2468,15 @@ and then sort leaving the indices of the source array .I s -unchanged. +unchanged. The optional string +.I how +controls the direction and the comparsion mode. +Valid values for +.I how +are "ascending string", "ascending number", +"descending string" and "descending number". .TP "\w'\fBsprintf(\^\fIfmt\fB\^, \fIexpr-list\^\fB)\fR'u+1n" -\fBasorti(\fIs \fR[\fB, \fId\fR]\fB)\fR +\fBasorti(\fIs \fR[\fB, \fId\fR [\fB, \fIhow\fR] ]\fB)\fR Return the number of elements in the source array .IR s . @@ -2481,6 +2489,11 @@ When done, the array is indexed numerically, and the values are those of the original indices. The original values are lost; thus provide a second array if you wish to preserve the original. +The purpose of the optional string +.I how +is the same as described in +.BR asort() +above. .TP \fBgensub(\fIr\fB, \fIs\fB, \fIh \fR[\fB, \fIt\fR]\fB)\fR Search the target string diff --git a/doc/gawk.info b/doc/gawk.info index a67eafbb..06d2dbb9 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -9409,24 +9409,23 @@ with a pound sign (`#'). words; separate pairs of words by a single space. One word controls sort direction, `ascending' or `descending'; another controls the sort key, `index' or `value'; and the remaining - one, which is only valid for sorting by index, is comparison - mode, `string' or `number'. When two or three words are - present, they may be specified in any order, so `ascending - index string' and `string ascending index' are equivalent. - Also, each word may be truncated, so `asc index str' and `a i - s' are also equivalent. Note that a separating space is - required even when the words have been shortened down to one - letter each. + one affects comparison mode, `string' or `number'. When two + or three words are present, they may be specified in any + order, so `ascending index string' and `string ascending + index' are equivalent. Also, each word may be truncated, so + `asc index str' and `a i s' are also equivalent. Note that a + separating space is required even when the words have been + shortened down to one letter each. You can omit direction and/or key type and/or comparison mode. Provided that at least one is present, the missing parts of a sort specification default to `ascending', - `index', and (for indices only) `string', respectively. An - empty string, `""', is the same as `unsorted' and will cause - `for (index in array) ...' to process the indices in - arbitrary order. Another thing to note is that the array - sorting takes place at the time the `for' loop is about to - start executing, so changing the value of + `index', and `string', respectively. An empty string, `""', + is the same as `ascending index string', and a value of + `unsorted' will cause `for (index in array) ...' to process + the indices in arbitrary order. Another thing to note is + that the array sorting takes place at the time the `for' loop + is about to start executing, so changing the value of `PROCINFO["sorted_in"]' during loop execution does not have any effect on the order in which any remaining array elements get processed. *Note Scanning an Array::, for more @@ -9972,11 +9971,14 @@ are available: process. Any index with non-numeric value will end up positioned as if it were zero. -`ascending value' - Order by element values rather than by indices. Comparisons are - done as numeric when both values being compared are numeric, or - done as strings when either or both aren't numeric (*note Variable - Typing::). Subarrays, if present, come out last. +`ascending value string' + Order by element values rather than by indices. Scalar values are + compared as strings. Subarrays, if present, come out last. + +`ascending value number' + Order by values but force scalar values to be treated as numbers + for the purpose of comparison. If there are subarrays, those + appear at the end of the sorted list. `descending index string' Reverse order from the most basic sort. @@ -9984,22 +9986,31 @@ are available: `descending index number' Numeric indices ordered from high to low. -`descending value' - Element values ordered from high to low. Subarrays, if present, - come out first. +`descending value string' + Element values, treated as strings, ordered from high to low. + Subarrays, if present, come out first. + +`descending value number' + Element values, treated as numbers, ordered from high to low. + Subarrays, if present, come out first. `unsorted' Array elements are processed in arbitrary order, the normal `awk' - behavior. + behavior. You can also get the normal behavior by just deleting + the `"sorted_in"' item from the `PROCINFO' array, if it previously + had a value assigned to it. The array traversal order is determined before the `for' loop starts -to run. Changing `PROCINFO["sorted_in"]' in the looop body will not +to run. Changing `PROCINFO["sorted_in"]' in the loop body will not affect the loop. Portions of the sort specification string may be truncated or omitted. The default is `ascending' for direction, `index' for sort -key type, and (when sorting by index only) `string' for comparison mode. -For example: +key type, and `string' for comparison mode. This implies that one can +simply assign the empty string, "", instead of "ascending index string" +to `PROCINFO["sorted_in"]' for the same effect. + + For example: $ gawk 'BEGIN { > a[4] = 4 @@ -10025,11 +10036,6 @@ value, regardless of what the subarray itself contains, and all subarrays are treated as being equal to each other. Their order relative to each other is determined by their index strings. - Sorting by array element values (for values other than subarrays) -always uses basic `awk' comparison mode: if both values happen to be -numbers then they're compared as numbers, otherwise they're compared as -strings. - When string comparisons are made during a sort, either for element values where one or both aren't numbers or for element indices handled as strings, the value of `IGNORECASE' (*note Built-in Variables::) @@ -10365,8 +10371,7 @@ 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 of array elements is done using `gawk''s usual -comparison rules (*note Typing and Comparison::). +on. The array elements are compared as strings. An important side effect of calling `asort()' is that _the array's original indices are irrevocably lost_. As this isn't always @@ -10381,6 +10386,19 @@ desirable, `asort()' accepts a second argument: and then sorts `dest', destroying its indices. However, the `source' array is not affected. + `asort()' and `asorti()' accept a third string argument to control +the comparison rule for the array elements, and the direction of the +sorted results. The valid comparison modes are `string' and `number', +and the direction can be either `ascending' or `descending'. Either +mode or direction, or both, can be omitted in which case the defaults, +`string' or `ascending' is assumed for the comparison mode and the +direction, respectively. Seperate comparison mode from direction with +a single space, and they can appear in any order. To compare the +elements as numbers, and to reverse the elements of the `dest' array, +the call to asort in the above example can be replaced with: + + asort(source, dest, "descending number") + 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 @@ -10403,7 +10421,8 @@ result array: 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. +indices. This is an alternative to specifying `descending' for the +sorting order using the optional third argument. Copying array indices and elements isn't expensive in terms of memory. Internally, `gawk' maintains "reference counts" to data. For @@ -10411,12 +10430,10 @@ 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. - We said previously that comparisons are done using `gawk''s "usual -comparison rules." 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.(1) Caveat -Emptor. + 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.(1) Caveat Emptor. ---------- Footnotes ---------- @@ -10780,15 +10797,26 @@ pound sign (`#'): `&' with `sub()', `gsub()', and `gensub()'. -`asort(SOURCE [, DEST]) #' +`asort(SOURCE [, DEST [, HOW ] ]) #' Return the number of elements in the array SOURCE. `gawk' sorts - the contents of SOURCE using the normal rules for comparing values - (in particular, `IGNORECASE' affects the sorting) 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. For example, if the contents of `a' - are as follows: + 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. *Note Scanning an Array::, for + more information. + + For example, if the contents of `a' are as follows: a["last"] = "de" a["first"] = "sac" @@ -10804,16 +10832,20 @@ 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::. `asort()' is a `gawk' extension; it is not available in compatibility mode (*note Options::). -`asorti(SOURCE [, DEST]) #' +`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. As array indices are always strings, the - comparison performed is always a string comparison. (Here too, - `IGNORECASE' affects the sorting.) + of the values. (Here too, `IGNORECASE' affects the sorting.) The `asorti()' function is described in more detail in *note Array Sorting::. `asorti()' is a `gawk' extension; it is not available @@ -24444,7 +24476,7 @@ Index (line 67) * advanced features, data files as single record: Records. (line 175) * advanced features, fixed-width data: Constant Size. (line 9) -* advanced features, FNR/NR variables: Auto-set. (line 230) +* advanced features, FNR/NR variables: Auto-set. (line 229) * advanced features, gawk: Advanced Features. (line 6) * advanced features, gawk, network programming: TCP/IP Networking. (line 6) @@ -24518,7 +24550,7 @@ Index * arrays, names of: Arrays. (line 18) * arrays, scanning: Scanning an Array. (line 6) * arrays, sorting: Array Sorting. (line 6) -* arrays, sorting, IGNORECASE variable and: Array Sorting. (line 68) +* arrays, sorting, IGNORECASE variable and: Array Sorting. (line 81) * arrays, sparse: Array Intro. (line 71) * arrays, subscripts: Numeric Array Subscripts. (line 6) @@ -24531,7 +24563,7 @@ Index * asort() function (gawk) <1>: String Functions. (line 29) * asort() function (gawk): Array Sorting. (line 6) * asort() function (gawk), arrays, sorting: Array Sorting. (line 6) -* asorti() function (gawk): String Functions. (line 57) +* asorti() function (gawk): String Functions. (line 74) * assert() function (C library): Assert Function. (line 6) * assert() user-defined function: Assert Function. (line 28) * assertions: Assert Function. (line 6) @@ -24775,7 +24807,7 @@ Index * caret (^), in bracket expressions: Bracket Expressions. (line 16) * case keyword: Switch Statement. (line 6) * case sensitivity, array indices and: Array Intro. (line 92) -* case sensitivity, converting case: String Functions. (line 504) +* case sensitivity, converting case: String Functions. (line 519) * case sensitivity, example programs: Library Functions. (line 42) * case sensitivity, gawk: Case-sensitivity. (line 26) * case sensitivity, regexps and <1>: User-modified. (line 82) @@ -24850,7 +24882,7 @@ Index * common extensions, fflush() function: I/O Functions. (line 25) * common extensions, func keyword: Definition Syntax. (line 83) * common extensions, length() applied to an array: String Functions. - (line 178) + (line 193) * common extensions, nextfile statement: Nextfile Statement. (line 6) * common extensions, RS as a regexp: Records. (line 115) * common extensions, single character fields: Single Character Fields. @@ -24892,7 +24924,7 @@ Index * constants, types of: Constants. (line 6) * continue statement: Continue Statement. (line 6) * control statements: Statements. (line 6) -* converting, case: String Functions. (line 504) +* converting, case: String Functions. (line 519) * converting, dates to timestamps: Time Functions. (line 74) * converting, during subscripting: Numeric Array Subscripts. (line 31) @@ -24944,13 +24976,13 @@ Index (line 47) * dark corner, FILENAME variable <1>: Auto-set. (line 92) * dark corner, FILENAME variable: Getline Notes. (line 19) -* dark corner, FNR/NR variables: Auto-set. (line 230) +* dark corner, FNR/NR variables: Auto-set. (line 229) * dark corner, format-control characters: Control Letters. (line 18) * dark corner, FS as null string: Single Character Fields. (line 20) * dark corner, input files: Records. (line 98) * dark corner, invoking awk: Command Line. (line 16) -* dark corner, length() function: String Functions. (line 164) +* dark corner, length() function: String Functions. (line 179) * dark corner, multiline records: Multiple Line. (line 35) * dark corner, NF variable, decrementing: Changing Fields. (line 107) * dark corner, OFMT variable: OFMT. (line 27) @@ -24960,7 +24992,7 @@ Index (line 148) * dark corner, regexp constants, as arguments to user-defined functions: Using Constant Regexps. (line 43) -* dark corner, split() function: String Functions. (line 343) +* dark corner, split() function: String Functions. (line 358) * dark corner, strings, storing: Records. (line 191) * dark corner, value of ARGV[0]: Auto-set. (line 35) * data, fixed-width: Constant Size. (line 9) @@ -25091,7 +25123,7 @@ Index * deleting elements in arrays: Delete. (line 6) * deleting entire arrays: Delete. (line 39) * dgawk: Debugger. (line 6) -* differences between gawk and awk: String Functions. (line 178) +* 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) @@ -25131,7 +25163,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 241) + (line 256) * differences in awk and gawk, next/nextfile statements: Nextfile Statement. (line 6) * differences in awk and gawk, print/printf statements: Format Modifiers. @@ -25143,15 +25175,15 @@ Index * differences in awk and gawk, regular expressions: Case-sensitivity. (line 26) * differences in awk and gawk, RS/RT variables: Records. (line 167) -* differences in awk and gawk, RT variable: Auto-set. (line 219) +* differences in awk and gawk, RT variable: Auto-set. (line 218) * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. - (line 331) + (line 346) * differences in awk and gawk, strings: Scalar Constants. (line 20) * differences in awk and gawk, strings, storing: Records. (line 187) * differences in awk and gawk, strtonum() function (gawk): String Functions. - (line 386) + (line 401) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. (line 153) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. @@ -25299,7 +25331,7 @@ Index * extensions, common, fflush() function: I/O Functions. (line 25) * extensions, common, func keyword: Definition Syntax. (line 83) * extensions, common, length() applied to an array: String Functions. - (line 178) + (line 193) * extensions, common, nextfile statement: Nextfile Statement. (line 6) * extensions, common, RS as a regexp: Records. (line 115) * extensions, common, single character fields: Single Character Fields. @@ -25424,7 +25456,7 @@ Index * floating-point, numbers, AWKNUM internal type: Internals. (line 19) * FNR variable <1>: Auto-set. (line 102) * FNR variable: Records. (line 6) -* FNR variable, changing: Auto-set. (line 230) +* FNR variable, changing: Auto-set. (line 229) * for statement: For Statement. (line 6) * for statement, in arrays: Scanning an Array. (line 24) * force_number() internal function: Internals. (line 27) @@ -25561,7 +25593,7 @@ Index * gawk, functions, adding: Dynamic Extensions. (line 10) * gawk, hexadecimal numbers and: Nondecimal-numbers. (line 42) * gawk, IGNORECASE variable in <1>: String Functions. (line 29) -* gawk, IGNORECASE variable in <2>: Array Sorting. (line 68) +* gawk, IGNORECASE variable in <2>: Array Sorting. (line 81) * gawk, IGNORECASE variable in <3>: Array Intro. (line 92) * gawk, IGNORECASE variable in <4>: User-modified. (line 82) * gawk, IGNORECASE variable in: Case-sensitivity. (line 26) @@ -25596,7 +25628,7 @@ Index * gawk, regular expressions, operators: GNU Regexp Operators. (line 6) * gawk, regular expressions, precedence: Regexp Operators. (line 157) -* gawk, RT variable in <1>: Auto-set. (line 219) +* gawk, RT variable in <1>: Auto-set. (line 218) * gawk, RT variable in <2>: Getline/Variable/File. (line 10) * gawk, RT variable in <3>: Multiple Line. (line 129) @@ -25614,7 +25646,7 @@ Index (line 63) * General Public License (GPL): Glossary. (line 306) * General Public License, See GPL: Manual History. (line 11) -* gensub() function (gawk) <1>: String Functions. (line 68) +* gensub() function (gawk) <1>: String Functions. (line 83) * gensub() function (gawk): Using Constant Regexps. (line 43) * gensub() function (gawk), escape processing: Gory Details. (line 6) @@ -25683,10 +25715,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 121) +* gsub() function <1>: String Functions. (line 136) * gsub() function: Using Constant Regexps. (line 43) -* gsub() function, arguments of: String Functions. (line 444) +* gsub() function, arguments of: String Functions. (line 459) * gsub() function, escape processing: Gory Details. (line 6) * h debugger command (alias for help): Miscellaneous Dgawk Commands. (line 68) @@ -25720,11 +25752,11 @@ Index * igawk.sh program: Igawk Program. (line 124) * ignore debugger command: Breakpoint Control. (line 86) * IGNORECASE variable <1>: String Functions. (line 29) -* IGNORECASE variable <2>: Array Sorting. (line 68) +* IGNORECASE variable <2>: Array Sorting. (line 81) * IGNORECASE variable <3>: Array Intro. (line 92) * IGNORECASE variable <4>: User-modified. (line 82) * IGNORECASE variable: Case-sensitivity. (line 26) -* IGNORECASE variable, array sorting and: Array Sorting. (line 68) +* IGNORECASE variable, array sorting and: Array Sorting. (line 81) * IGNORECASE variable, array subscripts and: Array Intro. (line 92) * IGNORECASE variable, in example programs: Library Functions. (line 42) @@ -25741,7 +25773,7 @@ Index * in operator, arrays and: Reference to Elements. (line 37) * increment operators: Increment Ops. (line 6) -* index() function: String Functions. (line 137) +* index() function: String Functions. (line 152) * indexing arrays: Array Intro. (line 50) * indirect function calls: Indirect Calls. (line 6) * info debugger command: Dgawk Info. (line 12) @@ -25877,7 +25909,7 @@ Index (line 11) * left shift, bitwise: Bitwise Functions. (line 32) * leftmost longest match: Multiple Line. (line 26) -* length() function: String Functions. (line 148) +* length() function: String Functions. (line 163) * Lesser General Public License (LGPL): Glossary. (line 385) * LGPL (Lesser General Public License): Glossary. (line 385) * libmawk: Other Versions. (line 104) @@ -25961,9 +25993,9 @@ Index (line 6) * marked strings, extracting: String Extraction. (line 6) * Marx, Groucho: Increment Ops. (line 61) -* match() function: String Functions. (line 188) +* match() function: String Functions. (line 203) * match() function, RSTART/RLENGTH variables: String Functions. - (line 205) + (line 220) * matching, expressions, See comparison expressions: Typing and Comparison. (line 9) * matching, leftmost longest: Multiple Line. (line 26) @@ -26038,7 +26070,7 @@ Index * not Boolean-logic operator: Boolean Ops. (line 6) * NR variable <1>: Auto-set. (line 118) * NR variable: Records. (line 6) -* NR variable, changing: Auto-set. (line 230) +* NR variable, changing: Auto-set. (line 229) * null strings <1>: Basic Data Typing. (line 50) * null strings <2>: Truth Values. (line 6) * null strings <3>: Regexp Field Splitting. @@ -26162,7 +26194,7 @@ Index * parentheses (): Regexp Operators. (line 79) * parentheses (), pgawk program: Profiling. (line 141) * password file: Passwd Functions. (line 16) -* patsplit() function: String Functions. (line 275) +* patsplit() function: String Functions. (line 290) * patterns: Patterns and Actions. (line 6) * patterns, comparison expressions as: Expression Patterns. (line 14) @@ -26220,7 +26252,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 157) +* 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) @@ -26228,7 +26260,7 @@ Index * portability, operators: Increment Ops. (line 61) * portability, operators, not in POSIX awk: Precedence. (line 98) * portability, POSIXLY_CORRECT environment variable: Options. (line 305) -* portability, substr() function: String Functions. (line 494) +* 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. @@ -26264,7 +26296,7 @@ Index * POSIX awk, field separators and: Fields. (line 6) * POSIX awk, FS variable and: User-modified. (line 66) * POSIX awk, function keyword in: Definition Syntax. (line 83) -* POSIX awk, functions and, length(): String Functions. (line 157) +* 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) @@ -26402,7 +26434,7 @@ Index * recursive functions: Definition Syntax. (line 73) * redirection of input: Getline/File. (line 6) * redirection of output: Redirection. (line 6) -* reference counting, sorting arrays: Array Sorting. (line 62) +* reference counting, sorting arrays: Array Sorting. (line 75) * regexp constants <1>: Comparison Operators. (line 103) * regexp constants <2>: Regexp Constants. (line 6) @@ -26468,8 +26500,8 @@ Index * right angle bracket (>), >> operator (I/O): Redirection. (line 50) * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 74) -* RLENGTH variable: Auto-set. (line 206) -* RLENGTH variable, match() function and: String Functions. (line 205) +* RLENGTH variable: Auto-set. (line 205) +* 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 106) @@ -26493,9 +26525,9 @@ Index * RS variable: Records. (line 20) * RS variable, multiline records and: Multiple Line. (line 17) * rshift() function (gawk): Bitwise Functions. (line 51) -* RSTART variable: Auto-set. (line 212) -* RSTART variable, match() function and: String Functions. (line 205) -* RT variable <1>: Auto-set. (line 219) +* RSTART variable: Auto-set. (line 211) +* RSTART variable, match() function and: String Functions. (line 220) +* RT variable <1>: Auto-set. (line 218) * RT variable <2>: Getline/Variable/File. (line 10) * RT variable <3>: Multiple Line. (line 129) @@ -26521,7 +26553,7 @@ Index * search paths, for source files <2>: PC Using. (line 11) * search paths, for source files <3>: Igawk Program. (line 364) * search paths, for source files: AWKPATH Variable. (line 6) -* searching: String Functions. (line 137) +* searching: String Functions. (line 152) * searching, files for regular expressions: Egrep Program. (line 6) * searching, for words: Dupword Program. (line 6) * sed utility <1>: Glossary. (line 12) @@ -26560,7 +26592,7 @@ Index * side effects: Concatenation. (line 42) * side effects, array indexing: Reference to Elements. (line 42) -* side effects, asort() function: Array Sorting. (line 25) +* side effects, asort() function: Array Sorting. (line 24) * side effects, assignment expressions: Assignment Ops. (line 23) * side effects, Boolean operators: Boolean Ops. (line 30) * side effects, conditional expressions: Conditional Exp. (line 22) @@ -26612,10 +26644,10 @@ Index * sparse arrays: Array Intro. (line 71) * Spencer, Henry: Glossary. (line 12) * split utility: Split Program. (line 6) -* split() function: String Functions. (line 297) +* split() function: String Functions. (line 312) * split() function, array elements, deleting: Delete. (line 57) * split.awk program: Split Program. (line 30) -* sprintf() function <1>: String Functions. (line 362) +* 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. @@ -26664,14 +26696,14 @@ Index * strings, null: Regexp Field Splitting. (line 43) * strings, numeric: Variable Typing. (line 6) -* strings, splitting: String Functions. (line 317) -* strtonum() function (gawk): String Functions. (line 369) +* 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 390) +* sub() function <1>: String Functions. (line 405) * sub() function: Using Constant Regexps. (line 43) -* sub() function, arguments of: String Functions. (line 444) +* sub() function, arguments of: String Functions. (line 459) * sub() function, escape processing: Gory Details. (line 6) * subscript separators: User-modified. (line 147) * subscripts in arrays, multidimensional: Multi-dimensional. (line 10) @@ -26684,7 +26716,7 @@ Index * SUBSEP variable: User-modified. (line 147) * SUBSEP variable, multidimensional arrays: Multi-dimensional. (line 16) -* substr() function: String Functions. (line 463) +* substr() function: String Functions. (line 478) * Sumner, Andrew: Other Versions. (line 55) * switch statement: Switch Statement. (line 6) * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. @@ -26735,8 +26767,8 @@ Index * timestamps, converting dates to: Time Functions. (line 74) * timestamps, formatted: Gettimeofday Function. (line 6) -* tolower() function: String Functions. (line 505) -* toupper() function: String Functions. (line 511) +* tolower() function: String Functions. (line 520) +* toupper() function: String Functions. (line 526) * tr utility: Translate Program. (line 6) * trace debugger command: Miscellaneous Dgawk Commands. (line 110) @@ -26759,9 +26791,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 454) -* troubleshooting, match() function: String Functions. (line 270) -* troubleshooting, patsplit() function: String Functions. (line 293) +* 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) @@ -26770,7 +26802,7 @@ Index * troubleshooting, regexp constants vs. string constants: Computed Regexps. (line 38) * troubleshooting, string concatenation: Concatenation. (line 27) -* troubleshooting, substr() function: String Functions. (line 481) +* troubleshooting, substr() function: String Functions. (line 496) * troubleshooting, system() function: I/O Functions. (line 85) * troubleshooting, typographical errors, global variables: Options. (line 94) @@ -27122,225 +27154,225 @@ Node: Built-in Variables383628 Node: User-modified384723 Ref: User-modified-Footnote-1392749 Node: Auto-set392811 -Ref: Auto-set-Footnote-1403553 -Node: ARGC and ARGV403758 -Node: Arrays407609 -Node: Array Basics409180 -Node: Array Intro409891 -Node: Reference to Elements414209 -Node: Assigning Elements416479 -Node: Array Example416970 -Node: Scanning an Array418702 -Node: Controlling Scanning421078 -Node: Delete424416 -Ref: Delete-Footnote-1426851 -Node: Numeric Array Subscripts426908 -Node: Uninitialized Subscripts429091 -Node: Multi-dimensional430719 -Node: Multi-scanning433810 -Node: Array Sorting435394 -Ref: Array Sorting-Footnote-1438488 -Node: Arrays of Arrays438682 -Node: Functions443255 -Node: Built-in444077 -Node: Calling Built-in445155 -Node: Numeric Functions447143 -Ref: Numeric Functions-Footnote-1450908 -Ref: Numeric Functions-Footnote-2451265 -Ref: Numeric Functions-Footnote-3451313 -Node: String Functions451582 -Ref: String Functions-Footnote-1474084 -Ref: String Functions-Footnote-2474213 -Ref: String Functions-Footnote-3474461 -Node: Gory Details474548 -Ref: table-sub-escapes476227 -Ref: table-posix-sub477541 -Ref: table-gensub-escapes478454 -Node: I/O Functions479625 -Ref: I/O Functions-Footnote-1486280 -Node: Time Functions486427 -Ref: Time Functions-Footnote-1497319 -Ref: Time Functions-Footnote-2497387 -Ref: Time Functions-Footnote-3497545 -Ref: Time Functions-Footnote-4497656 -Ref: Time Functions-Footnote-5497768 -Ref: Time Functions-Footnote-6497995 -Node: Bitwise Functions498261 -Ref: table-bitwise-ops498819 -Ref: Bitwise Functions-Footnote-1502979 -Node: Type Functions503163 -Node: I18N Functions503633 -Node: User-defined505260 -Node: Definition Syntax506064 -Ref: Definition Syntax-Footnote-1510974 -Node: Function Example511043 -Node: Function Caveats513637 -Node: Calling A Function514058 -Node: Variable Scope515173 -Node: Pass By Value/Reference517148 -Node: Return Statement520588 -Node: Dynamic Typing523569 -Node: Indirect Calls524304 -Node: Internationalization533989 -Node: I18N and L10N535415 -Node: Explaining gettext536101 -Ref: Explaining gettext-Footnote-1541167 -Ref: Explaining gettext-Footnote-2541351 -Node: Programmer i18n541516 -Node: Translator i18n545716 -Node: String Extraction546509 -Ref: String Extraction-Footnote-1547470 -Node: Printf Ordering547556 -Ref: Printf Ordering-Footnote-1550340 -Node: I18N Portability550404 -Ref: I18N Portability-Footnote-1552853 -Node: I18N Example552916 -Ref: I18N Example-Footnote-1555551 -Node: Gawk I18N555623 -Node: Advanced Features556240 -Node: Nondecimal Data557559 -Node: Two-way I/O559140 -Ref: Two-way I/O-Footnote-1564574 -Node: TCP/IP Networking564644 -Node: Profiling567488 -Node: Library Functions574962 -Ref: Library Functions-Footnote-1577969 -Node: Library Names578140 -Ref: Library Names-Footnote-1581611 -Ref: Library Names-Footnote-2581831 -Node: General Functions581917 -Node: Strtonum Function582870 -Node: Assert Function585800 -Node: Round Function589126 -Node: Cliff Random Function590669 -Node: Ordinal Functions591685 -Ref: Ordinal Functions-Footnote-1594755 -Ref: Ordinal Functions-Footnote-2595007 -Node: Join Function595216 -Ref: Join Function-Footnote-1596987 -Node: Gettimeofday Function597187 -Node: Data File Management600902 -Node: Filetrans Function601534 -Node: Rewind Function605673 -Node: File Checking607060 -Node: Empty Files608154 -Node: Ignoring Assigns610384 -Node: Getopt Function611937 -Ref: Getopt Function-Footnote-1623241 -Node: Passwd Functions623444 -Ref: Passwd Functions-Footnote-1632419 -Node: Group Functions632507 -Node: Walking Arrays640591 -Node: Sample Programs642160 -Node: Running Examples642825 -Node: Clones643553 -Node: Cut Program644777 -Node: Egrep Program654622 -Ref: Egrep Program-Footnote-1662395 -Node: Id Program662505 -Node: Split Program666121 -Ref: Split Program-Footnote-1669640 -Node: Tee Program669768 -Node: Uniq Program672571 -Node: Wc Program680000 -Ref: Wc Program-Footnote-1684266 -Ref: Wc Program-Footnote-2684466 -Node: Miscellaneous Programs684558 -Node: Dupword Program685746 -Node: Alarm Program687777 -Node: Translate Program692526 -Ref: Translate Program-Footnote-1696913 -Ref: Translate Program-Footnote-2697141 -Node: Labels Program697275 -Ref: Labels Program-Footnote-1700646 -Node: Word Sorting700730 -Node: History Sorting704614 -Node: Extract Program706453 -Ref: Extract Program-Footnote-1713936 -Node: Simple Sed714064 -Node: Igawk Program717126 -Ref: Igawk Program-Footnote-1732159 -Ref: Igawk Program-Footnote-2732360 -Node: Anagram Program732498 -Node: Signature Program735566 -Node: Debugger736666 -Node: Debugging737577 -Node: Debugging Concepts737990 -Node: Debugging Terms739846 -Node: Awk Debugging742468 -Node: Sample dgawk session743360 -Node: dgawk invocation743852 -Node: Finding The Bug745034 -Node: List of Debugger Commands751520 -Node: Breakpoint Control752831 -Node: Dgawk Execution Control756467 -Node: Viewing And Changing Data759818 -Node: Dgawk Stack763155 -Node: Dgawk Info764615 -Node: Miscellaneous Dgawk Commands768563 -Node: Readline Support773991 -Node: Dgawk Limitations774829 -Node: Language History777018 -Node: V7/SVR3.1778456 -Node: SVR4780777 -Node: POSIX782219 -Node: BTL783227 -Node: POSIX/GNU783961 -Node: Common Extensions789062 -Node: Contributors790163 -Node: Installation794302 -Node: Gawk Distribution795196 -Node: Getting795680 -Node: Extracting796506 -Node: Distribution contents798198 -Node: Unix Installation803420 -Node: Quick Installation804037 -Node: Additional Configuration Options805999 -Node: Configuration Philosophy807476 -Node: Non-Unix Installation809818 -Node: PC Installation810276 -Node: PC Binary Installation811575 -Node: PC Compiling813423 -Node: PC Testing816367 -Node: PC Using817543 -Node: Cygwin821728 -Node: MSYS822728 -Node: VMS Installation823242 -Node: VMS Compilation823845 -Ref: VMS Compilation-Footnote-1824852 -Node: VMS Installation Details824910 -Node: VMS Running826545 -Node: VMS Old Gawk828152 -Node: Bugs828626 -Node: Other Versions832536 -Node: Notes837815 -Node: Compatibility Mode838507 -Node: Additions839290 -Node: Accessing The Source840102 -Node: Adding Code841527 -Node: New Ports847494 -Node: Dynamic Extensions851607 -Node: Internals852983 -Node: Plugin License862086 -Node: Sample Library862720 -Node: Internal File Description863406 -Node: Internal File Ops867121 -Ref: Internal File Ops-Footnote-1871902 -Node: Using Internal File Ops872042 -Node: Future Extensions874419 -Node: Basic Concepts876923 -Node: Basic High Level877680 -Ref: Basic High Level-Footnote-1881715 -Node: Basic Data Typing881900 -Node: Floating Point Issues886425 -Node: String Conversion Precision887508 -Ref: String Conversion Precision-Footnote-1889202 -Node: Unexpected Results889311 -Node: POSIX Floating Point Problems891137 -Ref: POSIX Floating Point Problems-Footnote-1894839 -Node: Glossary894877 -Node: Copying919020 -Node: GNU Free Documentation License956577 -Node: Index981714 +Ref: Auto-set-Footnote-1403524 +Node: ARGC and ARGV403729 +Node: Arrays407580 +Node: Array Basics409151 +Node: Array Intro409862 +Node: Reference to Elements414180 +Node: Assigning Elements416450 +Node: Array Example416941 +Node: Scanning an Array418673 +Node: Controlling Scanning421049 +Node: Delete424695 +Ref: Delete-Footnote-1427130 +Node: Numeric Array Subscripts427187 +Node: Uninitialized Subscripts429370 +Node: Multi-dimensional430998 +Node: Multi-scanning434089 +Node: Array Sorting435673 +Ref: Array Sorting-Footnote-1439452 +Node: Arrays of Arrays439646 +Node: Functions444219 +Node: Built-in445041 +Node: Calling Built-in446119 +Node: Numeric Functions448107 +Ref: Numeric Functions-Footnote-1451872 +Ref: Numeric Functions-Footnote-2452229 +Ref: Numeric Functions-Footnote-3452277 +Node: String Functions452546 +Ref: String Functions-Footnote-1475818 +Ref: String Functions-Footnote-2475947 +Ref: String Functions-Footnote-3476195 +Node: Gory Details476282 +Ref: table-sub-escapes477961 +Ref: table-posix-sub479275 +Ref: table-gensub-escapes480188 +Node: I/O Functions481359 +Ref: I/O Functions-Footnote-1488014 +Node: Time Functions488161 +Ref: Time Functions-Footnote-1499053 +Ref: Time Functions-Footnote-2499121 +Ref: Time Functions-Footnote-3499279 +Ref: Time Functions-Footnote-4499390 +Ref: Time Functions-Footnote-5499502 +Ref: Time Functions-Footnote-6499729 +Node: Bitwise Functions499995 +Ref: table-bitwise-ops500553 +Ref: Bitwise Functions-Footnote-1504713 +Node: Type Functions504897 +Node: I18N Functions505367 +Node: User-defined506994 +Node: Definition Syntax507798 +Ref: Definition Syntax-Footnote-1512708 +Node: Function Example512777 +Node: Function Caveats515371 +Node: Calling A Function515792 +Node: Variable Scope516907 +Node: Pass By Value/Reference518882 +Node: Return Statement522322 +Node: Dynamic Typing525303 +Node: Indirect Calls526038 +Node: Internationalization535723 +Node: I18N and L10N537149 +Node: Explaining gettext537835 +Ref: Explaining gettext-Footnote-1542901 +Ref: Explaining gettext-Footnote-2543085 +Node: Programmer i18n543250 +Node: Translator i18n547450 +Node: String Extraction548243 +Ref: String Extraction-Footnote-1549204 +Node: Printf Ordering549290 +Ref: Printf Ordering-Footnote-1552074 +Node: I18N Portability552138 +Ref: I18N Portability-Footnote-1554587 +Node: I18N Example554650 +Ref: I18N Example-Footnote-1557285 +Node: Gawk I18N557357 +Node: Advanced Features557974 +Node: Nondecimal Data559293 +Node: Two-way I/O560874 +Ref: Two-way I/O-Footnote-1566308 +Node: TCP/IP Networking566378 +Node: Profiling569222 +Node: Library Functions576696 +Ref: Library Functions-Footnote-1579703 +Node: Library Names579874 +Ref: Library Names-Footnote-1583345 +Ref: Library Names-Footnote-2583565 +Node: General Functions583651 +Node: Strtonum Function584604 +Node: Assert Function587534 +Node: Round Function590860 +Node: Cliff Random Function592403 +Node: Ordinal Functions593419 +Ref: Ordinal Functions-Footnote-1596489 +Ref: Ordinal Functions-Footnote-2596741 +Node: Join Function596950 +Ref: Join Function-Footnote-1598721 +Node: Gettimeofday Function598921 +Node: Data File Management602636 +Node: Filetrans Function603268 +Node: Rewind Function607407 +Node: File Checking608794 +Node: Empty Files609888 +Node: Ignoring Assigns612118 +Node: Getopt Function613671 +Ref: Getopt Function-Footnote-1624975 +Node: Passwd Functions625178 +Ref: Passwd Functions-Footnote-1634153 +Node: Group Functions634241 +Node: Walking Arrays642325 +Node: Sample Programs643894 +Node: Running Examples644559 +Node: Clones645287 +Node: Cut Program646511 +Node: Egrep Program656356 +Ref: Egrep Program-Footnote-1664129 +Node: Id Program664239 +Node: Split Program667855 +Ref: Split Program-Footnote-1671374 +Node: Tee Program671502 +Node: Uniq Program674305 +Node: Wc Program681734 +Ref: Wc Program-Footnote-1686000 +Ref: Wc Program-Footnote-2686200 +Node: Miscellaneous Programs686292 +Node: Dupword Program687480 +Node: Alarm Program689511 +Node: Translate Program694260 +Ref: Translate Program-Footnote-1698647 +Ref: Translate Program-Footnote-2698875 +Node: Labels Program699009 +Ref: Labels Program-Footnote-1702380 +Node: Word Sorting702464 +Node: History Sorting706348 +Node: Extract Program708187 +Ref: Extract Program-Footnote-1715670 +Node: Simple Sed715798 +Node: Igawk Program718860 +Ref: Igawk Program-Footnote-1733893 +Ref: Igawk Program-Footnote-2734094 +Node: Anagram Program734232 +Node: Signature Program737300 +Node: Debugger738400 +Node: Debugging739311 +Node: Debugging Concepts739724 +Node: Debugging Terms741580 +Node: Awk Debugging744202 +Node: Sample dgawk session745094 +Node: dgawk invocation745586 +Node: Finding The Bug746768 +Node: List of Debugger Commands753254 +Node: Breakpoint Control754565 +Node: Dgawk Execution Control758201 +Node: Viewing And Changing Data761552 +Node: Dgawk Stack764889 +Node: Dgawk Info766349 +Node: Miscellaneous Dgawk Commands770297 +Node: Readline Support775725 +Node: Dgawk Limitations776563 +Node: Language History778752 +Node: V7/SVR3.1780190 +Node: SVR4782511 +Node: POSIX783953 +Node: BTL784961 +Node: POSIX/GNU785695 +Node: Common Extensions790796 +Node: Contributors791897 +Node: Installation796036 +Node: Gawk Distribution796930 +Node: Getting797414 +Node: Extracting798240 +Node: Distribution contents799932 +Node: Unix Installation805154 +Node: Quick Installation805771 +Node: Additional Configuration Options807733 +Node: Configuration Philosophy809210 +Node: Non-Unix Installation811552 +Node: PC Installation812010 +Node: PC Binary Installation813309 +Node: PC Compiling815157 +Node: PC Testing818101 +Node: PC Using819277 +Node: Cygwin823462 +Node: MSYS824462 +Node: VMS Installation824976 +Node: VMS Compilation825579 +Ref: VMS Compilation-Footnote-1826586 +Node: VMS Installation Details826644 +Node: VMS Running828279 +Node: VMS Old Gawk829886 +Node: Bugs830360 +Node: Other Versions834270 +Node: Notes839549 +Node: Compatibility Mode840241 +Node: Additions841024 +Node: Accessing The Source841836 +Node: Adding Code843261 +Node: New Ports849228 +Node: Dynamic Extensions853341 +Node: Internals854717 +Node: Plugin License863820 +Node: Sample Library864454 +Node: Internal File Description865140 +Node: Internal File Ops868855 +Ref: Internal File Ops-Footnote-1873636 +Node: Using Internal File Ops873776 +Node: Future Extensions876153 +Node: Basic Concepts878657 +Node: Basic High Level879414 +Ref: Basic High Level-Footnote-1883449 +Node: Basic Data Typing883634 +Node: Floating Point Issues888159 +Node: String Conversion Precision889242 +Ref: String Conversion Precision-Footnote-1890936 +Node: Unexpected Results891045 +Node: POSIX Floating Point Problems892871 +Ref: POSIX Floating Point Problems-Footnote-1896573 +Node: Glossary896611 +Node: Copying920754 +Node: GNU Free Documentation License958311 +Node: Index983448 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 2adad8be..def2a019 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -12755,9 +12755,8 @@ The value should contain one to three words; separate pairs of words by a single space. One word controls sort direction, @samp{ascending} or @samp{descending}; another controls the sort key, @samp{index} or @samp{value}; and the remaining -one, which is only valid for sorting by index, is comparison mode, -@samp{string} or @samp{number}. When two or three words are present, they may -be specified in any order, so @samp{ascending index string} and +one affects comparison mode, @samp{string} or @samp{number}. When two or three +words are present, they may be specified in any order, so @samp{ascending index string} and @samp{string ascending index} are equivalent. Also, each word may be truncated, so @samp{asc index str} and @samp{a i s} are also equivalent. Note that a separating space is required even when the @@ -12765,11 +12764,10 @@ words have been shortened down to one letter each. You can omit direction and/or key type and/or comparison mode. Provided that at least one is present, the missing parts of a sort specification -default to @samp{ascending}, @samp{index}, and (for indices only) @samp{string}, -respectively. -An empty string, @code{""}, is the same as @samp{unsorted} and will cause -@samp{for (index in array) @dots{}} to process the indices in -arbitrary order. Another thing to note is that the array sorting +default to @samp{ascending}, @samp{index}, and @samp{string}, respectively. +An empty string, @code{""}, is the same as @samp{ascending index string}, +and a value of @samp{unsorted} will cause @samp{for (index in array) @dots{}} to process +the indices in arbitrary order. Another thing to note is that the array sorting takes place at the time the @code{for} loop is about to start executing, so changing the value of @code{PROCINFO["sorted_in"]} during loop execution does not have any effect on the order in which any @@ -13465,11 +13463,14 @@ the index is actually @code{"10"} rather than numeric 10.) Order by indices but force them to be treated as numbers in the process. Any index with non-numeric value will end up positioned as if it were zero. -@item ascending value -Order by element values rather than by indices. Comparisons are done -as numeric when both values being compared are numeric, or done as -strings when either or both aren't numeric (@pxref{Variable Typing}). -Subarrays, if present, come out last. +@item ascending value string +Order by element values rather than by indices. Scalar values are +compared as strings. Subarrays, if present, come out last. + +@item ascending value number +Order by values but force scalar values to be treated as numbers +for the purpose of comparison. If there are subarrays, those appear +at the end of the sorted list. @item descending index string Reverse order from the most basic sort. @@ -13477,22 +13478,31 @@ Reverse order from the most basic sort. @item descending index number Numeric indices ordered from high to low. -@item descending value -Element values ordered from high to low. Subarrays, if present, +@item descending value string +Element values, treated as strings, ordered from high to low. Subarrays, if present, +come out first. + +@item descending value number +Element values, treated as numbers, ordered from high to low. Subarrays, if present, come out first. @item unsorted Array elements are processed in arbitrary order, the normal @command{awk} -behavior. +behavior. You can also get the normal behavior by just +deleting the @code{"sorted_in"} item from the @code{PROCINFO} array, if +it previously had a value assigned to it. @end table The array traversal order is determined before the @code{for} loop -starts to run. Changing @code{PROCINFO["sorted_in"]} in the looop body +starts to run. Changing @code{PROCINFO["sorted_in"]} in the loop body will not affect the loop. Portions of the sort specification string may be truncated or omitted. The default is @samp{ascending} for direction, @samp{index} for sort key type, -and (when sorting by index only) @samp{string} for comparison mode. +and @samp{string} for comparison mode. This implies that one can +simply assign the empty string, "", instead of "ascending index string" to +@code{PROCINFO["sorted_in"]} for the same effect. + For example: @example @@ -13521,11 +13531,6 @@ numeric value, regardless of what the subarray itself contains, and all subarrays are treated as being equal to each other. Their order relative to each other is determined by their index strings. -Sorting by array element values (for values other than subarrays) -always uses basic @command{awk} comparison mode: if both values -happen to be numbers then they're compared as numbers, otherwise -they're compared as strings. - When string comparisons are made during a sort, either for element values where one or both aren't numbers or for element indices handled as strings, the value of @code{IGNORECASE} @@ -13952,9 +13957,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 of array elements is done -using @command{gawk}'s usual comparison rules -(@pxref{Typing and Comparison}). +The array elements are compared as strings. @cindex side effects, @code{asort()} function An important side effect of calling @code{asort()} is that @@ -13973,6 +13976,22 @@ 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()} and @code{asorti()} accept a third string argument +to control the comparison rule for the array elements, and the direction +of the sorted results. The valid comparison modes are @samp{string} and @samp{number}, +and the direction can be either @samp{ascending} or @samp{descending}. +Either mode or direction, or both, can be omitted in which +case the defaults, @samp{string} or @samp{ascending} is assumed +for the comparison mode and the direction, respectively. Seperate comparison +mode from direction with a single space, and they can appear in any +order. To compare the elements as numbers, and to reverse the elements +of the @code{dest} array, the call to asort in the above example can be +replaced with: + +@example +asort(source, dest, "descending number") +@end example + 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 @@ -13997,7 +14016,9 @@ END @{ 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. +@var{n} down to 1, either over the elements or over the indices. This +is an alternative to specifying @samp{descending} for the sorting order +using the optional third argument. @cindex reference counting, sorting arrays Copying array indices and elements isn't expensive in terms of memory. @@ -14011,10 +14032,8 @@ both arrays use the values. @cindex @code{IGNORECASE} variable @cindex arrays, sorting, @code{IGNORECASE} variable and @cindex @code{IGNORECASE} variable, array sorting and -We said previously that comparisons are done using @command{gawk}'s -``usual comparison rules.'' Because @code{IGNORECASE} affects -string comparisons, the value of @code{IGNORECASE} also -affects sorting for both @code{asort()} and @code{asorti()}. +Because @code{IGNORECASE} affects string comparisons, the value +of @code{IGNORECASE} also affects sorting for both @code{asort()} and @code{asorti()}. Note also that the locale's sorting order does @emph{not} come into play; comparisons are based on character values only.@footnote{This is true because locale-based comparison occurs only when in POSIX @@ -14439,20 +14458,29 @@ pound sign@w{ (@samp{#}):} @end menu @table @code -@item asort(@var{source} @r{[}, @var{dest}@r{]}) # +@item asort(@var{source} @r{[}, @var{dest} @r{[}, @var{how} @r{]} @r{]}) # @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} -using the normal rules for comparing values -(in particular, @code{IGNORECASE} affects the sorting) 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, +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. +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. +@xref{Scanning an Array}, for more information. + For example, if the contents of @code{a} are as follows: @example @@ -14477,17 +14505,23 @@ 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: + +@example +asort(a, a, "descending") +@end example + The @code{asort()} function is described in more detail in @ref{Array Sorting}. @code{asort()} is a @command{gawk} extension; it is not available in compatibility mode (@pxref{Options}). -@item asorti(@var{source} @r{[}, @var{dest}@r{]}) # +@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. As array indices are always strings, -the comparison performed is always a string comparison. (Here too, +are sorted, instead of the values. (Here too, @code{IGNORECASE} affects the sorting.) The @code{asorti()} function is described in more detail in |