[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, master, updated. 963bfd011dffc072a3fdc63
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, master, updated. 963bfd011dffc072a3fdc63b74910679d6660f50 |
|
Date: |
Sun, 24 Apr 2011 10:03:46 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, master has been updated
via 963bfd011dffc072a3fdc63b74910679d6660f50 (commit)
from 8eb45b02e704c95866970005fe771e3507fb935c (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=963bfd011dffc072a3fdc63b74910679d6660f50
commit 963bfd011dffc072a3fdc63b74910679d6660f50
Author: Arnold D. Robbins <address@hidden>
Date: Sun Apr 24 13:03:28 2011 +0300
Update docs some more.
diff --git a/doc/gawk.1 b/doc/gawk.1
index 3fdf560..5723152 100644
--- a/doc/gawk.1
+++ b/doc/gawk.1
@@ -14,7 +14,7 @@
. if \w'\(rq' .ds rq "\(rq
. \}
.\}
-.TH GAWK 1 "Mar 29 2011" "Free Software Foundation" "Utility Commands"
+.TH GAWK 1 "Apr 24 2011" "Free Software Foundation" "Utility Commands"
.SH NAME
gawk \- pattern scanning and processing language
.SH SYNOPSIS
@@ -2492,8 +2492,12 @@ unchanged. The optional string
controls the direction and the comparsion mode.
Valid values for
.I how
-are "ascending string", "ascending number",
-"descending string" and "descending number".
+are
+\fB"ascending string"\fR,
+\fB"ascending number"\fR,
+\fB"descending string\fR"
+and
+\fB"descending number"\fR.
It can also be the name of a user-defined
comparison function as described in
\fBPROCINFO["sorted_in"]\fR.
diff --git a/doc/gawk.info b/doc/gawk.info
index 09828f4..f5f3413 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -9899,6 +9899,7 @@ File: gawk.info, Node: Scanning an Array, Prev: Array
Example, Up: Array Basi
* Menu:
* Controlling Scanning:: Controlling the order in which arrays are scanned.
+* Controlling Scanning With A Function:: Using a function to control scanning.
In programs that use arrays, it is often necessary to use a loop that
executes once for each element of an array. In other languages, where
@@ -9951,7 +9952,7 @@ loop will reach them. Similarly, changing VAR inside the
loop may
produce strange results. It is best to avoid such things.
-File: gawk.info, Node: Controlling Scanning, Up: Scanning an Array
+File: gawk.info, Node: Controlling Scanning, Next: Controlling Scanning With
A Function, Up: Scanning an Array
8.1.5.1 Controlling Array Scanning Order
........................................
@@ -10036,14 +10037,16 @@ value, regardless of what the subarray itself
contains, and all
subarrays are treated as being equal to each other. Their order
relative to each other is determined by their index strings.
+
+File: gawk.info, Node: Controlling Scanning With A Function, Prev:
Controlling Scanning, Up: Scanning an Array
+
8.1.5.2 Controlling Array Scanning Order With a User-defined Function
.....................................................................
-The value of `PROCINFO["sorted_in"]' can also be a function name that
-will let you traverse an array based on any custom criterion. The
-array elements are ordered according to the return value of this
-function. This comparison function should be defined with at least
-four arguments:
+The value of `PROCINFO["sorted_in"]' can also be a function name. This
+lets you traverse an array based on any custom criterion. The array
+elements are ordered according to the return value of this function.
+This comparison function should be defined with at least four arguments:
function comp_func(i1, v1, i2, v2)
{
@@ -10056,15 +10059,15 @@ values of the two elements being compared. Either V1
or V2, or both,
can be arrays if the array being traversed contains subarrays as
values. The three possible return values are interpreted this way:
- * If the return value of `comp_func(i1, v1, i2, v2)' is less than
- 0, index I1 comes before index I2 during loop traversal.
+ * If the return value of `comp_func(i1, v1, i2, v2)' is less than
+ zero, index I1 comes before index I2 during loop traversal.
- * If `comp_func(i1, v1, i2, v2)' returns 0, I1 and I2 come
- together but relative order with respect to each other is
+ * If `comp_func(i1, v1, i2, v2)' returns zero, I1 and I2 come
+ together but the relative order with respect to each other is
undefined.
- * If the return value of `comp_func(i1, v1, i2, v2)' is greater
- than 0, I1 comes after I2.
+ * If the return value of `comp_func(i1, v1, i2, v2)' is greater than
+ zero, I1 comes after I2.
The following comparison function can be used to scan an array in
numerical order of the indices:
@@ -10075,21 +10078,22 @@ numerical order of the indices:
return (i1 - i2)
}
- This function will traverse an array based on an order by element
-values rather than by indices:
+ This function traverses an array based on an order by element values
+rather than by indices:
function cmp_str_val(i1, v1, i2, v2)
{
# string value comparison, ascending order
- v1 = v1 ""
- v2 = v2 ""
- if (v1 < v2) return -1
+ v1 = v1 ""
+ v2 = v2 ""
+ if (v1 < v2)
+ return -1
return (v1 != v2)
}
- A comparison function to make all numbers, and numeric strings
-without any leading or trailing spaces come out first during loop
-traversal:
+ Here is a comparison function to make all numbers, and numeric
+strings without any leading or trailing spaces, come out first during
+loop traversal:
function cmp_num_str_val(i1, v1, i2, v2, n1, n2)
{
@@ -10108,7 +10112,7 @@ according to login names. The following program which
sorts records by
a specific field position can be used for this purpose:
# sort.awk --- simple program to sort by field position
- # field position is specified by POS
+ # field position is specified by the global variable POS
function cmp_field(i1, v1, i2, v2)
{
@@ -10156,15 +10160,15 @@ seemingly ordered data:
As mentioned above, the order of the indices is arbitrary if two
elements compare equal. This is usually not a problem, but letting the
-tied elements come out in arbitrary order can be an issue, specially
+tied elements come out in arbitrary order can be an issue, especially
when comparing item values. The partial ordering of the equal elements
-may change during next loop traversal, if other elements are added or
-removed from the array. One way to resolve ties when comparing elements
-with otherwise equal values is to include the indices in the comparison
-rules. Note that doing this may make the loop traversal less efficient,
-so consider it only if necessary. The following comparison functions
-will force a deterministic order, and are based on the fact that the
-indices of two elements are never equal:
+may change during the next loop traversal, if other elements are added
+or removed from the array. One way to resolve ties when comparing
+elements with otherwise equal values is to include the indices in the
+comparison rules. Note that doing this may make the loop traversal
+less efficient, so consider it only if necessary. The following
+comparison functions force a deterministic order, and are based on the
+fact that the indices of two elements are never equal:
function cmp_numeric(i1, v1, i2, v2)
{
@@ -10185,13 +10189,13 @@ traversal, and the the sky is really the limit when
it comes to
designing such a function.
When string comparisons are made during a sort, either for element
-values where one or both aren't numbers or for element indices handled
+values where one or both aren't numbers, or for element indices handled
as strings, the value of `IGNORECASE' (*note Built-in Variables::)
-controls whether the comparisons treat corresponding upper and lower
-case letters as equivalent or distinct.
+controls whether the comparisons treat corresponding uppercase and
+lowercase letters as equivalent or distinct.
- This sorting extension is disabled in POSIX mode, since the
-`PROCINFO' array is not special in that case.
+ All sorting based on `PROCINFO["sorted_in"]' is disabled in POSIX
+mode, since the `PROCINFO' array is not special in that case.
As a side note, sorting the array indices before traversing the
array has been reported to add 15% to 20% overhead to the execution
@@ -24692,11 +24696,11 @@ Index
* arrays, elements, assigning: Assigning Elements. (line 6)
* arrays, elements, deleting: Delete. (line 6)
* arrays, elements, installing: Internals. (line 79)
-* arrays, elements, order of: Scanning an Array. (line 52)
+* arrays, elements, order of: Scanning an Array. (line 53)
* arrays, elements, referencing: Reference to Elements.
(line 6)
* arrays, elements, retrieving number of: String Functions. (line 29)
-* arrays, for statement and: Scanning an Array. (line 24)
+* arrays, for statement and: Scanning an Array. (line 25)
* arrays, IGNORECASE variable and: Array Intro. (line 92)
* arrays, indexing: Array Intro. (line 50)
* arrays, merging into strings: Join Function. (line 6)
@@ -25382,7 +25386,7 @@ Index
(line 6)
* elements in arrays, assigning: Assigning Elements. (line 6)
* elements in arrays, deleting: Delete. (line 6)
-* elements in arrays, order of: Scanning an Array. (line 52)
+* elements in arrays, order of: Scanning an Array. (line 53)
* elements in arrays, scanning: Scanning an Array. (line 6)
* email address for bug reports, address@hidden: Bugs. (line 30)
* EMISTERED: TCP/IP Networking. (line 6)
@@ -25613,7 +25617,7 @@ Index
* FNR variable: Records. (line 6)
* FNR variable, changing: Auto-set. (line 229)
* for statement: For Statement. (line 6)
-* for statement, in arrays: Scanning an Array. (line 24)
+* for statement, in arrays: Scanning an Array. (line 25)
* force_number() internal function: Internals. (line 27)
* force_string() internal function: Internals. (line 32)
* force_wstring() internal function: Internals. (line 37)
@@ -25924,7 +25928,7 @@ Index
* in operator <3>: Precedence. (line 83)
* in operator: Comparison Operators.
(line 11)
-* in operator, arrays and <1>: Scanning an Array. (line 21)
+* in operator, arrays and <1>: Scanning an Array. (line 22)
* in operator, arrays and: Reference to Elements.
(line 37)
* increment operators: Increment Ops. (line 6)
@@ -27318,216 +27322,217 @@ Node: Reference to Elements414180
Node: Assigning Elements416450
Node: Array Example416941
Node: Scanning an Array418673
-Node: Controlling Scanning421049
-Node: Delete429855
-Ref: Delete-Footnote-1432290
-Node: Numeric Array Subscripts432347
-Node: Uninitialized Subscripts434530
-Node: Multi-dimensional436158
-Node: Multi-scanning439249
-Node: Array Sorting440833
-Ref: Array Sorting-Footnote-1444819
-Node: Arrays of Arrays445013
-Node: Functions449586
-Node: Built-in450408
-Node: Calling Built-in451486
-Node: Numeric Functions453474
-Ref: Numeric Functions-Footnote-1457239
-Ref: Numeric Functions-Footnote-2457596
-Ref: Numeric Functions-Footnote-3457644
-Node: String Functions457913
-Ref: String Functions-Footnote-1481384
-Ref: String Functions-Footnote-2481513
-Ref: String Functions-Footnote-3481761
-Node: Gory Details481848
-Ref: table-sub-escapes483527
-Ref: table-posix-sub484841
-Ref: table-gensub-escapes485754
-Node: I/O Functions486925
-Ref: I/O Functions-Footnote-1493580
-Node: Time Functions493727
-Ref: Time Functions-Footnote-1504619
-Ref: Time Functions-Footnote-2504687
-Ref: Time Functions-Footnote-3504845
-Ref: Time Functions-Footnote-4504956
-Ref: Time Functions-Footnote-5505068
-Ref: Time Functions-Footnote-6505295
-Node: Bitwise Functions505561
-Ref: table-bitwise-ops506119
-Ref: Bitwise Functions-Footnote-1510279
-Node: Type Functions510463
-Node: I18N Functions510933
-Node: User-defined512560
-Node: Definition Syntax513364
-Ref: Definition Syntax-Footnote-1518274
-Node: Function Example518343
-Node: Function Caveats520937
-Node: Calling A Function521358
-Node: Variable Scope522473
-Node: Pass By Value/Reference524448
-Node: Return Statement527888
-Node: Dynamic Typing530869
-Node: Indirect Calls531604
-Node: Internationalization541289
-Node: I18N and L10N542715
-Node: Explaining gettext543401
-Ref: Explaining gettext-Footnote-1548467
-Ref: Explaining gettext-Footnote-2548651
-Node: Programmer i18n548816
-Node: Translator i18n553016
-Node: String Extraction553809
-Ref: String Extraction-Footnote-1554770
-Node: Printf Ordering554856
-Ref: Printf Ordering-Footnote-1557640
-Node: I18N Portability557704
-Ref: I18N Portability-Footnote-1560153
-Node: I18N Example560216
-Ref: I18N Example-Footnote-1562851
-Node: Gawk I18N562923
-Node: Advanced Features563540
-Node: Nondecimal Data564859
-Node: Two-way I/O566440
-Ref: Two-way I/O-Footnote-1571874
-Node: TCP/IP Networking571944
-Node: Profiling574788
-Node: Library Functions582262
-Ref: Library Functions-Footnote-1585269
-Node: Library Names585440
-Ref: Library Names-Footnote-1588911
-Ref: Library Names-Footnote-2589131
-Node: General Functions589217
-Node: Strtonum Function590170
-Node: Assert Function593100
-Node: Round Function596426
-Node: Cliff Random Function597969
-Node: Ordinal Functions598985
-Ref: Ordinal Functions-Footnote-1602055
-Ref: Ordinal Functions-Footnote-2602307
-Node: Join Function602516
-Ref: Join Function-Footnote-1604287
-Node: Gettimeofday Function604487
-Node: Data File Management608202
-Node: Filetrans Function608834
-Node: Rewind Function612973
-Node: File Checking614360
-Node: Empty Files615454
-Node: Ignoring Assigns617684
-Node: Getopt Function619237
-Ref: Getopt Function-Footnote-1630541
-Node: Passwd Functions630744
-Ref: Passwd Functions-Footnote-1639719
-Node: Group Functions639807
-Node: Walking Arrays647891
-Node: Sample Programs649460
-Node: Running Examples650125
-Node: Clones650853
-Node: Cut Program652077
-Node: Egrep Program661922
-Ref: Egrep Program-Footnote-1669695
-Node: Id Program669805
-Node: Split Program673421
-Ref: Split Program-Footnote-1676940
-Node: Tee Program677068
-Node: Uniq Program679871
-Node: Wc Program687300
-Ref: Wc Program-Footnote-1691566
-Ref: Wc Program-Footnote-2691766
-Node: Miscellaneous Programs691858
-Node: Dupword Program693046
-Node: Alarm Program695077
-Node: Translate Program699826
-Ref: Translate Program-Footnote-1704213
-Ref: Translate Program-Footnote-2704441
-Node: Labels Program704575
-Ref: Labels Program-Footnote-1707946
-Node: Word Sorting708030
-Node: History Sorting711914
-Node: Extract Program713753
-Ref: Extract Program-Footnote-1721236
-Node: Simple Sed721364
-Node: Igawk Program724426
-Ref: Igawk Program-Footnote-1739459
-Ref: Igawk Program-Footnote-2739660
-Node: Anagram Program739798
-Node: Signature Program742866
-Node: Debugger743966
-Node: Debugging744877
-Node: Debugging Concepts745290
-Node: Debugging Terms747146
-Node: Awk Debugging749768
-Node: Sample dgawk session750660
-Node: dgawk invocation751152
-Node: Finding The Bug752334
-Node: List of Debugger Commands758820
-Node: Breakpoint Control760131
-Node: Dgawk Execution Control763767
-Node: Viewing And Changing Data767118
-Node: Dgawk Stack770455
-Node: Dgawk Info771915
-Node: Miscellaneous Dgawk Commands775863
-Node: Readline Support781291
-Node: Dgawk Limitations782129
-Node: Language History784318
-Node: V7/SVR3.1785756
-Node: SVR4788077
-Node: POSIX789519
-Node: BTL790527
-Node: POSIX/GNU791261
-Node: Common Extensions796362
-Node: Contributors797463
-Node: Installation801602
-Node: Gawk Distribution802496
-Node: Getting802980
-Node: Extracting803806
-Node: Distribution contents805498
-Node: Unix Installation810720
-Node: Quick Installation811337
-Node: Additional Configuration Options813299
-Node: Configuration Philosophy814776
-Node: Non-Unix Installation817118
-Node: PC Installation817576
-Node: PC Binary Installation818875
-Node: PC Compiling820723
-Node: PC Testing823667
-Node: PC Using824843
-Node: Cygwin829028
-Node: MSYS830028
-Node: VMS Installation830542
-Node: VMS Compilation831145
-Ref: VMS Compilation-Footnote-1832152
-Node: VMS Installation Details832210
-Node: VMS Running833845
-Node: VMS Old Gawk835452
-Node: Bugs835926
-Node: Other Versions839836
-Node: Notes845115
-Node: Compatibility Mode845807
-Node: Additions846590
-Node: Accessing The Source847402
-Node: Adding Code848827
-Node: New Ports854794
-Node: Dynamic Extensions858907
-Node: Internals860283
-Node: Plugin License869386
-Node: Sample Library870020
-Node: Internal File Description870706
-Node: Internal File Ops874421
-Ref: Internal File Ops-Footnote-1879202
-Node: Using Internal File Ops879342
-Node: Future Extensions881719
-Node: Basic Concepts884223
-Node: Basic High Level884980
-Ref: Basic High Level-Footnote-1889015
-Node: Basic Data Typing889200
-Node: Floating Point Issues893725
-Node: String Conversion Precision894808
-Ref: String Conversion Precision-Footnote-1896502
-Node: Unexpected Results896611
-Node: POSIX Floating Point Problems898437
-Ref: POSIX Floating Point Problems-Footnote-1902139
-Node: Glossary902177
-Node: Copying926320
-Node: GNU Free Documentation License963877
-Node: Index989014
+Node: Controlling Scanning421129
+Node: Controlling Scanning With A Function424172
+Node: Delete430174
+Ref: Delete-Footnote-1432609
+Node: Numeric Array Subscripts432666
+Node: Uninitialized Subscripts434849
+Node: Multi-dimensional436477
+Node: Multi-scanning439568
+Node: Array Sorting441152
+Ref: Array Sorting-Footnote-1445138
+Node: Arrays of Arrays445332
+Node: Functions449905
+Node: Built-in450727
+Node: Calling Built-in451805
+Node: Numeric Functions453793
+Ref: Numeric Functions-Footnote-1457558
+Ref: Numeric Functions-Footnote-2457915
+Ref: Numeric Functions-Footnote-3457963
+Node: String Functions458232
+Ref: String Functions-Footnote-1481703
+Ref: String Functions-Footnote-2481832
+Ref: String Functions-Footnote-3482080
+Node: Gory Details482167
+Ref: table-sub-escapes483846
+Ref: table-posix-sub485160
+Ref: table-gensub-escapes486073
+Node: I/O Functions487244
+Ref: I/O Functions-Footnote-1493899
+Node: Time Functions494046
+Ref: Time Functions-Footnote-1504938
+Ref: Time Functions-Footnote-2505006
+Ref: Time Functions-Footnote-3505164
+Ref: Time Functions-Footnote-4505275
+Ref: Time Functions-Footnote-5505387
+Ref: Time Functions-Footnote-6505614
+Node: Bitwise Functions505880
+Ref: table-bitwise-ops506438
+Ref: Bitwise Functions-Footnote-1510598
+Node: Type Functions510782
+Node: I18N Functions511252
+Node: User-defined512879
+Node: Definition Syntax513683
+Ref: Definition Syntax-Footnote-1518593
+Node: Function Example518662
+Node: Function Caveats521256
+Node: Calling A Function521677
+Node: Variable Scope522792
+Node: Pass By Value/Reference524767
+Node: Return Statement528207
+Node: Dynamic Typing531188
+Node: Indirect Calls531923
+Node: Internationalization541608
+Node: I18N and L10N543034
+Node: Explaining gettext543720
+Ref: Explaining gettext-Footnote-1548786
+Ref: Explaining gettext-Footnote-2548970
+Node: Programmer i18n549135
+Node: Translator i18n553335
+Node: String Extraction554128
+Ref: String Extraction-Footnote-1555089
+Node: Printf Ordering555175
+Ref: Printf Ordering-Footnote-1557959
+Node: I18N Portability558023
+Ref: I18N Portability-Footnote-1560472
+Node: I18N Example560535
+Ref: I18N Example-Footnote-1563170
+Node: Gawk I18N563242
+Node: Advanced Features563859
+Node: Nondecimal Data565178
+Node: Two-way I/O566759
+Ref: Two-way I/O-Footnote-1572193
+Node: TCP/IP Networking572263
+Node: Profiling575107
+Node: Library Functions582581
+Ref: Library Functions-Footnote-1585588
+Node: Library Names585759
+Ref: Library Names-Footnote-1589230
+Ref: Library Names-Footnote-2589450
+Node: General Functions589536
+Node: Strtonum Function590489
+Node: Assert Function593419
+Node: Round Function596745
+Node: Cliff Random Function598288
+Node: Ordinal Functions599304
+Ref: Ordinal Functions-Footnote-1602374
+Ref: Ordinal Functions-Footnote-2602626
+Node: Join Function602835
+Ref: Join Function-Footnote-1604606
+Node: Gettimeofday Function604806
+Node: Data File Management608521
+Node: Filetrans Function609153
+Node: Rewind Function613292
+Node: File Checking614679
+Node: Empty Files615773
+Node: Ignoring Assigns618003
+Node: Getopt Function619556
+Ref: Getopt Function-Footnote-1630860
+Node: Passwd Functions631063
+Ref: Passwd Functions-Footnote-1640038
+Node: Group Functions640126
+Node: Walking Arrays648210
+Node: Sample Programs649779
+Node: Running Examples650444
+Node: Clones651172
+Node: Cut Program652396
+Node: Egrep Program662241
+Ref: Egrep Program-Footnote-1670014
+Node: Id Program670124
+Node: Split Program673740
+Ref: Split Program-Footnote-1677259
+Node: Tee Program677387
+Node: Uniq Program680190
+Node: Wc Program687619
+Ref: Wc Program-Footnote-1691885
+Ref: Wc Program-Footnote-2692085
+Node: Miscellaneous Programs692177
+Node: Dupword Program693365
+Node: Alarm Program695396
+Node: Translate Program700145
+Ref: Translate Program-Footnote-1704532
+Ref: Translate Program-Footnote-2704760
+Node: Labels Program704894
+Ref: Labels Program-Footnote-1708265
+Node: Word Sorting708349
+Node: History Sorting712233
+Node: Extract Program714072
+Ref: Extract Program-Footnote-1721555
+Node: Simple Sed721683
+Node: Igawk Program724745
+Ref: Igawk Program-Footnote-1739778
+Ref: Igawk Program-Footnote-2739979
+Node: Anagram Program740117
+Node: Signature Program743185
+Node: Debugger744285
+Node: Debugging745196
+Node: Debugging Concepts745609
+Node: Debugging Terms747465
+Node: Awk Debugging750087
+Node: Sample dgawk session750979
+Node: dgawk invocation751471
+Node: Finding The Bug752653
+Node: List of Debugger Commands759139
+Node: Breakpoint Control760450
+Node: Dgawk Execution Control764086
+Node: Viewing And Changing Data767437
+Node: Dgawk Stack770774
+Node: Dgawk Info772234
+Node: Miscellaneous Dgawk Commands776182
+Node: Readline Support781610
+Node: Dgawk Limitations782448
+Node: Language History784637
+Node: V7/SVR3.1786075
+Node: SVR4788396
+Node: POSIX789838
+Node: BTL790846
+Node: POSIX/GNU791580
+Node: Common Extensions796681
+Node: Contributors797782
+Node: Installation801921
+Node: Gawk Distribution802815
+Node: Getting803299
+Node: Extracting804125
+Node: Distribution contents805817
+Node: Unix Installation811039
+Node: Quick Installation811656
+Node: Additional Configuration Options813618
+Node: Configuration Philosophy815095
+Node: Non-Unix Installation817437
+Node: PC Installation817895
+Node: PC Binary Installation819194
+Node: PC Compiling821042
+Node: PC Testing823986
+Node: PC Using825162
+Node: Cygwin829347
+Node: MSYS830347
+Node: VMS Installation830861
+Node: VMS Compilation831464
+Ref: VMS Compilation-Footnote-1832471
+Node: VMS Installation Details832529
+Node: VMS Running834164
+Node: VMS Old Gawk835771
+Node: Bugs836245
+Node: Other Versions840155
+Node: Notes845434
+Node: Compatibility Mode846126
+Node: Additions846909
+Node: Accessing The Source847721
+Node: Adding Code849146
+Node: New Ports855113
+Node: Dynamic Extensions859226
+Node: Internals860602
+Node: Plugin License869705
+Node: Sample Library870339
+Node: Internal File Description871025
+Node: Internal File Ops874740
+Ref: Internal File Ops-Footnote-1879521
+Node: Using Internal File Ops879661
+Node: Future Extensions882038
+Node: Basic Concepts884542
+Node: Basic High Level885299
+Ref: Basic High Level-Footnote-1889334
+Node: Basic Data Typing889519
+Node: Floating Point Issues894044
+Node: String Conversion Precision895127
+Ref: String Conversion Precision-Footnote-1896821
+Node: Unexpected Results896930
+Node: POSIX Floating Point Problems898756
+Ref: POSIX Floating Point Problems-Footnote-1902458
+Node: Glossary902496
+Node: Copying926639
+Node: GNU Free Documentation License964196
+Node: Index989333
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index b4b014e..60cfd1d 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -12766,7 +12766,8 @@ You can omit direction and/or key type and/or
comparison mode. Provided
that at least one is present, the missing parts of a sort specification
default to @samp{ascending}, @samp{index}, and @samp{string}, respectively.
An empty string, @code{""}, is the same as @samp{ascending index string},
-and a value of @samp{unsorted} will cause @samp{for (index in array) @dots{}}
to process
+and a value of @samp{unsorted} will cause @samp{for (index in array) @dots{}}
+to process
the indices in arbitrary order. Another thing to note is that the array
sorting
takes place at the time the @code{for} loop is about to
start executing, so changing the value of @code{PROCINFO["sorted_in"]}
@@ -13379,6 +13380,7 @@ END @{
@menu
* Controlling Scanning:: Controlling the order in which arrays are scanned.
+* Controlling Scanning With A Function:: Using a function to control scanning.
@end menu
In programs that use arrays, it is often necessary to use a loop that
@@ -13531,10 +13533,11 @@ numeric value, regardless of what the subarray itself
contains,
and all subarrays are treated as being equal to each other. Their
order relative to each other is determined by their index strings.
address@hidden Controlling Scanning With A Function
@subsubsection Controlling Array Scanning Order With a User-defined Function
-The value of @code{PROCINFO["sorted_in"]} can also be a function name
-that will let you traverse an array based on any custom criterion.
+The value of @code{PROCINFO["sorted_in"]} can also be a function name.
+This lets you traverse an array based on any custom criterion.
The array elements are ordered according to the return value of this
function. This comparison function should be defined with at least
four arguments:
@@ -13553,16 +13556,19 @@ Either @var{v1} or @var{v2}, or both, can be arrays
if the array being
traversed contains subarrays as values. The three possible return values
are interpreted this way:
address@hidden
-* If the return value of @code{comp_func(i1, v1, i2, v2)} is less than 0,
address@hidden @bullet
address@hidden
+If the return value of @code{comp_func(i1, v1, i2, v2)} is less than zero,
index @var{i1} comes before index @var{i2} during loop traversal.
-* If @code{comp_func(i1, v1, i2, v2)} returns 0, @var{i1} and @var{i2}
-come together but relative order with respect to each other is undefined.
address@hidden
+If @code{comp_func(i1, v1, i2, v2)} returns zero, @var{i1} and @var{i2}
+come together but the relative order with respect to each other is undefined.
-* If the return value of @code{comp_func(i1, v1, i2, v2)} is greater than 0,
address@hidden
+If the return value of @code{comp_func(i1, v1, i2, v2)} is greater than zero,
@var{i1} comes after @var{i2}.
address@hidden quotation
address@hidden itemize
The following comparison function can be used to scan an array in
numerical order of the indices:
@@ -13575,22 +13581,24 @@ function cmp_num_idx(i1, v1, i2, v2)
@}
@end example
-This function will traverse an array based on an order by element values
+This function traverses an array based on an order by element values
rather than by indices:
@example
function cmp_str_val(i1, v1, i2, v2)
@{
# string value comparison, ascending order
- v1 = v1 ""
- v2 = v2 ""
- if (v1 < v2) return -1
+ v1 = v1 ""
+ v2 = v2 ""
+ if (v1 < v2)
+ return -1
return (v1 != v2)
@}
@end example
-A comparison function to make all numbers, and numeric strings without
-any leading or trailing spaces come out first during loop traversal:
+Here is a
+comparison function to make all numbers, and numeric strings without
+any leading or trailing spaces, come out first during loop traversal:
@example
function cmp_num_str_val(i1, v1, i2, v2, n1, n2)
@@ -13612,7 +13620,7 @@ by a specific field position can be used for this
purpose:
@example
# sort.awk --- simple program to sort by field position
-# field position is specified by POS
+# field position is specified by the global variable POS
function cmp_field(i1, v1, i2, v2)
@{
@@ -13642,7 +13650,7 @@ and the fields are seperated by colons. Running the
program produces the
following output:
@example
address@hidden gawk -vPOS=1 -F: -f sort.awk /etc/passwd}
+$ @kbd{gawk -vPOS=1 -F: -f sort.awk /etc/passwd}
@print{} adm:x:3:4:adm:/var/adm:/sbin/nologin
@print{} apache:x:48:48:Apache:/var/www:/sbin/nologin
@print{} avahi:x:70:70:Avahi daemon:/:/sbin/nologin
@@ -13665,14 +13673,14 @@ function cmp_randomize(i1, v1, i2, v2)
As mentioned above, the order of the indices is arbitrary if two
elements compare equal. This is usually not a problem, but letting
-the tied elements come out in arbitrary order can be an issue, specially
+the tied elements come out in arbitrary order can be an issue, especially
when comparing item values. The partial ordering of the equal elements
-may change during next loop traversal, if other elements are added or
+may change during the next loop traversal, if other elements are added or
removed from the array. One way to resolve ties when comparing elements
with otherwise equal values is to include the indices in the comparison
rules. Note that doing this may make the loop traversal less efficient,
so consider it only if necessary. The following comparison functions
-will force a deterministic order, and are based on the fact that the
+force a deterministic order, and are based on the fact that the
indices of two elements are never equal:
@example
@@ -13691,32 +13699,31 @@ function cmp_string(i1, v1, i2, v2)
@}
@end example
address@hidden
-Avoid using the term stable when describing the unpredictable behavior
-if two items compare equal. Usually, the goal of a "stable algorithm"
-is to maintain the original order of the items, which is a meaningless
-concept for a list constructed from a hash.
address@hidden ignore
address@hidden Avoid using the term ``stable'' when describing the
unpredictable behavior
address@hidden if two items compare equal. Usually, the goal of a "stable
algorithm"
address@hidden is to maintain the original order of the items, which is a
meaningless
address@hidden concept for a list constructed from a hash.
A custom comparison function can often simplify ordered loop
traversal, and the the sky is really the limit when it comes to
designing such a function.
-
When string comparisons are made during a sort, either for element
-values where one or both aren't numbers or for element indices
+values where one or both aren't numbers, or for element indices
handled as strings, the value of @code{IGNORECASE}
(@pxref{Built-in Variables}) controls whether
-the comparisons treat corresponding upper and lower case letters as
+the comparisons treat corresponding uppercase and lowercase letters as
equivalent or distinct.
-This sorting extension is disabled in POSIX mode,
+All sorting based on @code{PROCINFO["sorted_in"]}
+is disabled in POSIX mode,
since the @code{PROCINFO} array is not special in that case.
As a side note, sorting the array indices before traversing
the array has been reported to add 15% to 20% overhead to the
execution time of @command{awk} programs. For this reason,
sorted array traversal is not the default.
+
@c The @command{gawk}
@c maintainers believe that only the people who wish to use a
@c feature should have to pay for it.
-----------------------------------------------------------------------
Summary of changes:
doc/gawk.1 | 10 +-
doc/gawk.info | 505 +++++++++++++++++++++++++++++----------------------------
doc/gawk.texi | 67 +++++----
3 files changed, 299 insertions(+), 283 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, master, updated. 963bfd011dffc072a3fdc63b74910679d6660f50,
Arnold Robbins <=