PATCH: pws-21: arithmetic documentation

[Peter Stephenson <pws@xxxxxxxxxxxxxxxxx>]

--- Doc/Zsh/arith.yo.rw	Thu Dec 17 17:10:13 1998
+++ Doc/Zsh/arith.yo	Fri Jun 11 10:58:47 1999
@@ -5,16 +5,42 @@
 )\
 cindex(arithmetic evaluation)
 cindex(evaluation, arithmetic)
-An ability to perform integer arithmetic is provided with the builtin tt(let).
 findex(let, use of)
-Evaluations are performed using em(long) arithmetic.
+The shell can perform integer arithmetic, either using the builtin tt(let),
+or via a substitution of the form tt($((...))).  Usually arithmetic is
+performed with em(long) integers; however, on certain systems where a
+em(long) has 4-byte precision, zsh may be compiled to use 8-byte precision
+instead.  This can be tested, for example, by giving the command
+`tt(print - $(( 12345678901 )))'; if the number appears unchanged, the
+precision is at least 8 bytes.
+
+The tt(let) builtin command takes arithmetic expressions as arguments; each
+is evaluated separately.  Since many of the arithmetic operators, as well
+as spaces, require quoting, an alternative form is provided: for any
+command which begins with a `tt(LPAR()LPAR())', all the characters until a
+matching `tt(RPAR()RPAR())' are treated as a quoted expression and
+arithmetic expansion performed as for an argument of tt(let).  More
+precisely, `tt(LPAR()LPAR())var(...)tt(RPAR()RPAR())' is equivalent to
+`tt(let ")var(...)tt(")'.  For example, the following statement
+
+nofill(tt((( val = 2 + 1 ))))
+
+is equivalent to
+
+nofill(tt(let "val = 2 + 1"))
+
+both assigning the value 3 to the shell variable tt(foo) and returning a
+zero status.
+
+cindex(bases, in arithmetic)
+Numbers can be in bases other than 10.
 A leading `tt(0x)' or `tt(0X)' denotes hexadecimal.
-Otherwise, numbers are of the form `[var(base)tt(#)]var(n)',
+Numbers may also be of the form `var(base)tt(#)var(n)',
 where var(base) is a decimal number between two and thirty-six
 representing the arithmetic base and var(n)
 is a number in that base (for example, `tt(16#ff)' is 255 in hexadecimal).
-If var(base) is omitted
-then base 10 is used.  For backwards compatibility the form
+The var(base)tt(#) may also be omitted, in which case
+base 10 is used.  For backwards compatibility the form
 `tt([)var(base)tt(])var(n)' is also accepted.
 
 cindex(arithmetic operators)
@@ -50,10 +76,15 @@
 An expression of the form `tt(#\)var(x)' where var(x) is any character
 gives the ascii value of this character and an expression of the form
 `tt(#)var(foo)' gives the ascii value of the first character of the value
+of the parameter var(foo).  Note that this is different from the expression
+`tt($#)var(foo)', a standard parameter substitution which gives the length
 of the parameter var(foo).
 
 Named parameters and subscripted arrays can be referenced by name within an
-arithmetic expression without using the parameter expansion syntax.
+arithmetic expression without using the parameter expansion syntax.  For
+example,
+nofill(tt(((val2 = val1 * 2))))
+assigns twice the value of tt($val1) to the parameter named tt(val2).
 
 An internal integer representation of a named parameter
 can be specified with the tt(integer) builtin.
@@ -63,11 +94,3 @@
 Arithmetic evaluation is performed on the value of each
 assignment to a named parameter declared integer
 in this manner.
-
-Since many of the arithmetic operators require
-quoting, an alternative form of the tt(let) command is provided.
-For any command which begins with a tt(LPAR()LPAR()),
-all the characters until a matching tt(RPAR()RPAR())
-are treated as a quoted expression.
-More precisely, `tt(LPAR()LPAR()) ... tt(RPAR()RPAR())'
-is equivalent to `tt(let ")...tt(")'.

-- 
Peter Stephenson <pws@xxxxxxxxxxxxxxxxx>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy