diff options
| -rw-r--r-- | doc/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/gawk.info | 473 | ||||
| -rw-r--r-- | doc/gawk.texi | 52 | ||||
| -rw-r--r-- | doc/gawktexi.in | 52 |
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 |