[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawkdiffs] [SCM] gawk branch, master, updated. 1ef98b7f216198b5c17b516
From: 
Arnold Robbins 
Subject: 
[gawkdiffs] [SCM] gawk branch, master, updated. 1ef98b7f216198b5c17b516642eded9d3ef7c6b2 
Date: 
Sun, 26 Aug 2012 19:17:38 +0000 
This is an automated email from the git hooks/postreceive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, master has been updated
via 1ef98b7f216198b5c17b516642eded9d3ef7c6b2 (commit)
from 0b4ff99fec136012af7a54f179bdf601e55e6274 (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=1ef98b7f216198b5c17b516642eded9d3ef7c6b2
commit 1ef98b7f216198b5c17b516642eded9d3ef7c6b2
Author: Arnold D. Robbins <address@hidden>
Date: Sun Aug 26 22:17:10 2012 +0300
More edits to arithmetic chapter.
diff git a/doc/ChangeLog b/doc/ChangeLog
index b112c72..bb01197 100644
 a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ 1,3 +1,8 @@
+20120826 Arnold D. Robbins <address@hidden>
+
+ * gawk.texi: More edits to chapter on arithmetic.
+ Primarily English changes.
+
20120824 Arnold D. Robbins <address@hidden>
* gawk.texi: Emphasize more that floating point behavior is
diff git a/doc/gawk.info b/doc/gawk.info
index 797a35a..cae67b8 100644
 a/doc/gawk.info
+++ b/doc/gawk.info
@@ 14020,7 +14020,7 @@ login name, and the fields are separated by colons.
Each record
defines a subarray, with each field as an element in the subarray.
Running the program produces the following output:
 $ gawk vPOS=1 F: f sort.awk /etc/passwd
+ $ gawk v POS=1 F: f sort.awk /etc/passwd
 adm:x:3:4:adm:/var/adm:/sbin/nologin
 apache:x:48:48:Apache:/var/www:/sbin/nologin
 avahi:x:70:70:Avahi daemon:/:/sbin/nologin
@@ 20057,7 +20057,7 @@ atributes of computer arithmetic, along with how this
can influence
what you see when running `awk' programs. This discussion applies to
all versions of `awk'.
 Then the discussion moves on to "arbitrary precsion arithmetic", a
+ Then the major node moves on to "arbitrary precsion arithmetic", a
feature which is specific to `gawk'.
* Menu:
@@ 20119,10 +20119,7 @@ File: gawk.info, Node: Floating Point Issues, Next:
Integer Programming, Up:
15.1.1 FloatingPoint Number Caveats

As mentioned earlier, floatingpoint numbers represent what are called
"real" numbers, i.e., those that have a fractional part. `awk' uses
double precision floatingpoint numbers to represent all numeric
values. This minor node describes some of the issues involved in using
+This minor node describes some of the issues involved in using
floatingpoint numbers.
There is a very nice paper on floatingpoint arithmetic
@@ 20341,10 +20338,10 @@ File: gawk.info, Node: Integer Programming, Prev:
Floating Point Issues, Up:
As has been mentioned already, `gawk' ordinarily uses hardware double
precision with 64bit IEEE binary floatingpoint representation for
numbers on most systems. A large integer like 9007199254740997 has a
binary representation that, although finite, is more than 53 bits long;
it must also be rounded to 53 bits. The biggest integer that can be
stored in a C `double' is usually the same as the largest possible
+numbers on most systems. A large integer like 9,007,199,254,740,997 has
+a binary representation that, although finite, is more than 53 bits
+long; it must also be rounded to 53 bits. The biggest integer that can
+be stored in a C `double' is usually the same as the largest possible
value of a `double'. If your system `double' is an IEEE 64bit
`double', this largest possible value is an integer and can be
represented precisely. What more should one know about integers?
@@ 20379,7 +20376,7 @@ Numerical programming is an extensive area; if you need
to develop
sophisticated numerical algorithms then `gawk' may not be the ideal
tool, and this documentation may not be sufficient. It might require
digesting a book or two to really internalize how to compute with ideal
accuracy and precision and the result often depends on the particular
+accuracy and precision, and the result often depends on the particular
application.
NOTE: A floatingpoint calculation's "accuracy" is how close it
@@ 20392,9 +20389,9 @@ application.
There are two options for doing floatingpoint calculations:
hardware floatingpoint (as used by standard `awk' and the default for
`gawk'), and "arbitraryprecision" floatingpoint, which is software
based. This major node aims to provide enough information to
understand both, and then will focus on `gawk''s facilities for the
latter.(1)
+based. From this point forward, this major node aims to provide enough
+information to understand both, and then will focus on `gawk''s
+facilities for the latter.(1)
Binary floatingpoint representations and arithmetic are inexact.
Simple values like 0.1 cannot be precisely represented using binary
@@ 20430,10 +20427,10 @@ you can always specify how much precision you would
like in your output.
Usually this is a format string like `"%.15g"', which when used in the
previous example, produces an output identical to the input.
 Because the underlying representation can be little bit off from the
exact value, comparing floatingpoint values to see if they are equal
is generally not a good idea. Here is an example where it does not
work like you expect:
+ Because the underlying representation can be a little bit off from
+the exact value, comparing floatingpoint values to see if they are
+equal is generally not a good idea. Here is an example where it does
+not work like you expect:
$ gawk 'BEGIN { print (0.1 + 12.2 == 12.3) }'
 0
@@ 20470,7 +20467,7 @@ zero.
 0.000000000000000
error> gawk: pi.awk:6: fatal: division by zero attempted
 Here is one more example where the inaccuracies in internal
+ Here is an additional example where the inaccuracies in internal
representations yield an unexpected result:
$ gawk 'BEGIN {
@@ 20506,13 +20503,14 @@ iterations:
There is no need to be unduly suspicious about the results from
floatingpoint arithmetic. The lesson to remember is that
floatingpoint arithmetic is always more complex than the arithmetic
using pencil and paper. In order to take advantage of the power of
computer floatingpoint, you need to know its limitations and work
within them. For most casual use of floatingpoint arithmetic, you will
often get the expected result in the end if you simply round the
display of your final results to the correct number of significant
decimal digits. And, avoid presenting numerical data in a manner that
+floatingpoint arithmetic is always more complex than arithmetic using
+pencil and paper. In order to take advantage of the power of computer
+floatingpoint, you need to know its limitations and work within them.
+For most casual use of floatingpoint arithmetic, you will often get
+the expected result in the end if you simply round the display of your
+final results to the correct number of significant decimal digits.
+
+ As general advice, avoid presenting numerical data in a manner that
implies better precision than is actually the case.
* Menu:
@@ 20541,23 +20539,21 @@ IEEE 754 Standard. An IEEE754 format value has three
components:
* A sign bit telling whether the number is positive or negative.
 * An "exponent" giving its order of magnitude, E.
+ * An "exponent", E, giving its order of magnitude.
* A "significand", S, specifying the actual digits of the number.
The value of the number is then S * 2^E. The first bit of a
nonzero binary significand is always one, so the significand in an
IEEE754 format only includes the fractional part, leaving the leading
one implicit.
+one implicit. The significand is stored in "normalized" format, which
+means that the first bit is always a one.
Three of the standard IEEE754 types are 32bit single precision,
64bit double precision and 128bit quadruple precision. The standard
also specifies extended precision formats to allow greater precisions
and larger exponent ranges.
 The significand is stored in "normalized" format, which means that
the first bit is always a one.

File: gawk.info, Node: Floatingpoint Context, Next: Rounding Mode, Prev:
Floatingpoint Representation, Up: Floatingpoint Programming
@@ 20739,23 +20735,23 @@ File: gawk.info, Node: Arbitrary Precision Floats,
Next: Arbitrary Precision I
`gawk' uses the GNU MPFR library for arbitrary precision floatingpoint
arithmetic. The MPFR library provides precise control over precisions
and rounding modes, and gives correctly rounded reproducible
+and rounding modes, and gives correctly rounded, reproducible,
platformindependent results. With the commandline option `bignum'
or `M', all floatingpoint arithmetic operators and numeric functions
can yield results to any desired precision level supported by MPFR.
Two builtin variables `PREC' (*note Setting Precision::) and
`ROUNDMODE' (*note Setting Rounding Mode::) provide control over the
working precision and the rounding mode. The precision and the
rounding mode are set globally for every operation to follow.
+Two builtin variables, `PREC' and `ROUNDMODE', provide control over
+the working precision and the rounding mode (*note Setting Precision::,
+and *note Setting Rounding Mode::). The precision and the rounding
+mode are set globally for every operation to follow.
The default working precision for arbitrary precision floatingpoint
values is 53, and the default value for `ROUNDMODE' is `"N"', which
selects the IEEE754 `roundTiesToEven' (*note Rounding Mode::) rounding
mode.(1) `gawk' uses the default exponent range in MPFR (EMAX = 2^30 
1, EMIN = EMAX) for all floatingpoint contexts. There is no explicit
mechanism to adjust the exponent range. MPFR does not implement
subnormal numbers by default, and this behavior cannot be changed in
`gawk'.
+selects the IEEE754 `roundTiesToEven' rounding mode (*note Rounding
+Mode::).(1) `gawk' uses the default exponent range in MPFR (EMAX = 2^30
+ 1, EMIN = EMAX) for all floatingpoint contexts. There is no
+explicit mechanism to adjust the exponent range. MPFR does not
+implement subnormal numbers by default, and this behavior cannot be
+changed in `gawk'.
NOTE: When emulating an IEEE754 format (*note Setting
Precision::), `gawk' internally adjusts the exponent range to the
@@ 20793,7 +20789,7 @@ File: gawk.info, Node: Setting Precision, Next:
Setting Rounding Mode, Up: Ar
`gawk' uses a global working precision; it does not keep track of the
precision or accuracy of individual numbers. Performing an arithmetic
operation or calling a builtin function rounds the result to the
current working precision. The default working precision is 53 which
+current working precision. The default working precision is 53, which
can be modified using the builtin variable `PREC'. You can also set the
value to one of the following predefined caseinsensitive strings to
emulate an IEEE754 binary format:
@@ 20809,13 +20805,13 @@ emulate an IEEE754 binary format:
The following example illustrates the effects of changing precision
on arithmetic operations:
 $ gawk M vPREC=100 'BEGIN { x = 1.0e400; print x + 0; \
+ $ gawk M v PREC=100 'BEGIN { x = 1.0e400; print x + 0; \
> PREC = "double"; print x + 0 }'
 1e400
 0
 Binary and decimal precisions are related approximately according to
the formula:
+ Binary and decimal precisions are related approximately, according
+to the formula:
PREC = 3.322 * DPS
@@ 20842,9 +20838,11 @@ floatingpoint computations with more than 15
significant digits in
them.
Conversely, it takes a precision of 332 bits to hold an approximation
of the constant pi that is accurate to 100 decimal places. You should
always add some extra bits in order to avoid the confusing roundoff
issues that occur because numbers are stored internally in binary.
+of the constant pi that is accurate to 100 decimal places.
+
+ You should always add some extra bits in order to avoid the
+confusing roundoff issues that occur because numbers are stored
+internally in binary.
File: gawk.info, Node: Setting Rounding Mode, Next: Floatingpoint
Constants, Prev: Setting Precision, Up: Arbitrary Precision Floats
@@ 20868,9 +20866,9 @@ from zero
Table 15.3: `gawk' Rounding Modes
`ROUNDMODE' has the default value `"N"', which selects the IEEE754
rounding mode `roundTiesToEven'. Besides the values listed in *note
Table 15.3: tablegawkroundingmodes, `gawk' also accepts `"A"' to
select the IEEE754 mode `roundTiesToAway' if your version of the MPFR
+rounding mode `roundTiesToEven'. *note Table 15.3:
+tablegawkroundingmodes, lists `"A"' to select the IEEE754 mode
+`roundTiesToAway'. This is only available if your version of the MPFR
library supports it; otherwise setting `ROUNDMODE' to this value has no
effect. *Note Rounding Mode::, for the meanings of the various rounding
modes.
@@ 20878,7 +20876,7 @@ modes.
Here is an example of how to change the default rounding behavior of
`printf''s output:
 $ gawk M vROUNDMODE="Z" 'BEGIN { printf("%.2f\n", 1.378) }'
+ $ gawk M v ROUNDMODE="Z" 'BEGIN { printf("%.2f\n", 1.378) }'
 1.37
@@ 20891,17 +20889,17 @@ Be wary of floatingpoint constants! When reading a
floatingpoint
constant from program source code, `gawk' uses the default precision,
unless overridden by an assignment to the special variable `PREC' on
the command line, to store it internally as a MPFR number. Changing
the precision using `PREC' in the program text does not change the
+the precision using `PREC' in the program text does _not_ change the
precision of a constant. If you need to represent a floatingpoint
constant at a higher precision than the default and cannot use a
command line assignment to `PREC', you should either specify the
constant as a string, or as a rational number whenever possible. The
+constant as a string, or as a rational number, whenever possible. The
following example illustrates the differences among various ways to
print a floatingpoint constant:
$ gawk M 'BEGIN { PREC = 113; printf("%0.25f\n", 0.1) }'
 0.1000000000000000055511151
 $ gawk M vPREC = 113 'BEGIN { printf("%0.25f\n", 0.1) }'
+ $ gawk M v PREC=113 'BEGIN { printf("%0.25f\n", 0.1) }'
 0.1000000000000000000000000
$ gawk M 'BEGIN { PREC = 113; printf("%0.25f\n", "0.1") }'
 0.1000000000000000000000000
@@ 20972,14 +20970,14 @@ they are not equal! (*Note Floatingpoint
Programming::.) You can get
the result you want by increasing the precision; 56 in this case will
get the job done:
 $ gawk M vPREC=56 'BEGIN { print (0.1 + 12.2 == 12.3) }'
+ $ gawk M v PREC=56 'BEGIN { print (0.1 + 12.2 == 12.3) }'
 1
If adding more bits is good, perhaps adding even more bits of
precision is better? Here is what happens if we use an even larger
value of `PREC':
 $ gawk M vPREC=201 'BEGIN { print (0.1 + 12.2 == 12.3) }'
+ $ gawk M v PREC=201 'BEGIN { print (0.1 + 12.2 == 12.3) }'
 0
This is not a bug in `gawk' or in the MPFR library. It is easy to
@@ 21001,8 +20999,8 @@ range of the other.
double precision arithmetic can be adequate, and is usually much faster.
But you do need to keep in mind that every floatingpoint operation can
suffer a new rounding error with catastrophic consequences as
illustrated by our attempt to compute the value of the constant pi
(*note Floatingpoint Programming::). Extra precision can greatly
+illustrated by our earlier attempt to compute the value of the constant
+pi (*note Floatingpoint Programming::). Extra precision can greatly
enhance the stability and the accuracy of your computation in such
cases.
@@ 21047,8 +21045,7 @@ computes 5^4^3^2, the result of which is beyond the
limits of ordinary
If you were to compute the same value using arbitrary precision
floatingpoint values instead, the precision needed for correct output
(using the formula `prec = 3.322 * dps'), would be 3.322 x 183231, or
608693. (Thus, the floatingpoint representation requires over 30
times as many decimal digits!)
+608693.
The result from an arithmetic operation with an integer and a
floatingpoint value is a floatingpoint value with a precision equal
@@ 21063,12 +21060,12 @@ term in Sylvester's sequence(1) using a recurrence:
> }'
 113423713055421845118910464
 The output differs from the acutal number,
113423713055421844361000443, because the default precision of 53 is not
enough to represent the floatingpoint results exactly. You can either
increase the precision (100 is enough in this case), or replace the
floatingpoint constant `2.0' with an integer, to perform all
computations using integer arithmetic to get the correct output.
+ The output differs from the actual number,
+113,423,713,055,421,844,361,000,443, because the default precision of
+53 is not enough to represent the floatingpoint results exactly. You
+can either increase the precision (100 is enough in this case), or
+replace the floatingpoint constant `2.0' with an integer, to perform
+all computations using integer arithmetic to get the correct output.
It will sometimes be necessary for `gawk' to implicitly convert an
arbitrary precision integer into an arbitrary precision floatingpoint
@@ 28691,182 +28688,182 @@ Node: Advanced Features569310
Node: Nondecimal Data570823
Node: Array Sorting572406
Node: Controlling Array Traversal573103
Node: Array Sorting Functions581340
Ref: Array Sorting FunctionsFootnote1585014
Ref: Array Sorting FunctionsFootnote2585107
Node: Twoway I/O585301
Ref: Twoway I/OFootnote1590733
Node: TCP/IP Networking590803
Node: Profiling593647
Node: Library Functions601101
Ref: Library FunctionsFootnote1604108
Node: Library Names604279
Ref: Library NamesFootnote1607750
Ref: Library NamesFootnote2607970
Node: General Functions608056
Node: Strtonum Function609009
Node: Assert Function611939
Node: Round Function615265
Node: Cliff Random Function616808
Node: Ordinal Functions617824
Ref: Ordinal FunctionsFootnote1620894
Ref: Ordinal FunctionsFootnote2621146
Node: Join Function621355
Ref: Join FunctionFootnote1623126
Node: Getlocaltime Function623326
Node: Data File Management627041
Node: Filetrans Function627673
Node: Rewind Function631812
Node: File Checking633199
Node: Empty Files634293
Node: Ignoring Assigns636523
Node: Getopt Function638076
Ref: Getopt FunctionFootnote1649380
Node: Passwd Functions649583
Ref: Passwd FunctionsFootnote1658558
Node: Group Functions658646
Node: Walking Arrays666730
Node: Sample Programs668299
Node: Running Examples668964
Node: Clones669692
Node: Cut Program670916
Node: Egrep Program680761
Ref: Egrep ProgramFootnote1688534
Node: Id Program688644
Node: Split Program692260
Ref: Split ProgramFootnote1695779
Node: Tee Program695907
Node: Uniq Program698710
Node: Wc Program706139
Ref: Wc ProgramFootnote1710405
Ref: Wc ProgramFootnote2710605
Node: Miscellaneous Programs710697
Node: Dupword Program711885
Node: Alarm Program713916
Node: Translate Program718665
Ref: Translate ProgramFootnote1723052
Ref: Translate ProgramFootnote2723280
Node: Labels Program723414
Ref: Labels ProgramFootnote1726785
Node: Word Sorting726869
Node: History Sorting730753
Node: Extract Program732592
Ref: Extract ProgramFootnote1740075
Node: Simple Sed740203
Node: Igawk Program743265
Ref: Igawk ProgramFootnote1758422
Ref: Igawk ProgramFootnote2758623
Node: Anagram Program758761
Node: Signature Program761829
Node: Debugger762929
Node: Debugging763895
Node: Debugging Concepts764328
Node: Debugging Terms766184
Node: Awk Debugging768781
Node: Sample Debugging Session769673
Node: Debugger Invocation770193
Node: Finding The Bug771522
Node: List of Debugger Commands778010
Node: Breakpoint Control779344
Node: Debugger Execution Control783008
Node: Viewing And Changing Data786368
Node: Execution Stack789724
Node: Debugger Info791191
Node: Miscellaneous Debugger Commands795172
Node: Readline Support800617
Node: Limitations801448
Node: Arbitrary Precision Arithmetic803700
Ref: Arbitrary Precision ArithmeticFootnote1805341
Node: General Arithmetic805489
Node: Floating Point Issues807209
Node: String Conversion Precision808304
Ref: String Conversion PrecisionFootnote1810010
Node: Unexpected Results810119
Node: POSIX Floating Point Problems812272
Ref: POSIX Floating Point ProblemsFootnote1816097
Node: Integer Programming816135
Node: Floatingpoint Programming817883
Ref: Floatingpoint ProgrammingFootnote1824147
Node: Floatingpoint Representation824411
Node: Floatingpoint Context825578
Ref: tableieeeformats826420
Node: Rounding Mode827804
Ref: tableroundingmodes828283
Ref: Rounding ModeFootnote1831287
Node: Gawk and MPFR831468
Node: Arbitrary Precision Floats832709
Ref: Arbitrary Precision FloatsFootnote1835131
Node: Setting Precision835442
Node: Setting Rounding Mode838169
Ref: tablegawkroundingmodes838573
Node: Floatingpoint Constants839770
Node: Changing Precision841192
Ref: Changing PrecisionFootnote1842592
Node: Exact Arithmetic842766
Node: Arbitrary Precision Integers845864
Ref: Arbitrary Precision IntegersFootnote1848946
Node: Dynamic Extensions849093
Node: Plugin License850011
Node: Sample Library850625
Node: Internal File Description851309
Node: Internal File Ops855022
Ref: Internal File OpsFootnote1859585
Node: Using Internal File Ops859725
Node: Language History862101
Node: V7/SVR3.1863623
Node: SVR4865944
Node: POSIX867386
Node: BTL868394
Node: POSIX/GNU869128
Node: Common Extensions874663
Node: Ranges and Locales875770
Ref: Ranges and LocalesFootnote1880388
Ref: Ranges and LocalesFootnote2880415
Ref: Ranges and LocalesFootnote3880675
Node: Contributors880896
Node: Installation885192
Node: Gawk Distribution886086
Node: Getting886570
Node: Extracting887396
Node: Distribution contents889088
Node: Unix Installation894310
Node: Quick Installation894927
Node: Additional Configuration Options896889
Node: Configuration Philosophy898366
Node: NonUnix Installation900708
Node: PC Installation901166
Node: PC Binary Installation902465
Node: PC Compiling904313
Node: PC Testing907257
Node: PC Using908433
Node: Cygwin912618
Node: MSYS913618
Node: VMS Installation914132
Node: VMS Compilation914735
Ref: VMS CompilationFootnote1915742
Node: VMS Installation Details915800
Node: VMS Running917435
Node: VMS Old Gawk919042
Node: Bugs919516
Node: Other Versions923368
Node: Notes928683
Node: Compatibility Mode929270
Node: Additions930053
Node: Accessing The Source930980
Node: Adding Code932405
Node: New Ports938413
Node: Derived Files942548
Ref: Derived FilesFootnote1947852
Ref: Derived FilesFootnote2947886
Ref: Derived FilesFootnote3948486
Node: Future Extensions948584
Node: Basic Concepts950071
Node: Basic High Level950752
Ref: Basic High LevelFootnote1954787
Node: Basic Data Typing954972
Node: Glossary958327
Node: Copying983303
Node: GNU Free Documentation License1020860
Node: Index1045997
+Node: Array Sorting Functions581341
+Ref: Array Sorting FunctionsFootnote1585015
+Ref: Array Sorting FunctionsFootnote2585108
+Node: Twoway I/O585302
+Ref: Twoway I/OFootnote1590734
+Node: TCP/IP Networking590804
+Node: Profiling593648
+Node: Library Functions601102
+Ref: Library FunctionsFootnote1604109
+Node: Library Names604280
+Ref: Library NamesFootnote1607751
+Ref: Library NamesFootnote2607971
+Node: General Functions608057
+Node: Strtonum Function609010
+Node: Assert Function611940
+Node: Round Function615266
+Node: Cliff Random Function616809
+Node: Ordinal Functions617825
+Ref: Ordinal FunctionsFootnote1620895
+Ref: Ordinal FunctionsFootnote2621147
+Node: Join Function621356
+Ref: Join FunctionFootnote1623127
+Node: Getlocaltime Function623327
+Node: Data File Management627042
+Node: Filetrans Function627674
+Node: Rewind Function631813
+Node: File Checking633200
+Node: Empty Files634294
+Node: Ignoring Assigns636524
+Node: Getopt Function638077
+Ref: Getopt FunctionFootnote1649381
+Node: Passwd Functions649584
+Ref: Passwd FunctionsFootnote1658559
+Node: Group Functions658647
+Node: Walking Arrays666731
+Node: Sample Programs668300
+Node: Running Examples668965
+Node: Clones669693
+Node: Cut Program670917
+Node: Egrep Program680762
+Ref: Egrep ProgramFootnote1688535
+Node: Id Program688645
+Node: Split Program692261
+Ref: Split ProgramFootnote1695780
+Node: Tee Program695908
+Node: Uniq Program698711
+Node: Wc Program706140
+Ref: Wc ProgramFootnote1710406
+Ref: Wc ProgramFootnote2710606
+Node: Miscellaneous Programs710698
+Node: Dupword Program711886
+Node: Alarm Program713917
+Node: Translate Program718666
+Ref: Translate ProgramFootnote1723053
+Ref: Translate ProgramFootnote2723281
+Node: Labels Program723415
+Ref: Labels ProgramFootnote1726786
+Node: Word Sorting726870
+Node: History Sorting730754
+Node: Extract Program732593
+Ref: Extract ProgramFootnote1740076
+Node: Simple Sed740204
+Node: Igawk Program743266
+Ref: Igawk ProgramFootnote1758423
+Ref: Igawk ProgramFootnote2758624
+Node: Anagram Program758762
+Node: Signature Program761830
+Node: Debugger762930
+Node: Debugging763896
+Node: Debugging Concepts764329
+Node: Debugging Terms766185
+Node: Awk Debugging768782
+Node: Sample Debugging Session769674
+Node: Debugger Invocation770194
+Node: Finding The Bug771523
+Node: List of Debugger Commands778011
+Node: Breakpoint Control779345
+Node: Debugger Execution Control783009
+Node: Viewing And Changing Data786369
+Node: Execution Stack789725
+Node: Debugger Info791192
+Node: Miscellaneous Debugger Commands795173
+Node: Readline Support800618
+Node: Limitations801449
+Node: Arbitrary Precision Arithmetic803701
+Ref: Arbitrary Precision ArithmeticFootnote1805342
+Node: General Arithmetic805490
+Node: Floating Point Issues807210
+Node: String Conversion Precision808091
+Ref: String Conversion PrecisionFootnote1809797
+Node: Unexpected Results809906
+Node: POSIX Floating Point Problems812059
+Ref: POSIX Floating Point ProblemsFootnote1815884
+Node: Integer Programming815922
+Node: Floatingpoint Programming817675
+Ref: Floatingpoint ProgrammingFootnote1823986
+Node: Floatingpoint Representation824250
+Node: Floatingpoint Context825415
+Ref: tableieeeformats826257
+Node: Rounding Mode827641
+Ref: tableroundingmodes828120
+Ref: Rounding ModeFootnote1831124
+Node: Gawk and MPFR831305
+Node: Arbitrary Precision Floats832546
+Ref: Arbitrary Precision FloatsFootnote1834975
+Node: Setting Precision835286
+Node: Setting Rounding Mode838019
+Ref: tablegawkroundingmodes838423
+Node: Floatingpoint Constants839603
+Node: Changing Precision841027
+Ref: Changing PrecisionFootnote1842427
+Node: Exact Arithmetic842601
+Node: Arbitrary Precision Integers845709
+Ref: Arbitrary Precision IntegersFootnote1848709
+Node: Dynamic Extensions848856
+Node: Plugin License849774
+Node: Sample Library850388
+Node: Internal File Description851072
+Node: Internal File Ops854785
+Ref: Internal File OpsFootnote1859348
+Node: Using Internal File Ops859488
+Node: Language History861864
+Node: V7/SVR3.1863386
+Node: SVR4865707
+Node: POSIX867149
+Node: BTL868157
+Node: POSIX/GNU868891
+Node: Common Extensions874426
+Node: Ranges and Locales875533
+Ref: Ranges and LocalesFootnote1880151
+Ref: Ranges and LocalesFootnote2880178
+Ref: Ranges and LocalesFootnote3880438
+Node: Contributors880659
+Node: Installation884955
+Node: Gawk Distribution885849
+Node: Getting886333
+Node: Extracting887159
+Node: Distribution contents888851
+Node: Unix Installation894073
+Node: Quick Installation894690
+Node: Additional Configuration Options896652
+Node: Configuration Philosophy898129
+Node: NonUnix Installation900471
+Node: PC Installation900929
+Node: PC Binary Installation902228
+Node: PC Compiling904076
+Node: PC Testing907020
+Node: PC Using908196
+Node: Cygwin912381
+Node: MSYS913381
+Node: VMS Installation913895
+Node: VMS Compilation914498
+Ref: VMS CompilationFootnote1915505
+Node: VMS Installation Details915563
+Node: VMS Running917198
+Node: VMS Old Gawk918805
+Node: Bugs919279
+Node: Other Versions923131
+Node: Notes928446
+Node: Compatibility Mode929033
+Node: Additions929816
+Node: Accessing The Source930743
+Node: Adding Code932168
+Node: New Ports938176
+Node: Derived Files942311
+Ref: Derived FilesFootnote1947615
+Ref: Derived FilesFootnote2947649
+Ref: Derived FilesFootnote3948249
+Node: Future Extensions948347
+Node: Basic Concepts949834
+Node: Basic High Level950515
+Ref: Basic High LevelFootnote1954550
+Node: Basic Data Typing954735
+Node: Glossary958090
+Node: Copying983066
+Node: GNU Free Documentation License1020623
+Node: Index1045760
End Tag Table
diff git a/doc/gawk.texi b/doc/gawk.texi
index d700f2a..19cc407 100644
 a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ 18808,7 +18808,7 @@ Running the program produces the
following output:
@example
$ @kbd{gawk vPOS=1 F: f sort.awk /etc/passwd}
+$ @kbd{gawk v POS=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
@@ 26752,7 +26752,7 @@ the general atributes of computer arithmetic, along
with how
this can influence what you see when running @command{awk} programs.
This discussion applies to all versions of @command{awk}.
Then the discussion moves on to @dfn{arbitrary precsion
+Then the @value{CHAPTER} moves on to @dfn{arbitrary precsion
arithmetic}, a feature which is specific to @command{gawk}.
@menu
@@ 26816,10 +26816,7 @@ There a several important issues to be aware of,
described next.
@node Floating Point Issues
@subsection FloatingPoint Number Caveats
As mentioned earlier, floatingpoint numbers represent what are called
``real'' numbers, i.e., those that have a fractional part. @command{awk}
uses double precision floatingpoint numbers to represent all
numeric values. This @value{SECTION} describes some of the issues
+This @value{SECTION} describes some of the issues
involved in using floatingpoint numbers.
There is a very nice
@@ 27062,7 +27059,7 @@ Thus @samp{+nan} and @samp{+NaN} are the same.
As has been mentioned already, @command{gawk} ordinarily uses hardware double
precision with 64bit IEEE binary floatingpoint representation
for numbers on most systems. A large integer like 9007199254740997
+for numbers on most systems. A large integer like 9,007,199,254,740,997
has a binary representation that, although finite, is more than 53 bits long;
it must also be rounded to 53 bits.
The biggest integer that can be stored in a C @code{double} is usually the same
@@ 27127,7 +27124,7 @@ sophisticated numerical algorithms then @command{gawk}
may not be
the ideal tool, and this documentation may not be sufficient.
@c FIXME: JOHN: Do you want to cite some actual books?
It might require digesting a book or two to really internalize how to compute
with ideal accuracy and precision
+with ideal accuracy and precision,
and the result often depends on the particular application.
@quotation NOTE
@@ 27141,7 +27138,8 @@ the Wikipedia article} for more information).
There are two options for doing floatingpoint calculations:
hardware floatingpoint (as used by standard @command{awk} and
the default for @command{gawk}), and @dfn{arbitraryprecision}
floatingpoint, which is software based. This @value{CHAPTER}
+floatingpoint, which is software based.
+From this point forward, this @value{CHAPTER}
aims to provide enough information to understand both, and then
will focus on @command{gawk}'s facilities for the address@hidden you
are interested in other tools that perform arbitrary precision arithmetic,
@@ 27189,7 +27187,7 @@ you can always specify how much precision you would
like in your output.
Usually this is a format string like @code{"%.15g"}, which when
used in the previous example, produces an output identical to the input.
Because the underlying representation can be little bit off from the exact
value,
+Because the underlying representation can be a little bit off from the exact
value,
comparing floatingpoint values to see if they are equal is generally not a
good idea.
Here is an example where it does not work like you expect:
@@ 27233,7 +27231,7 @@ $ @kbd{gawk f pi.awk}
@error{} gawk: pi.awk:6: fatal: division by zero attempted
@end example
Here is one more example where the inaccuracies in internal representations
+Here is an additional example where the inaccuracies in internal
representations
yield an unexpected result:
@example
@@ 27278,13 +27276,15 @@ $ @kbd{gawk f /tmp/pi2.awk}
There is no need to be unduly suspicious about the results from
floatingpoint arithmetic. The lesson to remember is that
floatingpoint arithmetic is always more complex than the arithmetic using
+floatingpoint arithmetic is always more complex than arithmetic using
pencil and paper. In order to take advantage of the power
of computer floatingpoint, you need to know its limitations
and work within them. For most casual use of floatingpoint arithmetic,
you will often get the expected result in the end if you simply round
the display of your final results to the correct number of significant
decimal digits. And, avoid presenting numerical data in a manner that
+decimal digits.
+
+As general advice, avoid presenting numerical data in a manner that
implies better precision than is actually the case.
@menu
@@ 27306,7 +27306,7 @@ IEEE 754 Standard. An IEEE754 format value has three
components:
A sign bit telling whether the number is positive or negative.
@item
An @dfn{exponent} giving its order of magnitude, @var{e}.
+An @dfn{exponent}, @var{e}, giving its order of magnitude.
@item
A @dfn{significand}, @var{s},
@@ 27324,15 +27324,14 @@ number is then
The first bit of a nonzero binary significand
is always one, so the significand in an IEEE754 format only includes the
fractional part, leaving the leading one implicit.
+The significand is stored in @dfn{normalized} format,
+which means that the first bit is always a one.
Three of the standard IEEE754 types are 32bit single precision,
64bit double precision and 128bit quadruple precision.
The standard also specifies extended precision formats
to allow greater precisions and larger exponent ranges.
The significand is stored in @dfn{normalized} format,
which means that the first bit is always a one.

@node Floatingpoint Context
@subsection Floatingpoint Context
@cindex context, floatingpoint
@@ 27533,23 +27532,21 @@ in general, and the limitations of doing arithmetic
with ordinary
@command{gawk} uses the GNU MPFR library
for arbitrary precision floatingpoint arithmetic. The MPFR library
provides precise control over precisions and rounding modes, and gives
correctly rounded reproducible platformindependent results. With the
+correctly rounded, reproducible, platformindependent results. With the
commandline option @option{bignum} or @option{M},
all floatingpoint arithmetic operators and numeric functions can yield
results to any desired precision level supported by MPFR.
Two builtin
variables @code{PREC}
(@pxref{Setting Precision})
and @code{ROUNDMODE}
(@pxref{Setting Rounding Mode})
provide control over the working precision and the rounding mode.
+Two builtin variables, @code{PREC} and @code{ROUNDMODE},
+provide control over the working precision and the rounding mode
+(@pxref{Setting Precision}, and
address@hidden Rounding Mode}).
The precision and the rounding mode are set globally for every operation
to follow.
The default working precision for arbitrary precision floatingpoint values is
53,
and the default value for @code{ROUNDMODE} is @code{"N"},
which selects the IEEE754
address@hidden (@pxref{Rounding Mode}) rounding address@hidden
+which selects the IEEE754 @code{roundTiesToEven} rounding mode
+(@pxref{Rounding Mode})address@hidden
default precision is 53, since according to the MPFR documentation,
the library should be able to exactly reproduce all computations with
doubleprecision machine floatingpoint numbers (@code{double} type
@@ 27597,7 +27594,7 @@ your program.
@command{gawk} uses a global working precision; it does not keep track of
the precision or accuracy of individual numbers. Performing an arithmetic
operation or calling a builtin function rounds the result to the current
working precision. The default working precision is 53 which can be
+working precision. The default working precision is 53, which can be
modified using the builtin variable @code{PREC}. You can also set the
value to one of the following predefined caseinsensitive strings
to emulate an IEEE754 binary format:
@@ 27615,13 +27612,13 @@ The following example illustrates the effects of
changing precision
on arithmetic operations:
@example
$ @kbd{gawk M vPREC=100 'BEGIN @{ x = 1.0e400; print x + 0; \}
+$ @kbd{gawk M v PREC=100 'BEGIN @{ x = 1.0e400; print x + 0; \}
> @kbd{PREC = "double"; print x + 0 @}'}
@print{} 1e400
@print{} 0
@end example
Binary and decimal precisions are related approximately according to the
+Binary and decimal precisions are related approximately, according to the
formula:
@iftex
@@ 27657,6 +27654,7 @@ significant digits in them.
Conversely, it takes a precision of 332 bits to hold an approximation
of the constant @value{PI} that is accurate to 100 decimal places.
+
You should always add some extra bits in order to avoid the confusing roundoff
issues that occur because numbers are stored internally in binary.
@@ 27683,9 +27681,8 @@ rounding modes is shown in
@ref{tablegawkroundingmodes}.
@code{ROUNDMODE} has the default value @code{"N"},
which selects the IEEE754 rounding mode @code{roundTiesToEven}.
Besides the values listed in @ref{tablegawkroundingmodes},
address@hidden also accepts @code{"A"} to select the IEEE754 mode
address@hidden
address@hidden, lists @code{"A"} to select the IEEE754 mode
address@hidden This is only available
if your version of the MPFR library supports it; otherwise setting
@code{ROUNDMODE} to this value has no effect. @xref{Rounding Mode},
for the meanings of the various rounding modes.
@@ 27694,7 +27691,7 @@ Here is an example of how to change the default
rounding behavior of
@code{printf}'s output:
@example
$ @kbd{gawk M vROUNDMODE="Z" 'BEGIN @{ printf("%.2f\n", 1.378) @}'}
+$ @kbd{gawk M v ROUNDMODE="Z" 'BEGIN @{ printf("%.2f\n", 1.378) @}'}
@print{} 1.37
@end example
@@ 27708,18 +27705,18 @@ unless overridden
by an assignment to the special variable @code{PREC} on the command
line, to store it internally as a MPFR number.
Changing the precision using @code{PREC} in the program text does
not change the precision of a constant. If you need to
address@hidden change the precision of a constant. If you need to
represent a floatingpoint constant at a higher precision than the
default and cannot use a command line assignment to @code{PREC},
you should either specify the constant as a string, or
as a rational number whenever possible. The following example
+as a rational number, whenever possible. The following example
illustrates the differences among various ways to
print a floatingpoint constant:
@example
$ @kbd{gawk M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 0.1) @}'}
@print{} 0.1000000000000000055511151
$ @kbd{gawk M vPREC = 113 'BEGIN @{ printf("%0.25f\n", 0.1) @}'}
+$ @kbd{gawk M v PREC=113 'BEGIN @{ printf("%0.25f\n", 0.1) @}'}
@print{} 0.1000000000000000000000000
$ @kbd{gawk M 'BEGIN @{ PREC = 113; printf("%0.25f\n", "0.1") @}'}
@print{} 0.1000000000000000000000000
@@ 27793,7 +27790,7 @@ You can get the result you want by increasing the
precision;
56 in this case will get the job done:
@example
$ @kbd{gawk M vPREC=56 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'}
+$ @kbd{gawk M v PREC=56 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'}
@print{} 1
@end example
@@ 27802,7 +27799,7 @@ precision is better?
Here is what happens if we use an even larger value of @code{PREC}:
@example
$ @kbd{gawk M vPREC=201 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'}
+$ @kbd{gawk M v PREC=201 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'}
@print{} 0
@end example
@@ 27824,7 +27821,7 @@ In applications where 15 or fewer decimal places
suffice,
hardware double precision arithmetic can be adequate, and is usually much
faster.
But you do need to keep in mind that every floatingpoint operation
can suffer a new rounding error with catastrophic consequences as illustrated
by our attempt to compute the value of the constant @value{PI}
+by our earlier attempt to compute the value of the constant @value{PI}
(@pxref{Floatingpoint Programming}).
Extra precision can greatly enhance the stability and the accuracy
of your computation in such cases.
@@ 27890,8 +27887,6 @@ would be @math{3.322 @cdot 183231},
would be 3.322 x 183231,
@end ifnottex
or 608693.
(Thus, the floatingpoint representation requires over 30 times as
many decimal digits!)
The result from an arithmetic operation with an integer and a floatingpoint
value
is a floatingpoint value with a precision equal to the working precision.
@@ 27911,7 +27906,7 @@ $ @kbd{gawk M 'BEGIN @{}
@print{} 113423713055421845118910464
@end example
The output differs from the acutal number, 113423713055421844361000443,
+The output differs from the actual number, 113,423,713,055,421,844,361,000,443,
because the default precision of 53 is not enough to represent the
floatingpoint results exactly. You can either increase the precision
(100 is enough in this case), or replace the floatingpoint constant

Summary of changes:
doc/ChangeLog  5 +
doc/gawk.info  487 ++++++++++++++++++++++++++++
doc/gawk.texi  79 +++++
3 files changed, 284 insertions(+), 287 deletions()
hooks/postreceive

gawk
[Prev in Thread] 
Current Thread 
[Next in Thread] 
 [gawkdiffs] [SCM] gawk branch, master, updated. 1ef98b7f216198b5c17b516642eded9d3ef7c6b2,
Arnold Robbins <=