Add example of asort() with a function name parameter.

4 files changed, 366 insertions, 211 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 2fc9384d..b0eb67ed 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2016-01-13         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in (Array Sorting Functions): Add an example of
+	using a function name with asort(). Response to bug report
+	Stephane Goujet <stephane.goujet@wanadoo.fr>.
+
 2015-12-27         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in: Fix some @c endfile. Thanks to Antonio
diff --git a/doc/gawk.info b/doc/gawk.info
index da2ef6b7..3be5cea8 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -19445,6 +19445,51 @@ result array.
 Note also that the locale's sorting order does _not_ come into play;
 comparisons are based on character values only.(1)
 
+   The following example demonstrates the use of a comparison function
+with 'asort()'.  The comparison function, 'case_fold_compare()', does a
+string comparison ignoring case (by mapping both values to lowercase).
+
+     # case_fold_compare --- compare as strings, ignoring case
+
+     function case_fold_compare(i1, v1, i2, v2,    l, r)
+     {
+         l = tolower(v1)
+         r = tolower(v2)
+
+         if (l < r)
+             return -1
+         else if (l == r)
+             return 0
+         else
+             return 1
+     }
+
+   And here is the test program for it:
+
+     # Test program
+
+     BEGIN {
+         Letters = "abcdefghijklmnopqrstuvwxyz" \
+                   "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+         split(Letters, data, "")
+
+         asort(data, result, "case_fold_compare")
+
+         for (i = 1; i <= 52; i++) {
+             printf("%s", result[i])
+             if (i % 26 == 0)
+                 printf("\n")
+             else
+                 printf(" ")
+         }
+     }
+
+   When run, we get the following:
+
+     $ gawk -f case_fold_compare.awk
+     -| A a B b c C D d e E F f g G H h i I J j k K l L M m
+     -| n N O o p P Q q r R S s t T u U V v w W X x y Y z Z
+
    ---------- Footnotes ----------
 
    (1) This is true because locale-based comparison occurs only when in
@@ -34829,216 +34874,216 @@ Node: Array Sorting778396
 Node: Controlling Array Traversal779096
 Ref: Controlling Array Traversal-Footnote-1787465
 Node: Array Sorting Functions787583
-Ref: Array Sorting Functions-Footnote-1791470
-Node: Two-way I/O791666
-Ref: Two-way I/O-Footnote-1796617
-Ref: Two-way I/O-Footnote-2796804
-Node: TCP/IP Networking796886
-Node: Profiling800004
-Node: Advanced Features Summary807543
-Node: Internationalization809479
-Node: I18N and L10N810959
-Node: Explaining gettext811646
-Ref: Explaining gettext-Footnote-1816669
-Ref: Explaining gettext-Footnote-2816854
-Node: Programmer i18n817019
-Ref: Programmer i18n-Footnote-1821875
-Node: Translator i18n821924
-Node: String Extraction822718
-Ref: String Extraction-Footnote-1823851
-Node: Printf Ordering823937
-Ref: Printf Ordering-Footnote-1826723
-Node: I18N Portability826787
-Ref: I18N Portability-Footnote-1829243
-Node: I18N Example829306
-Ref: I18N Example-Footnote-1832112
-Node: Gawk I18N832185
-Node: I18N Summary832830
-Node: Debugger834171
-Node: Debugging835193
-Node: Debugging Concepts835634
-Node: Debugging Terms837443
-Node: Awk Debugging840018
-Node: Sample Debugging Session840924
-Node: Debugger Invocation841458
-Node: Finding The Bug842844
-Node: List of Debugger Commands849322
-Node: Breakpoint Control850655
-Node: Debugger Execution Control854349
-Node: Viewing And Changing Data857711
-Node: Execution Stack861085
-Node: Debugger Info862722
-Node: Miscellaneous Debugger Commands866793
-Node: Readline Support871881
-Node: Limitations872777
-Node: Debugging Summary874886
-Node: Arbitrary Precision Arithmetic876059
-Node: Computer Arithmetic877475
-Ref: table-numeric-ranges881066
-Ref: Computer Arithmetic-Footnote-1881788
-Node: Math Definitions881845
-Ref: table-ieee-formats885159
-Ref: Math Definitions-Footnote-1885762
-Node: MPFR features885867
-Node: FP Math Caution887540
-Ref: FP Math Caution-Footnote-1888612
-Node: Inexactness of computations888981
-Node: Inexact representation889941
-Node: Comparing FP Values891301
-Node: Errors accumulate892383
-Node: Getting Accuracy893816
-Node: Try To Round896526
-Node: Setting precision897425
-Ref: table-predefined-precision-strings898122
-Node: Setting the rounding mode899952
-Ref: table-gawk-rounding-modes900326
-Ref: Setting the rounding mode-Footnote-1903734
-Node: Arbitrary Precision Integers903913
-Ref: Arbitrary Precision Integers-Footnote-1906897
-Node: POSIX Floating Point Problems907046
-Ref: POSIX Floating Point Problems-Footnote-1910928
-Node: Floating point summary910966
-Node: Dynamic Extensions913156
-Node: Extension Intro914709
-Node: Plugin License915975
-Node: Extension Mechanism Outline916772
-Ref: figure-load-extension917211
-Ref: figure-register-new-function918776
-Ref: figure-call-new-function919868
-Node: Extension API Description921931
-Node: Extension API Functions Introduction923379
-Node: General Data Types928191
-Ref: General Data Types-Footnote-1934146
-Node: Memory Allocation Functions934445
-Ref: Memory Allocation Functions-Footnote-1937290
-Node: Constructor Functions937389
-Node: Registration Functions939134
-Node: Extension Functions939819
-Node: Exit Callback Functions942118
-Node: Extension Version String943368
-Node: Input Parsers944031
-Node: Output Wrappers953916
-Node: Two-way processors958428
-Node: Printing Messages960692
-Ref: Printing Messages-Footnote-1961766
-Node: Updating ERRNO961919
-Node: Requesting Values962658
-Ref: table-value-types-returned963395
-Node: Accessing Parameters964278
-Node: Symbol Table Access965514
-Node: Symbol table by name966026
-Node: Symbol table by cookie968047
-Ref: Symbol table by cookie-Footnote-1972196
-Node: Cached values972260
-Ref: Cached values-Footnote-1975761
-Node: Array Manipulation975852
-Ref: Array Manipulation-Footnote-1976951
-Node: Array Data Types976988
-Ref: Array Data Types-Footnote-1979646
-Node: Array Functions979738
-Node: Flattening Arrays983597
-Node: Creating Arrays990505
-Node: Extension API Variables995277
-Node: Extension Versioning995913
-Node: Extension API Informational Variables997804
-Node: Extension API Boilerplate998868
-Node: Finding Extensions1002682
-Node: Extension Example1003242
-Node: Internal File Description1004040
-Node: Internal File Ops1008120
-Ref: Internal File Ops-Footnote-11019882
-Node: Using Internal File Ops1020022
-Ref: Using Internal File Ops-Footnote-11022405
-Node: Extension Samples1022680
-Node: Extension Sample File Functions1024209
-Node: Extension Sample Fnmatch1031858
-Node: Extension Sample Fork1033345
-Node: Extension Sample Inplace1034563
-Node: Extension Sample Ord1037773
-Node: Extension Sample Readdir1038609
-Ref: table-readdir-file-types1039498
-Node: Extension Sample Revout1040303
-Node: Extension Sample Rev2way1040892
-Node: Extension Sample Read write array1041632
-Node: Extension Sample Readfile1043574
-Node: Extension Sample Time1044669
-Node: Extension Sample API Tests1046017
-Node: gawkextlib1046509
-Node: Extension summary1048933
-Node: Extension Exercises1052625
-Node: Language History1054122
-Node: V7/SVR3.11055778
-Node: SVR41057930
-Node: POSIX1059364
-Node: BTL1060744
-Node: POSIX/GNU1061474
-Node: Feature History1066995
-Node: Common Extensions1080324
-Node: Ranges and Locales1081607
-Ref: Ranges and Locales-Footnote-11086223
-Ref: Ranges and Locales-Footnote-21086250
-Ref: Ranges and Locales-Footnote-31086485
-Node: Contributors1086706
-Node: History summary1092275
-Node: Installation1093655
-Node: Gawk Distribution1094600
-Node: Getting1095084
-Node: Extracting1096045
-Node: Distribution contents1097683
-Node: Unix Installation1103436
-Node: Quick Installation1104052
-Node: Additional Configuration Options1106479
-Node: Configuration Philosophy1108283
-Node: Non-Unix Installation1110653
-Node: PC Installation1111111
-Node: PC Binary Installation1112431
-Node: PC Compiling1114283
-Ref: PC Compiling-Footnote-11117307
-Node: PC Testing1117416
-Node: PC Using1118596
-Node: Cygwin1122710
-Node: MSYS1123480
-Node: VMS Installation1123981
-Node: VMS Compilation1124772
-Ref: VMS Compilation-Footnote-11126002
-Node: VMS Dynamic Extensions1126060
-Node: VMS Installation Details1127745
-Node: VMS Running1129998
-Node: VMS GNV1132839
-Node: VMS Old Gawk1133574
-Node: Bugs1134045
-Node: Other Versions1138242
-Node: Installation summary1144828
-Node: Notes1145886
-Node: Compatibility Mode1146751
-Node: Additions1147533
-Node: Accessing The Source1148458
-Node: Adding Code1149894
-Node: New Ports1156113
-Node: Derived Files1160601
-Ref: Derived Files-Footnote-11166086
-Ref: Derived Files-Footnote-21166121
-Ref: Derived Files-Footnote-31166719
-Node: Future Extensions1166833
-Node: Implementation Limitations1167491
-Node: Extension Design1168674
-Node: Old Extension Problems1169828
-Ref: Old Extension Problems-Footnote-11171346
-Node: Extension New Mechanism Goals1171403
-Ref: Extension New Mechanism Goals-Footnote-11174767
-Node: Extension Other Design Decisions1174956
-Node: Extension Future Growth1177069
-Node: Old Extension Mechanism1177905
-Node: Notes summary1179668
-Node: Basic Concepts1180850
-Node: Basic High Level1181531
-Ref: figure-general-flow1181813
-Ref: figure-process-flow1182498
-Ref: Basic High Level-Footnote-11185799
-Node: Basic Data Typing1185984
-Node: Glossary1189312
-Node: Copying1221258
-Node: GNU Free Documentation License1258797
-Node: Index1283915
+Ref: Array Sorting Functions-Footnote-1792652
+Node: Two-way I/O792848
+Ref: Two-way I/O-Footnote-1797799
+Ref: Two-way I/O-Footnote-2797986
+Node: TCP/IP Networking798068
+Node: Profiling801186
+Node: Advanced Features Summary808725
+Node: Internationalization810661
+Node: I18N and L10N812141
+Node: Explaining gettext812828
+Ref: Explaining gettext-Footnote-1817851
+Ref: Explaining gettext-Footnote-2818036
+Node: Programmer i18n818201
+Ref: Programmer i18n-Footnote-1823057
+Node: Translator i18n823106
+Node: String Extraction823900
+Ref: String Extraction-Footnote-1825033
+Node: Printf Ordering825119
+Ref: Printf Ordering-Footnote-1827905
+Node: I18N Portability827969
+Ref: I18N Portability-Footnote-1830425
+Node: I18N Example830488
+Ref: I18N Example-Footnote-1833294
+Node: Gawk I18N833367
+Node: I18N Summary834012
+Node: Debugger835353
+Node: Debugging836375
+Node: Debugging Concepts836816
+Node: Debugging Terms838625
+Node: Awk Debugging841200
+Node: Sample Debugging Session842106
+Node: Debugger Invocation842640
+Node: Finding The Bug844026
+Node: List of Debugger Commands850504
+Node: Breakpoint Control851837
+Node: Debugger Execution Control855531
+Node: Viewing And Changing Data858893
+Node: Execution Stack862267
+Node: Debugger Info863904
+Node: Miscellaneous Debugger Commands867975
+Node: Readline Support873063
+Node: Limitations873959
+Node: Debugging Summary876068
+Node: Arbitrary Precision Arithmetic877241
+Node: Computer Arithmetic878657
+Ref: table-numeric-ranges882248
+Ref: Computer Arithmetic-Footnote-1882970
+Node: Math Definitions883027
+Ref: table-ieee-formats886341
+Ref: Math Definitions-Footnote-1886944
+Node: MPFR features887049
+Node: FP Math Caution888722
+Ref: FP Math Caution-Footnote-1889794
+Node: Inexactness of computations890163
+Node: Inexact representation891123
+Node: Comparing FP Values892483
+Node: Errors accumulate893565
+Node: Getting Accuracy894998
+Node: Try To Round897708
+Node: Setting precision898607
+Ref: table-predefined-precision-strings899304
+Node: Setting the rounding mode901134
+Ref: table-gawk-rounding-modes901508
+Ref: Setting the rounding mode-Footnote-1904916
+Node: Arbitrary Precision Integers905095
+Ref: Arbitrary Precision Integers-Footnote-1908079
+Node: POSIX Floating Point Problems908228
+Ref: POSIX Floating Point Problems-Footnote-1912110
+Node: Floating point summary912148
+Node: Dynamic Extensions914338
+Node: Extension Intro915891
+Node: Plugin License917157
+Node: Extension Mechanism Outline917954
+Ref: figure-load-extension918393
+Ref: figure-register-new-function919958
+Ref: figure-call-new-function921050
+Node: Extension API Description923113
+Node: Extension API Functions Introduction924561
+Node: General Data Types929373
+Ref: General Data Types-Footnote-1935328
+Node: Memory Allocation Functions935627
+Ref: Memory Allocation Functions-Footnote-1938472
+Node: Constructor Functions938571
+Node: Registration Functions940316
+Node: Extension Functions941001
+Node: Exit Callback Functions943300
+Node: Extension Version String944550
+Node: Input Parsers945213
+Node: Output Wrappers955098
+Node: Two-way processors959610
+Node: Printing Messages961874
+Ref: Printing Messages-Footnote-1962948
+Node: Updating ERRNO963101
+Node: Requesting Values963840
+Ref: table-value-types-returned964577
+Node: Accessing Parameters965460
+Node: Symbol Table Access966696
+Node: Symbol table by name967208
+Node: Symbol table by cookie969229
+Ref: Symbol table by cookie-Footnote-1973378
+Node: Cached values973442
+Ref: Cached values-Footnote-1976943
+Node: Array Manipulation977034
+Ref: Array Manipulation-Footnote-1978133
+Node: Array Data Types978170
+Ref: Array Data Types-Footnote-1980828
+Node: Array Functions980920
+Node: Flattening Arrays984779
+Node: Creating Arrays991687
+Node: Extension API Variables996459
+Node: Extension Versioning997095
+Node: Extension API Informational Variables998986
+Node: Extension API Boilerplate1000050
+Node: Finding Extensions1003864
+Node: Extension Example1004424
+Node: Internal File Description1005222
+Node: Internal File Ops1009302
+Ref: Internal File Ops-Footnote-11021064
+Node: Using Internal File Ops1021204
+Ref: Using Internal File Ops-Footnote-11023587
+Node: Extension Samples1023862
+Node: Extension Sample File Functions1025391
+Node: Extension Sample Fnmatch1033040
+Node: Extension Sample Fork1034527
+Node: Extension Sample Inplace1035745
+Node: Extension Sample Ord1038955
+Node: Extension Sample Readdir1039791
+Ref: table-readdir-file-types1040680
+Node: Extension Sample Revout1041485
+Node: Extension Sample Rev2way1042074
+Node: Extension Sample Read write array1042814
+Node: Extension Sample Readfile1044756
+Node: Extension Sample Time1045851
+Node: Extension Sample API Tests1047199
+Node: gawkextlib1047691
+Node: Extension summary1050115
+Node: Extension Exercises1053807
+Node: Language History1055304
+Node: V7/SVR3.11056960
+Node: SVR41059112
+Node: POSIX1060546
+Node: BTL1061926
+Node: POSIX/GNU1062656
+Node: Feature History1068177
+Node: Common Extensions1081506
+Node: Ranges and Locales1082789
+Ref: Ranges and Locales-Footnote-11087405
+Ref: Ranges and Locales-Footnote-21087432
+Ref: Ranges and Locales-Footnote-31087667
+Node: Contributors1087888
+Node: History summary1093457
+Node: Installation1094837
+Node: Gawk Distribution1095782
+Node: Getting1096266
+Node: Extracting1097227
+Node: Distribution contents1098865
+Node: Unix Installation1104618
+Node: Quick Installation1105234
+Node: Additional Configuration Options1107661
+Node: Configuration Philosophy1109465
+Node: Non-Unix Installation1111835
+Node: PC Installation1112293
+Node: PC Binary Installation1113613
+Node: PC Compiling1115465
+Ref: PC Compiling-Footnote-11118489
+Node: PC Testing1118598
+Node: PC Using1119778
+Node: Cygwin1123892
+Node: MSYS1124662
+Node: VMS Installation1125163
+Node: VMS Compilation1125954
+Ref: VMS Compilation-Footnote-11127184
+Node: VMS Dynamic Extensions1127242
+Node: VMS Installation Details1128927
+Node: VMS Running1131180
+Node: VMS GNV1134021
+Node: VMS Old Gawk1134756
+Node: Bugs1135227
+Node: Other Versions1139424
+Node: Installation summary1146010
+Node: Notes1147068
+Node: Compatibility Mode1147933
+Node: Additions1148715
+Node: Accessing The Source1149640
+Node: Adding Code1151076
+Node: New Ports1157295
+Node: Derived Files1161783
+Ref: Derived Files-Footnote-11167268
+Ref: Derived Files-Footnote-21167303
+Ref: Derived Files-Footnote-31167901
+Node: Future Extensions1168015
+Node: Implementation Limitations1168673
+Node: Extension Design1169856
+Node: Old Extension Problems1171010
+Ref: Old Extension Problems-Footnote-11172528
+Node: Extension New Mechanism Goals1172585
+Ref: Extension New Mechanism Goals-Footnote-11175949
+Node: Extension Other Design Decisions1176138
+Node: Extension Future Growth1178251
+Node: Old Extension Mechanism1179087
+Node: Notes summary1180850
+Node: Basic Concepts1182032
+Node: Basic High Level1182713
+Ref: figure-general-flow1182995
+Ref: figure-process-flow1183680
+Ref: Basic High Level-Footnote-11186981
+Node: Basic Data Typing1187166
+Node: Glossary1190494
+Node: Copying1222440
+Node: GNU Free Documentation License1259979
+Node: Index1285097
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index f6114b4e..5d1e45c6 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -27238,6 +27238,58 @@ is true because locale-based comparison occurs only when in
 POSIX-compatibility mode, and because @code{asort()} and @code{asorti()} are
 @command{gawk} extensions, they are not available in that case.}
 
+The following example demonstrates the use of a comparison function
+with @code{asort()}.  The comparison function,
+@code{case_fold_compare()}, does a string comparison ignoring case
+(by mapping both values to lowercase).
+
+@example
+# case_fold_compare --- compare as strings, ignoring case
+
+function case_fold_compare(i1, v1, i2, v2,    l, r)
+@{
+    l = tolower(v1)
+    r = tolower(v2)
+
+    if (l < r)
+        return -1
+    else if (l == r)
+        return 0
+    else
+        return 1
+@}
+@end example
+
+And here is the test program for it:
+
+@example
+# Test program
+
+BEGIN @{
+    Letters = "abcdefghijklmnopqrstuvwxyz" \
+              "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    split(Letters, data, "")
+
+    asort(data, result, "case_fold_compare")
+
+    for (i = 1; i <= 52; i++) @{
+        printf("%s", result[i])
+        if (i % 26 == 0)
+            printf("\n")
+        else
+            printf(" ")
+    @}
+@}
+@end example
+
+When run, we get the following:
+
+@example
+$ @kbd{gawk -f case_fold_compare.awk}
+@print{} A a B b c C D d e E F f g G H h i I J j k K l L M m
+@print{} n N O o p P Q q r R S s t T u U V v w W X x y Y z Z
+@end example
+
 @node Two-way I/O
 @section Two-Way Communications with Another Process
 
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index edd945db..081e067a 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -26329,6 +26329,58 @@ is true because locale-based comparison occurs only when in
 POSIX-compatibility mode, and because @code{asort()} and @code{asorti()} are
 @command{gawk} extensions, they are not available in that case.}
 
+The following example demonstrates the use of a comparison function
+with @code{asort()}.  The comparison function,
+@code{case_fold_compare()}, does a string comparison ignoring case
+(by mapping both values to lowercase).
+
+@example
+# case_fold_compare --- compare as strings, ignoring case
+
+function case_fold_compare(i1, v1, i2, v2,    l, r)
+@{
+    l = tolower(v1)
+    r = tolower(v2)
+
+    if (l < r)
+        return -1
+    else if (l == r)
+        return 0
+    else
+        return 1
+@}
+@end example
+
+And here is the test program for it:
+
+@example
+# Test program
+
+BEGIN @{
+    Letters = "abcdefghijklmnopqrstuvwxyz" \
+              "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    split(Letters, data, "")
+
+    asort(data, result, "case_fold_compare")
+
+    for (i = 1; i <= 52; i++) @{
+        printf("%s", result[i])
+        if (i % 26 == 0)
+            printf("\n")
+        else
+            printf(" ")
+    @}
+@}
+@end example
+
+When run, we get the following:
+
+@example
+$ @kbd{gawk -f case_fold_compare.awk}
+@print{} A a B b c C D d e E F f g G H h i I J j k K l L M m
+@print{} n N O o p P Q q r R S s t T u U V v w W X x y Y z Z
+@end example
+
 @node Two-way I/O
 @section Two-Way Communications with Another Process