Merge branch 'gawk-4.1-stable'

4 files changed, 369 insertions, 214 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 8d29cd88..f6e1b6bc 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>.
+
 2016-01-06         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in: Finish documenting that --pretty-print
diff --git a/doc/gawk.info b/doc/gawk.info
index ad05dcf4..1d50f327 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -19705,6 +19705,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
@@ -35381,219 +35426,219 @@ Node: Array Sorting789561
 Node: Controlling Array Traversal790261
 Ref: Controlling Array Traversal-Footnote-1798630
 Node: Array Sorting Functions798748
-Ref: Array Sorting Functions-Footnote-1802635
-Node: Two-way I/O802831
-Ref: Two-way I/O-Footnote-1807782
-Ref: Two-way I/O-Footnote-2807969
-Node: TCP/IP Networking808051
-Node: Profiling811169
-Node: Advanced Features Summary819440
-Node: Internationalization821284
-Node: I18N and L10N822764
-Node: Explaining gettext823451
-Ref: Explaining gettext-Footnote-1828474
-Ref: Explaining gettext-Footnote-2828659
-Node: Programmer i18n828824
-Ref: Programmer i18n-Footnote-1833680
-Node: Translator i18n833729
-Node: String Extraction834523
-Ref: String Extraction-Footnote-1835656
-Node: Printf Ordering835742
-Ref: Printf Ordering-Footnote-1838528
-Node: I18N Portability838592
-Ref: I18N Portability-Footnote-1841048
-Node: I18N Example841111
-Ref: I18N Example-Footnote-1843917
-Node: Gawk I18N843990
-Node: I18N Summary844635
-Node: Debugger845976
-Node: Debugging846998
-Node: Debugging Concepts847439
-Node: Debugging Terms849248
-Node: Awk Debugging851823
-Node: Sample Debugging Session852729
-Node: Debugger Invocation853263
-Node: Finding The Bug854649
-Node: List of Debugger Commands861127
-Node: Breakpoint Control862460
-Node: Debugger Execution Control866154
-Node: Viewing And Changing Data869516
-Node: Execution Stack872890
-Node: Debugger Info874527
-Node: Miscellaneous Debugger Commands878598
-Node: Readline Support883686
-Node: Limitations884582
-Ref: Limitations-Footnote-1888813
-Node: Debugging Summary888864
-Node: Arbitrary Precision Arithmetic890143
-Node: Computer Arithmetic891559
-Ref: table-numeric-ranges895150
-Ref: Computer Arithmetic-Footnote-1895872
-Node: Math Definitions895929
-Ref: table-ieee-formats899243
-Ref: Math Definitions-Footnote-1899846
-Node: MPFR features899951
-Node: FP Math Caution901624
-Ref: FP Math Caution-Footnote-1902696
-Node: Inexactness of computations903065
-Node: Inexact representation904025
-Node: Comparing FP Values905385
-Node: Errors accumulate906467
-Node: Getting Accuracy907900
-Node: Try To Round910610
-Node: Setting precision911509
-Ref: table-predefined-precision-strings912206
-Node: Setting the rounding mode914036
-Ref: table-gawk-rounding-modes914410
-Ref: Setting the rounding mode-Footnote-1917818
-Node: Arbitrary Precision Integers917997
-Ref: Arbitrary Precision Integers-Footnote-1922914
-Node: POSIX Floating Point Problems923063
-Ref: POSIX Floating Point Problems-Footnote-1926945
-Node: Floating point summary926983
-Node: Dynamic Extensions929173
-Node: Extension Intro930726
-Node: Plugin License931992
-Node: Extension Mechanism Outline932789
-Ref: figure-load-extension933228
-Ref: figure-register-new-function934793
-Ref: figure-call-new-function935885
-Node: Extension API Description937948
-Node: Extension API Functions Introduction939480
-Node: General Data Types944339
-Ref: General Data Types-Footnote-1950294
-Node: Memory Allocation Functions950593
-Ref: Memory Allocation Functions-Footnote-1953438
-Node: Constructor Functions953537
-Node: Registration Functions955282
-Node: Extension Functions955967
-Node: Exit Callback Functions958266
-Node: Extension Version String959516
-Node: Input Parsers960179
-Node: Output Wrappers970064
-Node: Two-way processors974576
-Node: Printing Messages976840
-Ref: Printing Messages-Footnote-1977914
-Node: Updating ERRNO978067
-Node: Requesting Values978806
-Ref: table-value-types-returned979543
-Node: Accessing Parameters980426
-Node: Symbol Table Access981662
-Node: Symbol table by name982174
-Node: Symbol table by cookie984195
-Ref: Symbol table by cookie-Footnote-1988344
-Node: Cached values988408
-Ref: Cached values-Footnote-1991909
-Node: Array Manipulation992000
-Ref: Array Manipulation-Footnote-1993091
-Node: Array Data Types993128
-Ref: Array Data Types-Footnote-1995786
-Node: Array Functions995878
-Node: Flattening Arrays999737
-Node: Creating Arrays1006645
-Node: Redirection API1011417
-Node: Extension API Variables1014248
-Node: Extension Versioning1014881
-Node: Extension API Informational Variables1016772
-Node: Extension API Boilerplate1017836
-Node: Finding Extensions1021650
-Node: Extension Example1022210
-Node: Internal File Description1023008
-Node: Internal File Ops1027088
-Ref: Internal File Ops-Footnote-11038850
-Node: Using Internal File Ops1038990
-Ref: Using Internal File Ops-Footnote-11041373
-Node: Extension Samples1041648
-Node: Extension Sample File Functions1043177
-Node: Extension Sample Fnmatch1050826
-Node: Extension Sample Fork1052313
-Node: Extension Sample Inplace1053531
-Node: Extension Sample Ord1056741
-Node: Extension Sample Readdir1057577
-Ref: table-readdir-file-types1058466
-Node: Extension Sample Revout1059271
-Node: Extension Sample Rev2way1059860
-Node: Extension Sample Read write array1060600
-Node: Extension Sample Readfile1062542
-Node: Extension Sample Time1063637
-Node: Extension Sample API Tests1064985
-Node: gawkextlib1065477
-Node: Extension summary1067924
-Node: Extension Exercises1071616
-Node: Language History1073113
-Node: V7/SVR3.11074769
-Node: SVR41076921
-Node: POSIX1078355
-Node: BTL1079735
-Node: POSIX/GNU1080465
-Node: Feature History1086304
-Node: Common Extensions1100674
-Node: Ranges and Locales1101957
-Ref: Ranges and Locales-Footnote-11106573
-Ref: Ranges and Locales-Footnote-21106600
-Ref: Ranges and Locales-Footnote-31106835
-Node: Contributors1107056
-Node: History summary1112625
-Node: Installation1114005
-Node: Gawk Distribution1114950
-Node: Getting1115434
-Node: Extracting1116395
-Node: Distribution contents1118033
-Node: Unix Installation1124129
-Node: Quick Installation1124811
-Node: Shell Startup Files1127225
-Node: Additional Configuration Options1128303
-Node: Configuration Philosophy1130108
-Node: Non-Unix Installation1132478
-Node: PC Installation1132936
-Node: PC Binary Installation1134256
-Node: PC Compiling1136108
-Ref: PC Compiling-Footnote-11139132
-Node: PC Testing1139241
-Node: PC Using1140421
-Node: Cygwin1144535
-Node: MSYS1145305
-Node: VMS Installation1145806
-Node: VMS Compilation1146597
-Ref: VMS Compilation-Footnote-11147827
-Node: VMS Dynamic Extensions1147885
-Node: VMS Installation Details1149570
-Node: VMS Running1151823
-Node: VMS GNV1154664
-Node: VMS Old Gawk1155399
-Node: Bugs1155870
-Node: Other Versions1160067
-Node: Installation summary1166653
-Node: Notes1167711
-Node: Compatibility Mode1168576
-Node: Additions1169358
-Node: Accessing The Source1170283
-Node: Adding Code1171719
-Node: New Ports1177938
-Node: Derived Files1182426
-Ref: Derived Files-Footnote-11187911
-Ref: Derived Files-Footnote-21187946
-Ref: Derived Files-Footnote-31188544
-Node: Future Extensions1188658
-Node: Implementation Limitations1189316
-Node: Extension Design1190499
-Node: Old Extension Problems1191653
-Ref: Old Extension Problems-Footnote-11193171
-Node: Extension New Mechanism Goals1193228
-Ref: Extension New Mechanism Goals-Footnote-11196592
-Node: Extension Other Design Decisions1196781
-Node: Extension Future Growth1198894
-Node: Old Extension Mechanism1199730
-Node: Notes summary1201493
-Node: Basic Concepts1202675
-Node: Basic High Level1203356
-Ref: figure-general-flow1203638
-Ref: figure-process-flow1204323
-Ref: Basic High Level-Footnote-11207624
-Node: Basic Data Typing1207809
-Node: Glossary1211137
-Node: Copying1243083
-Node: GNU Free Documentation License1280622
-Node: Index1305740
+Ref: Array Sorting Functions-Footnote-1803817
+Node: Two-way I/O804013
+Ref: Two-way I/O-Footnote-1808964
+Ref: Two-way I/O-Footnote-2809151
+Node: TCP/IP Networking809233
+Node: Profiling812351
+Node: Advanced Features Summary820622
+Node: Internationalization822466
+Node: I18N and L10N823946
+Node: Explaining gettext824633
+Ref: Explaining gettext-Footnote-1829656
+Ref: Explaining gettext-Footnote-2829841
+Node: Programmer i18n830006
+Ref: Programmer i18n-Footnote-1834862
+Node: Translator i18n834911
+Node: String Extraction835705
+Ref: String Extraction-Footnote-1836838
+Node: Printf Ordering836924
+Ref: Printf Ordering-Footnote-1839710
+Node: I18N Portability839774
+Ref: I18N Portability-Footnote-1842230
+Node: I18N Example842293
+Ref: I18N Example-Footnote-1845099
+Node: Gawk I18N845172
+Node: I18N Summary845817
+Node: Debugger847158
+Node: Debugging848180
+Node: Debugging Concepts848621
+Node: Debugging Terms850430
+Node: Awk Debugging853005
+Node: Sample Debugging Session853911
+Node: Debugger Invocation854445
+Node: Finding The Bug855831
+Node: List of Debugger Commands862309
+Node: Breakpoint Control863642
+Node: Debugger Execution Control867336
+Node: Viewing And Changing Data870698
+Node: Execution Stack874072
+Node: Debugger Info875709
+Node: Miscellaneous Debugger Commands879780
+Node: Readline Support884868
+Node: Limitations885764
+Ref: Limitations-Footnote-1889995
+Node: Debugging Summary890046
+Node: Arbitrary Precision Arithmetic891325
+Node: Computer Arithmetic892741
+Ref: table-numeric-ranges896332
+Ref: Computer Arithmetic-Footnote-1897054
+Node: Math Definitions897111
+Ref: table-ieee-formats900425
+Ref: Math Definitions-Footnote-1901028
+Node: MPFR features901133
+Node: FP Math Caution902806
+Ref: FP Math Caution-Footnote-1903878
+Node: Inexactness of computations904247
+Node: Inexact representation905207
+Node: Comparing FP Values906567
+Node: Errors accumulate907649
+Node: Getting Accuracy909082
+Node: Try To Round911792
+Node: Setting precision912691
+Ref: table-predefined-precision-strings913388
+Node: Setting the rounding mode915218
+Ref: table-gawk-rounding-modes915592
+Ref: Setting the rounding mode-Footnote-1919000
+Node: Arbitrary Precision Integers919179
+Ref: Arbitrary Precision Integers-Footnote-1924096
+Node: POSIX Floating Point Problems924245
+Ref: POSIX Floating Point Problems-Footnote-1928127
+Node: Floating point summary928165
+Node: Dynamic Extensions930355
+Node: Extension Intro931908
+Node: Plugin License933174
+Node: Extension Mechanism Outline933971
+Ref: figure-load-extension934410
+Ref: figure-register-new-function935975
+Ref: figure-call-new-function937067
+Node: Extension API Description939130
+Node: Extension API Functions Introduction940662
+Node: General Data Types945521
+Ref: General Data Types-Footnote-1951476
+Node: Memory Allocation Functions951775
+Ref: Memory Allocation Functions-Footnote-1954620
+Node: Constructor Functions954719
+Node: Registration Functions956464
+Node: Extension Functions957149
+Node: Exit Callback Functions959448
+Node: Extension Version String960698
+Node: Input Parsers961361
+Node: Output Wrappers971246
+Node: Two-way processors975758
+Node: Printing Messages978022
+Ref: Printing Messages-Footnote-1979096
+Node: Updating ERRNO979249
+Node: Requesting Values979988
+Ref: table-value-types-returned980725
+Node: Accessing Parameters981608
+Node: Symbol Table Access982844
+Node: Symbol table by name983356
+Node: Symbol table by cookie985377
+Ref: Symbol table by cookie-Footnote-1989526
+Node: Cached values989590
+Ref: Cached values-Footnote-1993091
+Node: Array Manipulation993182
+Ref: Array Manipulation-Footnote-1994273
+Node: Array Data Types994310
+Ref: Array Data Types-Footnote-1996968
+Node: Array Functions997060
+Node: Flattening Arrays1000919
+Node: Creating Arrays1007827
+Node: Redirection API1012599
+Node: Extension API Variables1015430
+Node: Extension Versioning1016063
+Node: Extension API Informational Variables1017954
+Node: Extension API Boilerplate1019018
+Node: Finding Extensions1022832
+Node: Extension Example1023392
+Node: Internal File Description1024190
+Node: Internal File Ops1028270
+Ref: Internal File Ops-Footnote-11040032
+Node: Using Internal File Ops1040172
+Ref: Using Internal File Ops-Footnote-11042555
+Node: Extension Samples1042830
+Node: Extension Sample File Functions1044359
+Node: Extension Sample Fnmatch1052008
+Node: Extension Sample Fork1053495
+Node: Extension Sample Inplace1054713
+Node: Extension Sample Ord1057923
+Node: Extension Sample Readdir1058759
+Ref: table-readdir-file-types1059648
+Node: Extension Sample Revout1060453
+Node: Extension Sample Rev2way1061042
+Node: Extension Sample Read write array1061782
+Node: Extension Sample Readfile1063724
+Node: Extension Sample Time1064819
+Node: Extension Sample API Tests1066167
+Node: gawkextlib1066659
+Node: Extension summary1069106
+Node: Extension Exercises1072798
+Node: Language History1074295
+Node: V7/SVR3.11075951
+Node: SVR41078103
+Node: POSIX1079537
+Node: BTL1080917
+Node: POSIX/GNU1081647
+Node: Feature History1087486
+Node: Common Extensions1101856
+Node: Ranges and Locales1103139
+Ref: Ranges and Locales-Footnote-11107755
+Ref: Ranges and Locales-Footnote-21107782
+Ref: Ranges and Locales-Footnote-31108017
+Node: Contributors1108238
+Node: History summary1113807
+Node: Installation1115187
+Node: Gawk Distribution1116132
+Node: Getting1116616
+Node: Extracting1117577
+Node: Distribution contents1119215
+Node: Unix Installation1125311
+Node: Quick Installation1125993
+Node: Shell Startup Files1128407
+Node: Additional Configuration Options1129485
+Node: Configuration Philosophy1131290
+Node: Non-Unix Installation1133660
+Node: PC Installation1134118
+Node: PC Binary Installation1135438
+Node: PC Compiling1137290
+Ref: PC Compiling-Footnote-11140314
+Node: PC Testing1140423
+Node: PC Using1141603
+Node: Cygwin1145717
+Node: MSYS1146487
+Node: VMS Installation1146988
+Node: VMS Compilation1147779
+Ref: VMS Compilation-Footnote-11149009
+Node: VMS Dynamic Extensions1149067
+Node: VMS Installation Details1150752
+Node: VMS Running1153005
+Node: VMS GNV1155846
+Node: VMS Old Gawk1156581
+Node: Bugs1157052
+Node: Other Versions1161249
+Node: Installation summary1167835
+Node: Notes1168893
+Node: Compatibility Mode1169758
+Node: Additions1170540
+Node: Accessing The Source1171465
+Node: Adding Code1172901
+Node: New Ports1179120
+Node: Derived Files1183608
+Ref: Derived Files-Footnote-11189093
+Ref: Derived Files-Footnote-21189128
+Ref: Derived Files-Footnote-31189726
+Node: Future Extensions1189840
+Node: Implementation Limitations1190498
+Node: Extension Design1191681
+Node: Old Extension Problems1192835
+Ref: Old Extension Problems-Footnote-11194353
+Node: Extension New Mechanism Goals1194410
+Ref: Extension New Mechanism Goals-Footnote-11197774
+Node: Extension Other Design Decisions1197963
+Node: Extension Future Growth1200076
+Node: Old Extension Mechanism1200912
+Node: Notes summary1202675
+Node: Basic Concepts1203857
+Node: Basic High Level1204538
+Ref: figure-general-flow1204820
+Ref: figure-process-flow1205505
+Ref: Basic High Level-Footnote-11208806
+Node: Basic Data Typing1208991
+Node: Glossary1212319
+Node: Copying1244265
+Node: GNU Free Documentation License1281804
+Node: Index1306922
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index d609c660..3a53597b 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -27569,6 +27569,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 7975d288..699079f3 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -26660,6 +26660,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