[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, gawk-4.0-stable, updated. 2a63ca5d9af44d
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, gawk-4.0-stable, updated. 2a63ca5d9af44de631e7853c8320357c6f5d6a3a |
|
Date: |
Sun, 06 Nov 2011 20:03:08 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, gawk-4.0-stable has been updated
via 2a63ca5d9af44de631e7853c8320357c6f5d6a3a (commit)
from 029d61f3b4632a52679802d54e9972b1423ef805 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=2a63ca5d9af44de631e7853c8320357c6f5d6a3a
commit 2a63ca5d9af44de631e7853c8320357c6f5d6a3a
Author: Arnold D. Robbins <address@hidden>
Date: Sun Nov 6 22:02:31 2011 +0200
Improve discussion of sorted for traversal.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 53ab79a..e4855ca 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2011-11-06 Arnold D. Robbins <address@hidden>
+
+ * gawk.texi: Try to improve discussion of sorted array
+ traversal.
+
2011-09-24 Arnold D. Robbins <address@hidden>
* gawk.1: Fix some spelling errors. Thanks to
diff --git a/doc/gawk.info b/doc/gawk.info
index 0606273..53fe12d 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -10203,7 +10203,7 @@ File: gawk.info, Node: Multi-scanning, Up:
Multi-dimensional
--------------------------------------
There is no special `for' statement for scanning a "multidimensional"
-array. There cannot be one, because, in truth, there are no
+array. There cannot be one, because, in truth, `awk' does not have
multidimensional arrays or elements--there is only a multidimensional
_way of accessing_ an array.
@@ -10223,7 +10223,7 @@ in the array, and splits it into the individual indices
by breaking it
apart where the value of `SUBSEP' appears. The individual indices then
become the elements of the array `separate'.
- Thus, if a value is previously stored in `array[1, "foo"]'; then an
+ Thus, if a value is previously stored in `array[1, "foo"]', then an
element with index `"1\034foo"' exists in `array'. (Recall that the
default value of `SUBSEP' is the character with code 034.) Sooner or
later, the `for' statement finds that index and does an iteration with
@@ -10242,8 +10242,9 @@ File: gawk.info, Node: Arrays of Arrays, Prev:
Multi-dimensional, Up: Arrays
8.6 Arrays of Arrays
====================
-`gawk' supports arrays of arrays. Elements of a subarray are referred
-to by their own indices enclosed in square brackets, just like the
+`gawk' goes beyond standard `awk''s multidimensional array access and
+provides true arrays of arrays. Elements of a subarray are referred to
+by their own indices enclosed in square brackets, just like the
elements of the main array. For example, the following creates a
two-element subarray at index `1' of the main array `a':
@@ -13603,7 +13604,7 @@ of the previous functions:
-| data[10] = one
-| data[20] = two
-|
- -| Sort function: cmp_num_str_val Sort all numbers before all strings
+ -| Sort function: cmp_num_str_val Sort all numeric values before all
strings
-| data[one] = 10
-| data[two] = 20
-| data[100] = 100
@@ -13611,7 +13612,7 @@ of the previous functions:
-| data[20] = two
Consider sorting the entries of a GNU/Linux system password file
-according to login names. The following program sorts records by a
+according to login name. The following program sorts records by a
specific field position and can be used for this purpose:
# sort.awk --- simple program to sort by field position
@@ -13727,13 +13728,17 @@ based on comparing the indices in ascending order,"
or "sort based on
comparing the values in descending order." Having to write a simple
comparison function for this purpose for use in all of your programs
becomes tedious. For the common simple cases, `gawk' provides the
-option of supplying special names that do the requested sorting for you.
+option of using special names that do the requested sorting for you.
You can think of them as "predefined" sorting functions, if you like,
although the names purposely include characters that are not valid in
real `awk' function names.
The following special values are available:
+`"@unsorted"'
+ Array elements are processed in arbitrary order, which is the
+ 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'
@@ -13759,7 +13764,8 @@ real `awk' function names.
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)
+ 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.
@@ -13778,12 +13784,6 @@ real `awk' function names.
Element values, treated as numbers, ordered from high to low.
Subarrays, if present, come out first.
-`"@unsorted"'
- Array elements are processed in arbitrary order, which is the
- normal `awk' behavior. You can also get the normal behavior by just
- deleting the `"sorted_in"' element 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 loop body will not
affect the loop.
@@ -13814,6 +13814,31 @@ 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.
+ Here are some additional things to bear in mind about sorted array
+traversal.
+
+ * The value of `PROCINFO["sorted_in"]' is global. That is, it affects
+ all array traversal `for' loops. If you need to change it within
+ your own function, you should see if it's defined and save and
+ restore the value:
+
+ function myfunct(p1, p2, save_sorted)
+ {
+ ...
+ if ("sorted_in" in PROCINFO) {
+ save_sorted = PROCINFO["sorted_in"]
+ PROCINFO["sorted_in"] = "@val_str_desc" # or whatever
+ }
+ ...
+ if (save_sorted)
+ PROCINFO["sorted_in"] = save_sorted
+ }
+
+ * As mentioned, the default array traversal order is represented by
+ `"@unsorted"'. You can also get the default behavior by assigning
+ the null string to `PROCINFO["sorted_in"]' or by just deleting the
+ `"sorted_in"' element from the `PROCINFO' array.
+
---------- Footnotes ----------
(1) When two elements compare as equal, the C `qsort()' function
@@ -13842,7 +13867,9 @@ 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 array elements are compared as strings.
+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.
An important side effect of calling `asort()' is that _the array's
original indices are irrevocably lost_. As this isn't always
@@ -25015,7 +25042,7 @@ Index
* arrays, sorting: Array Sorting Functions.
(line 6)
* arrays, sorting, IGNORECASE variable and: Array Sorting Functions.
- (line 78)
+ (line 80)
* arrays, sparse: Array Intro. (line 71)
* arrays, subscripts: Numeric Array Subscripts.
(line 6)
@@ -26060,7 +26087,7 @@ Index
* gawk, functions, adding: Dynamic Extensions. (line 10)
* gawk, hexadecimal numbers and: Nondecimal-numbers. (line 42)
* gawk, IGNORECASE variable in <1>: Array Sorting Functions.
- (line 78)
+ (line 80)
* gawk, IGNORECASE variable in <2>: String Functions. (line 29)
* gawk, IGNORECASE variable in <3>: Array Intro. (line 92)
* gawk, IGNORECASE variable in <4>: User-modified. (line 82)
@@ -26220,13 +26247,13 @@ Index
* igawk.sh program: Igawk Program. (line 124)
* ignore debugger command: Breakpoint Control. (line 86)
* IGNORECASE variable <1>: Array Sorting Functions.
- (line 78)
+ (line 80)
* IGNORECASE variable <2>: String Functions. (line 29)
* 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 Functions.
- (line 78)
+ (line 80)
* IGNORECASE variable, array subscripts and: Array Intro. (line 92)
* IGNORECASE variable, in example programs: Library Functions.
(line 42)
@@ -26909,7 +26936,7 @@ Index
* redirection of input: Getline/File. (line 6)
* redirection of output: Redirection. (line 6)
* reference counting, sorting arrays: Array Sorting Functions.
- (line 72)
+ (line 74)
* regexp constants <1>: Comparison Operators.
(line 103)
* regexp constants <2>: Regexp Constants. (line 6)
@@ -27068,7 +27095,7 @@ Index
* side effects, array indexing: Reference to Elements.
(line 42)
* side effects, asort() function: Array Sorting Functions.
- (line 22)
+ (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)
@@ -27647,221 +27674,221 @@ Node: Numeric Array Subscripts424017
Node: Uninitialized Subscripts426200
Node: Multi-dimensional427828
Node: Multi-scanning430922
-Node: Arrays of Arrays432506
-Node: Functions437083
-Node: Built-in437905
-Node: Calling Built-in438983
-Node: Numeric Functions440971
-Ref: Numeric Functions-Footnote-1444736
-Ref: Numeric Functions-Footnote-2445093
-Ref: Numeric Functions-Footnote-3445141
-Node: String Functions445410
-Ref: String Functions-Footnote-1468907
-Ref: String Functions-Footnote-2469036
-Ref: String Functions-Footnote-3469284
-Node: Gory Details469371
-Ref: table-sub-escapes471050
-Ref: table-sub-posix-92472404
-Ref: table-sub-proposed473747
-Ref: table-posix-sub475097
-Ref: table-gensub-escapes476643
-Ref: Gory Details-Footnote-1477850
-Ref: Gory Details-Footnote-2477901
-Node: I/O Functions478052
-Ref: I/O Functions-Footnote-1484707
-Node: Time Functions484854
-Ref: Time Functions-Footnote-1495746
-Ref: Time Functions-Footnote-2495814
-Ref: Time Functions-Footnote-3495972
-Ref: Time Functions-Footnote-4496083
-Ref: Time Functions-Footnote-5496195
-Ref: Time Functions-Footnote-6496422
-Node: Bitwise Functions496688
-Ref: table-bitwise-ops497246
-Ref: Bitwise Functions-Footnote-1501406
-Node: Type Functions501590
-Node: I18N Functions502060
-Node: User-defined503687
-Node: Definition Syntax504491
-Ref: Definition Syntax-Footnote-1509401
-Node: Function Example509470
-Node: Function Caveats512064
-Node: Calling A Function512485
-Node: Variable Scope513600
-Node: Pass By Value/Reference515575
-Node: Return Statement519015
-Node: Dynamic Typing521996
-Node: Indirect Calls522731
-Node: Internationalization532416
-Node: I18N and L10N533842
-Node: Explaining gettext534528
-Ref: Explaining gettext-Footnote-1539594
-Ref: Explaining gettext-Footnote-2539778
-Node: Programmer i18n539943
-Node: Translator i18n544143
-Node: String Extraction544936
-Ref: String Extraction-Footnote-1545897
-Node: Printf Ordering545983
-Ref: Printf Ordering-Footnote-1548767
-Node: I18N Portability548831
-Ref: I18N Portability-Footnote-1551280
-Node: I18N Example551343
-Ref: I18N Example-Footnote-1553978
-Node: Gawk I18N554050
-Node: Advanced Features554667
-Node: Nondecimal Data556180
-Node: Array Sorting557763
-Node: Controlling Array Traversal558463
-Node: Controlling Scanning With A Function559210
-Node: Controlling Scanning566913
-Ref: Controlling Scanning-Footnote-1570714
-Node: Array Sorting Functions571030
-Ref: Array Sorting Functions-Footnote-1574546
-Ref: Array Sorting Functions-Footnote-2574639
-Node: Two-way I/O574833
-Ref: Two-way I/O-Footnote-1580265
-Node: TCP/IP Networking580335
-Node: Profiling583179
-Node: Library Functions590653
-Ref: Library Functions-Footnote-1593660
-Node: Library Names593831
-Ref: Library Names-Footnote-1597302
-Ref: Library Names-Footnote-2597522
-Node: General Functions597608
-Node: Strtonum Function598561
-Node: Assert Function601491
-Node: Round Function604817
-Node: Cliff Random Function606360
-Node: Ordinal Functions607376
-Ref: Ordinal Functions-Footnote-1610446
-Ref: Ordinal Functions-Footnote-2610698
-Node: Join Function610907
-Ref: Join Function-Footnote-1612678
-Node: Gettimeofday Function612878
-Node: Data File Management616593
-Node: Filetrans Function617225
-Node: Rewind Function621364
-Node: File Checking622751
-Node: Empty Files623845
-Node: Ignoring Assigns626075
-Node: Getopt Function627628
-Ref: Getopt Function-Footnote-1638932
-Node: Passwd Functions639135
-Ref: Passwd Functions-Footnote-1648110
-Node: Group Functions648198
-Node: Walking Arrays656282
-Node: Sample Programs657851
-Node: Running Examples658516
-Node: Clones659244
-Node: Cut Program660468
-Node: Egrep Program670313
-Ref: Egrep Program-Footnote-1678086
-Node: Id Program678196
-Node: Split Program681812
-Ref: Split Program-Footnote-1685331
-Node: Tee Program685459
-Node: Uniq Program688262
-Node: Wc Program695691
-Ref: Wc Program-Footnote-1699957
-Ref: Wc Program-Footnote-2700157
-Node: Miscellaneous Programs700249
-Node: Dupword Program701437
-Node: Alarm Program703468
-Node: Translate Program708217
-Ref: Translate Program-Footnote-1712604
-Ref: Translate Program-Footnote-2712832
-Node: Labels Program712966
-Ref: Labels Program-Footnote-1716337
-Node: Word Sorting716421
-Node: History Sorting720305
-Node: Extract Program722144
-Ref: Extract Program-Footnote-1729627
-Node: Simple Sed729755
-Node: Igawk Program732817
-Ref: Igawk Program-Footnote-1747974
-Ref: Igawk Program-Footnote-2748175
-Node: Anagram Program748313
-Node: Signature Program751381
-Node: Debugger752481
-Node: Debugging753392
-Node: Debugging Concepts753805
-Node: Debugging Terms755661
-Node: Awk Debugging758284
-Node: Sample dgawk session759176
-Node: dgawk invocation759668
-Node: Finding The Bug760850
-Node: List of Debugger Commands767336
-Node: Breakpoint Control768647
-Node: Dgawk Execution Control772283
-Node: Viewing And Changing Data775634
-Node: Dgawk Stack778971
-Node: Dgawk Info780431
-Node: Miscellaneous Dgawk Commands784379
-Node: Readline Support789807
-Node: Dgawk Limitations790645
-Node: Language History792834
-Node: V7/SVR3.1794346
-Node: SVR4796667
-Node: POSIX798109
-Node: BTL799117
-Node: POSIX/GNU799851
-Node: Common Extensions805002
-Node: Ranges and Locales806109
-Ref: Ranges and Locales-Footnote-1810716
-Node: Contributors810937
-Node: Installation815199
-Node: Gawk Distribution816093
-Node: Getting816577
-Node: Extracting817403
-Node: Distribution contents819095
-Node: Unix Installation824317
-Node: Quick Installation824934
-Node: Additional Configuration Options826896
-Node: Configuration Philosophy828373
-Node: Non-Unix Installation830715
-Node: PC Installation831173
-Node: PC Binary Installation832472
-Node: PC Compiling834320
-Node: PC Testing837264
-Node: PC Using838440
-Node: Cygwin842625
-Node: MSYS843625
-Node: VMS Installation844139
-Node: VMS Compilation844742
-Ref: VMS Compilation-Footnote-1845749
-Node: VMS Installation Details845807
-Node: VMS Running847442
-Node: VMS Old Gawk849049
-Node: Bugs849523
-Node: Other Versions853375
-Node: Notes858656
-Node: Compatibility Mode859348
-Node: Additions860131
-Node: Accessing The Source860943
-Node: Adding Code862368
-Node: New Ports868335
-Node: Dynamic Extensions872448
-Node: Internals873824
-Node: Plugin License882927
-Node: Sample Library883561
-Node: Internal File Description884247
-Node: Internal File Ops887962
-Ref: Internal File Ops-Footnote-1892743
-Node: Using Internal File Ops892883
-Node: Future Extensions895260
-Node: Basic Concepts897764
-Node: Basic High Level898521
-Ref: Basic High Level-Footnote-1902556
-Node: Basic Data Typing902741
-Node: Floating Point Issues907266
-Node: String Conversion Precision908349
-Ref: String Conversion Precision-Footnote-1910049
-Node: Unexpected Results910158
-Node: POSIX Floating Point Problems911984
-Ref: POSIX Floating Point Problems-Footnote-1915689
-Node: Glossary915727
-Node: Copying940703
-Node: GNU Free Documentation License978260
-Node: Index1003397
+Node: Arrays of Arrays432513
+Node: Functions437158
+Node: Built-in437980
+Node: Calling Built-in439058
+Node: Numeric Functions441046
+Ref: Numeric Functions-Footnote-1444811
+Ref: Numeric Functions-Footnote-2445168
+Ref: Numeric Functions-Footnote-3445216
+Node: String Functions445485
+Ref: String Functions-Footnote-1468982
+Ref: String Functions-Footnote-2469111
+Ref: String Functions-Footnote-3469359
+Node: Gory Details469446
+Ref: table-sub-escapes471125
+Ref: table-sub-posix-92472479
+Ref: table-sub-proposed473822
+Ref: table-posix-sub475172
+Ref: table-gensub-escapes476718
+Ref: Gory Details-Footnote-1477925
+Ref: Gory Details-Footnote-2477976
+Node: I/O Functions478127
+Ref: I/O Functions-Footnote-1484782
+Node: Time Functions484929
+Ref: Time Functions-Footnote-1495821
+Ref: Time Functions-Footnote-2495889
+Ref: Time Functions-Footnote-3496047
+Ref: Time Functions-Footnote-4496158
+Ref: Time Functions-Footnote-5496270
+Ref: Time Functions-Footnote-6496497
+Node: Bitwise Functions496763
+Ref: table-bitwise-ops497321
+Ref: Bitwise Functions-Footnote-1501481
+Node: Type Functions501665
+Node: I18N Functions502135
+Node: User-defined503762
+Node: Definition Syntax504566
+Ref: Definition Syntax-Footnote-1509476
+Node: Function Example509545
+Node: Function Caveats512139
+Node: Calling A Function512560
+Node: Variable Scope513675
+Node: Pass By Value/Reference515650
+Node: Return Statement519090
+Node: Dynamic Typing522071
+Node: Indirect Calls522806
+Node: Internationalization532491
+Node: I18N and L10N533917
+Node: Explaining gettext534603
+Ref: Explaining gettext-Footnote-1539669
+Ref: Explaining gettext-Footnote-2539853
+Node: Programmer i18n540018
+Node: Translator i18n544218
+Node: String Extraction545011
+Ref: String Extraction-Footnote-1545972
+Node: Printf Ordering546058
+Ref: Printf Ordering-Footnote-1548842
+Node: I18N Portability548906
+Ref: I18N Portability-Footnote-1551355
+Node: I18N Example551418
+Ref: I18N Example-Footnote-1554053
+Node: Gawk I18N554125
+Node: Advanced Features554742
+Node: Nondecimal Data556255
+Node: Array Sorting557838
+Node: Controlling Array Traversal558538
+Node: Controlling Scanning With A Function559285
+Node: Controlling Scanning566994
+Ref: Controlling Scanning-Footnote-1571648
+Node: Array Sorting Functions571964
+Ref: Array Sorting Functions-Footnote-1575613
+Ref: Array Sorting Functions-Footnote-2575706
+Node: Two-way I/O575900
+Ref: Two-way I/O-Footnote-1581332
+Node: TCP/IP Networking581402
+Node: Profiling584246
+Node: Library Functions591720
+Ref: Library Functions-Footnote-1594727
+Node: Library Names594898
+Ref: Library Names-Footnote-1598369
+Ref: Library Names-Footnote-2598589
+Node: General Functions598675
+Node: Strtonum Function599628
+Node: Assert Function602558
+Node: Round Function605884
+Node: Cliff Random Function607427
+Node: Ordinal Functions608443
+Ref: Ordinal Functions-Footnote-1611513
+Ref: Ordinal Functions-Footnote-2611765
+Node: Join Function611974
+Ref: Join Function-Footnote-1613745
+Node: Gettimeofday Function613945
+Node: Data File Management617660
+Node: Filetrans Function618292
+Node: Rewind Function622431
+Node: File Checking623818
+Node: Empty Files624912
+Node: Ignoring Assigns627142
+Node: Getopt Function628695
+Ref: Getopt Function-Footnote-1639999
+Node: Passwd Functions640202
+Ref: Passwd Functions-Footnote-1649177
+Node: Group Functions649265
+Node: Walking Arrays657349
+Node: Sample Programs658918
+Node: Running Examples659583
+Node: Clones660311
+Node: Cut Program661535
+Node: Egrep Program671380
+Ref: Egrep Program-Footnote-1679153
+Node: Id Program679263
+Node: Split Program682879
+Ref: Split Program-Footnote-1686398
+Node: Tee Program686526
+Node: Uniq Program689329
+Node: Wc Program696758
+Ref: Wc Program-Footnote-1701024
+Ref: Wc Program-Footnote-2701224
+Node: Miscellaneous Programs701316
+Node: Dupword Program702504
+Node: Alarm Program704535
+Node: Translate Program709284
+Ref: Translate Program-Footnote-1713671
+Ref: Translate Program-Footnote-2713899
+Node: Labels Program714033
+Ref: Labels Program-Footnote-1717404
+Node: Word Sorting717488
+Node: History Sorting721372
+Node: Extract Program723211
+Ref: Extract Program-Footnote-1730694
+Node: Simple Sed730822
+Node: Igawk Program733884
+Ref: Igawk Program-Footnote-1749041
+Ref: Igawk Program-Footnote-2749242
+Node: Anagram Program749380
+Node: Signature Program752448
+Node: Debugger753548
+Node: Debugging754459
+Node: Debugging Concepts754872
+Node: Debugging Terms756728
+Node: Awk Debugging759351
+Node: Sample dgawk session760243
+Node: dgawk invocation760735
+Node: Finding The Bug761917
+Node: List of Debugger Commands768403
+Node: Breakpoint Control769714
+Node: Dgawk Execution Control773350
+Node: Viewing And Changing Data776701
+Node: Dgawk Stack780038
+Node: Dgawk Info781498
+Node: Miscellaneous Dgawk Commands785446
+Node: Readline Support790874
+Node: Dgawk Limitations791712
+Node: Language History793901
+Node: V7/SVR3.1795413
+Node: SVR4797734
+Node: POSIX799176
+Node: BTL800184
+Node: POSIX/GNU800918
+Node: Common Extensions806069
+Node: Ranges and Locales807176
+Ref: Ranges and Locales-Footnote-1811783
+Node: Contributors812004
+Node: Installation816266
+Node: Gawk Distribution817160
+Node: Getting817644
+Node: Extracting818470
+Node: Distribution contents820162
+Node: Unix Installation825384
+Node: Quick Installation826001
+Node: Additional Configuration Options827963
+Node: Configuration Philosophy829440
+Node: Non-Unix Installation831782
+Node: PC Installation832240
+Node: PC Binary Installation833539
+Node: PC Compiling835387
+Node: PC Testing838331
+Node: PC Using839507
+Node: Cygwin843692
+Node: MSYS844692
+Node: VMS Installation845206
+Node: VMS Compilation845809
+Ref: VMS Compilation-Footnote-1846816
+Node: VMS Installation Details846874
+Node: VMS Running848509
+Node: VMS Old Gawk850116
+Node: Bugs850590
+Node: Other Versions854442
+Node: Notes859723
+Node: Compatibility Mode860415
+Node: Additions861198
+Node: Accessing The Source862010
+Node: Adding Code863435
+Node: New Ports869402
+Node: Dynamic Extensions873515
+Node: Internals874891
+Node: Plugin License883994
+Node: Sample Library884628
+Node: Internal File Description885314
+Node: Internal File Ops889029
+Ref: Internal File Ops-Footnote-1893810
+Node: Using Internal File Ops893950
+Node: Future Extensions896327
+Node: Basic Concepts898831
+Node: Basic High Level899588
+Ref: Basic High Level-Footnote-1903623
+Node: Basic Data Typing903808
+Node: Floating Point Issues908333
+Node: String Conversion Precision909416
+Ref: String Conversion Precision-Footnote-1911116
+Node: Unexpected Results911225
+Node: POSIX Floating Point Problems913051
+Ref: POSIX Floating Point Problems-Footnote-1916756
+Node: Glossary916794
+Node: Copying941770
+Node: GNU Free Documentation License979327
+Node: Index1004464
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 760340d..fa145bb 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -13785,8 +13785,9 @@ the program produces the following output:
@subsection Scanning Multidimensional Arrays
There is no special @code{for} statement for scanning a
-``multidimensional'' array. There cannot be one, because, in truth, there
-are no multidimensional arrays or elements---there is only a
+``multidimensional'' array. There cannot be one, because, in truth,
address@hidden does not have
+multidimensional arrays or elements---there is only a
multidimensional @emph{way of accessing} an array.
@cindex subscripts in arrays, multidimensional, scanning
@@ -13813,7 +13814,7 @@ into the individual indices by breaking it apart where
the value of
@code{SUBSEP} appears. The individual indices then become the elements of
the array @code{separate}.
-Thus, if a value is previously stored in @code{array[1, "foo"]}; then
+Thus, if a value is previously stored in @code{array[1, "foo"]}, then
an element with index @code{"1\034foo"} exists in @code{array}. (Recall
that the default value of @code{SUBSEP} is the character with code 034.)
Sooner or later, the @code{for} statement finds that index and does an
@@ -13833,7 +13834,8 @@ separate indices is recovered.
@node Arrays of Arrays
@section Arrays of Arrays
address@hidden supports arrays of
address@hidden goes beyond standard @command{awk}'s multidimensional
+array access and provides true arrays of
arrays. Elements of a subarray are referred to by their own indices
enclosed in square brackets, just like the elements of the main array.
For example, the following creates a two-element subarray at index @samp{1}
@@ -18314,7 +18316,7 @@ $ @kbd{gawk -f compdemo.awk}
@print{} data[10] = one
@print{} data[20] = two
@print{}
address@hidden Sort function: cmp_num_str_val @ii{Sort all numbers before all
strings}
address@hidden Sort function: cmp_num_str_val @ii{Sort all numeric values
before all strings}
@print{} data[one] = 10
@print{} data[two] = 20
@print{} data[100] = 100
@@ -18323,7 +18325,7 @@ $ @kbd{gawk -f compdemo.awk}
@end example
Consider sorting the entries of a GNU/Linux system password file
-according to login names. The following program sorts records
+according to login name. The following program sorts records
by a specific field position and can be used for this purpose:
@example
@@ -18464,7 +18466,7 @@ or ``sort based on comparing the values in descending
order.''
Having to write a simple comparison function for this purpose
for use in all of your programs becomes tedious.
For the common simple cases, @command{gawk} provides
-the option of supplying special names that do the requested
+the option of using special names that do the requested
sorting for you.
You can think of them as ``predefined'' sorting functions,
if you like, although the names purposely include characters
@@ -18473,6 +18475,10 @@ that are not valid in real @command{awk} function
names.
The following special values are available:
@table @code
address@hidden "@@unsorted"
+Array elements are processed in arbitrary order, which is the default
address@hidden behavior.
+
@item "@@ind_str_asc"
Order by indices compared as strings; this is the most basic sort.
(Internally, array indices are always strings, so with @samp{a[2*5] = 1}
@@ -18498,12 +18504,13 @@ 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 @code{qsort()} address@hidden two elements
+versions of the C @code{qsort()} address@hidden two elements
compare as equal, the C @code{qsort()} function does not guarantee
that they will maintain their original relative order after sorting.
Using the string value to provide a unique ordering when the numeric
values are equal ensures that @command{gawk} behaves consistently
-across different environments.}
+across different environments.}, which @command{gawk} uses internally
+to perform the sorting.
@item "@@ind_str_desc"
Reverse order from the most basic sort.
@@ -18521,12 +18528,6 @@ Subarrays, if present, come out first.
@item "@@val_num_desc"
Element values, treated as numbers, ordered from high to low.
Subarrays, if present, come out first.
-
address@hidden "@@unsorted"
-Array elements are processed in arbitrary order, which is the normal
address@hidden behavior. You can also get the normal behavior by just
-deleting the @code{"sorted_in"} element 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
@@ -18561,6 +18562,36 @@ 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.
+Here are some additional things to bear in mind about sorted
+array traversal.
+
address@hidden @bullet
address@hidden
+The value of @code{PROCINFO["sorted_in"]} is global. That is, it affects
+all array traversal @code{for} loops. If you need to change it within your
+own function, you should see if it's defined and save and restore the value:
+
address@hidden
+function myfunct(p1, p2, save_sorted)
address@hidden
+ @dots{}
+ if ("sorted_in" in PROCINFO) @{
+ save_sorted = PROCINFO["sorted_in"]
+ PROCINFO["sorted_in"] = "@@val_str_desc" # or whatever
+ @}
+ @dots{}
+ if (save_sorted)
+ PROCINFO["sorted_in"] = save_sorted
address@hidden
address@hidden example
+
address@hidden
+As mentioned, the default array traversal order is represented by
address@hidden"@@unsorted"}. You can also get the default behavior by assigning
+the null string to @code{PROCINFO["sorted_in"]} or by just deleting the
address@hidden"sorted_in"} element from the @code{PROCINFO} array.
address@hidden itemize
+
@node Array Sorting Functions
@subsection Sorting Array Values and Indices with @command{gawk}
@@ -18588,7 +18619,10 @@ 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 array elements are compared as strings.
+The 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.
@cindex side effects, @code{asort()} function
An important side effect of calling @code{asort()} is that
-----------------------------------------------------------------------
Summary of changes:
doc/ChangeLog | 5 +
doc/gawk.info | 501 ++++++++++++++++++++++++++++++---------------------------
doc/gawk.texi | 66 ++++++--
3 files changed, 319 insertions(+), 253 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, gawk-4.0-stable, updated. 2a63ca5d9af44de631e7853c8320357c6f5d6a3a,
Arnold Robbins <=