diff options
| -rw-r--r-- | doc/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/gawk.info | 1267 | ||||
| -rw-r--r-- | doc/gawk.texi | 34 | ||||
| -rw-r--r-- | doc/gawktexi.in | 34 |
4 files changed, 726 insertions, 614 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index f962ad87..d1d9f16f 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2021-10-20 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (FS versus FPAT): New subsection. + (String Functions): Reference it. + 2021-10-13 Arnold D. Robbins <arnold@skeeve.com> * awkcard.in, gawkinet.texi, gawkworkflow.texi: Update copyright year. diff --git a/doc/gawk.info b/doc/gawk.info index 6702dca4..6b183df6 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -205,6 +205,7 @@ in (a) below. A copy of the license is included in the section entitled * Fields with fixed data:: Field values with fixed-width data. * Splitting By Content:: Defining Fields By Content * More CSV:: More on CSV files. +* FS versus FPAT:: A subtle difference. * Testing field creation:: Checking how 'gawk' is splitting records. * Multiple Line:: Reading multiline records. @@ -5587,6 +5588,7 @@ File: gawk.info, Node: Splitting By Content, Next: Testing field creation, Pr * Menu: * More CSV:: More on CSV files. +* FS versus FPAT:: A subtle difference. This minor node discusses an advanced feature of 'gawk'. If you are a novice 'awk' user, you might want to skip it on the first reading. @@ -5685,7 +5687,7 @@ years. RFC 4180 (http://www.ietf.org/rfc/rfc4180.txt) standardizes the most common practices. -File: gawk.info, Node: More CSV, Up: Splitting By Content +File: gawk.info, Node: More CSV, Next: FS versus FPAT, Up: Splitting By Content 4.7.1 More on CSV Files ----------------------- @@ -5742,6 +5744,33 @@ that isn't covered. We recommend, instead, that you use Manuel Collado's 'CSVMODE' library for 'gawk' (http://mcollado.z15.es/xgawk/). +File: gawk.info, Node: FS versus FPAT, Prev: More CSV, Up: Splitting By Content + +4.7.2 'FS' Versus 'FPAT': A Subtle Difference +--------------------------------------------- + +As we discussed earlier, 'FS' describes the data between fields ("what +fields are not") and 'FPAT' describes the fields themselves ("what +fields are"). This leads to a subtle difference in how fields are found +when using regexps as the value for 'FS' or 'FPAT'. + + In order to distinguish one field from another, there must be a +non-empty separator between each field. This makes intuitive +sense--otherwise one could not distinguish fields from separators. + + Thus, regular expression matching as done when splitting fields with +'FS' is not allowed to match the null string; it must always match at +least one character, in order to be able to proceed through the entire +record. + + On the other hand, regular expression matching with 'FPAT' can match +the null string, and the non-matching intervening characters function as +the separators. + + This same difference is reflected in how matching is done with the +'split()' and 'patsplit()' functions (*note String Functions::). + + File: gawk.info, Node: Testing field creation, Next: Multiple Line, Prev: Splitting By Content, Up: Reading Files 4.8 Checking How 'gawk' Is Splitting Records @@ -13557,6 +13586,15 @@ Options::): Nonalphabetic characters are left unchanged. For example, 'toupper("MiXeD cAsE 123")' returns '"MIXED CASE 123"'. + At first glance, the 'split()' and 'patsplit()' functions appear to +be mirror images of each other. But there are differences: + + * 'split()' treats its third argument like 'FS', with all the special + rules involved for 'FS'. + + * Matching of null strings differs. This is discussed in *note FS + versus FPAT::. + Matching the Null String In 'awk', the '*' operator can match the null string. This is @@ -35064,7 +35102,7 @@ Index * * (asterisk), *= operator <1>: Precedence. (line 94) * * (asterisk), **= operator <1>: Precedence. (line 94) * * (asterisk), * operator, null strings, matching: String Functions. - (line 556) + (line 565) * + (plus sign), regexp operator: Regexp Operator Details. (line 107) * + (plus sign), += operator: Assignment Ops. (line 81) @@ -35353,7 +35391,7 @@ Index * adding, features to gawk: Adding Code. (line 6) * advanced features, fixed-width data: Constant Size. (line 6) * advanced features, specifying field content: Splitting By Content. - (line 13) + (line 14) * advanced features, gawk: Advanced Features. (line 6) * advanced features, nondecimal input data: Nondecimal Data. (line 6) * advanced features, processes, communicating with: Two-way I/O. @@ -35505,7 +35543,7 @@ Index * asterisk (*), *= operator <1>: Precedence. (line 94) * asterisk (*), **= operator <1>: Precedence. (line 94) * asterisk (*), * operator, null strings, matching: String Functions. - (line 556) + (line 565) * at-sign (@), @include directive: Include Files. (line 8) * at-sign (@), @load directive: Loading Shared Libraries. (line 8) @@ -35861,7 +35899,7 @@ Index * columns, cutting: Cut Program. (line 6) * comma (,), in range patterns: Ranges. (line 6) * Comma separated values (CSV) data, parsing with FPAT: Splitting By Content. - (line 19) + (line 20) * Comma separated values (CSV) data, parsing with FPAT library: More CSV. (line 52) * command completion, in debugger: Readline Support. (line 6) @@ -35980,7 +36018,7 @@ Index * csh utility, POSIXLY_CORRECT environment variable: Options. (line 406) * csh utility, |& operator, comparison with: Two-way I/O. (line 27) * CSV (comma separated values) data, parsing with FPAT: Splitting By Content. - (line 19) + (line 20) * CSV (comma separated values) data, parsing with CSVMODE library: More CSV. (line 52) * CSVMODE library for gawk: More CSV. (line 52) @@ -36690,7 +36728,7 @@ Index * forward slash (/), /= operator <1>: Precedence. (line 94) * forward slash (/), patterns and: Expression Patterns. (line 24) * FPAT variable: Splitting By Content. - (line 29) + (line 30) * FPAT variable <1>: User-modified. (line 46) * frame debugger command: Execution Stack. (line 27) * frawk: Other Versions. (line 117) @@ -36801,7 +36839,7 @@ Index * gawk, RT variable in <1>: gawk split records. (line 66) * gawk, FIELDWIDTHS variable in: Fixed width data. (line 17) * gawk, FPAT variable in: Splitting By Content. - (line 29) + (line 30) * gawk, splitting fields and: Testing field creation. (line 6) * gawk, RT variable in <2>: Multiple Line. (line 139) @@ -37273,7 +37311,7 @@ Index * matching, leftmost longest: Multiple Line. (line 26) * matching, expressions: Typing and Comparison. (line 9) -* matching, null strings: String Functions. (line 556) +* matching, null strings: String Functions. (line 565) * mawk utility: Escape Sequences. (line 121) * mawk utility <1>: Getline/Pipe. (line 62) * mawk utility <2>: Concatenation. (line 36) @@ -37402,7 +37440,7 @@ Index * null strings, as array subscripts: Uninitialized Subscripts. (line 43) * null strings, deleting array elements and: Delete. (line 27) -* null strings, matching: String Functions. (line 556) +* null strings, matching: String Functions. (line 565) * null strings <3>: Basic Data Typing. (line 26) * number of array elements: String Functions. (line 215) * number sign (#), #! (executable scripts): Executable Scripts. @@ -38073,7 +38111,7 @@ Index (line 147) * sidebar, Operator Evaluation Order: Increment Ops. (line 58) * sidebar, Changing NR and FNR: Auto-set. (line 407) -* sidebar, Matching the Null String: String Functions. (line 554) +* sidebar, Matching the Null String: String Functions. (line 563) * sidebar, Interactive Versus Noninteractive Buffering: I/O Functions. (line 74) * sidebar, Controlling Output Buffering with system(): I/O Functions. @@ -38522,609 +38560,610 @@ Index Tag Table: Node: Top1200 -Node: Foreword345252 -Node: Foreword449694 -Node: Preface51226 -Ref: Preface-Footnote-154085 -Ref: Preface-Footnote-254194 -Ref: Preface-Footnote-354428 -Node: History54570 -Node: Names56922 -Ref: Names-Footnote-158026 -Node: This Manual58173 -Ref: This Manual-Footnote-164812 -Node: Conventions64912 -Node: Manual History67281 -Ref: Manual History-Footnote-170278 -Ref: Manual History-Footnote-270319 -Node: How To Contribute70393 -Node: Acknowledgments71319 -Node: Getting Started76256 -Node: Running gawk78695 -Node: One-shot79885 -Node: Read Terminal81148 -Node: Long83141 -Node: Executable Scripts84654 -Ref: Executable Scripts-Footnote-187287 -Node: Comments87390 -Node: Quoting89874 -Node: DOS Quoting95400 -Node: Sample Data Files97456 -Node: Very Simple100051 -Node: Two Rules106153 -Node: More Complex108038 -Node: Statements/Lines110370 -Ref: Statements/Lines-Footnote-1114854 -Node: Other Features115119 -Node: When116055 -Ref: When-Footnote-1117809 -Node: Intro Summary117874 -Node: Invoking Gawk118758 -Node: Command Line120272 -Node: Options121070 -Ref: Options-Footnote-1138984 -Ref: Options-Footnote-2139215 -Node: Other Arguments139240 -Node: Naming Standard Input143251 -Node: Environment Variables144461 -Node: AWKPATH Variable145019 -Ref: AWKPATH Variable-Footnote-1148431 -Ref: AWKPATH Variable-Footnote-2148465 -Node: AWKLIBPATH Variable148836 -Ref: AWKLIBPATH Variable-Footnote-1150533 -Node: Other Environment Variables150908 -Node: Exit Status154729 -Node: Include Files155406 -Node: Loading Shared Libraries159096 -Node: Obsolete160524 -Node: Undocumented161216 -Node: Invoking Summary161513 -Node: Regexp164354 -Node: Regexp Usage165808 -Node: Escape Sequences167845 -Node: Regexp Operators174086 -Node: Regexp Operator Details174571 -Ref: Regexp Operator Details-Footnote-1181935 -Node: Interval Expressions182082 -Ref: Interval Expressions-Footnote-1184282 -Node: Bracket Expressions184380 -Ref: table-char-classes186856 -Node: Leftmost Longest190182 -Node: Computed Regexps191485 -Node: GNU Regexp Operators194912 -Node: Case-sensitivity198649 -Ref: Case-sensitivity-Footnote-1201515 -Ref: Case-sensitivity-Footnote-2201750 -Node: Regexp Summary201858 -Node: Reading Files203324 -Node: Records205593 -Node: awk split records206668 -Node: gawk split records211368 -Ref: gawk split records-Footnote-1216442 -Node: Fields216479 -Node: Nonconstant Fields219220 -Ref: Nonconstant Fields-Footnote-1221456 -Node: Changing Fields221660 -Node: Field Separators227691 -Node: Default Field Splitting230389 -Node: Regexp Field Splitting231507 -Node: Single Character Fields235184 -Node: Command Line Field Separator236244 -Node: Full Line Fields239462 -Ref: Full Line Fields-Footnote-1240984 -Ref: Full Line Fields-Footnote-2241030 -Node: Field Splitting Summary241131 -Node: Constant Size243205 -Node: Fixed width data243937 -Node: Skipping intervening247404 -Node: Allowing trailing data248202 -Node: Fields with fixed data249239 -Node: Splitting By Content250757 -Ref: Splitting By Content-Footnote-1254540 -Node: More CSV254703 -Node: Testing field creation256295 -Node: Multiple Line257920 -Node: Getline264197 -Node: Plain Getline266666 -Node: Getline/Variable269239 -Node: Getline/File270390 -Node: Getline/Variable/File271778 -Ref: Getline/Variable/File-Footnote-1273383 -Node: Getline/Pipe273471 -Node: Getline/Variable/Pipe276175 -Node: Getline/Coprocess277310 -Node: Getline/Variable/Coprocess278577 -Node: Getline Notes279319 -Node: Getline Summary282116 -Ref: table-getline-variants282540 -Node: Read Timeout283288 -Ref: Read Timeout-Footnote-1287194 -Node: Retrying Input287252 -Node: Command-line directories288451 -Node: Input Summary289357 -Node: Input Exercises292529 -Node: Printing292963 -Node: Print294797 -Node: Print Examples296254 -Node: Output Separators299034 -Node: OFMT301051 -Node: Printf302407 -Node: Basic Printf303192 -Node: Control Letters304766 -Node: Format Modifiers309930 -Node: Printf Examples315945 -Node: Redirection318431 -Node: Special FD325272 -Ref: Special FD-Footnote-1328440 -Node: Special Files328514 -Node: Other Inherited Files329131 -Node: Special Network330132 -Node: Special Caveats330992 -Node: Close Files And Pipes331941 -Ref: table-close-pipe-return-values338848 -Ref: Close Files And Pipes-Footnote-1339661 -Ref: Close Files And Pipes-Footnote-2339809 -Node: Nonfatal339961 -Node: Output Summary342299 -Node: Output Exercises343521 -Node: Expressions344200 -Node: Values345388 -Node: Constants346066 -Node: Scalar Constants346757 -Ref: Scalar Constants-Footnote-1349267 -Node: Nondecimal-numbers349517 -Node: Regexp Constants352518 -Node: Using Constant Regexps353044 -Node: Standard Regexp Constants353666 -Node: Strong Regexp Constants356854 -Node: Variables360567 -Node: Using Variables361224 -Node: Assignment Options363134 -Node: Conversion365605 -Node: Strings And Numbers366129 -Ref: Strings And Numbers-Footnote-1369192 -Node: Locale influences conversions369301 -Ref: table-locale-affects372059 -Node: All Operators372677 -Node: Arithmetic Ops373306 -Node: Concatenation376022 -Ref: Concatenation-Footnote-1378869 -Node: Assignment Ops378976 -Ref: table-assign-ops383967 -Node: Increment Ops385280 -Node: Truth Values and Conditions388740 -Node: Truth Values389814 -Node: Typing and Comparison390862 -Node: Variable Typing391682 -Ref: Variable Typing-Footnote-1398145 -Ref: Variable Typing-Footnote-2398217 -Node: Comparison Operators398294 -Ref: table-relational-ops398713 -Node: POSIX String Comparison402208 -Ref: POSIX String Comparison-Footnote-1403903 -Ref: POSIX String Comparison-Footnote-2404042 -Node: Boolean Ops404126 -Ref: Boolean Ops-Footnote-1408608 -Node: Conditional Exp408700 -Node: Function Calls410436 -Node: Precedence414313 -Node: Locales417972 -Node: Expressions Summary419604 -Node: Patterns and Actions422177 -Node: Pattern Overview423297 -Node: Regexp Patterns424974 -Node: Expression Patterns425516 -Node: Ranges429297 -Node: BEGIN/END432405 -Node: Using BEGIN/END433166 -Ref: Using BEGIN/END-Footnote-1435920 -Node: I/O And BEGIN/END436026 -Node: BEGINFILE/ENDFILE438339 -Node: Empty441570 -Node: Using Shell Variables441887 -Node: Action Overview444161 -Node: Statements446486 -Node: If Statement448334 -Node: While Statement449829 -Node: Do Statement451857 -Node: For Statement453005 -Node: Switch Statement456260 -Node: Break Statement458701 -Node: Continue Statement460793 -Node: Next Statement462620 -Node: Nextfile Statement465003 -Node: Exit Statement467692 -Node: Built-in Variables470095 -Node: User-modified471228 -Node: Auto-set478995 -Ref: Auto-set-Footnote-1495802 -Ref: Auto-set-Footnote-2496008 -Node: ARGC and ARGV496064 -Node: Pattern Action Summary500277 -Node: Arrays502707 -Node: Array Basics504036 -Node: Array Intro504880 -Ref: figure-array-elements506855 -Ref: Array Intro-Footnote-1509559 -Node: Reference to Elements509687 -Node: Assigning Elements512151 -Node: Array Example512642 -Node: Scanning an Array514401 -Node: Controlling Scanning517423 -Ref: Controlling Scanning-Footnote-1523879 -Node: Numeric Array Subscripts524195 -Node: Uninitialized Subscripts526379 -Node: Delete527998 -Ref: Delete-Footnote-1530750 -Node: Multidimensional530807 -Node: Multiscanning533902 -Node: Arrays of Arrays535493 -Node: Arrays Summary540261 -Node: Functions542354 -Node: Built-in543392 -Node: Calling Built-in544473 -Node: Numeric Functions546469 -Ref: Numeric Functions-Footnote-1550497 -Ref: Numeric Functions-Footnote-2551145 -Ref: Numeric Functions-Footnote-3551193 -Node: String Functions551465 -Ref: String Functions-Footnote-1575980 -Ref: String Functions-Footnote-2576108 -Ref: String Functions-Footnote-3576356 -Node: Gory Details576443 -Ref: table-sub-escapes578234 -Ref: table-sub-proposed579753 -Ref: table-posix-sub581116 -Ref: table-gensub-escapes582657 -Ref: Gory Details-Footnote-1583480 -Node: I/O Functions583634 -Ref: table-system-return-values590088 -Ref: I/O Functions-Footnote-1592168 -Ref: I/O Functions-Footnote-2592316 -Node: Time Functions592436 -Ref: Time Functions-Footnote-1603107 -Ref: Time Functions-Footnote-2603175 -Ref: Time Functions-Footnote-3603333 -Ref: Time Functions-Footnote-4603444 -Ref: Time Functions-Footnote-5603556 -Ref: Time Functions-Footnote-6603783 -Node: Bitwise Functions604049 -Ref: table-bitwise-ops604643 -Ref: Bitwise Functions-Footnote-1610706 -Ref: Bitwise Functions-Footnote-2610879 -Node: Type Functions611070 -Node: I18N Functions614399 -Node: User-defined616050 -Node: Definition Syntax616862 -Ref: Definition Syntax-Footnote-1622556 -Node: Function Example622627 -Ref: Function Example-Footnote-1625549 -Node: Function Calling625571 -Node: Calling A Function626159 -Node: Variable Scope627117 -Node: Pass By Value/Reference630111 -Node: Function Caveats632755 -Ref: Function Caveats-Footnote-1634802 -Node: Return Statement634922 -Node: Dynamic Typing637901 -Node: Indirect Calls638831 -Ref: Indirect Calls-Footnote-1649083 -Node: Functions Summary649211 -Node: Library Functions651916 -Ref: Library Functions-Footnote-1655523 -Ref: Library Functions-Footnote-2655666 -Node: Library Names655837 -Ref: Library Names-Footnote-1659504 -Ref: Library Names-Footnote-2659727 -Node: General Functions659813 -Node: Strtonum Function660995 -Node: Assert Function664017 -Node: Round Function667343 -Node: Cliff Random Function668883 -Node: Ordinal Functions669899 -Ref: Ordinal Functions-Footnote-1672962 -Ref: Ordinal Functions-Footnote-2673214 -Node: Join Function673424 -Ref: Join Function-Footnote-1675194 -Node: Getlocaltime Function675394 -Node: Readfile Function679136 -Node: Shell Quoting681113 -Node: Isnumeric Function682541 -Node: Data File Management683929 -Node: Filetrans Function684561 -Node: Rewind Function688657 -Node: File Checking690566 -Ref: File Checking-Footnote-1691900 -Node: Empty Files692101 -Node: Ignoring Assigns694080 -Node: Getopt Function695630 -Ref: Getopt Function-Footnote-1710853 -Node: Passwd Functions711053 -Ref: Passwd Functions-Footnote-1719892 -Node: Group Functions719980 -Ref: Group Functions-Footnote-1727878 -Node: Walking Arrays728085 -Node: Library Functions Summary731093 -Node: Library Exercises732499 -Node: Sample Programs732964 -Node: Running Examples733734 -Node: Clones734462 -Node: Cut Program735686 -Node: Egrep Program745826 -Node: Id Program754827 -Node: Split Program764762 -Ref: Split Program-Footnote-1774655 -Node: Tee Program774828 -Node: Uniq Program777618 -Node: Wc Program785206 -Node: Bytes vs. Characters785593 -Node: Using extensions787141 -Node: wc program787895 -Node: Miscellaneous Programs792760 -Node: Dupword Program793973 -Node: Alarm Program796003 -Node: Translate Program800858 -Ref: Translate Program-Footnote-1805423 -Node: Labels Program805693 -Ref: Labels Program-Footnote-1809044 -Node: Word Sorting809128 -Node: History Sorting813200 -Node: Extract Program815425 -Node: Simple Sed823479 -Node: Igawk Program826553 -Ref: Igawk Program-Footnote-1840884 -Ref: Igawk Program-Footnote-2841086 -Ref: Igawk Program-Footnote-3841208 -Node: Anagram Program841323 -Node: Signature Program844385 -Node: Programs Summary845632 -Node: Programs Exercises846846 -Ref: Programs Exercises-Footnote-1850976 -Node: Advanced Features851062 -Node: Nondecimal Data853129 -Node: Array Sorting854720 -Node: Controlling Array Traversal855420 -Ref: Controlling Array Traversal-Footnote-1863788 -Node: Array Sorting Functions863906 -Ref: Array Sorting Functions-Footnote-1869280 -Node: Two-way I/O869476 -Ref: Two-way I/O-Footnote-1877202 -Ref: Two-way I/O-Footnote-2877389 -Node: TCP/IP Networking877471 -Node: Profiling880589 -Node: Extension Philosophy889898 -Node: Advanced Features Summary891377 -Node: Internationalization893392 -Node: I18N and L10N895066 -Node: Explaining gettext895753 -Ref: Explaining gettext-Footnote-1901645 -Ref: Explaining gettext-Footnote-2901830 -Node: Programmer i18n901995 -Ref: Programmer i18n-Footnote-1906944 -Node: Translator i18n906993 -Node: String Extraction907787 -Ref: String Extraction-Footnote-1908919 -Node: Printf Ordering909005 -Ref: Printf Ordering-Footnote-1911791 -Node: I18N Portability911855 -Ref: I18N Portability-Footnote-1914311 -Node: I18N Example914374 -Ref: I18N Example-Footnote-1917649 -Ref: I18N Example-Footnote-2917722 -Node: Gawk I18N917831 -Node: I18N Summary918480 -Node: Debugger919821 -Node: Debugging920821 -Node: Debugging Concepts921262 -Node: Debugging Terms923071 -Node: Awk Debugging925646 -Ref: Awk Debugging-Footnote-1926591 -Node: Sample Debugging Session926723 -Node: Debugger Invocation927257 -Node: Finding The Bug928643 -Node: List of Debugger Commands935117 -Node: Breakpoint Control936450 -Node: Debugger Execution Control940144 -Node: Viewing And Changing Data943506 -Node: Execution Stack947047 -Node: Debugger Info948684 -Node: Miscellaneous Debugger Commands952755 -Node: Readline Support957817 -Node: Limitations958713 -Node: Debugging Summary961267 -Node: Namespaces962546 -Node: Global Namespace963657 -Node: Qualified Names965055 -Node: Default Namespace966054 -Node: Changing The Namespace966795 -Node: Naming Rules968409 -Node: Internal Name Management970257 -Node: Namespace Example971299 -Node: Namespace And Features973861 -Node: Namespace Summary975296 -Node: Arbitrary Precision Arithmetic976773 -Node: Computer Arithmetic978260 -Ref: table-numeric-ranges982026 -Ref: table-floating-point-ranges982519 -Ref: Computer Arithmetic-Footnote-1983177 -Node: Math Definitions983234 -Ref: table-ieee-formats986550 -Ref: Math Definitions-Footnote-1987153 -Node: MPFR features987258 -Node: FP Math Caution988976 -Ref: FP Math Caution-Footnote-1990048 -Node: Inexactness of computations990417 -Node: Inexact representation991377 -Node: Comparing FP Values992737 -Node: Errors accumulate993978 -Node: Getting Accuracy995411 -Node: Try To Round998121 -Node: Setting precision999020 -Ref: table-predefined-precision-strings999717 -Node: Setting the rounding mode1001547 -Ref: table-gawk-rounding-modes1001921 -Ref: Setting the rounding mode-Footnote-11005852 -Node: Arbitrary Precision Integers1006031 -Ref: Arbitrary Precision Integers-Footnote-11009206 -Node: Checking for MPFR1009355 -Node: POSIX Floating Point Problems1010829 -Ref: POSIX Floating Point Problems-Footnote-11015114 -Node: Floating point summary1015152 -Node: Dynamic Extensions1017342 -Node: Extension Intro1018895 -Node: Plugin License1020161 -Node: Extension Mechanism Outline1020958 -Ref: figure-load-extension1021397 -Ref: figure-register-new-function1022962 -Ref: figure-call-new-function1024054 -Node: Extension API Description1026116 -Node: Extension API Functions Introduction1027829 -Ref: table-api-std-headers1029665 -Node: General Data Types1033914 -Ref: General Data Types-Footnote-11042544 -Node: Memory Allocation Functions1042843 -Ref: Memory Allocation Functions-Footnote-11047344 -Node: Constructor Functions1047443 -Node: API Ownership of MPFR and GMP Values1050909 -Node: Registration Functions1052222 -Node: Extension Functions1052922 -Node: Exit Callback Functions1058244 -Node: Extension Version String1059494 -Node: Input Parsers1060157 -Node: Output Wrappers1072878 -Node: Two-way processors1077390 -Node: Printing Messages1079655 -Ref: Printing Messages-Footnote-11080826 -Node: Updating ERRNO1080979 -Node: Requesting Values1081718 -Ref: table-value-types-returned1082455 -Node: Accessing Parameters1083391 -Node: Symbol Table Access1084628 -Node: Symbol table by name1085140 -Ref: Symbol table by name-Footnote-11088165 -Node: Symbol table by cookie1088293 -Ref: Symbol table by cookie-Footnote-11092478 -Node: Cached values1092542 -Ref: Cached values-Footnote-11096078 -Node: Array Manipulation1096231 -Ref: Array Manipulation-Footnote-11097322 -Node: Array Data Types1097359 -Ref: Array Data Types-Footnote-11100017 -Node: Array Functions1100109 -Node: Flattening Arrays1104607 -Node: Creating Arrays1111583 -Node: Redirection API1116350 -Node: Extension API Variables1119183 -Node: Extension Versioning1119894 -Ref: gawk-api-version1120323 -Node: Extension GMP/MPFR Versioning1122054 -Node: Extension API Informational Variables1123682 -Node: Extension API Boilerplate1124755 -Node: Changes from API V11128729 -Node: Finding Extensions1130301 -Node: Extension Example1130860 -Node: Internal File Description1131658 -Node: Internal File Ops1135738 -Ref: Internal File Ops-Footnote-11147088 -Node: Using Internal File Ops1147228 -Ref: Using Internal File Ops-Footnote-11149611 -Node: Extension Samples1149885 -Node: Extension Sample File Functions1151414 -Node: Extension Sample Fnmatch1159063 -Node: Extension Sample Fork1160550 -Node: Extension Sample Inplace1161768 -Node: Extension Sample Ord1165394 -Node: Extension Sample Readdir1166230 -Ref: table-readdir-file-types1167119 -Node: Extension Sample Revout1168186 -Node: Extension Sample Rev2way1168775 -Node: Extension Sample Read write array1169515 -Node: Extension Sample Readfile1171457 -Node: Extension Sample Time1172552 -Node: Extension Sample API Tests1174304 -Node: gawkextlib1174796 -Node: Extension summary1177714 -Node: Extension Exercises1181416 -Node: Language History1182658 -Node: V7/SVR3.11184314 -Node: SVR41186466 -Node: POSIX1187900 -Node: BTL1189281 -Node: POSIX/GNU1190010 -Node: Feature History1195788 -Node: Common Extensions1212963 -Node: Ranges and Locales1214246 -Ref: Ranges and Locales-Footnote-11218862 -Ref: Ranges and Locales-Footnote-21218889 -Ref: Ranges and Locales-Footnote-31219124 -Node: Contributors1219347 -Node: History summary1225344 -Node: Installation1226724 -Node: Gawk Distribution1227668 -Node: Getting1228152 -Node: Extracting1229115 -Node: Distribution contents1230753 -Node: Unix Installation1237896 -Node: Quick Installation1238700 -Node: Compiling with MPFR1241176 -Node: Shell Startup Files1241866 -Node: Additional Configuration Options1242955 -Node: Configuration Philosophy1245270 -Node: Compiling from Git1247666 -Node: Building the Documentation1248221 -Node: Non-Unix Installation1249605 -Node: PC Installation1250065 -Node: PC Binary Installation1250903 -Node: PC Compiling1251338 -Node: PC Using1252455 -Node: Cygwin1256008 -Node: MSYS1257232 -Node: VMS Installation1257834 -Node: VMS Compilation1258553 -Ref: VMS Compilation-Footnote-11259782 -Node: VMS Dynamic Extensions1259840 -Node: VMS Installation Details1261525 -Node: VMS Running1263787 -Node: VMS GNV1268066 -Node: Bugs1268780 -Node: Bug definition1269692 -Node: Bug address1272628 -Node: Usenet1276016 -Node: Performance bugs1277205 -Node: Asking for help1280126 -Node: Maintainers1282093 -Node: Other Versions1283287 -Node: Installation summary1291139 -Node: Notes1292503 -Node: Compatibility Mode1293297 -Node: Additions1294079 -Node: Accessing The Source1295004 -Node: Adding Code1296441 -Node: New Ports1302660 -Node: Derived Files1307035 -Ref: Derived Files-Footnote-11312695 -Ref: Derived Files-Footnote-21312730 -Ref: Derived Files-Footnote-31313328 -Node: Future Extensions1313442 -Node: Implementation Limitations1314100 -Node: Extension Design1315310 -Node: Old Extension Problems1316454 -Ref: Old Extension Problems-Footnote-11317972 -Node: Extension New Mechanism Goals1318029 -Ref: Extension New Mechanism Goals-Footnote-11321393 -Node: Extension Other Design Decisions1321582 -Node: Extension Future Growth1323695 -Node: Notes summary1324301 -Node: Basic Concepts1325459 -Node: Basic High Level1326140 -Ref: figure-general-flow1326422 -Ref: figure-process-flow1327107 -Ref: Basic High Level-Footnote-11330408 -Node: Basic Data Typing1330593 -Node: Glossary1333921 -Node: Copying1365806 -Node: GNU Free Documentation License1403349 -Node: Index1428469 +Node: Foreword345313 +Node: Foreword449755 +Node: Preface51287 +Ref: Preface-Footnote-154146 +Ref: Preface-Footnote-254255 +Ref: Preface-Footnote-354489 +Node: History54631 +Node: Names56983 +Ref: Names-Footnote-158087 +Node: This Manual58234 +Ref: This Manual-Footnote-164873 +Node: Conventions64973 +Node: Manual History67342 +Ref: Manual History-Footnote-170339 +Ref: Manual History-Footnote-270380 +Node: How To Contribute70454 +Node: Acknowledgments71380 +Node: Getting Started76317 +Node: Running gawk78756 +Node: One-shot79946 +Node: Read Terminal81209 +Node: Long83202 +Node: Executable Scripts84715 +Ref: Executable Scripts-Footnote-187348 +Node: Comments87451 +Node: Quoting89935 +Node: DOS Quoting95461 +Node: Sample Data Files97517 +Node: Very Simple100112 +Node: Two Rules106214 +Node: More Complex108099 +Node: Statements/Lines110431 +Ref: Statements/Lines-Footnote-1114915 +Node: Other Features115180 +Node: When116116 +Ref: When-Footnote-1117870 +Node: Intro Summary117935 +Node: Invoking Gawk118819 +Node: Command Line120333 +Node: Options121131 +Ref: Options-Footnote-1139045 +Ref: Options-Footnote-2139276 +Node: Other Arguments139301 +Node: Naming Standard Input143312 +Node: Environment Variables144522 +Node: AWKPATH Variable145080 +Ref: AWKPATH Variable-Footnote-1148492 +Ref: AWKPATH Variable-Footnote-2148526 +Node: AWKLIBPATH Variable148897 +Ref: AWKLIBPATH Variable-Footnote-1150594 +Node: Other Environment Variables150969 +Node: Exit Status154790 +Node: Include Files155467 +Node: Loading Shared Libraries159157 +Node: Obsolete160585 +Node: Undocumented161277 +Node: Invoking Summary161574 +Node: Regexp164415 +Node: Regexp Usage165869 +Node: Escape Sequences167906 +Node: Regexp Operators174147 +Node: Regexp Operator Details174632 +Ref: Regexp Operator Details-Footnote-1181996 +Node: Interval Expressions182143 +Ref: Interval Expressions-Footnote-1184343 +Node: Bracket Expressions184441 +Ref: table-char-classes186917 +Node: Leftmost Longest190243 +Node: Computed Regexps191546 +Node: GNU Regexp Operators194973 +Node: Case-sensitivity198710 +Ref: Case-sensitivity-Footnote-1201576 +Ref: Case-sensitivity-Footnote-2201811 +Node: Regexp Summary201919 +Node: Reading Files203385 +Node: Records205654 +Node: awk split records206729 +Node: gawk split records211429 +Ref: gawk split records-Footnote-1216503 +Node: Fields216540 +Node: Nonconstant Fields219281 +Ref: Nonconstant Fields-Footnote-1221517 +Node: Changing Fields221721 +Node: Field Separators227752 +Node: Default Field Splitting230450 +Node: Regexp Field Splitting231568 +Node: Single Character Fields235245 +Node: Command Line Field Separator236305 +Node: Full Line Fields239523 +Ref: Full Line Fields-Footnote-1241045 +Ref: Full Line Fields-Footnote-2241091 +Node: Field Splitting Summary241192 +Node: Constant Size243266 +Node: Fixed width data243998 +Node: Skipping intervening247465 +Node: Allowing trailing data248263 +Node: Fields with fixed data249300 +Node: Splitting By Content250818 +Ref: Splitting By Content-Footnote-1254654 +Node: More CSV254817 +Node: FS versus FPAT256432 +Node: Testing field creation257592 +Node: Multiple Line259217 +Node: Getline265494 +Node: Plain Getline267963 +Node: Getline/Variable270536 +Node: Getline/File271687 +Node: Getline/Variable/File273075 +Ref: Getline/Variable/File-Footnote-1274680 +Node: Getline/Pipe274768 +Node: Getline/Variable/Pipe277472 +Node: Getline/Coprocess278607 +Node: Getline/Variable/Coprocess279874 +Node: Getline Notes280616 +Node: Getline Summary283413 +Ref: table-getline-variants283837 +Node: Read Timeout284585 +Ref: Read Timeout-Footnote-1288491 +Node: Retrying Input288549 +Node: Command-line directories289748 +Node: Input Summary290654 +Node: Input Exercises293826 +Node: Printing294260 +Node: Print296094 +Node: Print Examples297551 +Node: Output Separators300331 +Node: OFMT302348 +Node: Printf303704 +Node: Basic Printf304489 +Node: Control Letters306063 +Node: Format Modifiers311227 +Node: Printf Examples317242 +Node: Redirection319728 +Node: Special FD326569 +Ref: Special FD-Footnote-1329737 +Node: Special Files329811 +Node: Other Inherited Files330428 +Node: Special Network331429 +Node: Special Caveats332289 +Node: Close Files And Pipes333238 +Ref: table-close-pipe-return-values340145 +Ref: Close Files And Pipes-Footnote-1340958 +Ref: Close Files And Pipes-Footnote-2341106 +Node: Nonfatal341258 +Node: Output Summary343596 +Node: Output Exercises344818 +Node: Expressions345497 +Node: Values346685 +Node: Constants347363 +Node: Scalar Constants348054 +Ref: Scalar Constants-Footnote-1350564 +Node: Nondecimal-numbers350814 +Node: Regexp Constants353815 +Node: Using Constant Regexps354341 +Node: Standard Regexp Constants354963 +Node: Strong Regexp Constants358151 +Node: Variables361864 +Node: Using Variables362521 +Node: Assignment Options364431 +Node: Conversion366902 +Node: Strings And Numbers367426 +Ref: Strings And Numbers-Footnote-1370489 +Node: Locale influences conversions370598 +Ref: table-locale-affects373356 +Node: All Operators373974 +Node: Arithmetic Ops374603 +Node: Concatenation377319 +Ref: Concatenation-Footnote-1380166 +Node: Assignment Ops380273 +Ref: table-assign-ops385264 +Node: Increment Ops386577 +Node: Truth Values and Conditions390037 +Node: Truth Values391111 +Node: Typing and Comparison392159 +Node: Variable Typing392979 +Ref: Variable Typing-Footnote-1399442 +Ref: Variable Typing-Footnote-2399514 +Node: Comparison Operators399591 +Ref: table-relational-ops400010 +Node: POSIX String Comparison403505 +Ref: POSIX String Comparison-Footnote-1405200 +Ref: POSIX String Comparison-Footnote-2405339 +Node: Boolean Ops405423 +Ref: Boolean Ops-Footnote-1409905 +Node: Conditional Exp409997 +Node: Function Calls411733 +Node: Precedence415610 +Node: Locales419269 +Node: Expressions Summary420901 +Node: Patterns and Actions423474 +Node: Pattern Overview424594 +Node: Regexp Patterns426271 +Node: Expression Patterns426813 +Node: Ranges430594 +Node: BEGIN/END433702 +Node: Using BEGIN/END434463 +Ref: Using BEGIN/END-Footnote-1437217 +Node: I/O And BEGIN/END437323 +Node: BEGINFILE/ENDFILE439636 +Node: Empty442867 +Node: Using Shell Variables443184 +Node: Action Overview445458 +Node: Statements447783 +Node: If Statement449631 +Node: While Statement451126 +Node: Do Statement453154 +Node: For Statement454302 +Node: Switch Statement457557 +Node: Break Statement459998 +Node: Continue Statement462090 +Node: Next Statement463917 +Node: Nextfile Statement466300 +Node: Exit Statement468989 +Node: Built-in Variables471392 +Node: User-modified472525 +Node: Auto-set480292 +Ref: Auto-set-Footnote-1497099 +Ref: Auto-set-Footnote-2497305 +Node: ARGC and ARGV497361 +Node: Pattern Action Summary501574 +Node: Arrays504004 +Node: Array Basics505333 +Node: Array Intro506177 +Ref: figure-array-elements508152 +Ref: Array Intro-Footnote-1510856 +Node: Reference to Elements510984 +Node: Assigning Elements513448 +Node: Array Example513939 +Node: Scanning an Array515698 +Node: Controlling Scanning518720 +Ref: Controlling Scanning-Footnote-1525176 +Node: Numeric Array Subscripts525492 +Node: Uninitialized Subscripts527676 +Node: Delete529295 +Ref: Delete-Footnote-1532047 +Node: Multidimensional532104 +Node: Multiscanning535199 +Node: Arrays of Arrays536790 +Node: Arrays Summary541558 +Node: Functions543651 +Node: Built-in544689 +Node: Calling Built-in545770 +Node: Numeric Functions547766 +Ref: Numeric Functions-Footnote-1551794 +Ref: Numeric Functions-Footnote-2552442 +Ref: Numeric Functions-Footnote-3552490 +Node: String Functions552762 +Ref: String Functions-Footnote-1577604 +Ref: String Functions-Footnote-2577732 +Ref: String Functions-Footnote-3577980 +Node: Gory Details578067 +Ref: table-sub-escapes579858 +Ref: table-sub-proposed581377 +Ref: table-posix-sub582740 +Ref: table-gensub-escapes584281 +Ref: Gory Details-Footnote-1585104 +Node: I/O Functions585258 +Ref: table-system-return-values591712 +Ref: I/O Functions-Footnote-1593792 +Ref: I/O Functions-Footnote-2593940 +Node: Time Functions594060 +Ref: Time Functions-Footnote-1604731 +Ref: Time Functions-Footnote-2604799 +Ref: Time Functions-Footnote-3604957 +Ref: Time Functions-Footnote-4605068 +Ref: Time Functions-Footnote-5605180 +Ref: Time Functions-Footnote-6605407 +Node: Bitwise Functions605673 +Ref: table-bitwise-ops606267 +Ref: Bitwise Functions-Footnote-1612330 +Ref: Bitwise Functions-Footnote-2612503 +Node: Type Functions612694 +Node: I18N Functions616023 +Node: User-defined617674 +Node: Definition Syntax618486 +Ref: Definition Syntax-Footnote-1624180 +Node: Function Example624251 +Ref: Function Example-Footnote-1627173 +Node: Function Calling627195 +Node: Calling A Function627783 +Node: Variable Scope628741 +Node: Pass By Value/Reference631735 +Node: Function Caveats634379 +Ref: Function Caveats-Footnote-1636426 +Node: Return Statement636546 +Node: Dynamic Typing639525 +Node: Indirect Calls640455 +Ref: Indirect Calls-Footnote-1650707 +Node: Functions Summary650835 +Node: Library Functions653540 +Ref: Library Functions-Footnote-1657147 +Ref: Library Functions-Footnote-2657290 +Node: Library Names657461 +Ref: Library Names-Footnote-1661128 +Ref: Library Names-Footnote-2661351 +Node: General Functions661437 +Node: Strtonum Function662619 +Node: Assert Function665641 +Node: Round Function668967 +Node: Cliff Random Function670507 +Node: Ordinal Functions671523 +Ref: Ordinal Functions-Footnote-1674586 +Ref: Ordinal Functions-Footnote-2674838 +Node: Join Function675048 +Ref: Join Function-Footnote-1676818 +Node: Getlocaltime Function677018 +Node: Readfile Function680760 +Node: Shell Quoting682737 +Node: Isnumeric Function684165 +Node: Data File Management685553 +Node: Filetrans Function686185 +Node: Rewind Function690281 +Node: File Checking692190 +Ref: File Checking-Footnote-1693524 +Node: Empty Files693725 +Node: Ignoring Assigns695704 +Node: Getopt Function697254 +Ref: Getopt Function-Footnote-1712477 +Node: Passwd Functions712677 +Ref: Passwd Functions-Footnote-1721516 +Node: Group Functions721604 +Ref: Group Functions-Footnote-1729502 +Node: Walking Arrays729709 +Node: Library Functions Summary732717 +Node: Library Exercises734123 +Node: Sample Programs734588 +Node: Running Examples735358 +Node: Clones736086 +Node: Cut Program737310 +Node: Egrep Program747450 +Node: Id Program756451 +Node: Split Program766386 +Ref: Split Program-Footnote-1776279 +Node: Tee Program776452 +Node: Uniq Program779242 +Node: Wc Program786830 +Node: Bytes vs. Characters787217 +Node: Using extensions788765 +Node: wc program789519 +Node: Miscellaneous Programs794384 +Node: Dupword Program795597 +Node: Alarm Program797627 +Node: Translate Program802482 +Ref: Translate Program-Footnote-1807047 +Node: Labels Program807317 +Ref: Labels Program-Footnote-1810668 +Node: Word Sorting810752 +Node: History Sorting814824 +Node: Extract Program817049 +Node: Simple Sed825103 +Node: Igawk Program828177 +Ref: Igawk Program-Footnote-1842508 +Ref: Igawk Program-Footnote-2842710 +Ref: Igawk Program-Footnote-3842832 +Node: Anagram Program842947 +Node: Signature Program846009 +Node: Programs Summary847256 +Node: Programs Exercises848470 +Ref: Programs Exercises-Footnote-1852600 +Node: Advanced Features852686 +Node: Nondecimal Data854753 +Node: Array Sorting856344 +Node: Controlling Array Traversal857044 +Ref: Controlling Array Traversal-Footnote-1865412 +Node: Array Sorting Functions865530 +Ref: Array Sorting Functions-Footnote-1870904 +Node: Two-way I/O871100 +Ref: Two-way I/O-Footnote-1878826 +Ref: Two-way I/O-Footnote-2879013 +Node: TCP/IP Networking879095 +Node: Profiling882213 +Node: Extension Philosophy891522 +Node: Advanced Features Summary893001 +Node: Internationalization895016 +Node: I18N and L10N896690 +Node: Explaining gettext897377 +Ref: Explaining gettext-Footnote-1903269 +Ref: Explaining gettext-Footnote-2903454 +Node: Programmer i18n903619 +Ref: Programmer i18n-Footnote-1908568 +Node: Translator i18n908617 +Node: String Extraction909411 +Ref: String Extraction-Footnote-1910543 +Node: Printf Ordering910629 +Ref: Printf Ordering-Footnote-1913415 +Node: I18N Portability913479 +Ref: I18N Portability-Footnote-1915935 +Node: I18N Example915998 +Ref: I18N Example-Footnote-1919273 +Ref: I18N Example-Footnote-2919346 +Node: Gawk I18N919455 +Node: I18N Summary920104 +Node: Debugger921445 +Node: Debugging922445 +Node: Debugging Concepts922886 +Node: Debugging Terms924695 +Node: Awk Debugging927270 +Ref: Awk Debugging-Footnote-1928215 +Node: Sample Debugging Session928347 +Node: Debugger Invocation928881 +Node: Finding The Bug930267 +Node: List of Debugger Commands936741 +Node: Breakpoint Control938074 +Node: Debugger Execution Control941768 +Node: Viewing And Changing Data945130 +Node: Execution Stack948671 +Node: Debugger Info950308 +Node: Miscellaneous Debugger Commands954379 +Node: Readline Support959441 +Node: Limitations960337 +Node: Debugging Summary962891 +Node: Namespaces964170 +Node: Global Namespace965281 +Node: Qualified Names966679 +Node: Default Namespace967678 +Node: Changing The Namespace968419 +Node: Naming Rules970033 +Node: Internal Name Management971881 +Node: Namespace Example972923 +Node: Namespace And Features975485 +Node: Namespace Summary976920 +Node: Arbitrary Precision Arithmetic978397 +Node: Computer Arithmetic979884 +Ref: table-numeric-ranges983650 +Ref: table-floating-point-ranges984143 +Ref: Computer Arithmetic-Footnote-1984801 +Node: Math Definitions984858 +Ref: table-ieee-formats988174 +Ref: Math Definitions-Footnote-1988777 +Node: MPFR features988882 +Node: FP Math Caution990600 +Ref: FP Math Caution-Footnote-1991672 +Node: Inexactness of computations992041 +Node: Inexact representation993001 +Node: Comparing FP Values994361 +Node: Errors accumulate995602 +Node: Getting Accuracy997035 +Node: Try To Round999745 +Node: Setting precision1000644 +Ref: table-predefined-precision-strings1001341 +Node: Setting the rounding mode1003171 +Ref: table-gawk-rounding-modes1003545 +Ref: Setting the rounding mode-Footnote-11007476 +Node: Arbitrary Precision Integers1007655 +Ref: Arbitrary Precision Integers-Footnote-11010830 +Node: Checking for MPFR1010979 +Node: POSIX Floating Point Problems1012453 +Ref: POSIX Floating Point Problems-Footnote-11016738 +Node: Floating point summary1016776 +Node: Dynamic Extensions1018966 +Node: Extension Intro1020519 +Node: Plugin License1021785 +Node: Extension Mechanism Outline1022582 +Ref: figure-load-extension1023021 +Ref: figure-register-new-function1024586 +Ref: figure-call-new-function1025678 +Node: Extension API Description1027740 +Node: Extension API Functions Introduction1029453 +Ref: table-api-std-headers1031289 +Node: General Data Types1035538 +Ref: General Data Types-Footnote-11044168 +Node: Memory Allocation Functions1044467 +Ref: Memory Allocation Functions-Footnote-11048968 +Node: Constructor Functions1049067 +Node: API Ownership of MPFR and GMP Values1052533 +Node: Registration Functions1053846 +Node: Extension Functions1054546 +Node: Exit Callback Functions1059868 +Node: Extension Version String1061118 +Node: Input Parsers1061781 +Node: Output Wrappers1074502 +Node: Two-way processors1079014 +Node: Printing Messages1081279 +Ref: Printing Messages-Footnote-11082450 +Node: Updating ERRNO1082603 +Node: Requesting Values1083342 +Ref: table-value-types-returned1084079 +Node: Accessing Parameters1085015 +Node: Symbol Table Access1086252 +Node: Symbol table by name1086764 +Ref: Symbol table by name-Footnote-11089789 +Node: Symbol table by cookie1089917 +Ref: Symbol table by cookie-Footnote-11094102 +Node: Cached values1094166 +Ref: Cached values-Footnote-11097702 +Node: Array Manipulation1097855 +Ref: Array Manipulation-Footnote-11098946 +Node: Array Data Types1098983 +Ref: Array Data Types-Footnote-11101641 +Node: Array Functions1101733 +Node: Flattening Arrays1106231 +Node: Creating Arrays1113207 +Node: Redirection API1117974 +Node: Extension API Variables1120807 +Node: Extension Versioning1121518 +Ref: gawk-api-version1121947 +Node: Extension GMP/MPFR Versioning1123678 +Node: Extension API Informational Variables1125306 +Node: Extension API Boilerplate1126379 +Node: Changes from API V11130353 +Node: Finding Extensions1131925 +Node: Extension Example1132484 +Node: Internal File Description1133282 +Node: Internal File Ops1137362 +Ref: Internal File Ops-Footnote-11148712 +Node: Using Internal File Ops1148852 +Ref: Using Internal File Ops-Footnote-11151235 +Node: Extension Samples1151509 +Node: Extension Sample File Functions1153038 +Node: Extension Sample Fnmatch1160687 +Node: Extension Sample Fork1162174 +Node: Extension Sample Inplace1163392 +Node: Extension Sample Ord1167018 +Node: Extension Sample Readdir1167854 +Ref: table-readdir-file-types1168743 +Node: Extension Sample Revout1169810 +Node: Extension Sample Rev2way1170399 +Node: Extension Sample Read write array1171139 +Node: Extension Sample Readfile1173081 +Node: Extension Sample Time1174176 +Node: Extension Sample API Tests1175928 +Node: gawkextlib1176420 +Node: Extension summary1179338 +Node: Extension Exercises1183040 +Node: Language History1184282 +Node: V7/SVR3.11185938 +Node: SVR41188090 +Node: POSIX1189524 +Node: BTL1190905 +Node: POSIX/GNU1191634 +Node: Feature History1197412 +Node: Common Extensions1214587 +Node: Ranges and Locales1215870 +Ref: Ranges and Locales-Footnote-11220486 +Ref: Ranges and Locales-Footnote-21220513 +Ref: Ranges and Locales-Footnote-31220748 +Node: Contributors1220971 +Node: History summary1226968 +Node: Installation1228348 +Node: Gawk Distribution1229292 +Node: Getting1229776 +Node: Extracting1230739 +Node: Distribution contents1232377 +Node: Unix Installation1239520 +Node: Quick Installation1240324 +Node: Compiling with MPFR1242800 +Node: Shell Startup Files1243490 +Node: Additional Configuration Options1244579 +Node: Configuration Philosophy1246894 +Node: Compiling from Git1249290 +Node: Building the Documentation1249845 +Node: Non-Unix Installation1251229 +Node: PC Installation1251689 +Node: PC Binary Installation1252527 +Node: PC Compiling1252962 +Node: PC Using1254079 +Node: Cygwin1257632 +Node: MSYS1258856 +Node: VMS Installation1259458 +Node: VMS Compilation1260177 +Ref: VMS Compilation-Footnote-11261406 +Node: VMS Dynamic Extensions1261464 +Node: VMS Installation Details1263149 +Node: VMS Running1265411 +Node: VMS GNV1269690 +Node: Bugs1270404 +Node: Bug definition1271316 +Node: Bug address1274252 +Node: Usenet1277640 +Node: Performance bugs1278829 +Node: Asking for help1281750 +Node: Maintainers1283717 +Node: Other Versions1284911 +Node: Installation summary1292763 +Node: Notes1294127 +Node: Compatibility Mode1294921 +Node: Additions1295703 +Node: Accessing The Source1296628 +Node: Adding Code1298065 +Node: New Ports1304284 +Node: Derived Files1308659 +Ref: Derived Files-Footnote-11314319 +Ref: Derived Files-Footnote-21314354 +Ref: Derived Files-Footnote-31314952 +Node: Future Extensions1315066 +Node: Implementation Limitations1315724 +Node: Extension Design1316934 +Node: Old Extension Problems1318078 +Ref: Old Extension Problems-Footnote-11319596 +Node: Extension New Mechanism Goals1319653 +Ref: Extension New Mechanism Goals-Footnote-11323017 +Node: Extension Other Design Decisions1323206 +Node: Extension Future Growth1325319 +Node: Notes summary1325925 +Node: Basic Concepts1327083 +Node: Basic High Level1327764 +Ref: figure-general-flow1328046 +Ref: figure-process-flow1328731 +Ref: Basic High Level-Footnote-11332032 +Node: Basic Data Typing1332217 +Node: Glossary1335545 +Node: Copying1367430 +Node: GNU Free Documentation License1404973 +Node: Index1430093 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 24d2668d..2b0c74c4 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -579,6 +579,7 @@ particular records in a file and perform operations upon them. * Fields with fixed data:: Field values with fixed-width data. * Splitting By Content:: Defining Fields By Content * More CSV:: More on CSV files. +* FS versus FPAT:: A subtle difference. * Testing field creation:: Checking how @command{gawk} is splitting records. * Multiple Line:: Reading multiline records. @@ -8444,6 +8445,7 @@ four, and @code{$4} has the value @code{"ddd"}. @menu * More CSV:: More on CSV files. +* FS versus FPAT:: A subtle difference. @end menu @c O'Reilly doesn't like it as a note the first thing in the section. @@ -8653,6 +8655,28 @@ a bed with a blanket that's not quite big enough. There's always a corner that isn't covered. We recommend, instead, that you use Manuel Collado's @uref{http://mcollado.z15.es/xgawk/, @code{CSVMODE} library for @command{gawk}}. +@node FS versus FPAT +@subsection @code{FS} Versus @code{FPAT}: A Subtle Difference + +As we discussed earlier, @code{FS} describes the data between fields (``what fields are not'') +and @code{FPAT} describes the fields themselves (``what fields are''). +This leads to a subtle difference in how fields are found when using regexps as the value +for @code{FS} or @code{FPAT}. + +In order to distinguish one field from another, there must be a non-empty separator between +each field. This makes intuitive sense---otherwise one could not distinguish fields from +separators. + +Thus, regular expression matching as done when splitting fields with @code{FS} is not +allowed to match the null string; it must always match at least one character, in order +to be able to proceed through the entire record. + +On the other hand, regular expression matching with @code{FPAT} can match the null +string, and the non-matching intervening characters function as the separators. + +This same difference is reflected in how matching is done with the @code{split()} +and @code{patsplit()} functions (@pxref{String Functions}). + @node Testing field creation @section Checking How @command{gawk} Is Splitting Records @@ -19364,6 +19388,16 @@ Nonalphabetic characters are left unchanged. For example, @code{toupper("MiXeD cAsE 123")} returns @code{"MIXED CASE 123"}. @end table +At first glance, the @code{split()} and @code{patsplit()} functions appear to be +mirror images of each other. But there are differences: + +@itemize @bullet +@item @code{split()} treats its third argument like @code{FS}, with all the +special rules involved for @code{FS}. + +@item Matching of null strings differs. This is discussed in @ref{FS versus FPAT}. +@end itemize + @cindex sidebar @subentry Matching the Null String @ifdocbook @docbook diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 7b3c7ce8..e3b1bd2d 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -574,6 +574,7 @@ particular records in a file and perform operations upon them. * Fields with fixed data:: Field values with fixed-width data. * Splitting By Content:: Defining Fields By Content * More CSV:: More on CSV files. +* FS versus FPAT:: A subtle difference. * Testing field creation:: Checking how @command{gawk} is splitting records. * Multiple Line:: Reading multiline records. @@ -7913,6 +7914,7 @@ four, and @code{$4} has the value @code{"ddd"}. @menu * More CSV:: More on CSV files. +* FS versus FPAT:: A subtle difference. @end menu @c O'Reilly doesn't like it as a note the first thing in the section. @@ -8122,6 +8124,28 @@ a bed with a blanket that's not quite big enough. There's always a corner that isn't covered. We recommend, instead, that you use Manuel Collado's @uref{http://mcollado.z15.es/xgawk/, @code{CSVMODE} library for @command{gawk}}. +@node FS versus FPAT +@subsection @code{FS} Versus @code{FPAT}: A Subtle Difference + +As we discussed earlier, @code{FS} describes the data between fields (``what fields are not'') +and @code{FPAT} describes the fields themselves (``what fields are''). +This leads to a subtle difference in how fields are found when using regexps as the value +for @code{FS} or @code{FPAT}. + +In order to distinguish one field from another, there must be a non-empty separator between +each field. This makes intuitive sense---otherwise one could not distinguish fields from +separators. + +Thus, regular expression matching as done when splitting fields with @code{FS} is not +allowed to match the null string; it must always match at least one character, in order +to be able to proceed through the entire record. + +On the other hand, regular expression matching with @code{FPAT} can match the null +string, and the non-matching intervening characters function as the separators. + +This same difference is reflected in how matching is done with the @code{split()} +and @code{patsplit()} functions (@pxref{String Functions}). + @node Testing field creation @section Checking How @command{gawk} Is Splitting Records @@ -18505,6 +18529,16 @@ Nonalphabetic characters are left unchanged. For example, @code{toupper("MiXeD cAsE 123")} returns @code{"MIXED CASE 123"}. @end table +At first glance, the @code{split()} and @code{patsplit()} functions appear to be +mirror images of each other. But there are differences: + +@itemize @bullet +@item @code{split()} treats its third argument like @code{FS}, with all the +special rules involved for @code{FS}. + +@item Matching of null strings differs. This is discussed in @ref{FS versus FPAT}. +@end itemize + @sidebar Matching the Null String @cindex matching @subentry null strings @cindex null strings @subentry matching |