diff options
| -rw-r--r-- | doc/ChangeLog | 7 | ||||
| -rw-r--r-- | doc/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/Makefile.in | 2 | ||||
| -rw-r--r-- | doc/array-elements.eps | 158 | ||||
| -rw-r--r-- | doc/array-elements.fig | 27 | ||||
| -rw-r--r-- | doc/array-elements.pdf | bin | 0 -> 6822 bytes | |||
| -rw-r--r-- | doc/array-elements.png | bin | 0 -> 6143 bytes | |||
| -rw-r--r-- | doc/array-elements.txt | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 1168 | ||||
| -rw-r--r-- | doc/gawk.texi | 492 | ||||
| -rw-r--r-- | doc/gawktexi.in | 492 |
11 files changed, 1391 insertions, 961 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 3bd47bb7..5928b330 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,10 @@ +2014-05-02 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Editing progress. Through Chapter 8. + * array-elements.eps, array-elements.fig, array-elements.pdf, + array-elements.png array-elements.txt: New files. + * Makefile.am (EXTRA_DIST): Add them. + 2014-04-30 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Editing progress. Through Chapter 5. diff --git a/doc/Makefile.am b/doc/Makefile.am index 12692bd0..86321bbc 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -36,6 +36,8 @@ EXTRA_DIST = ChangeLog ChangeLog.0 README.card ad.block setter.outline \ api-figure2.png api-figure2.txt \ api-figure3.eps api-figure3.fig api-figure3.pdf \ api-figure3.png api-figure3.txt \ + array-elements.eps array-elements.fig array-elements.pdf \ + array-elements.png array-elements.txt \ gawktexi.in sidebar.awk \ general-program.eps general-program.fig general-program.pdf \ general-program.png general-program.txt \ diff --git a/doc/Makefile.in b/doc/Makefile.in index 52e5f873..abaf5601 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -350,6 +350,8 @@ EXTRA_DIST = ChangeLog ChangeLog.0 README.card ad.block setter.outline \ api-figure2.png api-figure2.txt \ api-figure3.eps api-figure3.fig api-figure3.pdf \ api-figure3.png api-figure3.txt \ + array-elements.eps array-elements.fig array-elements.pdf \ + array-elements.png array-elements.txt \ gawktexi.in sidebar.awk \ general-program.eps general-program.fig general-program.pdf \ general-program.png general-program.txt \ diff --git a/doc/array-elements.eps b/doc/array-elements.eps new file mode 100644 index 00000000..a0649959 --- /dev/null +++ b/doc/array-elements.eps @@ -0,0 +1,158 @@ +%!PS-Adobe-3.0 EPSF-3.0 +%%Title: array-figure1.fig +%%Creator: fig2dev Version 3.2 Patchlevel 5d +%%CreationDate: Thu May 1 22:19:24 2014 +%%BoundingBox: 0 0 384 76 +%Magnification: 1.0000 +%%EndComments +%%BeginProlog +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +/pageheader { +save +newpath 0 76 moveto 0 0 lineto 384 0 lineto 384 76 lineto closepath clip newpath +-203.3 199.4 translate +1 -1 scale +$F2psBegin +10 setmiterlimit +0 slj 0 slc + 0.06299 0.06299 sc +} bind def +/pagefooter { +$F2psEnd +restore +} bind def +%%EndProlog +pageheader +% +% Fig objects follow +% +% +% here starts figure with depth 50 +% Polyline +0 slj +0 slc +7.500 slw +n 4455 1980 m 4455 2700 l 4455 2655 l + 4455 2700 l gs col0 s gr +% Polyline +n 6075 1980 m + 6075 2700 l gs col0 s gr +% Polyline +n 7425 1980 m + 7425 2700 l gs col0 s gr +/Courier-Bold ff 180.00 scf sf +3735 2340 m +gs 1 -1 sc (8) col0 sh gr +/Courier-Bold ff 180.00 scf sf +5175 2295 m +gs 1 -1 sc ("foo") col0 sh gr +/Courier-Bold ff 180.00 scf sf +6930 2295 m +gs 1 -1 sc ("") col0 sh gr +/Courier-Bold ff 180.00 scf sf +7875 2250 m +gs 1 -1 sc (30) col0 sh gr +/Times-Roman ff 180.00 scf sf +3735 3105 m +gs 1 -1 sc (0) col0 sh gr +/Times-Roman ff 180.00 scf sf +5175 3150 m +gs 1 -1 sc (1) col0 sh gr +/Times-Roman ff 180.00 scf sf +6795 3150 m +gs 1 -1 sc (2) col0 sh gr +/Times-Roman ff 180.00 scf sf +7875 3105 m +gs 1 -1 sc (3) col0 sh gr +/Times-Roman ff 180.00 scf sf +8730 2340 m +gs 1 -1 sc (Value) col0 sh gr +/Times-Roman ff 180.00 scf sf +8820 3060 m +gs 1 -1 sc (Index) col0 sh gr +% here ends figure; +% +% here starts figure with depth 40 +% Polyline +0 slj +0 slc +7.500 slw +n 3240 1980 m 8415 1980 l 8415 2700 l 3240 2700 l + cp gs col0 s gr +% here ends figure; +pagefooter +showpage +%%Trailer +%EOF diff --git a/doc/array-elements.fig b/doc/array-elements.fig new file mode 100644 index 00000000..c5d65ba4 --- /dev/null +++ b/doc/array-elements.fig @@ -0,0 +1,27 @@ +#FIG 3.2 Produced by xfig version 3.2.5b +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +2 2 0 1 0 7 40 -1 -1 0.000 0 0 -1 0 0 5 + 3240 1980 8415 1980 8415 2700 3240 2700 3240 1980 +2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4 + 4455 1980 4455 2700 4455 2655 4455 2700 +2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 6075 1980 6075 2700 +2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 7425 1980 7425 2700 +4 0 0 50 -1 14 12 0.0000 4 120 120 3735 2340 8\001 +4 0 0 50 -1 14 12 0.0000 4 120 600 5175 2295 "foo"\001 +4 0 0 50 -1 14 12 0.0000 4 60 240 6930 2295 ""\001 +4 0 0 50 -1 14 12 0.0000 4 120 240 7875 2250 30\001 +4 0 0 50 -1 0 12 0.0000 4 135 105 3735 3105 0\001 +4 0 0 50 -1 0 12 0.0000 4 135 105 5175 3150 1\001 +4 0 0 50 -1 0 12 0.0000 4 135 105 6795 3150 2\001 +4 0 0 50 -1 0 12 0.0000 4 135 105 7875 3105 3\001 +4 0 0 50 -1 0 12 0.0000 4 135 480 8730 2340 Value\001 +4 0 0 50 -1 0 12 0.0000 4 135 465 8820 3060 Index\001 diff --git a/doc/array-elements.pdf b/doc/array-elements.pdf Binary files differnew file mode 100644 index 00000000..af0ef3b9 --- /dev/null +++ b/doc/array-elements.pdf diff --git a/doc/array-elements.png b/doc/array-elements.png Binary files differnew file mode 100644 index 00000000..c51424d1 --- /dev/null +++ b/doc/array-elements.png diff --git a/doc/array-elements.txt b/doc/array-elements.txt new file mode 100644 index 00000000..8906318a --- /dev/null +++ b/doc/array-elements.txt @@ -0,0 +1,4 @@ ++---------+---------+--------+---------+ +| 8 | "foo" | "" | 30 | @r{Value} ++---------+---------+--------+---------+ + 0 1 2 3 @r{Index} diff --git a/doc/gawk.info b/doc/gawk.info index dc0a7591..4c4f57b2 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -9555,9 +9555,9 @@ of these automatically, so that they enable you to tell `awk' how to do certain things. Others are set automatically by `awk', so that they carry information from the internal workings of `awk' to your program. - This minor node documents all the built-in variables of `gawk', most -of which are also documented in the chapters describing their areas of -activity. + This minor node documents all of `gawk''s built-in variables, most +of which are also documented in the major nodes describing their areas +of activity. * Menu: @@ -9574,8 +9574,13 @@ File: gawk.info, Node: User-modified, Next: Auto-set, Up: Built-in Variables ------------------------------------------- The following is an alphabetical list of variables that you can change -to control how `awk' does certain things. The variables that are -specific to `gawk' are marked with a pound sign (`#'). +to control how `awk' does certain things. + + The variables that are specific to `gawk' are marked with a pound +sign (`#'). These variables are `gawk' extensions. In other `awk' +implementations or if `gawk' is in compatibility mode (*note +Options::), they are not special. (Any exceptions are noted in the +description of each variable.) `BINMODE #' On non-POSIX systems, this variable specifies use of binary mode @@ -9588,14 +9593,11 @@ specific to `gawk' are marked with a pound sign (`#'). string value of `"rw"' or `"wr"' indicates that all files should use binary I/O. Any other string value is treated the same as `"rw"', but causes `gawk' to generate a warning message. - `BINMODE' is described in more detail in *note PC Using::. - - This variable is a `gawk' extension. In other `awk' - implementations (except `mawk', *note Other Versions::), or if - `gawk' is in compatibility mode (*note Options::), it is not - special. + `BINMODE' is described in more detail in *note PC Using::. `mawk' + *note Other Versions::), also supports this variable, but only + using numeric values. -`CONVFMT' +``CONVFMT'' This string controls conversion of numbers to strings (*note Conversion::). It works by being passed, in effect, as the first argument to the `sprintf()' function (*note String Functions::). @@ -9603,29 +9605,21 @@ specific to `gawk' are marked with a pound sign (`#'). POSIX standard. `FIELDWIDTHS #' - This is a space-separated list of columns that tells `gawk' how to - split input with fixed columnar boundaries. Assigning a value to + A space-separated list of columns that tells `gawk' how to split + input with fixed columnar boundaries. Assigning a value to `FIELDWIDTHS' overrides the use of `FS' and `FPAT' for field splitting. *Note Constant Size::, for more information. - If `gawk' is in compatibility mode (*note Options::), then - `FIELDWIDTHS' has no special meaning, and field-splitting - operations occur based exclusively on the value of `FS'. - `FPAT #' - This is a regular expression (as a string) that tells `gawk' to - create the fields based on text that matches the regular - expression. Assigning a value to `FPAT' overrides the use of `FS' - and `FIELDWIDTHS' for field splitting. *Note Splitting By - Content::, for more information. - - If `gawk' is in compatibility mode (*note Options::), then `FPAT' - has no special meaning, and field-splitting operations occur based - exclusively on the value of `FS'. + A regular expression (as a string) that tells `gawk' to create the + fields based on text that matches the regular expression. + Assigning a value to `FPAT' overrides the use of `FS' and + `FIELDWIDTHS' for field splitting. *Note Splitting By Content::, + for more information. `FS' - This is the input field separator (*note Field Separators::). The - value is a single-character string or a multicharacter regular + The input field separator (*note Field Separators::). The value + is a single-character string or a multicharacter regular expression that matches the separations between fields in an input record. If the value is the null string (`""'), then each character in the record becomes a separate field. (This behavior @@ -9661,13 +9655,9 @@ specific to `gawk' are marked with a pound sign (`#'). splitting when using a single-character field separator. *Note Case-sensitivity::. - If `gawk' is in compatibility mode (*note Options::), then - `IGNORECASE' has no special meaning. Thus, string and regexp - operations are always case-sensitive. - `LINT #' When this variable is true (nonzero or non-null), `gawk' behaves - as if the `--lint' command-line option is in effect. (*note + as if the `--lint' command-line option is in effect (*note Options::). With a value of `"fatal"', lint warnings become fatal errors. With a value of `"invalid"', only warnings about things that are actually invalid are issued. (This is not fully @@ -9683,13 +9673,13 @@ specific to `gawk' are marked with a pound sign (`#'). execution is independent of the flavor of `awk' being executed. `OFMT' - This string controls conversion of numbers to strings (*note - Conversion::) for printing with the `print' statement. It works - by being passed as the first argument to the `sprintf()' function - (*note String Functions::). Its default value is `"%.6g"'. - Earlier versions of `awk' also used `OFMT' to specify the format - for converting numbers to strings in general expressions; this is - now done by `CONVFMT'. + Controls conversion of numbers to strings (*note Conversion::) for + printing with the `print' statement. It works by being passed as + the first argument to the `sprintf()' function (*note String + Functions::). Its default value is `"%.6g"'. Earlier versions of + `awk' also used `OFMT' to specify the format for converting + numbers to strings in general expressions; this is now done by + `CONVFMT'. `OFS' This is the output field separator (*note Output Separators::). @@ -9697,8 +9687,8 @@ specific to `gawk' are marked with a pound sign (`#'). Its default value is `" "', a string consisting of a single space. `ORS' - This is the output record separator. It is output at the end of - every `print' statement. Its default value is `"\n"', the newline + The output record separator. It is output at the end of every + `print' statement. Its default value is `"\n"', the newline character. (*Note Output Separators::.) `PREC #' @@ -9708,38 +9698,34 @@ specific to `gawk' are marked with a pound sign (`#'). `ROUNDMODE #' The rounding mode to use for arbitrary precision arithmetic on numbers, by default `"N"' (`roundTiesToEven' in the IEEE-754 - standard) (*note Setting Rounding Mode::). + standard; *note Setting Rounding Mode::). -`RS' - This is `awk''s input record separator. Its default value is a - string containing a single newline character, which means that an - input record consists of a single line of text. It can also be - the null string, in which case records are separated by runs of - blank lines. If it is a regexp, records are separated by matches - of the regexp in the input text. (*Note Records::.) +``RS'' + The input record separator. Its default value is a string + containing a single newline character, which means that an input + record consists of a single line of text. It can also be the null + string, in which case records are separated by runs of blank lines. + If it is a regexp, records are separated by matches of the regexp + in the input text. (*Note Records::.) The ability for `RS' to be a regular expression is a `gawk' extension. In most other `awk' implementations, or if `gawk' is in compatibility mode (*note Options::), just the first character of `RS''s value is used. -`SUBSEP' - This is the subscript separator. It has the default value of - `"\034"' and is used to separate the parts of the indices of a - multidimensional array. Thus, the expression `foo["A", "B"]' - really accesses `foo["A\034B"]' (*note Multidimensional::). +``SUBSEP'' + The subscript separator. It has the default value of `"\034"' and + is used to separate the parts of the indices of a multidimensional + array. Thus, the expression `foo["A", "B"]' really accesses + `foo["A\034B"]' (*note Multidimensional::). `TEXTDOMAIN #' - This variable is used for internationalization of programs at the - `awk' level. It sets the default text domain for specially marked - string constants in the source text, as well as for the - `dcgettext()', `dcngettext()' and `bindtextdomain()' functions - (*note Internationalization::). The default value of `TEXTDOMAIN' - is `"messages"'. - - This variable is a `gawk' extension. In other `awk' - implementations, or if `gawk' is in compatibility mode (*note - Options::), it is not special. + Used for internationalization of programs at the `awk' level. It + sets the default text domain for specially marked string constants + in the source text, as well as for the `dcgettext()', + `dcngettext()' and `bindtextdomain()' functions (*note + Internationalization::). The default value of `TEXTDOMAIN' is + `"messages"'. ---------- Footnotes ---------- @@ -9753,8 +9739,12 @@ File: gawk.info, Node: Auto-set, Next: ARGC and ARGV, Prev: User-modified, U The following is an alphabetical list of variables that `awk' sets automatically on certain occasions in order to provide information to -your program. The variables that are specific to `gawk' are marked -with a pound sign (`#'). +your program. + + The variables that are specific to `gawk' are marked with a pound +sign (`#'). These variables are `gawk' extensions. In other `awk' +implementations or if `gawk' is in compatibility mode (*note +Options::), they are not special. `ARGC', `ARGV' The command-line arguments available to `awk' programs are stored @@ -9785,7 +9775,7 @@ with a pound sign (`#'). are any of `awk''s command-line options. *Note ARGC and ARGV::, for information about how `awk' uses these variables. (d.c.) -`ARGIND' # +`ARGIND #' The index in `ARGV' of the current file being processed. Every time `gawk' opens a new data file for processing, it sets `ARGIND' to the index in `ARGV' of the file name. When `gawk' is @@ -9801,10 +9791,6 @@ with a pound sign (`#'). program, `gawk' automatically sets it to a new value when the next file is opened. - This variable is a `gawk' extension. In other `awk' - implementations, or if `gawk' is in compatibility mode (*note - Options::), it is not special. - `ENVIRON' An associative array containing the values of the environment. The array indices are the environment variable names; the elements @@ -9824,12 +9810,12 @@ with a pound sign (`#'). Some operating systems may not have environment variables. On such systems, the `ENVIRON' array is empty (except for - `ENVIRON["AWKPATH"]', *note AWKPATH Variable:: and - `ENVIRON["AWKLIBPATH"]', *note AWKLIBPATH Variable::). + `ENVIRON["AWKPATH"]' and `ENVIRON["AWKLIBPATH"]'; *note AWKPATH + Variable::, and *note AWKLIBPATH Variable::). -`ERRNO' # - If a system error occurs during a redirection for `getline', - during a read for `getline', or during a `close()' operation, then +`ERRNO #' + If a system error occurs during a redirection for `getline', during + a read for `getline', or during a `close()' operation, then `ERRNO' contains a string describing the error. In addition, `gawk' clears `ERRNO' before opening each @@ -9843,19 +9829,14 @@ with a pound sign (`#'). `getline' returning -1. You are, of course, free to clear it yourself before doing an I/O operation. - This variable is a `gawk' extension. In other `awk' - implementations, or if `gawk' is in compatibility mode (*note - Options::), it is not special. - `FILENAME' - The name of the file that `awk' is currently reading. When no - data files are listed on the command line, `awk' reads from the - standard input and `FILENAME' is set to `"-"'. `FILENAME' is - changed each time a new file is read (*note Reading Files::). - Inside a `BEGIN' rule, the value of `FILENAME' is `""', since - there are no input files being processed yet.(1) (d.c.) Note, - though, that using `getline' (*note Getline::) inside a `BEGIN' - rule can give `FILENAME' a value. + The name of the current input file. When no data files are listed + on the command line, `awk' reads from the standard input and + `FILENAME' is set to `"-"'. `FILENAME' changes each time a new + file is read (*note Reading Files::). Inside a `BEGIN' rule, the + value of `FILENAME' is `""', since there are no input files being + processed yet.(1) (d.c.) Note, though, that using `getline' (*note + Getline::) inside a `BEGIN' rule can give `FILENAME' a value. `FNR' The current record number in the current file. `FNR' is @@ -9873,21 +9854,20 @@ with a pound sign (`#'). create or remove fields from the current record. *Note Changing Fields::. -`FUNCTAB' # +`FUNCTAB #' An array whose indices and corresponding values are the names of all the user-defined or extension functions in the program. NOTE: Attempting to use the `delete' statement with the - `FUNCTAB' array will cause a fatal error. Any attempt to - assign to an element of the `FUNCTAB' array will also cause a - fatal error. + `FUNCTAB' array causes a fatal error. Any attempt to assign + to an element of `FUNCTAB' also causes a fatal error. `NR' The number of input records `awk' has processed since the beginning of the program's execution (*note Records::). `NR' is incremented each time a new record is read. -`PROCINFO' # +`PROCINFO #' The elements of this array provide access to information about the running `awk' program. The following elements (listed alphabetically) are guaranteed to be available: @@ -9944,8 +9924,8 @@ with a pound sign (`#'). `PROCINFO["sorted_in"]' If this element exists in `PROCINFO', its value controls the - order in which array indices will be processed by `for (index - in array) ...' loops. Since this is an advanced feature, we + order in which array indices will be processed by `for (INDEX + in ARRAY)' loops. Since this is an advanced feature, we defer the full description until later; see *note Scanning an Array::. @@ -10003,10 +9983,6 @@ with a pound sign (`#'). open input file, pipe, or coprocess. *Note Read Timeout::, for more information. - This array is a `gawk' extension. In other `awk' implementations, - or if `gawk' is in compatibility mode (*note Options::), it is not - special. - `RLENGTH' The length of the substring matched by the `match()' function (*note String Functions::). `RLENGTH' is set by invoking the @@ -10020,15 +9996,11 @@ with a pound sign (`#'). of the string where the matched substring starts, or zero if no match was found. -`RT' # - This is set each time a record is read. It contains the input text - that matched the text denoted by `RS', the record separator. - - This variable is a `gawk' extension. In other `awk' - implementations, or if `gawk' is in compatibility mode (*note - Options::), it is not special. +`RT #' + The input text that matched the text denoted by `RS', the record + separator. It is set every time a record is read. -`SYMTAB' # +`SYMTAB #' An array whose indices are the names of all currently defined global variables and arrays in the program. The array may be used for indirect access to read or write the value of a variable: @@ -10062,7 +10034,7 @@ with a pound sign (`#'). return SYMTAB[variable] *= amount } - NOTE: In order to avoid severe time-travel paradoxes(2), + NOTE: In order to avoid severe time-travel paradoxes,(2) neither `FUNCTAB' nor `SYMTAB' are available as elements within the `SYMTAB' array. @@ -10212,7 +10184,7 @@ remove array elements. It also describes how `awk' simulates multidimensional arrays, as well as some of the less obvious points about array usage. The major node moves on to discuss `gawk''s facility for sorting arrays, and ends with a brief description of `gawk''s -ability to support true multidimensional arrays. +ability to support true arrays of arrays. `awk' maintains a single set of names that may be used for naming variables, arrays, and functions (*note User-defined::). Thus, you @@ -10290,12 +10262,13 @@ declared.) A contiguous array of four elements might look like the following example, conceptually, if the element values are 8, `"foo"', `""', and -30: +30 as shown in *note figure-array-elements::: - +---------+---------+--------+---------+ - | 8 | "foo" | "" | 30 | Value - +---------+---------+--------+---------+ - 0 1 2 3 Index ++---------+---------+--------+---------+ +| 8 | "foo" | "" | 30 | @r{Value} ++---------+---------+--------+---------+ + 0 1 2 3 @r{Index} +Figure 8.1: A Contiguous Array Only the values are stored; the indices are implicit from the order of the values. Here, 8 is the value at index zero, because 8 appears in the @@ -10338,9 +10311,9 @@ from English to French: Here we decided to translate the number one in both spelled-out and numeric form--thus illustrating that a single array can have both -numbers and strings as indices. In fact, array subscripts are always +numbers and strings as indices. (In fact, array subscripts are always strings; this is discussed in more detail in *note Numeric Array -Subscripts::. Here, the number `1' isn't double-quoted, since `awk' +Subscripts::.) Here, the number `1' isn't double-quoted, since `awk' automatically converts it to a string. The value of `IGNORECASE' has no effect upon array subscripting. @@ -10392,11 +10365,11 @@ been assigned any value as well as elements that have been deleted To determine whether an element exists in an array at a certain index, use the following expression: - IND in ARRAY + INDX in ARRAY -This expression tests whether the particular index IND exists, without +This expression tests whether the particular index INDX exists, without the side effect of creating that element if it is not present. The -expression has the value one (true) if `ARRAY[IND]' exists and zero +expression has the value one (true) if `ARRAY[INDX]' exists and zero (false) if it does not exist. For example, this statement tests whether the array `frequencies' contains the index `2': @@ -10531,19 +10504,54 @@ built-in function `length()'. The order in which elements of the array are accessed by this statement is determined by the internal arrangement of the array -elements within `awk' and normally cannot be controlled or changed. -This can lead to problems if new elements are added to ARRAY by -statements in the loop body; it is not predictable whether the `for' +elements within `awk' and in standard `awk' cannot be controlled or +changed. This can lead to problems if new elements are added to ARRAY +by statements in the loop body; it is not predictable whether the `for' loop will reach them. Similarly, changing VAR inside the loop may produce strange results. It is best to avoid such things. + As a point of information, `gawk' sets up the list of elements to be +iterated over before the loop starts, and does not change it. But not +all `awk' versions do so. Consider this program, named `loopcheck.awk': + + BEGIN { + a["here"] = "here" + a["is"] = "is" + a["a"] = "a" + a["loop"] = "loop" + for (i in a) { + j++ + a[j] = j + print i + } + } + + Here is what happens when run with `gawk': + + $ gawk -f loopcheck.awk + -| here + -| loop + -| a + -| is + + Contrast this to Brian Kernighan's `awk': + + $ nawk -f loopcheck.awk + -| loop + -| here + -| is + -| a + -| 1 + File: gawk.info, Node: Controlling Scanning, Prev: Scanning an Array, Up: Array Basics -8.1.6 Using Predefined Array Scanning Orders --------------------------------------------- +8.1.6 Using Predefined Array Scanning Orders With `gawk' +-------------------------------------------------------- + +This node describes a feature that is specific to `gawk'. -By default, when a `for' loop traverses an array, the order is + By default, when a `for' loop traverses an array, the order is undefined, meaning that the `awk' implementation determines the order in which the array is traversed. This order is usually based on the internal implementation of arrays and will vary from one version of @@ -10829,7 +10837,7 @@ might look like this: -| line 3 -| line 2 - Unfortunately, the very first line of input data did not come out in + Unfortunately, the very first line of input data did not appear in the output! Upon first glance, we would think that this program should have @@ -30433,15 +30441,15 @@ Index (line 6) * archeologists: Bugs. (line 6) * arctangent: Numeric Functions. (line 11) -* ARGC/ARGV variables: Auto-set. (line 11) +* ARGC/ARGV variables: Auto-set. (line 15) * ARGC/ARGV variables, command-line arguments: Other Arguments. (line 12) * ARGC/ARGV variables, how to use: ARGC and ARGV. (line 6) * ARGC/ARGV variables, portability and: Executable Scripts. (line 42) -* ARGIND variable: Auto-set. (line 40) +* ARGIND variable: Auto-set. (line 44) * ARGIND variable, command-line arguments: Other Arguments. (line 12) * arguments, command-line <1>: ARGC and ARGV. (line 6) -* arguments, command-line <2>: Auto-set. (line 11) +* arguments, command-line <2>: Auto-set. (line 15) * arguments, command-line: Other Arguments. (line 6) * arguments, command-line, invoking awk: Command Line. (line 6) * arguments, in function calls: Function Calls. (line 18) @@ -30452,15 +30460,15 @@ Index * array members: Reference to Elements. (line 6) * array scanning order, controlling: Controlling Scanning. - (line 12) + (line 14) * array, number of elements: String Functions. (line 194) * arrays: Arrays. (line 6) * arrays of arrays: Arrays of Arrays. (line 6) * arrays, an example of using: Array Example. (line 6) -* arrays, and IGNORECASE variable: Array Intro. (line 91) +* arrays, and IGNORECASE variable: Array Intro. (line 92) * arrays, as parameters to functions: Pass By Value/Reference. (line 47) -* arrays, associative: Array Intro. (line 49) +* arrays, associative: Array Intro. (line 50) * arrays, associative, library functions and: Library Names. (line 57) * arrays, deleting entire contents: Delete. (line 39) * arrays, elements that don't exist: Reference to Elements. @@ -30471,7 +30479,7 @@ Index (line 48) * arrays, elements, retrieving number of: String Functions. (line 32) * arrays, for statement and: Scanning an Array. (line 20) -* arrays, indexing: Array Intro. (line 49) +* arrays, indexing: Array Intro. (line 50) * arrays, merging into strings: Join Function. (line 6) * arrays, multidimensional: Multidimensional. (line 10) * arrays, multidimensional, scanning: Multiscanning. (line 11) @@ -30485,7 +30493,7 @@ Index (line 6) * arrays, sorting, and IGNORECASE variable: Array Sorting Functions. (line 83) -* arrays, sparse: Array Intro. (line 70) +* arrays, sparse: Array Intro. (line 71) * arrays, subscripts, uninitialized variables as: Uninitialized Subscripts. (line 6) * arrays, unassigned elements: Reference to Elements. @@ -30513,7 +30521,7 @@ Index * assignment operators, evaluation order: Assignment Ops. (line 111) * assignment operators, lvalues/rvalues: Assignment Ops. (line 32) * assignments as filenames: Ignoring Assigns. (line 6) -* associative arrays: Array Intro. (line 49) +* associative arrays: Array Intro. (line 50) * asterisk (*), * operator, as multiplication operator: Precedence. (line 55) * asterisk (*), * operator, as regexp operator: Regexp Operators. @@ -30671,14 +30679,14 @@ Index * Benzinger, Michael: Contributors. (line 97) * Berry, Karl <1>: Ranges and Locales. (line 74) * Berry, Karl: Acknowledgments. (line 33) -* binary input/output: User-modified. (line 10) +* binary input/output: User-modified. (line 15) * bindtextdomain <1>: Programmer i18n. (line 47) * bindtextdomain: I18N Functions. (line 12) * bindtextdomain() function (C library): Explaining gettext. (line 49) * bindtextdomain() function (gawk), portability and: I18N Portability. (line 33) * BINMODE variable <1>: PC Using. (line 33) -* BINMODE variable: User-modified. (line 10) +* BINMODE variable: User-modified. (line 15) * bit-manipulation functions: Bitwise Functions. (line 6) * bits2str() user-defined function: Bitwise Functions. (line 70) * bitwise AND: Bitwise Functions. (line 39) @@ -30782,9 +30790,9 @@ Index (line 59) * caret (^), regexp operator: Regexp Operators. (line 22) * case keyword: Switch Statement. (line 6) -* case sensitivity, and regexps: User-modified. (line 82) -* case sensitivity, and string comparisons: User-modified. (line 82) -* case sensitivity, array indices and: Array Intro. (line 91) +* case sensitivity, and regexps: User-modified. (line 76) +* case sensitivity, and string comparisons: User-modified. (line 76) +* case sensitivity, array indices and: Array Intro. (line 92) * case sensitivity, converting case: String Functions. (line 520) * case sensitivity, example programs: Library Functions. (line 53) * case sensitivity, gawk: Case-sensitivity. (line 26) @@ -30836,7 +30844,7 @@ Index * comma (,), in range patterns: Ranges. (line 6) * command completion, in debugger: Readline Support. (line 6) * command line, arguments <1>: ARGC and ARGV. (line 6) -* command line, arguments <2>: Auto-set. (line 11) +* command line, arguments <2>: Auto-set. (line 15) * command line, arguments: Other Arguments. (line 6) * command line, directories on: Command line directories. (line 6) @@ -30918,7 +30926,7 @@ Index * continue statement: Continue Statement. (line 6) * control statements: Statements. (line 6) * controlling array scanning order: Controlling Scanning. - (line 12) + (line 14) * convert string to lower case: String Functions. (line 521) * convert string to number: String Functions. (line 385) * convert string to upper case: String Functions. (line 527) @@ -30929,7 +30937,7 @@ Index * converting, numbers to strings: Conversion. (line 6) * converting, strings to numbers <1>: Bitwise Functions. (line 109) * converting, strings to numbers: Conversion. (line 6) -* CONVFMT variable <1>: User-modified. (line 28) +* CONVFMT variable <1>: User-modified. (line 30) * CONVFMT variable: Conversion. (line 29) * CONVFMT variable, and array subscripts: Numeric Array Subscripts. (line 6) @@ -30978,9 +30986,9 @@ Index * dark corner, exit statement: Exit Statement. (line 30) * dark corner, field separators: Field Splitting Summary. (line 46) -* dark corner, FILENAME variable <1>: Auto-set. (line 102) +* dark corner, FILENAME variable <1>: Auto-set. (line 98) * dark corner, FILENAME variable: Getline Notes. (line 19) -* dark corner, FNR/NR variables: Auto-set. (line 323) +* dark corner, FNR/NR variables: Auto-set. (line 309) * dark corner, format-control characters: Control Letters. (line 18) * dark corner, FS as null string: Single Character Fields. (line 20) @@ -30999,7 +31007,7 @@ Index (line 43) * dark corner, split() function: String Functions. (line 359) * dark corner, strings, storing: gawk split records. (line 83) -* dark corner, value of ARGV[0]: Auto-set. (line 35) +* dark corner, value of ARGV[0]: Auto-set. (line 39) * data, fixed-width: Constant Size. (line 10) * data-driven languages: Basic High Level. (line 85) * database, group, reading: Group Functions. (line 6) @@ -31145,7 +31153,7 @@ Index * differences between gawk and awk: String Functions. (line 194) * differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV. (line 88) -* differences in awk and gawk, ARGIND variable: Auto-set. (line 40) +* differences in awk and gawk, ARGIND variable: Auto-set. (line 44) * differences in awk and gawk, array elements, deleting: Delete. (line 39) * differences in awk and gawk, AWKLIBPATH environment variable: AWKLIBPATH Variable. @@ -31159,7 +31167,7 @@ Index * differences in awk and gawk, BINMODE variable <1>: PC Using. (line 33) * differences in awk and gawk, BINMODE variable: User-modified. - (line 23) + (line 15) * differences in awk and gawk, close() function: Close Files And Pipes. (line 81) * differences in awk and gawk, command line directories: Command line directories. @@ -31167,14 +31175,14 @@ Index * differences in awk and gawk, ERRNO variable: Auto-set. (line 82) * differences in awk and gawk, error messages: Special FD. (line 16) * differences in awk and gawk, FIELDWIDTHS variable: User-modified. - (line 35) -* differences in awk and gawk, FPAT variable: User-modified. (line 45) -* differences in awk and gawk, FUNCTAB variable: Auto-set. (line 128) + (line 37) +* differences in awk and gawk, FPAT variable: User-modified. (line 43) +* differences in awk and gawk, FUNCTAB variable: Auto-set. (line 123) * differences in awk and gawk, function arguments (gawk): Calling Built-in. (line 16) * differences in awk and gawk, getline command: Getline. (line 19) * differences in awk and gawk, IGNORECASE variable: User-modified. - (line 82) + (line 76) * differences in awk and gawk, implementation limitations <1>: Redirection. (line 135) * differences in awk and gawk, implementation limitations: Getline Notes. @@ -31187,12 +31195,12 @@ Index (line 6) * differences in awk and gawk, line continuations: Conditional Exp. (line 34) -* differences in awk and gawk, LINT variable: User-modified. (line 98) +* differences in awk and gawk, LINT variable: User-modified. (line 88) * differences in awk and gawk, match() function: String Functions. (line 257) * differences in awk and gawk, print/printf statements: Format Modifiers. (line 13) -* differences in awk and gawk, PROCINFO array: Auto-set. (line 142) +* differences in awk and gawk, PROCINFO array: Auto-set. (line 136) * differences in awk and gawk, read timeouts: Read Timeout. (line 6) * differences in awk and gawk, record separators: awk split records. (line 124) @@ -31202,7 +31210,7 @@ Index (line 26) * differences in awk and gawk, RS/RT variables: gawk split records. (line 58) -* differences in awk and gawk, RT variable: Auto-set. (line 275) +* differences in awk and gawk, RT variable: Auto-set. (line 265) * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. @@ -31210,9 +31218,9 @@ Index * differences in awk and gawk, strings: Scalar Constants. (line 20) * differences in awk and gawk, strings, storing: gawk split records. (line 77) -* differences in awk and gawk, SYMTAB variable: Auto-set. (line 283) +* differences in awk and gawk, SYMTAB variable: Auto-set. (line 269) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. - (line 162) + (line 152) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. (line 66) * directories, command line: Command line directories. @@ -31251,8 +31259,8 @@ Index * dynamically loaded extensions: Dynamic Extensions. (line 6) * e debugger command (alias for enable): Breakpoint Control. (line 73) * EBCDIC: Ordinal Functions. (line 45) -* effective group ID of gawk user: Auto-set. (line 147) -* effective user ID of gawk user: Auto-set. (line 151) +* effective group ID of gawk user: Auto-set. (line 141) +* effective user ID of gawk user: Auto-set. (line 145) * egrep utility <1>: Egrep Program. (line 6) * egrep utility: Bracket Expressions. (line 24) * egrep.awk program: Egrep Program. (line 54) @@ -31367,7 +31375,7 @@ Index (line 6) * extension API version: Extension Versioning. (line 6) -* extension API, version number: Auto-set. (line 238) +* extension API, version number: Auto-set. (line 232) * extension example: Extension Example. (line 6) * extension registration: Registration Functions. (line 6) @@ -31416,11 +31424,11 @@ Index (line 6) * field separator, POSIX and: Field Splitting Summary. (line 40) -* field separators <1>: User-modified. (line 56) +* field separators <1>: User-modified. (line 50) * field separators: Field Separators. (line 15) * field separators, choice of: Field Separators. (line 51) -* field separators, FIELDWIDTHS variable and: User-modified. (line 35) -* field separators, FPAT variable and: User-modified. (line 45) +* field separators, FIELDWIDTHS variable and: User-modified. (line 37) +* field separators, FPAT variable and: User-modified. (line 43) * field separators, POSIX and: Fields. (line 6) * field separators, regular expressions as <1>: Regexp Field Splitting. (line 6) @@ -31440,13 +31448,13 @@ Index * fields, separating: Field Separators. (line 15) * fields, single-character: Single Character Fields. (line 6) -* FIELDWIDTHS variable <1>: User-modified. (line 35) +* FIELDWIDTHS variable <1>: User-modified. (line 37) * FIELDWIDTHS variable: Constant Size. (line 23) * file descriptors: Special FD. (line 6) -* file names, distinguishing: Auto-set. (line 52) +* file names, distinguishing: Auto-set. (line 56) * file names, in compatibility mode: Special Caveats. (line 9) * file names, standard streams in gawk: Special FD. (line 46) -* FILENAME variable <1>: Auto-set. (line 102) +* FILENAME variable <1>: Auto-set. (line 98) * FILENAME variable: Reading Files. (line 6) * FILENAME variable, getline, setting with: Getline Notes. (line 19) * filenames, assignments as: Ignoring Assigns. (line 6) @@ -31492,7 +31500,7 @@ Index * files, portable object, converting to message object files: I18N Example. (line 62) * files, portable object, generating: Options. (line 147) -* files, processing, ARGIND variable and: Auto-set. (line 47) +* files, processing, ARGIND variable and: Auto-set. (line 51) * files, reading: Rewind Function. (line 6) * files, reading, multiline records: Multiple Line. (line 6) * files, searching for regular expressions: Egrep Program. (line 6) @@ -31516,9 +31524,9 @@ Index * flush buffered output: I/O Functions. (line 25) * fnmatch() extension function: Extension Sample Fnmatch. (line 12) -* FNR variable <1>: Auto-set. (line 112) +* FNR variable <1>: Auto-set. (line 107) * FNR variable: Records. (line 6) -* FNR variable, changing: Auto-set. (line 323) +* FNR variable, changing: Auto-set. (line 309) * for statement: For Statement. (line 6) * for statement, looping over arrays: Scanning an Array. (line 20) * fork() extension function: Extension Sample Fork. @@ -31540,7 +31548,7 @@ Index * forward slash (/), /= operator, vs. /=.../ regexp constant: Assignment Ops. (line 148) * forward slash (/), patterns and: Expression Patterns. (line 24) -* FPAT variable <1>: User-modified. (line 45) +* FPAT variable <1>: User-modified. (line 43) * FPAT variable: Splitting By Content. (line 27) * frame debugger command: Execution Stack. (line 25) @@ -31550,7 +31558,7 @@ Index * Free Software Foundation (FSF) <2>: Getting. (line 10) * Free Software Foundation (FSF): Manual History. (line 6) * FreeBSD: Glossary. (line 616) -* FS variable <1>: User-modified. (line 56) +* FS variable <1>: User-modified. (line 50) * FS variable: Field Separators. (line 15) * FS variable, --field-separator option and: Options. (line 21) * FS variable, as null string: Single Character Fields. @@ -31568,7 +31576,7 @@ Index * FSF (Free Software Foundation): Manual History. (line 6) * fts() extension function: Extension Sample File Functions. (line 77) -* FUNCTAB array: Auto-set. (line 128) +* FUNCTAB array: Auto-set. (line 123) * function calls: Function Calls. (line 6) * function calls, indirect: Indirect Calls. (line 6) * function definition example: Function Example. (line 6) @@ -31618,7 +31626,7 @@ Index * G-d: Acknowledgments. (line 78) * Garfinkle, Scott: Contributors. (line 34) * gawk program, dynamic profiling: Profiling. (line 179) -* gawk version: Auto-set. (line 213) +* gawk version: Auto-set. (line 207) * gawk, ARGIND variable in: Other Arguments. (line 12) * gawk, awk and <1>: This Manual. (line 14) * gawk, awk and: Preface. (line 23) @@ -31648,22 +31656,22 @@ Index * gawk, extensions, disabling: Options. (line 254) * gawk, features, adding: Adding Code. (line 6) * gawk, features, advanced: Advanced Features. (line 6) -* gawk, field separators and: User-modified. (line 77) -* gawk, FIELDWIDTHS variable in <1>: User-modified. (line 35) +* gawk, field separators and: User-modified. (line 71) +* gawk, FIELDWIDTHS variable in <1>: User-modified. (line 37) * gawk, FIELDWIDTHS variable in: Constant Size. (line 23) * gawk, file names in: Special Files. (line 6) * gawk, format-control characters: Control Letters. (line 18) -* gawk, FPAT variable in <1>: User-modified. (line 45) +* gawk, FPAT variable in <1>: User-modified. (line 43) * gawk, FPAT variable in: Splitting By Content. (line 27) -* gawk, FUNCTAB array in: Auto-set. (line 128) +* gawk, FUNCTAB array in: Auto-set. (line 123) * gawk, function arguments and: Calling Built-in. (line 16) * gawk, hexadecimal numbers and: Nondecimal-numbers. (line 42) * gawk, IGNORECASE variable in <1>: Array Sorting Functions. (line 83) * gawk, IGNORECASE variable in <2>: String Functions. (line 48) -* gawk, IGNORECASE variable in <3>: Array Intro. (line 91) -* gawk, IGNORECASE variable in <4>: User-modified. (line 82) +* gawk, IGNORECASE variable in <3>: Array Intro. (line 92) +* gawk, IGNORECASE variable in <4>: User-modified. (line 76) * gawk, IGNORECASE variable in: Case-sensitivity. (line 26) * gawk, implementation issues: Notes. (line 6) * gawk, implementation issues, debugging: Compatibility Mode. (line 6) @@ -31678,7 +31686,7 @@ Index (line 6) * gawk, interval expressions and: Regexp Operators. (line 140) * gawk, line continuation in: Conditional Exp. (line 34) -* gawk, LINT variable in: User-modified. (line 98) +* gawk, LINT variable in: User-modified. (line 88) * gawk, list of contributors to: Contributors. (line 6) * gawk, MS-DOS version of: PC Using. (line 10) * gawk, MS-Windows version of: PC Using. (line 10) @@ -31687,7 +31695,7 @@ Index * gawk, OS/2 version of: PC Using. (line 10) * gawk, PROCINFO array in <1>: Two-way I/O. (line 116) * gawk, PROCINFO array in <2>: Time Functions. (line 47) -* gawk, PROCINFO array in: Auto-set. (line 142) +* gawk, PROCINFO array in: Auto-set. (line 136) * gawk, regexp constants and: Using Constant Regexps. (line 28) * gawk, regular expressions, case sensitivity: Case-sensitivity. @@ -31695,15 +31703,15 @@ Index * gawk, regular expressions, operators: GNU Regexp Operators. (line 6) * gawk, regular expressions, precedence: Regexp Operators. (line 162) -* gawk, RT variable in <1>: Auto-set. (line 275) +* gawk, RT variable in <1>: Auto-set. (line 265) * gawk, RT variable in <2>: Multiple Line. (line 129) * gawk, RT variable in: awk split records. (line 124) * gawk, See Also awk: Preface. (line 36) * gawk, source code, obtaining: Getting. (line 6) * gawk, splitting fields and: Constant Size. (line 88) * gawk, string-translation functions: I18N Functions. (line 6) -* gawk, SYMTAB array in: Auto-set. (line 283) -* gawk, TEXTDOMAIN variable in: User-modified. (line 162) +* gawk, SYMTAB array in: Auto-set. (line 269) +* gawk, TEXTDOMAIN variable in: User-modified. (line 152) * gawk, timestamps: Time Functions. (line 6) * gawk, uses for: Preface. (line 36) * gawk, versions of, information about, printing: Options. (line 300) @@ -31789,7 +31797,7 @@ Index * Grigera, Juan: Contributors. (line 57) * group database, reading: Group Functions. (line 6) * group file: Group Functions. (line 6) -* group ID of gawk user: Auto-set. (line 186) +* group ID of gawk user: Auto-set. (line 180) * groups, information about: Group Functions. (line 6) * gsub <1>: String Functions. (line 135) * gsub: Using Constant Regexps. @@ -31830,8 +31838,8 @@ Index * igawk.sh program: Igawk Program. (line 124) * ignore breakpoint: Breakpoint Control. (line 87) * ignore debugger command: Breakpoint Control. (line 87) -* IGNORECASE variable: User-modified. (line 82) -* IGNORECASE variable, and array indices: Array Intro. (line 91) +* IGNORECASE variable: User-modified. (line 76) +* IGNORECASE variable, and array indices: Array Intro. (line 92) * IGNORECASE variable, and array sorting functions: Array Sorting Functions. (line 83) * IGNORECASE variable, in example programs: Library Functions. @@ -31856,7 +31864,7 @@ Index * in operator, use in loops: Scanning an Array. (line 17) * increment operators: Increment Ops. (line 6) * index: String Functions. (line 151) -* indexing arrays: Array Intro. (line 49) +* indexing arrays: Array Intro. (line 50) * indirect function calls: Indirect Calls. (line 6) * infinite precision: Arbitrary Precision Arithmetic. (line 6) @@ -31883,7 +31891,7 @@ Index * input, standard <1>: Special FD. (line 6) * input, standard: Read Terminal. (line 6) * input/output functions: I/O Functions. (line 6) -* input/output, binary: User-modified. (line 10) +* input/output, binary: User-modified. (line 15) * input/output, from BEGIN and END: I/O And BEGIN/END. (line 6) * input/output, two-way: Two-way I/O. (line 44) * insomnia, cure for: Alarm Program. (line 6) @@ -31903,7 +31911,7 @@ Index * internationalization: I18N Functions. (line 6) * internationalization, localization <1>: Internationalization. (line 13) -* internationalization, localization: User-modified. (line 162) +* internationalization, localization: User-modified. (line 152) * internationalization, localization, character classes: Bracket Expressions. (line 90) * internationalization, localization, gawk and: Internationalization. @@ -32015,7 +32023,7 @@ Index * lines, duplicate, removing: History Sorting. (line 6) * lines, matching ranges of: Ranges. (line 6) * lines, skipping between markers: Ranges. (line 43) -* lint checking: User-modified. (line 98) +* lint checking: User-modified. (line 88) * lint checking, array elements: Delete. (line 34) * lint checking, array subscripts: Uninitialized Subscripts. (line 43) @@ -32025,7 +32033,7 @@ Index (line 340) * lint checking, undefined functions: Pass By Value/Reference. (line 88) -* LINT variable: User-modified. (line 98) +* LINT variable: User-modified. (line 88) * Linux <1>: Glossary. (line 616) * Linux <2>: I18N Example. (line 55) * Linux: Manual History. (line 28) @@ -32084,7 +32092,7 @@ Index * mawk utility <3>: Concatenation. (line 36) * mawk utility <4>: Getline/Pipe. (line 62) * mawk utility: Escape Sequences. (line 124) -* maximum precision supported by MPFR library: Auto-set. (line 227) +* maximum precision supported by MPFR library: Auto-set. (line 221) * McPhee, Patrick: Contributors. (line 100) * message object files: Explaining gettext. (line 41) * message object files, converting from portable object files: I18N Example. @@ -32096,7 +32104,7 @@ Index * messages from extensions: Printing Messages. (line 6) * metacharacters in regular expressions: Regexp Operators. (line 6) * metacharacters, escape sequences for: Escape Sequences. (line 130) -* minimum precision supported by MPFR library: Auto-set. (line 230) +* minimum precision supported by MPFR library: Auto-set. (line 224) * mktime: Time Functions. (line 25) * modifiers, in format specifiers: Format Modifiers. (line 6) * monetary information, localization: Explaining gettext. (line 103) @@ -32150,7 +32158,7 @@ Index (line 47) * nexti debugger command: Debugger Execution Control. (line 49) -* NF variable <1>: Auto-set. (line 117) +* NF variable <1>: Auto-set. (line 112) * NF variable: Fields. (line 33) * NF variable, decrementing: Changing Fields. (line 107) * ni debugger command (alias for nexti): Debugger Execution Control. @@ -32159,9 +32167,9 @@ Index * non-existent array elements: Reference to Elements. (line 23) * not Boolean-logic operator: Boolean Ops. (line 6) -* NR variable <1>: Auto-set. (line 137) +* NR variable <1>: Auto-set. (line 131) * NR variable: Records. (line 6) -* NR variable, changing: Auto-set. (line 323) +* NR variable, changing: Auto-set. (line 309) * null strings <1>: Basic Data Typing. (line 26) * null strings <2>: Truth Values. (line 6) * null strings <3>: Regexp Field Splitting. @@ -32185,7 +32193,7 @@ Index (line 6) * numbers, converting <1>: Bitwise Functions. (line 109) * numbers, converting: Conversion. (line 6) -* numbers, converting, to strings: User-modified. (line 28) +* numbers, converting, to strings: User-modified. (line 30) * numbers, floating-point: General Arithmetic. (line 6) * numbers, hexadecimal: Nondecimal-numbers. (line 6) * numbers, octal: Nondecimal-numbers. (line 6) @@ -32199,11 +32207,11 @@ Index * obsolete features: Obsolete. (line 6) * octal numbers: Nondecimal-numbers. (line 6) * octal values, enabling interpretation of: Options. (line 211) -* OFMT variable <1>: User-modified. (line 115) +* OFMT variable <1>: User-modified. (line 105) * OFMT variable <2>: Conversion. (line 55) * OFMT variable: OFMT. (line 15) * OFMT variable, POSIX awk and: OFMT. (line 27) -* OFS variable <1>: User-modified. (line 124) +* OFS variable <1>: User-modified. (line 114) * OFS variable <2>: Output Separators. (line 6) * OFS variable: Changing Fields. (line 64) * OpenBSD: Glossary. (line 616) @@ -32256,7 +32264,7 @@ Index (line 12) * ord() user-defined function: Ordinal Functions. (line 16) * order of evaluation, concatenation: Concatenation. (line 41) -* ORS variable <1>: User-modified. (line 129) +* ORS variable <1>: User-modified. (line 119) * ORS variable: Output Separators. (line 20) * output field separator, See OFS variable: Changing Fields. (line 64) * output record separator, See ORS variable: Output Separators. @@ -32276,7 +32284,7 @@ Index * p debugger command (alias for print): Viewing And Changing Data. (line 36) * P1003.1 POSIX standard: Glossary. (line 454) -* parent process ID of gawk process: Auto-set. (line 195) +* parent process ID of gawk process: Auto-set. (line 189) * parentheses (), in a profile: Profiling. (line 146) * parentheses (), regexp operator: Regexp Operators. (line 80) * password file: Passwd Functions. (line 16) @@ -32373,12 +32381,12 @@ Index * POSIX awk, break statement and: Break Statement. (line 51) * POSIX awk, changes in awk versions: POSIX. (line 6) * POSIX awk, continue statement and: Continue Statement. (line 43) -* POSIX awk, CONVFMT variable and: User-modified. (line 28) +* POSIX awk, CONVFMT variable and: User-modified. (line 30) * POSIX awk, date utility and: Time Functions. (line 263) * POSIX awk, field separators and <1>: Field Splitting Summary. (line 40) * POSIX awk, field separators and: Fields. (line 6) -* POSIX awk, FS variable and: User-modified. (line 66) +* POSIX awk, FS variable and: User-modified. (line 60) * POSIX awk, function keyword in: Definition Syntax. (line 83) * POSIX awk, functions and, gsub()/sub(): Gory Details. (line 54) * POSIX awk, functions and, length(): String Functions. (line 173) @@ -32399,7 +32407,7 @@ Index * POSIX, programs, implementing in awk: Clones. (line 6) * POSIXLY_CORRECT environment variable: Options. (line 340) * PREC variable <1>: Setting Precision. (line 6) -* PREC variable: User-modified. (line 134) +* PREC variable: User-modified. (line 124) * precedence <1>: Precedence. (line 6) * precedence: Increment Ops. (line 60) * precedence, regexp operators: Regexp Operators. (line 157) @@ -32410,7 +32418,7 @@ Index * print statement, commas, omitting: Print Examples. (line 31) * print statement, I/O operators in: Precedence. (line 71) * print statement, line continuations and: Print Examples. (line 76) -* print statement, OFMT variable and: User-modified. (line 124) +* print statement, OFMT variable and: User-modified. (line 114) * print statement, See Also redirection, of output: Redirection. (line 17) * print statement, sprintf() function and: Round Function. (line 6) @@ -32441,29 +32449,29 @@ Index * printing, unduplicated lines of text: Uniq Program. (line 6) * printing, user information: Id Program. (line 6) * private variables: Library Names. (line 11) -* process group idIDof gawk process: Auto-set. (line 189) -* process ID of gawk process: Auto-set. (line 192) +* process group idIDof gawk process: Auto-set. (line 183) +* process ID of gawk process: Auto-set. (line 186) * processes, two-way communications with: Two-way I/O. (line 23) * processing data: Basic High Level. (line 6) * PROCINFO array <1>: Passwd Functions. (line 6) * PROCINFO array <2>: Time Functions. (line 47) -* PROCINFO array: Auto-set. (line 142) +* PROCINFO array: Auto-set. (line 136) * PROCINFO array, and communications via ptys: Two-way I/O. (line 116) * PROCINFO array, and group membership: Group Functions. (line 6) * PROCINFO array, and user and group ID numbers: Id Program. (line 15) * PROCINFO array, testing the field splitting: Passwd Functions. (line 161) -* PROCINFO array, uses: Auto-set. (line 248) +* PROCINFO array, uses: Auto-set. (line 242) * PROCINFO, values of sorted_in: Controlling Scanning. - (line 24) + (line 26) * profiling awk programs: Profiling. (line 6) * profiling awk programs, dynamically: Profiling. (line 179) -* program identifiers: Auto-set. (line 160) +* program identifiers: Auto-set. (line 154) * program, definition of: Getting Started. (line 21) * programmers, attractiveness of: Two-way I/O. (line 6) * programming conventions, --non-decimal-data option: Nondecimal Data. (line 36) -* programming conventions, ARGC/ARGV variables: Auto-set. (line 31) +* programming conventions, ARGC/ARGV variables: Auto-set. (line 35) * programming conventions, exit statement: Exit Statement. (line 38) * programming conventions, function parameters: Return Statement. (line 45) @@ -32527,7 +32535,7 @@ Index * readfile() user-defined function: Readfile Function. (line 30) * reading input files: Reading Files. (line 6) * recipe for a programming language: History. (line 6) -* record separators <1>: User-modified. (line 143) +* record separators <1>: User-modified. (line 133) * record separators: awk split records. (line 6) * record separators, changing: awk split records. (line 85) * record separators, regular expressions as: awk split records. @@ -32568,7 +32576,7 @@ Index * regular expressions, as patterns: Regexp Usage. (line 6) * regular expressions, as record separators: awk split records. (line 124) -* regular expressions, case sensitivity <1>: User-modified. (line 82) +* regular expressions, case sensitivity <1>: User-modified. (line 76) * regular expressions, case sensitivity: Case-sensitivity. (line 6) * regular expressions, computed: Computed Regexps. (line 6) * regular expressions, constants, See regexp constants: Regexp Usage. @@ -32618,7 +32626,7 @@ Index * right shift: Bitwise Functions. (line 52) * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 55) -* RLENGTH variable: Auto-set. (line 262) +* RLENGTH variable: Auto-set. (line 252) * RLENGTH variable, match() function and: String Functions. (line 221) * Robbins, Arnold <1>: Future Extensions. (line 6) * Robbins, Arnold <2>: Bugs. (line 32) @@ -32642,14 +32650,14 @@ Index * rounding numbers: Round Function. (line 6) * ROUNDMODE variable <1>: Setting Rounding Mode. (line 6) -* ROUNDMODE variable: User-modified. (line 138) -* RS variable <1>: User-modified. (line 143) +* ROUNDMODE variable: User-modified. (line 128) +* RS variable <1>: User-modified. (line 133) * RS variable: awk split records. (line 12) * RS variable, multiline records and: Multiple Line. (line 17) * rshift: Bitwise Functions. (line 52) -* RSTART variable: Auto-set. (line 268) +* RSTART variable: Auto-set. (line 258) * RSTART variable, match() function and: String Functions. (line 221) -* RT variable <1>: Auto-set. (line 275) +* RT variable <1>: Auto-set. (line 265) * RT variable <2>: Multiple Line. (line 129) * RT variable: awk split records. (line 124) * Rubin, Paul <1>: Contributors. (line 15) @@ -32669,6 +32677,7 @@ Index * scanning arrays: Scanning an Array. (line 6) * scanning multidimensional arrays: Multiscanning. (line 11) * Schorr, Andrew <1>: Contributors. (line 131) +* Schorr, Andrew <2>: Auto-set. (line 292) * Schorr, Andrew: Acknowledgments. (line 60) * Schreiber, Bert: Acknowledgments. (line 38) * Schreiber, Rita: Acknowledgments. (line 38) @@ -32696,16 +32705,16 @@ Index (line 19) * semicolon (;), separating statements in actions: Statements/Lines. (line 91) -* separators, field: User-modified. (line 56) -* separators, field, FIELDWIDTHS variable and: User-modified. (line 35) -* separators, field, FPAT variable and: User-modified. (line 45) +* separators, field: User-modified. (line 50) +* separators, field, FIELDWIDTHS variable and: User-modified. (line 37) +* separators, field, FPAT variable and: User-modified. (line 43) * separators, field, POSIX and: Fields. (line 6) -* separators, for records <1>: User-modified. (line 143) +* separators, for records <1>: User-modified. (line 133) * separators, for records: awk split records. (line 6) * separators, for records, regular expressions as: awk split records. (line 124) * separators, for statements in actions: Action Overview. (line 19) -* separators, subscript: User-modified. (line 156) +* separators, subscript: User-modified. (line 146) * set breakpoint: Breakpoint Control. (line 11) * set debugger command: Viewing And Changing Data. (line 59) @@ -32756,7 +32765,7 @@ Index (line 110) * sidebar, Changing FS Does Not Affect the Fields: Field Splitting Summary. (line 38) -* sidebar, Changing NR and FNR: Auto-set. (line 321) +* sidebar, Changing NR and FNR: Auto-set. (line 307) * sidebar, Controlling Output Buffering with system(): I/O Functions. (line 135) * sidebar, Escape Sequences for Metacharacters: Escape Sequences. @@ -32831,7 +32840,7 @@ Index * source code, QuikTrim Awk: Other Versions. (line 134) * source code, Solaris awk: Other Versions. (line 96) * source files, search path for: Igawk Program. (line 368) -* sparse arrays: Array Intro. (line 70) +* sparse arrays: Array Intro. (line 71) * Spencer, Henry: Glossary. (line 12) * split: String Functions. (line 313) * split string into array: String Functions. (line 291) @@ -32840,7 +32849,7 @@ Index * split.awk program: Split Program. (line 30) * sprintf <1>: String Functions. (line 378) * sprintf: OFMT. (line 15) -* sprintf() function, OFMT variable and: User-modified. (line 124) +* sprintf() function, OFMT variable and: User-modified. (line 114) * sprintf() function, print/printf statements and: Round Function. (line 6) * sqrt: Numeric Functions. (line 78) @@ -32886,7 +32895,7 @@ Index * strings, converting <1>: Bitwise Functions. (line 109) * strings, converting: Conversion. (line 6) * strings, converting letter case: String Functions. (line 520) -* strings, converting, numbers to: User-modified. (line 28) +* strings, converting, numbers to: User-modified. (line 30) * strings, empty, See null strings: awk split records. (line 114) * strings, extracting: String Extraction. (line 6) * strings, for localization: Programmer i18n. (line 14) @@ -32903,7 +32912,7 @@ Index (line 43) * sub() function, arguments of: String Functions. (line 460) * sub() function, escape processing: Gory Details. (line 6) -* subscript separators: User-modified. (line 156) +* subscript separators: User-modified. (line 146) * subscripts in arrays, multidimensional: Multidimensional. (line 10) * subscripts in arrays, multidimensional, scanning: Multiscanning. (line 11) @@ -32911,16 +32920,16 @@ Index (line 6) * subscripts in arrays, uninitialized variables as: Uninitialized Subscripts. (line 6) -* SUBSEP variable: User-modified. (line 156) +* SUBSEP variable: User-modified. (line 146) * SUBSEP variable, and multidimensional arrays: Multidimensional. (line 16) * substitute in string: String Functions. (line 82) * substr: String Functions. (line 479) * substring: String Functions. (line 479) * Sumner, Andrew: Other Versions. (line 64) -* supplementary groups of gawk process: Auto-set. (line 243) +* supplementary groups of gawk process: Auto-set. (line 237) * switch statement: Switch Statement. (line 6) -* SYMTAB array: Auto-set. (line 283) +* SYMTAB array: Auto-set. (line 269) * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. (line 148) * system: I/O Functions. (line 72) @@ -32950,7 +32959,7 @@ Index * text, printing: Print. (line 22) * text, printing, unduplicated lines of: Uniq Program. (line 6) * TEXTDOMAIN variable <1>: Programmer i18n. (line 9) -* TEXTDOMAIN variable: User-modified. (line 162) +* TEXTDOMAIN variable: User-modified. (line 152) * TEXTDOMAIN variable, BEGIN pattern and: Programmer i18n. (line 60) * TEXTDOMAIN variable, portability and: I18N Portability. (line 20) * textdomain() function (C library): Explaining gettext. (line 27) @@ -33099,10 +33108,10 @@ Index * variables, uninitialized, as array subscripts: Uninitialized Subscripts. (line 6) * variables, user-defined: Variables. (line 6) -* version of gawk: Auto-set. (line 213) -* version of gawk extension API: Auto-set. (line 238) -* version of GNU MP library: Auto-set. (line 224) -* version of GNU MPFR library: Auto-set. (line 220) +* version of gawk: Auto-set. (line 207) +* version of gawk extension API: Auto-set. (line 232) +* version of GNU MP library: Auto-set. (line 218) +* version of GNU MPFR library: Auto-set. (line 214) * vertical bar (|): Regexp Operators. (line 70) * vertical bar (|), | operator (I/O) <1>: Precedence. (line 65) * vertical bar (|), | operator (I/O): Getline/Pipe. (line 9) @@ -33378,344 +33387,345 @@ Node: Next Statement400827 Node: Nextfile Statement403217 Node: Exit Statement405872 Node: Built-in Variables408274 -Node: User-modified409369 -Ref: User-modified-Footnote-1417727 -Node: Auto-set417789 -Ref: Auto-set-Footnote-1431248 -Ref: Auto-set-Footnote-2431453 -Node: ARGC and ARGV431509 -Node: Arrays435363 -Node: Array Basics436868 -Node: Array Intro437694 -Node: Reference to Elements442011 -Node: Assigning Elements444281 -Node: Array Example444772 -Node: Scanning an Array446504 -Node: Controlling Scanning448818 -Ref: Controlling Scanning-Footnote-1453905 -Node: Delete454221 -Ref: Delete-Footnote-1456986 -Node: Numeric Array Subscripts457043 -Node: Uninitialized Subscripts459226 -Node: Multidimensional460853 -Node: Multiscanning463946 -Node: Arrays of Arrays465535 -Node: Functions470175 -Node: Built-in470994 -Node: Calling Built-in472072 -Node: Numeric Functions474060 -Ref: Numeric Functions-Footnote-1477894 -Ref: Numeric Functions-Footnote-2478251 -Ref: Numeric Functions-Footnote-3478299 -Node: String Functions478568 -Ref: String Functions-Footnote-1501571 -Ref: String Functions-Footnote-2501700 -Ref: String Functions-Footnote-3501948 -Node: Gory Details502035 -Ref: table-sub-escapes503714 -Ref: table-sub-posix-92505068 -Ref: table-sub-proposed506419 -Ref: table-posix-sub507773 -Ref: table-gensub-escapes509318 -Ref: Gory Details-Footnote-1510494 -Ref: Gory Details-Footnote-2510545 -Node: I/O Functions510696 -Ref: I/O Functions-Footnote-1517692 -Node: Time Functions517839 -Ref: Time Functions-Footnote-1528832 -Ref: Time Functions-Footnote-2528900 -Ref: Time Functions-Footnote-3529058 -Ref: Time Functions-Footnote-4529169 -Ref: Time Functions-Footnote-5529281 -Ref: Time Functions-Footnote-6529508 -Node: Bitwise Functions529774 -Ref: table-bitwise-ops530336 -Ref: Bitwise Functions-Footnote-1534581 -Node: Type Functions534765 -Node: I18N Functions535916 -Node: User-defined537568 -Node: Definition Syntax538372 -Ref: Definition Syntax-Footnote-1543286 -Node: Function Example543355 -Ref: Function Example-Footnote-1546004 -Node: Function Caveats546026 -Node: Calling A Function546544 -Node: Variable Scope547499 -Node: Pass By Value/Reference550462 -Node: Return Statement553970 -Node: Dynamic Typing556951 -Node: Indirect Calls557882 -Node: Library Functions567569 -Ref: Library Functions-Footnote-1571082 -Ref: Library Functions-Footnote-2571225 -Node: Library Names571396 -Ref: Library Names-Footnote-1574869 -Ref: Library Names-Footnote-2575089 -Node: General Functions575175 -Node: Strtonum Function576203 -Node: Assert Function579133 -Node: Round Function582459 -Node: Cliff Random Function584000 -Node: Ordinal Functions585016 -Ref: Ordinal Functions-Footnote-1588093 -Ref: Ordinal Functions-Footnote-2588345 -Node: Join Function588556 -Ref: Join Function-Footnote-1590327 -Node: Getlocaltime Function590527 -Node: Readfile Function594268 -Node: Data File Management596107 -Node: Filetrans Function596739 -Node: Rewind Function600808 -Node: File Checking602195 -Node: Empty Files603289 -Node: Ignoring Assigns605519 -Node: Getopt Function607073 -Ref: Getopt Function-Footnote-1618376 -Node: Passwd Functions618579 -Ref: Passwd Functions-Footnote-1627557 -Node: Group Functions627645 -Node: Walking Arrays635729 -Node: Sample Programs637865 -Node: Running Examples638539 -Node: Clones639267 -Node: Cut Program640491 -Node: Egrep Program650342 -Ref: Egrep Program-Footnote-1658115 -Node: Id Program658225 -Node: Split Program661874 -Ref: Split Program-Footnote-1665393 -Node: Tee Program665521 -Node: Uniq Program668324 -Node: Wc Program675753 -Ref: Wc Program-Footnote-1680019 -Ref: Wc Program-Footnote-2680219 -Node: Miscellaneous Programs680311 -Node: Dupword Program681499 -Node: Alarm Program683530 -Node: Translate Program688337 -Ref: Translate Program-Footnote-1692724 -Ref: Translate Program-Footnote-2692972 -Node: Labels Program693106 -Ref: Labels Program-Footnote-1696477 -Node: Word Sorting696561 -Node: History Sorting700445 -Node: Extract Program702284 -Ref: Extract Program-Footnote-1709787 -Node: Simple Sed709915 -Node: Igawk Program712977 -Ref: Igawk Program-Footnote-1728148 -Ref: Igawk Program-Footnote-2728349 -Node: Anagram Program728487 -Node: Signature Program731555 -Node: Advanced Features732655 -Node: Nondecimal Data734541 -Node: Array Sorting736124 -Node: Controlling Array Traversal736821 -Node: Array Sorting Functions745105 -Ref: Array Sorting Functions-Footnote-1748974 -Node: Two-way I/O749168 -Ref: Two-way I/O-Footnote-1754600 -Node: TCP/IP Networking754682 -Node: Profiling757526 -Node: Internationalization765029 -Node: I18N and L10N766454 -Node: Explaining gettext767140 -Ref: Explaining gettext-Footnote-1772208 -Ref: Explaining gettext-Footnote-2772392 -Node: Programmer i18n772557 -Node: Translator i18n776784 -Node: String Extraction777578 -Ref: String Extraction-Footnote-1778539 -Node: Printf Ordering778625 -Ref: Printf Ordering-Footnote-1781407 -Node: I18N Portability781471 -Ref: I18N Portability-Footnote-1783920 -Node: I18N Example783983 -Ref: I18N Example-Footnote-1786621 -Node: Gawk I18N786693 -Node: Debugger787314 -Node: Debugging788285 -Node: Debugging Concepts788718 -Node: Debugging Terms790574 -Node: Awk Debugging793171 -Node: Sample Debugging Session794063 -Node: Debugger Invocation794583 -Node: Finding The Bug795916 -Node: List of Debugger Commands802403 -Node: Breakpoint Control803737 -Node: Debugger Execution Control807401 -Node: Viewing And Changing Data810761 -Node: Execution Stack814117 -Node: Debugger Info815584 -Node: Miscellaneous Debugger Commands819578 -Node: Readline Support824756 -Node: Limitations825587 -Node: Arbitrary Precision Arithmetic827839 -Ref: Arbitrary Precision Arithmetic-Footnote-1829488 -Node: General Arithmetic829636 -Node: Floating Point Issues831356 -Node: String Conversion Precision832237 -Ref: String Conversion Precision-Footnote-1833942 -Node: Unexpected Results834051 -Node: POSIX Floating Point Problems836204 -Ref: POSIX Floating Point Problems-Footnote-1840029 -Node: Integer Programming840067 -Node: Floating-point Programming841806 -Ref: Floating-point Programming-Footnote-1848137 -Ref: Floating-point Programming-Footnote-2848407 -Node: Floating-point Representation848671 -Node: Floating-point Context849836 -Ref: table-ieee-formats850675 -Node: Rounding Mode852059 -Ref: table-rounding-modes852538 -Ref: Rounding Mode-Footnote-1855553 -Node: Gawk and MPFR855732 -Node: Arbitrary Precision Floats857141 -Ref: Arbitrary Precision Floats-Footnote-1859584 -Node: Setting Precision859900 -Ref: table-predefined-precision-strings860586 -Node: Setting Rounding Mode862731 -Ref: table-gawk-rounding-modes863135 -Node: Floating-point Constants864322 -Node: Changing Precision865751 -Ref: Changing Precision-Footnote-1867148 -Node: Exact Arithmetic867322 -Node: Arbitrary Precision Integers870460 -Ref: Arbitrary Precision Integers-Footnote-1873475 -Node: Dynamic Extensions873622 -Node: Extension Intro875080 -Node: Plugin License876345 -Node: Extension Mechanism Outline877030 -Ref: load-extension877447 -Ref: load-new-function878925 -Ref: call-new-function879920 -Node: Extension API Description881935 -Node: Extension API Functions Introduction883222 -Node: General Data Types888149 -Ref: General Data Types-Footnote-1893844 -Node: Requesting Values894143 -Ref: table-value-types-returned894880 -Node: Memory Allocation Functions895834 -Ref: Memory Allocation Functions-Footnote-1898580 -Node: Constructor Functions898676 -Node: Registration Functions900434 -Node: Extension Functions901119 -Node: Exit Callback Functions903421 -Node: Extension Version String904670 -Node: Input Parsers905320 -Node: Output Wrappers915077 -Node: Two-way processors919587 -Node: Printing Messages921795 -Ref: Printing Messages-Footnote-1922872 -Node: Updating `ERRNO'923024 -Node: Accessing Parameters923763 -Node: Symbol Table Access924993 -Node: Symbol table by name925507 -Node: Symbol table by cookie927483 -Ref: Symbol table by cookie-Footnote-1931615 -Node: Cached values931678 -Ref: Cached values-Footnote-1935168 -Node: Array Manipulation935259 -Ref: Array Manipulation-Footnote-1936357 -Node: Array Data Types936396 -Ref: Array Data Types-Footnote-1939099 -Node: Array Functions939191 -Node: Flattening Arrays943027 -Node: Creating Arrays949879 -Node: Extension API Variables954604 -Node: Extension Versioning955240 -Node: Extension API Informational Variables957141 -Node: Extension API Boilerplate958227 -Node: Finding Extensions962031 -Node: Extension Example962591 -Node: Internal File Description963321 -Node: Internal File Ops967412 -Ref: Internal File Ops-Footnote-1978921 -Node: Using Internal File Ops979061 -Ref: Using Internal File Ops-Footnote-1981408 -Node: Extension Samples981674 -Node: Extension Sample File Functions983198 -Node: Extension Sample Fnmatch991685 -Node: Extension Sample Fork993454 -Node: Extension Sample Inplace994667 -Node: Extension Sample Ord996445 -Node: Extension Sample Readdir997281 -Node: Extension Sample Revout998813 -Node: Extension Sample Rev2way999406 -Node: Extension Sample Read write array1000096 -Node: Extension Sample Readfile1001979 -Node: Extension Sample API Tests1003079 -Node: Extension Sample Time1003604 -Node: gawkextlib1004968 -Node: Language History1007749 -Node: V7/SVR3.11009342 -Node: SVR41011662 -Node: POSIX1013104 -Node: BTL1014490 -Node: POSIX/GNU1015224 -Node: Feature History1020823 -Node: Common Extensions1033799 -Node: Ranges and Locales1035111 -Ref: Ranges and Locales-Footnote-11039728 -Ref: Ranges and Locales-Footnote-21039755 -Ref: Ranges and Locales-Footnote-31039989 -Node: Contributors1040210 -Node: Installation1045591 -Node: Gawk Distribution1046485 -Node: Getting1046969 -Node: Extracting1047795 -Node: Distribution contents1049487 -Node: Unix Installation1055208 -Node: Quick Installation1055825 -Node: Additional Configuration Options1058271 -Node: Configuration Philosophy1060007 -Node: Non-Unix Installation1062361 -Node: PC Installation1062819 -Node: PC Binary Installation1064118 -Node: PC Compiling1065966 -Node: PC Testing1068910 -Node: PC Using1070086 -Node: Cygwin1074254 -Node: MSYS1075063 -Node: VMS Installation1075577 -Node: VMS Compilation1076373 -Ref: VMS Compilation-Footnote-11077625 -Node: VMS Dynamic Extensions1077683 -Node: VMS Installation Details1079056 -Node: VMS Running1081307 -Node: VMS GNV1084141 -Node: VMS Old Gawk1084864 -Node: Bugs1085334 -Node: Other Versions1089252 -Node: Notes1095336 -Node: Compatibility Mode1096136 -Node: Additions1096919 -Node: Accessing The Source1097846 -Node: Adding Code1099286 -Node: New Ports1105331 -Node: Derived Files1109466 -Ref: Derived Files-Footnote-11114787 -Ref: Derived Files-Footnote-21114821 -Ref: Derived Files-Footnote-31115421 -Node: Future Extensions1115519 -Node: Implementation Limitations1116102 -Node: Extension Design1117350 -Node: Old Extension Problems1118504 -Ref: Old Extension Problems-Footnote-11120012 -Node: Extension New Mechanism Goals1120069 -Ref: Extension New Mechanism Goals-Footnote-11123434 -Node: Extension Other Design Decisions1123620 -Node: Extension Future Growth1125726 -Node: Old Extension Mechanism1126562 -Node: Basic Concepts1128302 -Node: Basic High Level1128983 -Ref: figure-general-flow1129255 -Ref: figure-process-flow1129854 -Ref: Basic High Level-Footnote-11133083 -Node: Basic Data Typing1133268 -Node: Glossary1136623 -Node: Copying1161854 -Node: GNU Free Documentation License1199410 -Node: Index1224546 +Node: User-modified409370 +Ref: User-modified-Footnote-1417055 +Node: Auto-set417117 +Ref: Auto-set-Footnote-1430019 +Ref: Auto-set-Footnote-2430224 +Node: ARGC and ARGV430280 +Node: Arrays434134 +Node: Array Basics435632 +Node: Array Intro436458 +Ref: figure-array-elements438431 +Node: Reference to Elements440838 +Node: Assigning Elements443111 +Node: Array Example443602 +Node: Scanning an Array445334 +Node: Controlling Scanning448349 +Ref: Controlling Scanning-Footnote-1453522 +Node: Delete453838 +Ref: Delete-Footnote-1456603 +Node: Numeric Array Subscripts456660 +Node: Uninitialized Subscripts458843 +Node: Multidimensional460468 +Node: Multiscanning463561 +Node: Arrays of Arrays465150 +Node: Functions469790 +Node: Built-in470609 +Node: Calling Built-in471687 +Node: Numeric Functions473675 +Ref: Numeric Functions-Footnote-1477509 +Ref: Numeric Functions-Footnote-2477866 +Ref: Numeric Functions-Footnote-3477914 +Node: String Functions478183 +Ref: String Functions-Footnote-1501186 +Ref: String Functions-Footnote-2501315 +Ref: String Functions-Footnote-3501563 +Node: Gory Details501650 +Ref: table-sub-escapes503329 +Ref: table-sub-posix-92504683 +Ref: table-sub-proposed506034 +Ref: table-posix-sub507388 +Ref: table-gensub-escapes508933 +Ref: Gory Details-Footnote-1510109 +Ref: Gory Details-Footnote-2510160 +Node: I/O Functions510311 +Ref: I/O Functions-Footnote-1517307 +Node: Time Functions517454 +Ref: Time Functions-Footnote-1528447 +Ref: Time Functions-Footnote-2528515 +Ref: Time Functions-Footnote-3528673 +Ref: Time Functions-Footnote-4528784 +Ref: Time Functions-Footnote-5528896 +Ref: Time Functions-Footnote-6529123 +Node: Bitwise Functions529389 +Ref: table-bitwise-ops529951 +Ref: Bitwise Functions-Footnote-1534196 +Node: Type Functions534380 +Node: I18N Functions535531 +Node: User-defined537183 +Node: Definition Syntax537987 +Ref: Definition Syntax-Footnote-1542901 +Node: Function Example542970 +Ref: Function Example-Footnote-1545619 +Node: Function Caveats545641 +Node: Calling A Function546159 +Node: Variable Scope547114 +Node: Pass By Value/Reference550077 +Node: Return Statement553585 +Node: Dynamic Typing556566 +Node: Indirect Calls557497 +Node: Library Functions567184 +Ref: Library Functions-Footnote-1570697 +Ref: Library Functions-Footnote-2570840 +Node: Library Names571011 +Ref: Library Names-Footnote-1574484 +Ref: Library Names-Footnote-2574704 +Node: General Functions574790 +Node: Strtonum Function575818 +Node: Assert Function578748 +Node: Round Function582074 +Node: Cliff Random Function583615 +Node: Ordinal Functions584631 +Ref: Ordinal Functions-Footnote-1587708 +Ref: Ordinal Functions-Footnote-2587960 +Node: Join Function588171 +Ref: Join Function-Footnote-1589942 +Node: Getlocaltime Function590142 +Node: Readfile Function593883 +Node: Data File Management595722 +Node: Filetrans Function596354 +Node: Rewind Function600423 +Node: File Checking601810 +Node: Empty Files602904 +Node: Ignoring Assigns605134 +Node: Getopt Function606688 +Ref: Getopt Function-Footnote-1617991 +Node: Passwd Functions618194 +Ref: Passwd Functions-Footnote-1627172 +Node: Group Functions627260 +Node: Walking Arrays635344 +Node: Sample Programs637480 +Node: Running Examples638154 +Node: Clones638882 +Node: Cut Program640106 +Node: Egrep Program649957 +Ref: Egrep Program-Footnote-1657730 +Node: Id Program657840 +Node: Split Program661489 +Ref: Split Program-Footnote-1665008 +Node: Tee Program665136 +Node: Uniq Program667939 +Node: Wc Program675368 +Ref: Wc Program-Footnote-1679634 +Ref: Wc Program-Footnote-2679834 +Node: Miscellaneous Programs679926 +Node: Dupword Program681114 +Node: Alarm Program683145 +Node: Translate Program687952 +Ref: Translate Program-Footnote-1692339 +Ref: Translate Program-Footnote-2692587 +Node: Labels Program692721 +Ref: Labels Program-Footnote-1696092 +Node: Word Sorting696176 +Node: History Sorting700060 +Node: Extract Program701899 +Ref: Extract Program-Footnote-1709402 +Node: Simple Sed709530 +Node: Igawk Program712592 +Ref: Igawk Program-Footnote-1727763 +Ref: Igawk Program-Footnote-2727964 +Node: Anagram Program728102 +Node: Signature Program731170 +Node: Advanced Features732270 +Node: Nondecimal Data734156 +Node: Array Sorting735739 +Node: Controlling Array Traversal736436 +Node: Array Sorting Functions744720 +Ref: Array Sorting Functions-Footnote-1748589 +Node: Two-way I/O748783 +Ref: Two-way I/O-Footnote-1754215 +Node: TCP/IP Networking754297 +Node: Profiling757141 +Node: Internationalization764644 +Node: I18N and L10N766069 +Node: Explaining gettext766755 +Ref: Explaining gettext-Footnote-1771823 +Ref: Explaining gettext-Footnote-2772007 +Node: Programmer i18n772172 +Node: Translator i18n776399 +Node: String Extraction777193 +Ref: String Extraction-Footnote-1778154 +Node: Printf Ordering778240 +Ref: Printf Ordering-Footnote-1781022 +Node: I18N Portability781086 +Ref: I18N Portability-Footnote-1783535 +Node: I18N Example783598 +Ref: I18N Example-Footnote-1786236 +Node: Gawk I18N786308 +Node: Debugger786929 +Node: Debugging787900 +Node: Debugging Concepts788333 +Node: Debugging Terms790189 +Node: Awk Debugging792786 +Node: Sample Debugging Session793678 +Node: Debugger Invocation794198 +Node: Finding The Bug795531 +Node: List of Debugger Commands802018 +Node: Breakpoint Control803352 +Node: Debugger Execution Control807016 +Node: Viewing And Changing Data810376 +Node: Execution Stack813732 +Node: Debugger Info815199 +Node: Miscellaneous Debugger Commands819193 +Node: Readline Support824371 +Node: Limitations825202 +Node: Arbitrary Precision Arithmetic827454 +Ref: Arbitrary Precision Arithmetic-Footnote-1829103 +Node: General Arithmetic829251 +Node: Floating Point Issues830971 +Node: String Conversion Precision831852 +Ref: String Conversion Precision-Footnote-1833557 +Node: Unexpected Results833666 +Node: POSIX Floating Point Problems835819 +Ref: POSIX Floating Point Problems-Footnote-1839644 +Node: Integer Programming839682 +Node: Floating-point Programming841421 +Ref: Floating-point Programming-Footnote-1847752 +Ref: Floating-point Programming-Footnote-2848022 +Node: Floating-point Representation848286 +Node: Floating-point Context849451 +Ref: table-ieee-formats850290 +Node: Rounding Mode851674 +Ref: table-rounding-modes852153 +Ref: Rounding Mode-Footnote-1855168 +Node: Gawk and MPFR855347 +Node: Arbitrary Precision Floats856756 +Ref: Arbitrary Precision Floats-Footnote-1859199 +Node: Setting Precision859515 +Ref: table-predefined-precision-strings860201 +Node: Setting Rounding Mode862346 +Ref: table-gawk-rounding-modes862750 +Node: Floating-point Constants863937 +Node: Changing Precision865366 +Ref: Changing Precision-Footnote-1866763 +Node: Exact Arithmetic866937 +Node: Arbitrary Precision Integers870075 +Ref: Arbitrary Precision Integers-Footnote-1873090 +Node: Dynamic Extensions873237 +Node: Extension Intro874695 +Node: Plugin License875960 +Node: Extension Mechanism Outline876645 +Ref: load-extension877062 +Ref: load-new-function878540 +Ref: call-new-function879535 +Node: Extension API Description881550 +Node: Extension API Functions Introduction882837 +Node: General Data Types887764 +Ref: General Data Types-Footnote-1893459 +Node: Requesting Values893758 +Ref: table-value-types-returned894495 +Node: Memory Allocation Functions895449 +Ref: Memory Allocation Functions-Footnote-1898195 +Node: Constructor Functions898291 +Node: Registration Functions900049 +Node: Extension Functions900734 +Node: Exit Callback Functions903036 +Node: Extension Version String904285 +Node: Input Parsers904935 +Node: Output Wrappers914692 +Node: Two-way processors919202 +Node: Printing Messages921410 +Ref: Printing Messages-Footnote-1922487 +Node: Updating `ERRNO'922639 +Node: Accessing Parameters923378 +Node: Symbol Table Access924608 +Node: Symbol table by name925122 +Node: Symbol table by cookie927098 +Ref: Symbol table by cookie-Footnote-1931230 +Node: Cached values931293 +Ref: Cached values-Footnote-1934783 +Node: Array Manipulation934874 +Ref: Array Manipulation-Footnote-1935972 +Node: Array Data Types936011 +Ref: Array Data Types-Footnote-1938714 +Node: Array Functions938806 +Node: Flattening Arrays942642 +Node: Creating Arrays949494 +Node: Extension API Variables954219 +Node: Extension Versioning954855 +Node: Extension API Informational Variables956756 +Node: Extension API Boilerplate957842 +Node: Finding Extensions961646 +Node: Extension Example962206 +Node: Internal File Description962936 +Node: Internal File Ops967027 +Ref: Internal File Ops-Footnote-1978536 +Node: Using Internal File Ops978676 +Ref: Using Internal File Ops-Footnote-1981023 +Node: Extension Samples981289 +Node: Extension Sample File Functions982813 +Node: Extension Sample Fnmatch991300 +Node: Extension Sample Fork993069 +Node: Extension Sample Inplace994282 +Node: Extension Sample Ord996060 +Node: Extension Sample Readdir996896 +Node: Extension Sample Revout998428 +Node: Extension Sample Rev2way999021 +Node: Extension Sample Read write array999711 +Node: Extension Sample Readfile1001594 +Node: Extension Sample API Tests1002694 +Node: Extension Sample Time1003219 +Node: gawkextlib1004583 +Node: Language History1007364 +Node: V7/SVR3.11008957 +Node: SVR41011277 +Node: POSIX1012719 +Node: BTL1014105 +Node: POSIX/GNU1014839 +Node: Feature History1020438 +Node: Common Extensions1033414 +Node: Ranges and Locales1034726 +Ref: Ranges and Locales-Footnote-11039343 +Ref: Ranges and Locales-Footnote-21039370 +Ref: Ranges and Locales-Footnote-31039604 +Node: Contributors1039825 +Node: Installation1045206 +Node: Gawk Distribution1046100 +Node: Getting1046584 +Node: Extracting1047410 +Node: Distribution contents1049102 +Node: Unix Installation1054823 +Node: Quick Installation1055440 +Node: Additional Configuration Options1057886 +Node: Configuration Philosophy1059622 +Node: Non-Unix Installation1061976 +Node: PC Installation1062434 +Node: PC Binary Installation1063733 +Node: PC Compiling1065581 +Node: PC Testing1068525 +Node: PC Using1069701 +Node: Cygwin1073869 +Node: MSYS1074678 +Node: VMS Installation1075192 +Node: VMS Compilation1075988 +Ref: VMS Compilation-Footnote-11077240 +Node: VMS Dynamic Extensions1077298 +Node: VMS Installation Details1078671 +Node: VMS Running1080922 +Node: VMS GNV1083756 +Node: VMS Old Gawk1084479 +Node: Bugs1084949 +Node: Other Versions1088867 +Node: Notes1094951 +Node: Compatibility Mode1095751 +Node: Additions1096534 +Node: Accessing The Source1097461 +Node: Adding Code1098901 +Node: New Ports1104946 +Node: Derived Files1109081 +Ref: Derived Files-Footnote-11114402 +Ref: Derived Files-Footnote-21114436 +Ref: Derived Files-Footnote-31115036 +Node: Future Extensions1115134 +Node: Implementation Limitations1115717 +Node: Extension Design1116965 +Node: Old Extension Problems1118119 +Ref: Old Extension Problems-Footnote-11119627 +Node: Extension New Mechanism Goals1119684 +Ref: Extension New Mechanism Goals-Footnote-11123049 +Node: Extension Other Design Decisions1123235 +Node: Extension Future Growth1125341 +Node: Old Extension Mechanism1126177 +Node: Basic Concepts1127917 +Node: Basic High Level1128598 +Ref: figure-general-flow1128870 +Ref: figure-process-flow1129469 +Ref: Basic High Level-Footnote-11132698 +Node: Basic Data Typing1132883 +Node: Glossary1136238 +Node: Copying1161469 +Node: GNU Free Documentation License1199025 +Node: Index1224161 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index bce3f203..6fc8287b 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -13657,9 +13657,9 @@ automatically by @command{awk}, so that they carry information from the internal workings of @command{awk} to your program. @cindex @command{gawk}, built-in variables and -This @value{SECTION} documents all the built-in variables of -@command{gawk}, most of which are also documented in the chapters -describing their areas of activity. +This @value{SECTION} documents all of @command{gawk}'s built-in variables, +most of which are also documented in the @value{CHAPTER}s describing +their areas of activity. @menu * User-modified:: Built-in variables that you change to control @@ -13677,44 +13677,38 @@ describing their areas of activity. @cindex user-modifiable variables The following is an alphabetical list of variables that you can change to -control how @command{awk} does certain things. The variables that are -specific to @command{gawk} are marked with a pound sign@w{ (@samp{#}).} +control how @command{awk} does certain things. + +The variables that are specific to @command{gawk} are marked with a pound +sign (@samp{#}). These variables are @command{gawk} extensions. In other +@command{awk} implementations or if @command{gawk} is in compatibility +mode (@pxref{Options}), they are not special. (Any exceptions are noted +in the description of each variable.) @table @code @cindex @code{BINMODE} variable @cindex binary input/output @cindex input/output, binary -@item BINMODE # -On non-POSIX systems, this variable specifies use of binary mode for all I/O. -Numeric values of one, two, or three specify that input files, output files, or -all files, respectively, should use binary I/O. -A numeric value less than zero is treated as zero, and a numeric value greater than -three is treated as three. -Alternatively, -string values of @code{"r"} or @code{"w"} specify that input files and -output files, respectively, should use binary I/O. -A string value of @code{"rw"} or @code{"wr"} indicates that all -files should use binary I/O. -Any other string value is treated the same as @code{"rw"}, -but causes @command{gawk} -to generate a warning message. -@code{BINMODE} is described in more detail in -@ref{PC Using}. - @cindex differences in @command{awk} and @command{gawk}, @code{BINMODE} variable -This variable is a @command{gawk} extension. -In other @command{awk} implementations -(except @command{mawk}, -@pxref{Other Versions}), -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. +@item BINMODE # +On non-POSIX systems, this variable specifies use of binary mode +for all I/O. Numeric values of one, two, or three specify that input +files, output files, or all files, respectively, should use binary I/O. +A numeric value less than zero is treated as zero, and a numeric value +greater than three is treated as three. Alternatively, string values +of @code{"r"} or @code{"w"} specify that input files and output files, +respectively, should use binary I/O. A string value of @code{"rw"} or +@code{"wr"} indicates that all files should use binary I/O. Any other +string value is treated the same as @code{"rw"}, but causes @command{gawk} +to generate a warning message. @code{BINMODE} is described in more +detail in @ref{PC Using}. @command{mawk} @pxref{Other Versions}), +also supports this variable, but only using numeric values. @cindex @code{CONVFMT} variable @cindex POSIX @command{awk}, @code{CONVFMT} variable and @cindex numbers, converting, to strings @cindex strings, converting, numbers to -@item CONVFMT +@item @code{CONVFMT} This string controls conversion of numbers to strings (@pxref{Conversion}). It works by being passed, in effect, as the first argument to the @@ -13729,40 +13723,29 @@ Its default value is @code{"%.6g"}. @cindex field separators, @code{FIELDWIDTHS} variable and @cindex separators, field, @code{FIELDWIDTHS} variable and @item FIELDWIDTHS # -This is a space-separated list of columns that tells @command{gawk} +A space-separated list of columns that tells @command{gawk} how to split input with fixed columnar boundaries. Assigning a value to @code{FIELDWIDTHS} overrides the use of @code{FS} and @code{FPAT} for field splitting. @xref{Constant Size}, for more information. -If @command{gawk} is in compatibility mode -(@pxref{Options}), then @code{FIELDWIDTHS} -has no special meaning, and field-splitting operations occur based -exclusively on the value of @code{FS}. - @cindex @command{gawk}, @code{FPAT} variable in @cindex @code{FPAT} variable @cindex differences in @command{awk} and @command{gawk}, @code{FPAT} variable @cindex field separators, @code{FPAT} variable and @cindex separators, field, @code{FPAT} variable and @item FPAT # -This is a regular expression (as a string) that tells @command{gawk} +A regular expression (as a string) that tells @command{gawk} to create the fields based on text that matches the regular expression. Assigning a value to @code{FPAT} overrides the use of @code{FS} and @code{FIELDWIDTHS} for field splitting. @xref{Splitting By Content}, for more information. -If @command{gawk} is in compatibility mode -(@pxref{Options}), then @code{FPAT} -has no special meaning, and field-splitting operations occur based -exclusively on the value of @code{FS}. - @cindex @code{FS} variable @cindex separators, field @cindex field separators @item FS -This is the input field separator -(@pxref{Field Separators}). +The input field separator (@pxref{Field Separators}). The value is a single-character string or a multicharacter regular expression that matches the separations between fields in an input record. If the value is the null string (@code{""}), then each @@ -13812,18 +13795,13 @@ and it does not affect field splitting when using a single-character field separator. @xref{Case-sensitivity}. -If @command{gawk} is in compatibility mode -(@pxref{Options}), -then @code{IGNORECASE} has no special meaning. Thus, string -and regexp operations are always case-sensitive. - @cindex @command{gawk}, @code{LINT} variable in @cindex @code{LINT} variable @cindex differences in @command{awk} and @command{gawk}, @code{LINT} variable @cindex lint checking @item LINT # When this variable is true (nonzero or non-null), @command{gawk} -behaves as if the @option{--lint} command-line option is in effect. +behaves as if the @option{--lint} command-line option is in effect (@pxref{Options}). With a value of @code{"fatal"}, lint warnings become fatal errors. With a value of @code{"invalid"}, only warnings about things that are @@ -13844,7 +13822,7 @@ of @command{awk} being executed. @cindex numbers, converting, to strings @cindex strings, converting, numbers to @item OFMT -This string controls conversion of numbers to +Controls conversion of numbers to strings (@pxref{Conversion}) for printing with the @code{print} statement. It works by being passed as the first argument to the @code{sprintf()} function @@ -13865,7 +13843,7 @@ default value is @w{@code{" "}}, a string consisting of a single space. @cindex @code{ORS} variable @item ORS -This is the output record separator. It is output at the end of every +The output record separator. It is output at the end of every @code{print} statement. Its default value is @code{"\n"}, the newline character. (@xref{Output Separators}.) @@ -13878,14 +13856,13 @@ The working precision of arbitrary precision floating-point numbers, @item ROUNDMODE # The rounding mode to use for arbitrary precision arithmetic on numbers, by default @code{"N"} (@samp{roundTiesToEven} in -the IEEE-754 standard) -(@pxref{Setting Rounding Mode}). +the IEEE-754 standard; @pxref{Setting Rounding Mode}). @cindex @code{RS} variable @cindex separators, for records @cindex record separators -@item RS -This is @command{awk}'s input record separator. Its default value is a string +@item @code{RS} +The input record separator. Its default value is a string containing a single newline character, which means that an input record consists of a single line of text. It can also be the null string, in which case records are separated by @@ -13904,8 +13881,8 @@ just the first character of @code{RS}'s value is used. @cindex @code{SUBSEP} variable @cindex separators, subscript @cindex subscript separators -@item SUBSEP -This is the subscript separator. It has the default value of +@item @code{SUBSEP} +The subscript separator. It has the default value of @code{"\034"} and is used to separate the parts of the indices of a multidimensional array. Thus, the expression @code{@w{foo["A", "B"]}} really accesses @code{foo["A\034B"]} @@ -13916,18 +13893,12 @@ really accesses @code{foo["A\034B"]} @cindex differences in @command{awk} and @command{gawk}, @code{TEXTDOMAIN} variable @cindex internationalization, localization @item TEXTDOMAIN # -This variable is used for internationalization of programs at the +Used for internationalization of programs at the @command{awk} level. It sets the default text domain for specially marked string constants in the source text, as well as for the @code{dcgettext()}, @code{dcngettext()} and @code{bindtextdomain()} functions (@pxref{Internationalization}). The default value of @code{TEXTDOMAIN} is @code{"messages"}. - -This variable is a @command{gawk} extension. -In other @command{awk} implementations, -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. @end table @c ENDOFRANGE bvar @c ENDOFRANGE varb @@ -13943,8 +13914,12 @@ it is not special. @cindex variables, built-in, conveying information The following is an alphabetical list of variables that @command{awk} sets automatically on certain occasions in order to provide -information to your program. The variables that are specific to -@command{gawk} are marked with a pound sign@w{ (@samp{#}).} +information to your program. + +The variables that are specific to @command{gawk} are marked with a pound +sign (@samp{#}). These variables are @command{gawk} extensions. In other +@command{awk} implementations or if @command{gawk} is in compatibility +mode (@pxref{Options}), they are not special. @c @asis for docbook @table @asis @@ -13991,7 +13966,7 @@ about how @command{awk} uses these variables. @cindex @code{ARGIND} variable @cindex differences in @command{awk} and @command{gawk}, @code{ARGIND} variable -@item @code{ARGIND} # +@item @code{ARGIND #} The index in @code{ARGV} of the current file being processed. Every time @command{gawk} opens a new data file for processing, it sets @code{ARGIND} to the index in @code{ARGV} of the file name. @@ -14008,19 +13983,13 @@ While you can change the value of @code{ARGIND} within your @command{awk} program, @command{gawk} automatically sets it to a new value when the next file is opened. -This variable is a @command{gawk} extension. -In other @command{awk} implementations, -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. - @cindex @code{ENVIRON} array @cindex environment variables, in @code{ENVIRON} array @item @code{ENVIRON} An associative array containing the values of the environment. The array indices are the environment variable names; the elements are the values of the particular environment variables. For example, -@code{ENVIRON["HOME"]} might be @file{/home/arnold}. +@code{ENVIRON["HOME"]} might be @code{/home/arnold}. For POSIX @command{awk}, changing this array does not affect the environment passed on to any programs that @command{awk} may spawn via @@ -14035,59 +14004,45 @@ executable programs. Some operating systems may not have environment variables. On such systems, the @code{ENVIRON} array is empty (except for -@w{@code{ENVIRON["AWKPATH"]}}, -@pxref{AWKPATH Variable} and -@w{@code{ENVIRON["AWKLIBPATH"]}}, +@w{@code{ENVIRON["AWKPATH"]}} and +@w{@code{ENVIRON["AWKLIBPATH"]}}; +@pxref{AWKPATH Variable}, and @pxref{AWKLIBPATH Variable}). @cindex @command{gawk}, @code{ERRNO} variable in @cindex @code{ERRNO} variable @cindex differences in @command{awk} and @command{gawk}, @code{ERRNO} variable @cindex error handling, @code{ERRNO} variable and -@item @code{ERRNO} # -If a system error occurs during a redirection for @code{getline}, -during a read for @code{getline}, or during a @code{close()} operation, -then @code{ERRNO} contains a string describing the error. - -In addition, @command{gawk} clears @code{ERRNO} -before opening each command-line input file. This enables checking if -the file is readable inside a @code{BEGINFILE} pattern (@pxref{BEGINFILE/ENDFILE}). - -Otherwise, -@code{ERRNO} works similarly to the C variable @code{errno}. -Except for the case just mentioned, -@command{gawk} @emph{never} clears it (sets it -to zero or @code{""}). Thus, you should only expect its value -to be meaningful when an I/O operation returns a failure -value, such as @code{getline} returning @minus{}1. -You are, of course, free to clear it yourself before doing an -I/O operation. - -This variable is a @command{gawk} extension. -In other @command{awk} implementations, -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. +@item @code{ERRNO #} +If a system error occurs during a redirection for @code{getline}, during +a read for @code{getline}, or during a @code{close()} operation, then +@code{ERRNO} contains a string describing the error. + +In addition, @command{gawk} clears @code{ERRNO} before opening each +command-line input file. This enables checking if the file is readable +inside a @code{BEGINFILE} pattern (@pxref{BEGINFILE/ENDFILE}). + +Otherwise, @code{ERRNO} works similarly to the C variable @code{errno}. +Except for the case just mentioned, @command{gawk} @emph{never} clears +it (sets it to zero or @code{""}). Thus, you should only expect its +value to be meaningful when an I/O operation returns a failure value, +such as @code{getline} returning @minus{}1. You are, of course, free +to clear it yourself before doing an I/O operation. @cindex @code{FILENAME} variable @cindex dark corner, @code{FILENAME} variable @item @code{FILENAME} -The name of the file that @command{awk} is currently reading. -When no data files are listed on the command line, @command{awk} reads -from the standard input and @code{FILENAME} is set to @code{"-"}. -@code{FILENAME} is changed each time a new file is read -(@pxref{Reading Files}). -Inside a @code{BEGIN} rule, the value of @code{FILENAME} is -@code{""}, since there are no input files being processed -yet.@footnote{Some early implementations of Unix @command{awk} initialized -@code{FILENAME} to @code{"-"}, even if there were data files to be -processed. This behavior was incorrect and should not be relied -upon in your programs.} -@value{DARKCORNER} -Note, though, that using @code{getline} -(@pxref{Getline}) -inside a @code{BEGIN} rule can give -@code{FILENAME} a value. +The name of the current input file. When no data files are listed +on the command line, @command{awk} reads from the standard input and +@code{FILENAME} is set to @code{"-"}. @code{FILENAME} changes each +time a new file is read (@pxref{Reading Files}). Inside a @code{BEGIN} +rule, the value of @code{FILENAME} is @code{""}, since there are no input +files being processed yet.@footnote{Some early implementations of Unix +@command{awk} initialized @code{FILENAME} to @code{"-"}, even if there +were data files to be processed. This behavior was incorrect and should +not be relied upon in your programs.} @value{DARKCORNER} Note, though, +that using @code{getline} (@pxref{Getline}) inside a @code{BEGIN} rule +can give @code{FILENAME} a value. @cindex @code{FNR} variable @item @code{FNR} @@ -14111,14 +14066,14 @@ current record. @xref{Changing Fields}. @cindex @code{FUNCTAB} array @cindex @command{gawk}, @code{FUNCTAB} array in @cindex differences in @command{awk} and @command{gawk}, @code{FUNCTAB} variable -@item @code{FUNCTAB} # +@item @code{FUNCTAB #} An array whose indices and corresponding values are the names of all the user-defined or extension functions in the program. @quotation NOTE Attempting to use the @code{delete} statement with the @code{FUNCTAB} -array will cause a fatal error. Any attempt to assign to an element of -the @code{FUNCTAB} array will also cause a fatal error. +array causes a fatal error. Any attempt to assign to an element of +@code{FUNCTAB} also causes a fatal error. @end quotation @cindex @code{NR} variable @@ -14131,7 +14086,7 @@ the beginning of the program's execution @cindex @command{gawk}, @code{PROCINFO} array in @cindex @code{PROCINFO} array @cindex differences in @command{awk} and @command{gawk}, @code{PROCINFO} array -@item @code{PROCINFO} # +@item @code{PROCINFO #} The elements of this array provide access to information about the running @command{awk} program. The following elements (listed alphabetically) @@ -14200,7 +14155,7 @@ The parent process ID of the current process. @item PROCINFO["sorted_in"] If this element exists in @code{PROCINFO}, its value controls the order in which array indices will be processed by -@samp{for (index in array) @dots{}} loops. +@samp{for (@var{index} in @var{array})} loops. Since this is an advanced feature, we defer the full description until later; see @ref{Scanning an Array}. @@ -14270,10 +14225,9 @@ The @code{PROCINFO} array has the following additional uses: @itemize @bullet @item -It may be -used to cause coprocesses -to communicate over pseudo-ttys instead of through two-way pipes; -this is discussed further in @ref{Two-way I/O}. +It may be used to cause coprocesses to communicate over pseudo-ttys +instead of through two-way pipes; this is discussed further in +@ref{Two-way I/O}. @item It may be used to provide a timeout when reading from any @@ -14281,12 +14235,6 @@ open input file, pipe, or coprocess. @xref{Read Timeout}, for more information. @end itemize -This array is a @command{gawk} extension. -In other @command{awk} implementations, -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. - @cindex @code{RLENGTH} variable @item @code{RLENGTH} The length of the substring matched by the @@ -14307,20 +14255,14 @@ if no match was found. @cindex @command{gawk}, @code{RT} variable in @cindex @code{RT} variable @cindex differences in @command{awk} and @command{gawk}, @code{RT} variable -@item @code{RT} # -This is set each time a record is read. It contains the input text -that matched the text denoted by @code{RS}, the record separator. - -This variable is a @command{gawk} extension. -In other @command{awk} implementations, -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. +@item @code{RT #} +The input text that matched the text denoted by @code{RS}, +the record separator. It is set every time a record is read. @cindex @command{gawk}, @code{SYMTAB} array in @cindex @code{SYMTAB} array @cindex differences in @command{awk} and @command{gawk}, @code{SYMTAB} variable -@item @code{SYMTAB} # +@item @code{SYMTAB #} An array whose indices are the names of all currently defined global variables and arrays in the program. The array may be used for indirect access to read or write the value of a variable: @@ -14349,6 +14291,7 @@ This works as expected: in this case @code{SYMTAB} acts just like a regular array. The only difference is that you can't then delete @code{SYMTAB["xxx"]}. +@cindex Schorr, Andrew The @code{SYMTAB} array is more interesting than it looks. Andrew Schorr points out that it effectively gives @command{awk} data pointers. Consider his example: @@ -14363,8 +14306,8 @@ function multiply(variable, amount) @end example @quotation NOTE -In order to avoid severe time-travel paradoxes@footnote{Not to mention difficult -implementation issues.}, neither @code{FUNCTAB} nor @code{SYMTAB} +In order to avoid severe time-travel paradoxes,@footnote{Not to mention difficult +implementation issues.} neither @code{FUNCTAB} nor @code{SYMTAB} are available as elements within the @code{SYMTAB} array. @end quotation @end table @@ -14592,7 +14535,7 @@ It also describes how @command{awk} simulates multidimensional arrays, as well as some of the less obvious points about array usage. The @value{CHAPTER} moves on to discuss @command{gawk}'s facility for sorting arrays, and ends with a brief description of @command{gawk}'s -ability to support true multidimensional arrays. +ability to support true arrays of arrays. @cindex variables, names of @cindex functions, names of @@ -14676,35 +14619,32 @@ the array is declared.) A contiguous array of four elements might look like the following example, conceptually, if the element values are 8, @code{"foo"}, -@code{""}, and 30: +@code{""}, and 30 +@ifnotdocbook +as shown in @ref{figure-array-elements}: +@end ifnotdocbook +@ifdocbook +as shown in @inlineraw{docbook, <xref linkend="figure-array-elements"/>}: +@end ifdocbook -@c @strong{FIXME: NEXT ED:} Use real images here, and an @float -@iftex -@c from Karl Berry, much thanks for the help. -@tex -\bigskip % space above the table (about 1 linespace) -\offinterlineskip -\newdimen\width \width = 1.5cm -\newdimen\hwidth \hwidth = 4\width \advance\hwidth by 2pt % 5 * 0.4pt -\centerline{\vbox{ -\halign{\strut\hfil\ignorespaces#&&\vrule#&\hbox to\width{\hfil#\unskip\hfil}\cr -\noalign{\hrule width\hwidth} - &&{\tt 8} &&{\tt "foo"} &&{\tt ""} &&{\tt 30} &&\quad Value\cr -\noalign{\hrule width\hwidth} -\noalign{\smallskip} - &\omit&0&\omit &1 &\omit&2 &\omit&3 &\omit&\quad Index\cr -} -}} -@end tex -@end iftex -@ifnottex -@example -+---------+---------+--------+---------+ -| 8 | "foo" | "" | 30 | @r{Value} -+---------+---------+--------+---------+ - 0 1 2 3 @r{Index} -@end example -@end ifnottex +@ifnotdocbook +@float Figure,figure-array-elements +@caption{A Contiguous Array} +@ifinfo +@center @image{array-elements, , , Basic Program Stages, txt} +@end ifinfo +@ifnotinfo +@center @image{array-elements, , , Basic Program Stages} +@end ifnotinfo +@end float +@end ifnotdocbook + +@docbook +<figure id="figure-array-elements"> +<title>A Contiguous Array</title> +<graphic fileref="array-elements.eps"/> +</figure> +@end docbook @noindent Only the values are stored; the indices are implicit from the order of @@ -14721,12 +14661,53 @@ Arrays in @command{awk} are different---they are @dfn{associative}. This means that each array is a collection of pairs: an index and its corresponding array element value: +@ifnotdocbook @example @r{Index} 3 @r{Value} 30 @r{Index} 1 @r{Value} "foo" @r{Index} 0 @r{Value} 8 @r{Index} 2 @r{Value} "" @end example +@end ifnotdocbook + +@docbook +<informaltable> +<tgroup cols="2"> +<colspec colname="1" align="center"/> +<colspec colname="2" align="center"/> +<thead> +<row> +<entry>Index</entry> +<entry>Value</entry> +</row> +</thead> + +<tbody> +<row> +<entry><literal>3</literal></entry> +<entry><literal>30</literal></entry> +</row> + +<row> +<entry><literal>1</literal></entry> +<entry><literal>"foo"</literal></entry> +</row> + +<row> +<entry><literal>0</literal></entry> +<entry><literal>8</literal></entry> +</row> + +<row> +<entry><literal>2</literal></entry> +<entry><literal>""</literal></entry> +</row> + +</tbody> +</tgroup> +</informaltable> + +@end docbook @noindent The pairs are shown in jumbled order because their order is irrelevant. @@ -14735,6 +14716,7 @@ One advantage of associative arrays is that new pairs can be added at any time. For example, suppose a tenth element is added to the array whose value is @w{@code{"number ten"}}. The result is: +@ifnotdocbook @example @r{Index} 10 @r{Value} "number ten" @r{Index} 3 @r{Value} 30 @@ -14742,6 +14724,51 @@ whose value is @w{@code{"number ten"}}. The result is: @r{Index} 0 @r{Value} 8 @r{Index} 2 @r{Value} "" @end example +@end ifnotdocbook + +@docbook +<informaltable> +<tgroup cols="2"> +<colspec colname="1" align="center"/> +<colspec colname="2" align="center"/> +<thead> +<row> +<entry>Index</entry> +<entry>Value</entry> +</row> +</thead> +<tbody> + +<row> +<entry><literal>10</literal></entry> +<entry><literal>"number ten"</literal></entry> +</row> + +<row> +<entry><literal>3</literal></entry> +<entry><literal>30</literal></entry> +</row> + +<row> +<entry><literal>1</literal></entry> +<entry><literal>"foo"</literal></entry> +</row> + +<row> +<entry><literal>0</literal></entry> +<entry><literal>8</literal></entry> +</row> + +<row> +<entry><literal>2</literal></entry> +<entry><literal>""</literal></entry> +</row> + +</tbody> +</tgroup> +</informaltable> + +@end docbook @noindent @cindex sparse arrays @@ -14754,20 +14781,60 @@ have to be positive integers. Any number, or even a string, can be an index. For example, the following is an array that translates words from English to French: +@ifnotdocbook @example @r{Index} "dog" @r{Value} "chien" @r{Index} "cat" @r{Value} "chat" @r{Index} "one" @r{Value} "un" @r{Index} 1 @r{Value} "un" @end example +@end ifnotdocbook + +@docbook +<informaltable> +<tgroup cols="2"> +<colspec colname="1" align="center"/> +<colspec colname="2" align="center"/> +<thead> +<row> +<entry>Index</entry> +<entry>Value</entry> +</row> +</thead> +<tbody> +<row> +<entry><literal>"dog"</literal></entry> +<entry><literal>"chien"</literal></entry> +</row> + +<row> +<entry><literal>"cat"</literal></entry> +<entry><literal>"chat"</literal></entry> +</row> + +<row> +<entry><literal>"one"</literal></entry> +<entry><literal>"un"</literal></entry> +</row> + +<row> +<entry><literal>1</literal></entry> +<entry><literal>"un"</literal></entry> +</row> + +</tbody> +</tgroup> +</informaltable> + +@end docbook @noindent Here we decided to translate the number one in both spelled-out and numeric form---thus illustrating that a single array can have both numbers and strings as indices. -In fact, array subscripts are always strings; this is discussed +(In fact, array subscripts are always strings; this is discussed in more detail in -@ref{Numeric Array Subscripts}. +@ref{Numeric Array Subscripts}.) Here, the number @code{1} isn't double-quoted, since @command{awk} automatically converts it to a string. @@ -14843,14 +14910,14 @@ To determine whether an element exists in an array at a certain index, use the following expression: @example -@var{ind} in @var{array} +@var{indx} in @var{array} @end example @cindex side effects, array indexing @noindent -This expression tests whether the particular index @var{ind} exists, +This expression tests whether the particular index @var{indx} exists, without the side effect of creating that element if it is not present. -The expression has the value one (true) if @code{@var{array}[@var{ind}]} +The expression has the value one (true) if @code{@var{array}[@var{indx}]} exists and zero (false) if it does not exist. For example, this statement tests whether the array @code{frequencies} contains the index @samp{2}: @@ -15024,14 +15091,56 @@ for a more detailed example of this type. @cindex @code{in} operator, order of array access The order in which elements of the array are accessed by this statement is determined by the internal arrangement of the array elements within -@command{awk} and normally cannot be controlled or changed. This can lead to -problems if new elements are added to @var{array} by statements in -the loop body; it is not predictable whether the @code{for} loop will -reach them. Similarly, changing @var{var} inside the loop may produce -strange results. It is best to avoid such things. +@command{awk} and in standard @command{awk} cannot be controlled +or changed. This can lead to problems if new elements are added to +@var{array} by statements in the loop body; it is not predictable whether +the @code{for} loop will reach them. Similarly, changing @var{var} inside +the loop may produce strange results. It is best to avoid such things. + +As a point of information, @command{gawk} sets up the list of elements +to be iterated over before the loop starts, and does not change it. +But not all @command{awk} versions do so. Consider this program, named +@file{loopcheck.awk}: + +@example +BEGIN @{ + a["here"] = "here" + a["is"] = "is" + a["a"] = "a" + a["loop"] = "loop" + for (i in a) @{ + j++ + a[j] = j + print i + @} +@} +@end example + +Here is what happens when run with @command{gawk}: + +@example +$ @kbd{gawk -f loopcheck.awk} +@print{} here +@print{} loop +@print{} a +@print{} is +@end example + +Contrast this to Brian Kernighan's @command{awk}: + +@example +$ @kbd{nawk -f loopcheck.awk} +@print{} loop +@print{} here +@print{} is +@print{} a +@print{} 1 +@end example @node Controlling Scanning -@subsection Using Predefined Array Scanning Orders +@subsection Using Predefined Array Scanning Orders With @command{gawk} + +This @value{SUBSECTION} describes a feature that is specific to @command{gawk}. By default, when a @code{for} loop traverses an array, the order is undefined, meaning that the @command{awk} implementation @@ -15385,7 +15494,7 @@ $ @kbd{echo 'line 1} @print{} line 2 @end example -Unfortunately, the very first line of input data did not come out in the +Unfortunately, the very first line of input data did not appear in the output! Upon first glance, we would think that this program should have worked. @@ -15583,7 +15692,7 @@ separate indices is recovered. array access and provides true arrays of arrays. Elements of a subarray are referred to by their own indices enclosed in square brackets, just like the elements of the main array. -For example, the following creates a two-element subarray at index @samp{1} +For example, the following creates a two-element subarray at index @code{1} of the main array @code{a}: @example @@ -15607,7 +15716,7 @@ Each subarray and the main array can be of different length. In fact, the elements of an array or its subarray do not all have to have the same type. This means that the main array and any of its subarrays can be non-rectangular, or jagged in structure. One can assign a scalar value to -the index @samp{4} of the main array @code{a}: +the index @code{4} of the main array @code{a}: @example a[4] = "An element in a jagged array" @@ -15628,7 +15737,7 @@ a[4][5][6][7] = "An element in a four-dimensional array" @end example @noindent -This removes the scalar value from index @samp{4} and then inserts a +This removes the scalar value from index @code{4} and then inserts a subarray of subarray of subarray containing a scalar. You can also delete an entire subarray or subarray of subarrays: @@ -37953,7 +38062,7 @@ of the following, very basic set of steps, as shown in @ref{figure-process-flow}: @end ifnotdocbook @ifdocbook -as shown in @inlineraw{docbook <xref linkend="figure-process-flow"/>}: +as shown in @inlineraw{docbook, <xref linkend="figure-process-flow"/>}: @end ifdocbook @ifnotdocbook @@ -40299,4 +40408,5 @@ which sorta sucks. TODO: ----- -2. Add back in docbook fixes for @r{}. +3. Check all docbook figures, if they should include with a +specific extension or not. diff --git a/doc/gawktexi.in b/doc/gawktexi.in index ac3d0afe..43bc36b1 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -13037,9 +13037,9 @@ automatically by @command{awk}, so that they carry information from the internal workings of @command{awk} to your program. @cindex @command{gawk}, built-in variables and -This @value{SECTION} documents all the built-in variables of -@command{gawk}, most of which are also documented in the chapters -describing their areas of activity. +This @value{SECTION} documents all of @command{gawk}'s built-in variables, +most of which are also documented in the @value{CHAPTER}s describing +their areas of activity. @menu * User-modified:: Built-in variables that you change to control @@ -13057,44 +13057,38 @@ describing their areas of activity. @cindex user-modifiable variables The following is an alphabetical list of variables that you can change to -control how @command{awk} does certain things. The variables that are -specific to @command{gawk} are marked with a pound sign@w{ (@samp{#}).} +control how @command{awk} does certain things. + +The variables that are specific to @command{gawk} are marked with a pound +sign (@samp{#}). These variables are @command{gawk} extensions. In other +@command{awk} implementations or if @command{gawk} is in compatibility +mode (@pxref{Options}), they are not special. (Any exceptions are noted +in the description of each variable.) @table @code @cindex @code{BINMODE} variable @cindex binary input/output @cindex input/output, binary -@item BINMODE # -On non-POSIX systems, this variable specifies use of binary mode for all I/O. -Numeric values of one, two, or three specify that input files, output files, or -all files, respectively, should use binary I/O. -A numeric value less than zero is treated as zero, and a numeric value greater than -three is treated as three. -Alternatively, -string values of @code{"r"} or @code{"w"} specify that input files and -output files, respectively, should use binary I/O. -A string value of @code{"rw"} or @code{"wr"} indicates that all -files should use binary I/O. -Any other string value is treated the same as @code{"rw"}, -but causes @command{gawk} -to generate a warning message. -@code{BINMODE} is described in more detail in -@ref{PC Using}. - @cindex differences in @command{awk} and @command{gawk}, @code{BINMODE} variable -This variable is a @command{gawk} extension. -In other @command{awk} implementations -(except @command{mawk}, -@pxref{Other Versions}), -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. +@item BINMODE # +On non-POSIX systems, this variable specifies use of binary mode +for all I/O. Numeric values of one, two, or three specify that input +files, output files, or all files, respectively, should use binary I/O. +A numeric value less than zero is treated as zero, and a numeric value +greater than three is treated as three. Alternatively, string values +of @code{"r"} or @code{"w"} specify that input files and output files, +respectively, should use binary I/O. A string value of @code{"rw"} or +@code{"wr"} indicates that all files should use binary I/O. Any other +string value is treated the same as @code{"rw"}, but causes @command{gawk} +to generate a warning message. @code{BINMODE} is described in more +detail in @ref{PC Using}. @command{mawk} @pxref{Other Versions}), +also supports this variable, but only using numeric values. @cindex @code{CONVFMT} variable @cindex POSIX @command{awk}, @code{CONVFMT} variable and @cindex numbers, converting, to strings @cindex strings, converting, numbers to -@item CONVFMT +@item @code{CONVFMT} This string controls conversion of numbers to strings (@pxref{Conversion}). It works by being passed, in effect, as the first argument to the @@ -13109,40 +13103,29 @@ Its default value is @code{"%.6g"}. @cindex field separators, @code{FIELDWIDTHS} variable and @cindex separators, field, @code{FIELDWIDTHS} variable and @item FIELDWIDTHS # -This is a space-separated list of columns that tells @command{gawk} +A space-separated list of columns that tells @command{gawk} how to split input with fixed columnar boundaries. Assigning a value to @code{FIELDWIDTHS} overrides the use of @code{FS} and @code{FPAT} for field splitting. @xref{Constant Size}, for more information. -If @command{gawk} is in compatibility mode -(@pxref{Options}), then @code{FIELDWIDTHS} -has no special meaning, and field-splitting operations occur based -exclusively on the value of @code{FS}. - @cindex @command{gawk}, @code{FPAT} variable in @cindex @code{FPAT} variable @cindex differences in @command{awk} and @command{gawk}, @code{FPAT} variable @cindex field separators, @code{FPAT} variable and @cindex separators, field, @code{FPAT} variable and @item FPAT # -This is a regular expression (as a string) that tells @command{gawk} +A regular expression (as a string) that tells @command{gawk} to create the fields based on text that matches the regular expression. Assigning a value to @code{FPAT} overrides the use of @code{FS} and @code{FIELDWIDTHS} for field splitting. @xref{Splitting By Content}, for more information. -If @command{gawk} is in compatibility mode -(@pxref{Options}), then @code{FPAT} -has no special meaning, and field-splitting operations occur based -exclusively on the value of @code{FS}. - @cindex @code{FS} variable @cindex separators, field @cindex field separators @item FS -This is the input field separator -(@pxref{Field Separators}). +The input field separator (@pxref{Field Separators}). The value is a single-character string or a multicharacter regular expression that matches the separations between fields in an input record. If the value is the null string (@code{""}), then each @@ -13192,18 +13175,13 @@ and it does not affect field splitting when using a single-character field separator. @xref{Case-sensitivity}. -If @command{gawk} is in compatibility mode -(@pxref{Options}), -then @code{IGNORECASE} has no special meaning. Thus, string -and regexp operations are always case-sensitive. - @cindex @command{gawk}, @code{LINT} variable in @cindex @code{LINT} variable @cindex differences in @command{awk} and @command{gawk}, @code{LINT} variable @cindex lint checking @item LINT # When this variable is true (nonzero or non-null), @command{gawk} -behaves as if the @option{--lint} command-line option is in effect. +behaves as if the @option{--lint} command-line option is in effect (@pxref{Options}). With a value of @code{"fatal"}, lint warnings become fatal errors. With a value of @code{"invalid"}, only warnings about things that are @@ -13224,7 +13202,7 @@ of @command{awk} being executed. @cindex numbers, converting, to strings @cindex strings, converting, numbers to @item OFMT -This string controls conversion of numbers to +Controls conversion of numbers to strings (@pxref{Conversion}) for printing with the @code{print} statement. It works by being passed as the first argument to the @code{sprintf()} function @@ -13245,7 +13223,7 @@ default value is @w{@code{" "}}, a string consisting of a single space. @cindex @code{ORS} variable @item ORS -This is the output record separator. It is output at the end of every +The output record separator. It is output at the end of every @code{print} statement. Its default value is @code{"\n"}, the newline character. (@xref{Output Separators}.) @@ -13258,14 +13236,13 @@ The working precision of arbitrary precision floating-point numbers, @item ROUNDMODE # The rounding mode to use for arbitrary precision arithmetic on numbers, by default @code{"N"} (@samp{roundTiesToEven} in -the IEEE-754 standard) -(@pxref{Setting Rounding Mode}). +the IEEE-754 standard; @pxref{Setting Rounding Mode}). @cindex @code{RS} variable @cindex separators, for records @cindex record separators -@item RS -This is @command{awk}'s input record separator. Its default value is a string +@item @code{RS} +The input record separator. Its default value is a string containing a single newline character, which means that an input record consists of a single line of text. It can also be the null string, in which case records are separated by @@ -13284,8 +13261,8 @@ just the first character of @code{RS}'s value is used. @cindex @code{SUBSEP} variable @cindex separators, subscript @cindex subscript separators -@item SUBSEP -This is the subscript separator. It has the default value of +@item @code{SUBSEP} +The subscript separator. It has the default value of @code{"\034"} and is used to separate the parts of the indices of a multidimensional array. Thus, the expression @code{@w{foo["A", "B"]}} really accesses @code{foo["A\034B"]} @@ -13296,18 +13273,12 @@ really accesses @code{foo["A\034B"]} @cindex differences in @command{awk} and @command{gawk}, @code{TEXTDOMAIN} variable @cindex internationalization, localization @item TEXTDOMAIN # -This variable is used for internationalization of programs at the +Used for internationalization of programs at the @command{awk} level. It sets the default text domain for specially marked string constants in the source text, as well as for the @code{dcgettext()}, @code{dcngettext()} and @code{bindtextdomain()} functions (@pxref{Internationalization}). The default value of @code{TEXTDOMAIN} is @code{"messages"}. - -This variable is a @command{gawk} extension. -In other @command{awk} implementations, -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. @end table @c ENDOFRANGE bvar @c ENDOFRANGE varb @@ -13323,8 +13294,12 @@ it is not special. @cindex variables, built-in, conveying information The following is an alphabetical list of variables that @command{awk} sets automatically on certain occasions in order to provide -information to your program. The variables that are specific to -@command{gawk} are marked with a pound sign@w{ (@samp{#}).} +information to your program. + +The variables that are specific to @command{gawk} are marked with a pound +sign (@samp{#}). These variables are @command{gawk} extensions. In other +@command{awk} implementations or if @command{gawk} is in compatibility +mode (@pxref{Options}), they are not special. @c @asis for docbook @table @asis @@ -13371,7 +13346,7 @@ about how @command{awk} uses these variables. @cindex @code{ARGIND} variable @cindex differences in @command{awk} and @command{gawk}, @code{ARGIND} variable -@item @code{ARGIND} # +@item @code{ARGIND #} The index in @code{ARGV} of the current file being processed. Every time @command{gawk} opens a new data file for processing, it sets @code{ARGIND} to the index in @code{ARGV} of the file name. @@ -13388,19 +13363,13 @@ While you can change the value of @code{ARGIND} within your @command{awk} program, @command{gawk} automatically sets it to a new value when the next file is opened. -This variable is a @command{gawk} extension. -In other @command{awk} implementations, -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. - @cindex @code{ENVIRON} array @cindex environment variables, in @code{ENVIRON} array @item @code{ENVIRON} An associative array containing the values of the environment. The array indices are the environment variable names; the elements are the values of the particular environment variables. For example, -@code{ENVIRON["HOME"]} might be @file{/home/arnold}. +@code{ENVIRON["HOME"]} might be @code{/home/arnold}. For POSIX @command{awk}, changing this array does not affect the environment passed on to any programs that @command{awk} may spawn via @@ -13415,59 +13384,45 @@ executable programs. Some operating systems may not have environment variables. On such systems, the @code{ENVIRON} array is empty (except for -@w{@code{ENVIRON["AWKPATH"]}}, -@pxref{AWKPATH Variable} and -@w{@code{ENVIRON["AWKLIBPATH"]}}, +@w{@code{ENVIRON["AWKPATH"]}} and +@w{@code{ENVIRON["AWKLIBPATH"]}}; +@pxref{AWKPATH Variable}, and @pxref{AWKLIBPATH Variable}). @cindex @command{gawk}, @code{ERRNO} variable in @cindex @code{ERRNO} variable @cindex differences in @command{awk} and @command{gawk}, @code{ERRNO} variable @cindex error handling, @code{ERRNO} variable and -@item @code{ERRNO} # -If a system error occurs during a redirection for @code{getline}, -during a read for @code{getline}, or during a @code{close()} operation, -then @code{ERRNO} contains a string describing the error. - -In addition, @command{gawk} clears @code{ERRNO} -before opening each command-line input file. This enables checking if -the file is readable inside a @code{BEGINFILE} pattern (@pxref{BEGINFILE/ENDFILE}). - -Otherwise, -@code{ERRNO} works similarly to the C variable @code{errno}. -Except for the case just mentioned, -@command{gawk} @emph{never} clears it (sets it -to zero or @code{""}). Thus, you should only expect its value -to be meaningful when an I/O operation returns a failure -value, such as @code{getline} returning @minus{}1. -You are, of course, free to clear it yourself before doing an -I/O operation. - -This variable is a @command{gawk} extension. -In other @command{awk} implementations, -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. +@item @code{ERRNO #} +If a system error occurs during a redirection for @code{getline}, during +a read for @code{getline}, or during a @code{close()} operation, then +@code{ERRNO} contains a string describing the error. + +In addition, @command{gawk} clears @code{ERRNO} before opening each +command-line input file. This enables checking if the file is readable +inside a @code{BEGINFILE} pattern (@pxref{BEGINFILE/ENDFILE}). + +Otherwise, @code{ERRNO} works similarly to the C variable @code{errno}. +Except for the case just mentioned, @command{gawk} @emph{never} clears +it (sets it to zero or @code{""}). Thus, you should only expect its +value to be meaningful when an I/O operation returns a failure value, +such as @code{getline} returning @minus{}1. You are, of course, free +to clear it yourself before doing an I/O operation. @cindex @code{FILENAME} variable @cindex dark corner, @code{FILENAME} variable @item @code{FILENAME} -The name of the file that @command{awk} is currently reading. -When no data files are listed on the command line, @command{awk} reads -from the standard input and @code{FILENAME} is set to @code{"-"}. -@code{FILENAME} is changed each time a new file is read -(@pxref{Reading Files}). -Inside a @code{BEGIN} rule, the value of @code{FILENAME} is -@code{""}, since there are no input files being processed -yet.@footnote{Some early implementations of Unix @command{awk} initialized -@code{FILENAME} to @code{"-"}, even if there were data files to be -processed. This behavior was incorrect and should not be relied -upon in your programs.} -@value{DARKCORNER} -Note, though, that using @code{getline} -(@pxref{Getline}) -inside a @code{BEGIN} rule can give -@code{FILENAME} a value. +The name of the current input file. When no data files are listed +on the command line, @command{awk} reads from the standard input and +@code{FILENAME} is set to @code{"-"}. @code{FILENAME} changes each +time a new file is read (@pxref{Reading Files}). Inside a @code{BEGIN} +rule, the value of @code{FILENAME} is @code{""}, since there are no input +files being processed yet.@footnote{Some early implementations of Unix +@command{awk} initialized @code{FILENAME} to @code{"-"}, even if there +were data files to be processed. This behavior was incorrect and should +not be relied upon in your programs.} @value{DARKCORNER} Note, though, +that using @code{getline} (@pxref{Getline}) inside a @code{BEGIN} rule +can give @code{FILENAME} a value. @cindex @code{FNR} variable @item @code{FNR} @@ -13491,14 +13446,14 @@ current record. @xref{Changing Fields}. @cindex @code{FUNCTAB} array @cindex @command{gawk}, @code{FUNCTAB} array in @cindex differences in @command{awk} and @command{gawk}, @code{FUNCTAB} variable -@item @code{FUNCTAB} # +@item @code{FUNCTAB #} An array whose indices and corresponding values are the names of all the user-defined or extension functions in the program. @quotation NOTE Attempting to use the @code{delete} statement with the @code{FUNCTAB} -array will cause a fatal error. Any attempt to assign to an element of -the @code{FUNCTAB} array will also cause a fatal error. +array causes a fatal error. Any attempt to assign to an element of +@code{FUNCTAB} also causes a fatal error. @end quotation @cindex @code{NR} variable @@ -13511,7 +13466,7 @@ the beginning of the program's execution @cindex @command{gawk}, @code{PROCINFO} array in @cindex @code{PROCINFO} array @cindex differences in @command{awk} and @command{gawk}, @code{PROCINFO} array -@item @code{PROCINFO} # +@item @code{PROCINFO #} The elements of this array provide access to information about the running @command{awk} program. The following elements (listed alphabetically) @@ -13580,7 +13535,7 @@ The parent process ID of the current process. @item PROCINFO["sorted_in"] If this element exists in @code{PROCINFO}, its value controls the order in which array indices will be processed by -@samp{for (index in array) @dots{}} loops. +@samp{for (@var{index} in @var{array})} loops. Since this is an advanced feature, we defer the full description until later; see @ref{Scanning an Array}. @@ -13650,10 +13605,9 @@ The @code{PROCINFO} array has the following additional uses: @itemize @bullet @item -It may be -used to cause coprocesses -to communicate over pseudo-ttys instead of through two-way pipes; -this is discussed further in @ref{Two-way I/O}. +It may be used to cause coprocesses to communicate over pseudo-ttys +instead of through two-way pipes; this is discussed further in +@ref{Two-way I/O}. @item It may be used to provide a timeout when reading from any @@ -13661,12 +13615,6 @@ open input file, pipe, or coprocess. @xref{Read Timeout}, for more information. @end itemize -This array is a @command{gawk} extension. -In other @command{awk} implementations, -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. - @cindex @code{RLENGTH} variable @item @code{RLENGTH} The length of the substring matched by the @@ -13687,20 +13635,14 @@ if no match was found. @cindex @command{gawk}, @code{RT} variable in @cindex @code{RT} variable @cindex differences in @command{awk} and @command{gawk}, @code{RT} variable -@item @code{RT} # -This is set each time a record is read. It contains the input text -that matched the text denoted by @code{RS}, the record separator. - -This variable is a @command{gawk} extension. -In other @command{awk} implementations, -or if @command{gawk} is in compatibility mode -(@pxref{Options}), -it is not special. +@item @code{RT #} +The input text that matched the text denoted by @code{RS}, +the record separator. It is set every time a record is read. @cindex @command{gawk}, @code{SYMTAB} array in @cindex @code{SYMTAB} array @cindex differences in @command{awk} and @command{gawk}, @code{SYMTAB} variable -@item @code{SYMTAB} # +@item @code{SYMTAB #} An array whose indices are the names of all currently defined global variables and arrays in the program. The array may be used for indirect access to read or write the value of a variable: @@ -13729,6 +13671,7 @@ This works as expected: in this case @code{SYMTAB} acts just like a regular array. The only difference is that you can't then delete @code{SYMTAB["xxx"]}. +@cindex Schorr, Andrew The @code{SYMTAB} array is more interesting than it looks. Andrew Schorr points out that it effectively gives @command{awk} data pointers. Consider his example: @@ -13743,8 +13686,8 @@ function multiply(variable, amount) @end example @quotation NOTE -In order to avoid severe time-travel paradoxes@footnote{Not to mention difficult -implementation issues.}, neither @code{FUNCTAB} nor @code{SYMTAB} +In order to avoid severe time-travel paradoxes,@footnote{Not to mention difficult +implementation issues.} neither @code{FUNCTAB} nor @code{SYMTAB} are available as elements within the @code{SYMTAB} array. @end quotation @end table @@ -13926,7 +13869,7 @@ It also describes how @command{awk} simulates multidimensional arrays, as well as some of the less obvious points about array usage. The @value{CHAPTER} moves on to discuss @command{gawk}'s facility for sorting arrays, and ends with a brief description of @command{gawk}'s -ability to support true multidimensional arrays. +ability to support true arrays of arrays. @cindex variables, names of @cindex functions, names of @@ -14010,35 +13953,32 @@ the array is declared.) A contiguous array of four elements might look like the following example, conceptually, if the element values are 8, @code{"foo"}, -@code{""}, and 30: +@code{""}, and 30 +@ifnotdocbook +as shown in @ref{figure-array-elements}: +@end ifnotdocbook +@ifdocbook +as shown in @inlineraw{docbook, <xref linkend="figure-array-elements"/>}: +@end ifdocbook -@c @strong{FIXME: NEXT ED:} Use real images here, and an @float -@iftex -@c from Karl Berry, much thanks for the help. -@tex -\bigskip % space above the table (about 1 linespace) -\offinterlineskip -\newdimen\width \width = 1.5cm -\newdimen\hwidth \hwidth = 4\width \advance\hwidth by 2pt % 5 * 0.4pt -\centerline{\vbox{ -\halign{\strut\hfil\ignorespaces#&&\vrule#&\hbox to\width{\hfil#\unskip\hfil}\cr -\noalign{\hrule width\hwidth} - &&{\tt 8} &&{\tt "foo"} &&{\tt ""} &&{\tt 30} &&\quad Value\cr -\noalign{\hrule width\hwidth} -\noalign{\smallskip} - &\omit&0&\omit &1 &\omit&2 &\omit&3 &\omit&\quad Index\cr -} -}} -@end tex -@end iftex -@ifnottex -@example -+---------+---------+--------+---------+ -| 8 | "foo" | "" | 30 | @r{Value} -+---------+---------+--------+---------+ - 0 1 2 3 @r{Index} -@end example -@end ifnottex +@ifnotdocbook +@float Figure,figure-array-elements +@caption{A Contiguous Array} +@ifinfo +@center @image{array-elements, , , Basic Program Stages, txt} +@end ifinfo +@ifnotinfo +@center @image{array-elements, , , Basic Program Stages} +@end ifnotinfo +@end float +@end ifnotdocbook + +@docbook +<figure id="figure-array-elements"> +<title>A Contiguous Array</title> +<graphic fileref="array-elements.eps"/> +</figure> +@end docbook @noindent Only the values are stored; the indices are implicit from the order of @@ -14055,12 +13995,53 @@ Arrays in @command{awk} are different---they are @dfn{associative}. This means that each array is a collection of pairs: an index and its corresponding array element value: +@ifnotdocbook @example @r{Index} 3 @r{Value} 30 @r{Index} 1 @r{Value} "foo" @r{Index} 0 @r{Value} 8 @r{Index} 2 @r{Value} "" @end example +@end ifnotdocbook + +@docbook +<informaltable> +<tgroup cols="2"> +<colspec colname="1" align="center"/> +<colspec colname="2" align="center"/> +<thead> +<row> +<entry>Index</entry> +<entry>Value</entry> +</row> +</thead> + +<tbody> +<row> +<entry><literal>3</literal></entry> +<entry><literal>30</literal></entry> +</row> + +<row> +<entry><literal>1</literal></entry> +<entry><literal>"foo"</literal></entry> +</row> + +<row> +<entry><literal>0</literal></entry> +<entry><literal>8</literal></entry> +</row> + +<row> +<entry><literal>2</literal></entry> +<entry><literal>""</literal></entry> +</row> + +</tbody> +</tgroup> +</informaltable> + +@end docbook @noindent The pairs are shown in jumbled order because their order is irrelevant. @@ -14069,6 +14050,7 @@ One advantage of associative arrays is that new pairs can be added at any time. For example, suppose a tenth element is added to the array whose value is @w{@code{"number ten"}}. The result is: +@ifnotdocbook @example @r{Index} 10 @r{Value} "number ten" @r{Index} 3 @r{Value} 30 @@ -14076,6 +14058,51 @@ whose value is @w{@code{"number ten"}}. The result is: @r{Index} 0 @r{Value} 8 @r{Index} 2 @r{Value} "" @end example +@end ifnotdocbook + +@docbook +<informaltable> +<tgroup cols="2"> +<colspec colname="1" align="center"/> +<colspec colname="2" align="center"/> +<thead> +<row> +<entry>Index</entry> +<entry>Value</entry> +</row> +</thead> +<tbody> + +<row> +<entry><literal>10</literal></entry> +<entry><literal>"number ten"</literal></entry> +</row> + +<row> +<entry><literal>3</literal></entry> +<entry><literal>30</literal></entry> +</row> + +<row> +<entry><literal>1</literal></entry> +<entry><literal>"foo"</literal></entry> +</row> + +<row> +<entry><literal>0</literal></entry> +<entry><literal>8</literal></entry> +</row> + +<row> +<entry><literal>2</literal></entry> +<entry><literal>""</literal></entry> +</row> + +</tbody> +</tgroup> +</informaltable> + +@end docbook @noindent @cindex sparse arrays @@ -14088,20 +14115,60 @@ have to be positive integers. Any number, or even a string, can be an index. For example, the following is an array that translates words from English to French: +@ifnotdocbook @example @r{Index} "dog" @r{Value} "chien" @r{Index} "cat" @r{Value} "chat" @r{Index} "one" @r{Value} "un" @r{Index} 1 @r{Value} "un" @end example +@end ifnotdocbook + +@docbook +<informaltable> +<tgroup cols="2"> +<colspec colname="1" align="center"/> +<colspec colname="2" align="center"/> +<thead> +<row> +<entry>Index</entry> +<entry>Value</entry> +</row> +</thead> +<tbody> +<row> +<entry><literal>"dog"</literal></entry> +<entry><literal>"chien"</literal></entry> +</row> + +<row> +<entry><literal>"cat"</literal></entry> +<entry><literal>"chat"</literal></entry> +</row> + +<row> +<entry><literal>"one"</literal></entry> +<entry><literal>"un"</literal></entry> +</row> + +<row> +<entry><literal>1</literal></entry> +<entry><literal>"un"</literal></entry> +</row> + +</tbody> +</tgroup> +</informaltable> + +@end docbook @noindent Here we decided to translate the number one in both spelled-out and numeric form---thus illustrating that a single array can have both numbers and strings as indices. -In fact, array subscripts are always strings; this is discussed +(In fact, array subscripts are always strings; this is discussed in more detail in -@ref{Numeric Array Subscripts}. +@ref{Numeric Array Subscripts}.) Here, the number @code{1} isn't double-quoted, since @command{awk} automatically converts it to a string. @@ -14177,14 +14244,14 @@ To determine whether an element exists in an array at a certain index, use the following expression: @example -@var{ind} in @var{array} +@var{indx} in @var{array} @end example @cindex side effects, array indexing @noindent -This expression tests whether the particular index @var{ind} exists, +This expression tests whether the particular index @var{indx} exists, without the side effect of creating that element if it is not present. -The expression has the value one (true) if @code{@var{array}[@var{ind}]} +The expression has the value one (true) if @code{@var{array}[@var{indx}]} exists and zero (false) if it does not exist. For example, this statement tests whether the array @code{frequencies} contains the index @samp{2}: @@ -14358,14 +14425,56 @@ for a more detailed example of this type. @cindex @code{in} operator, order of array access The order in which elements of the array are accessed by this statement is determined by the internal arrangement of the array elements within -@command{awk} and normally cannot be controlled or changed. This can lead to -problems if new elements are added to @var{array} by statements in -the loop body; it is not predictable whether the @code{for} loop will -reach them. Similarly, changing @var{var} inside the loop may produce -strange results. It is best to avoid such things. +@command{awk} and in standard @command{awk} cannot be controlled +or changed. This can lead to problems if new elements are added to +@var{array} by statements in the loop body; it is not predictable whether +the @code{for} loop will reach them. Similarly, changing @var{var} inside +the loop may produce strange results. It is best to avoid such things. + +As a point of information, @command{gawk} sets up the list of elements +to be iterated over before the loop starts, and does not change it. +But not all @command{awk} versions do so. Consider this program, named +@file{loopcheck.awk}: + +@example +BEGIN @{ + a["here"] = "here" + a["is"] = "is" + a["a"] = "a" + a["loop"] = "loop" + for (i in a) @{ + j++ + a[j] = j + print i + @} +@} +@end example + +Here is what happens when run with @command{gawk}: + +@example +$ @kbd{gawk -f loopcheck.awk} +@print{} here +@print{} loop +@print{} a +@print{} is +@end example + +Contrast this to Brian Kernighan's @command{awk}: + +@example +$ @kbd{nawk -f loopcheck.awk} +@print{} loop +@print{} here +@print{} is +@print{} a +@print{} 1 +@end example @node Controlling Scanning -@subsection Using Predefined Array Scanning Orders +@subsection Using Predefined Array Scanning Orders With @command{gawk} + +This @value{SUBSECTION} describes a feature that is specific to @command{gawk}. By default, when a @code{for} loop traverses an array, the order is undefined, meaning that the @command{awk} implementation @@ -14719,7 +14828,7 @@ $ @kbd{echo 'line 1} @print{} line 2 @end example -Unfortunately, the very first line of input data did not come out in the +Unfortunately, the very first line of input data did not appear in the output! Upon first glance, we would think that this program should have worked. @@ -14917,7 +15026,7 @@ separate indices is recovered. array access and provides true arrays of arrays. Elements of a subarray are referred to by their own indices enclosed in square brackets, just like the elements of the main array. -For example, the following creates a two-element subarray at index @samp{1} +For example, the following creates a two-element subarray at index @code{1} of the main array @code{a}: @example @@ -14941,7 +15050,7 @@ Each subarray and the main array can be of different length. In fact, the elements of an array or its subarray do not all have to have the same type. This means that the main array and any of its subarrays can be non-rectangular, or jagged in structure. One can assign a scalar value to -the index @samp{4} of the main array @code{a}: +the index @code{4} of the main array @code{a}: @example a[4] = "An element in a jagged array" @@ -14962,7 +15071,7 @@ a[4][5][6][7] = "An element in a four-dimensional array" @end example @noindent -This removes the scalar value from index @samp{4} and then inserts a +This removes the scalar value from index @code{4} and then inserts a subarray of subarray of subarray containing a scalar. You can also delete an entire subarray or subarray of subarrays: @@ -37097,7 +37206,7 @@ of the following, very basic set of steps, as shown in @ref{figure-process-flow}: @end ifnotdocbook @ifdocbook -as shown in @inlineraw{docbook <xref linkend="figure-process-flow"/>}: +as shown in @inlineraw{docbook, <xref linkend="figure-process-flow"/>}: @end ifdocbook @ifnotdocbook @@ -39443,4 +39552,5 @@ which sorta sucks. TODO: ----- -2. Add back in docbook fixes for @r{}. +3. Check all docbook figures, if they should include with a +specific extension or not. |
