Mercurial > hg > xemacs-beta
annotate man/lispref/numbers.texi @ 5903:5afddd952c46
Return ratios in canonical form too, #'string-to-number
src/ChangeLog addition:
2015-05-08 Aidan Kehoe <kehoea@parhasard.net>
* data.c (Fstring_to_number):
Canonicalise ratios in this function, as we do bignums.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Fri, 08 May 2015 13:58:22 +0100 |
| parents | 9fae6227ede5 |
| children | 6174848f3e6c |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
| 428 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../../info/numbers.info | |
| 6 @node Numbers, Strings and Characters, Lisp Data Types, Top | |
| 7 @chapter Numbers | |
| 2090 | 8 @c #### Improve the indexing in this file!!!! |
| 428 | 9 @cindex integers |
| 10 @cindex numbers | |
| 11 | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
12 XEmacs supports two to five numeric data types. @dfn{Fixnums} and |
| 2028 | 13 @dfn{floating point numbers} are always supported. As a build-time |
| 14 option, @dfn{bignums}, @dfn{ratios}, and @dfn{bigfloats} may be | |
| 15 enabled on some platforms. | |
| 16 | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
17 Fixnums (called just @dfn{integers} in GNU Emacs and older versions |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
18 of XEmacs) are whole numbers such as @minus{}3, 0, #b0111, #xFEED, |
| 2028 | 19 #o744. Their values are exact, and their range is limited. The |
| 428 | 20 number prefixes `#b', `#o', and `#x' are supported to represent numbers |
| 21 in binary, octal, and hexadecimal notation (or radix). Floating point | |
| 22 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or | |
| 23 2.71828. They can also be expressed in exponential notation: 1.5e2 | |
| 24 equals 150; in this example, @samp{e2} stands for ten to the second | |
| 25 power, and is multiplied by 1.5. Floating point values are not exact; | |
| 26 they have a fixed, limited amount of precision. | |
| 27 | |
| 2028 | 28 Bignums are arbitrary precision integers. When supported, XEmacs can |
| 29 handle any integral calculations you have enough virtual memory to | |
| 30 store. (More precisely, on current architectures the representation | |
| 31 allows integers whose storage would exhaust the address space.) They | |
| 32 are notated in the same way as other integers (fixnums). XEmacs | |
| 33 automatically converts results of computations from fixnum to bignum, | |
| 34 and back, depending on the storage required to represent the number. | |
| 35 Thus use of bignums are entirely transparent to the user, except for a | |
| 36 few special applications that expect overflows. Ratios are rational | |
| 2090 | 37 numbers with arbitrary precision. They are notated in the |
| 38 usual way with the solidus, for example 5/3 or @minus{}22/7. | |
| 39 | |
| 40 Bigfloats are floating point numbers with arbitrary precision, which | |
| 41 may be specified by the user (and may be different for different | |
| 42 bigfloats at the same time). Unlike integers, which are always | |
| 43 infinitely precise if they can be represented, floating point numbers | |
| 44 are inherently imprecise. This means that choice of precision can be a | |
| 45 very delicate issue. XEmacs automatically converts @emph{from float to | |
| 46 bigfloat} when floats and bigfloats are mixed in an expression, but a | |
| 47 bigfloat will never be converted to a float unless the user explicitly | |
| 48 coerces the value. Nor will the result of a float operation be | |
| 49 converted to bigfloat, except for ``contagion'' from another operand | |
| 50 that is already a bigfloat. However, when bigfloats of differing | |
| 51 precision are mixed, the result will always have the larger precision. | |
| 52 The exact rules are more carefully explained elsewhere | |
| 53 (@pxref{Canonicalization and Contagion}). | |
| 2028 | 54 |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
55 Common Lisp terminology and historical Emacs terminology conflict |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
56 here, to an extent. We attempt to use ``fixnum'' and ``integer'' |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
57 consistently, but older XEmacs and GNU Emacs code and documentation use |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
58 the latter to mean the former. ``Float'' is used in Emacs documentation |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
59 to mean ``fixed precision floating point number'', and the Common Lisp |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
60 distinctions among @dfn{short-floats}, @dfn{long-floats}, @emph{etc.}, |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
61 and bigfloats (which are not standardized in Common Lisp) are not |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
62 reflected in XEmacs terminology. We're working on this, but volunteers |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
63 to fix it in the XEmacs manuals would be heartily welcomed. |
| 2028 | 64 |
| 428 | 65 @menu |
| 66 * Integer Basics:: Representation and range of integers. | |
| 2028 | 67 * Rational Basics:: Representation and range of rational numbers. |
| 68 * Float Basics:: Representation and range of floating point. | |
| 69 * The Bignum Extension:: Arbitrary precision integers, ratios, and floats. | |
| 428 | 70 * Predicates on Numbers:: Testing for numbers. |
| 71 * Comparison of Numbers:: Equality and inequality predicates. | |
| 2028 | 72 * Numeric Conversions:: Converting float to integer and vice versa. |
| 428 | 73 * Arithmetic Operations:: How to add, subtract, multiply and divide. |
| 74 * Rounding Operations:: Explicitly rounding floating point numbers. | |
| 75 * Bitwise Operations:: Logical and, or, not, shifting. | |
| 76 * Math Functions:: Trig, exponential and logarithmic functions. | |
| 77 * Random Numbers:: Obtaining random integers, predictable or not. | |
| 78 @end menu | |
| 79 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
80 @node Integer Basics, Rational Basics, Numbers, Numbers |
| 428 | 81 @section Integer Basics |
| 82 | |
| 2028 | 83 The range of values for an integer depends on the machine. If a |
| 84 multiple-precision arithmetic library is available on your platform, | |
| 2090 | 85 support for bignums, that is, integers with arbitrary precision, may be |
| 2028 | 86 compiled in to your XEmacs. The rest of this section assumes that the |
| 87 bignum extension is @emph{not} available. The bignum extension and the | |
| 88 user-visible differences in normal integer arithmetic are discussed in a | |
| 89 separate section @ref{The Bignum Extension}. | |
| 90 | |
| 91 The minimum range is @minus{}1073741824 to 1073741823 (31 bits; i.e., | |
| 444 | 92 @ifinfo |
| 2028 | 93 -2**30 |
| 428 | 94 @end ifinfo |
| 444 | 95 @tex |
| 2028 | 96 $-2^{30}$ |
| 428 | 97 @end tex |
| 444 | 98 to |
| 99 @ifinfo | |
| 2028 | 100 2**30 - 1), |
| 428 | 101 @end ifinfo |
| 444 | 102 @tex |
| 2028 | 103 $2^{30}-1$), |
| 428 | 104 @end tex |
| 105 but some machines may provide a wider range. Many examples in this | |
| 2028 | 106 chapter assume an integer has 31 bits. |
| 428 | 107 @cindex overflow |
| 108 | |
| 2028 | 109 The range of fixnums is available to Lisp programs: |
| 110 | |
| 111 @defvar most-positive-fixnum | |
| 112 The fixed-precision integer closest in value to positive infinity. | |
| 113 @end defvar | |
| 114 | |
| 115 @defvar most-negative-fixnum | |
| 116 The fixed-precision integer closest in value to negative infinity. | |
| 117 @end defvar | |
| 118 | |
| 119 Here is a common idiom to temporarily suppress garbage collection: | |
| 120 @example | |
| 121 (garbage-collect) | |
| 122 (let ((gc-cons-threshold most-positive-fixnum)) | |
| 123 ;; allocation-intensive computation | |
| 124 ) | |
| 125 (garbage-collect) | |
| 126 @end example | |
| 127 | |
| 428 | 128 The Lisp reader reads an integer as a sequence of digits with optional |
| 129 initial sign and optional final period. | |
| 130 | |
| 131 @example | |
| 132 1 ; @r{The integer 1.} | |
| 133 1. ; @r{The integer 1.} | |
| 134 +1 ; @r{Also the integer 1.} | |
| 135 -1 ; @r{The integer @minus{}1.} | |
| 2028 | 136 2147483648 ; @r{Read error, due to overflow.} |
| 428 | 137 0 ; @r{The integer 0.} |
| 138 -0 ; @r{The integer 0.} | |
| 139 @end example | |
| 140 | |
| 141 To understand how various functions work on integers, especially the | |
| 142 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to | |
| 143 view the numbers in their binary form. | |
| 144 | |
| 2028 | 145 In 31-bit binary, the decimal integer 5 looks like this: |
| 428 | 146 |
| 147 @example | |
| 2028 | 148 000 0000 0000 0000 0000 0000 0000 0101 |
| 428 | 149 @end example |
| 150 | |
| 151 @noindent | |
| 152 (We have inserted spaces between groups of 4 bits, and two spaces | |
| 153 between groups of 8 bits, to make the binary integer easier to read.) | |
| 154 | |
| 155 The integer @minus{}1 looks like this: | |
| 156 | |
| 157 @example | |
| 2028 | 158 111 1111 1111 1111 1111 1111 1111 1111 |
| 428 | 159 @end example |
| 160 | |
| 161 @noindent | |
| 162 @cindex two's complement | |
| 2028 | 163 @minus{}1 is represented as 31 ones. (This is called @dfn{two's |
| 428 | 164 complement} notation.) |
| 165 | |
| 166 The negative integer, @minus{}5, is creating by subtracting 4 from | |
| 167 @minus{}1. In binary, the decimal integer 4 is 100. Consequently, | |
| 168 @minus{}5 looks like this: | |
| 169 | |
| 170 @example | |
| 2028 | 171 111 1111 1111 1111 1111 1111 1111 1011 |
| 428 | 172 @end example |
| 173 | |
| 2028 | 174 In this implementation, the largest 31-bit binary integer is the |
| 175 decimal integer 1,073,741,823. In binary, it looks like this: | |
| 428 | 176 |
| 177 @example | |
| 2028 | 178 011 1111 1111 1111 1111 1111 1111 1111 |
| 428 | 179 @end example |
| 180 | |
| 181 Since the arithmetic functions do not check whether integers go | |
| 2028 | 182 outside their range, when you add 1 to 1,073,741,823, the value is the |
| 183 negative integer @minus{}1,073,741,824: | |
| 428 | 184 |
| 185 @example | |
| 2028 | 186 (+ 1 1073741823) |
| 187 @result{} -1073741824 | |
| 188 @result{} 100 0000 0000 0000 0000 0000 0000 0000 | |
| 428 | 189 @end example |
| 190 | |
| 2028 | 191 Many of the arithmetic functions accept markers for arguments as well |
| 428 | 192 as integers. (@xref{Markers}.) More precisely, the actual arguments to |
| 193 such functions may be either integers or markers, which is why we often | |
| 194 give these arguments the name @var{int-or-marker}. When the argument | |
| 195 value is a marker, its position value is used and its buffer is ignored. | |
| 196 | |
| 197 @ignore | |
| 198 In version 19, except where @emph{integer} is specified as an | |
| 199 argument, all of the functions for markers and integers also work for | |
| 200 floating point numbers. | |
| 201 @end ignore | |
| 202 | |
| 2028 | 203 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
204 @node Rational Basics, Float Basics, Integer Basics, Numbers |
| 2032 | 205 @section Rational Basics |
| 2028 | 206 |
| 207 Ratios (built-in rational numbers) are available only when the bignum | |
| 208 extension is built into your XEmacs. This facility is new and | |
| 209 experimental. It is discussed in a separate section for convenience of | |
| 2090 | 210 updating the documentation @ref{The Bignum Extension}. The following |
| 211 functions are defined regardless of the presence of the extension, but | |
| 212 have trivial results for integers. | |
| 213 | |
| 214 @defun numerator rational | |
| 215 @cindex numbers | |
| 216 Return the numerator of the canonical form of @var{rational}. | |
| 217 If @var{rational} is an integer, @var{rational} is returned. | |
| 218 @var{rational} must be an integer or a ratio. | |
| 219 @end defun | |
| 220 | |
| 221 @defun denominator rational | |
| 222 Return the denominator of the canonical form of @var{rational}. | |
| 223 If @var{rational} is an integer, 1 is returned. @var{rational} must be | |
| 224 an integer or a ratio. | |
| 225 @end defun | |
| 2028 | 226 |
| 227 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
228 @node Float Basics, The Bignum Extension, Rational Basics, Numbers |
| 428 | 229 @section Floating Point Basics |
| 230 | |
| 231 XEmacs supports floating point numbers. The precise range of floating | |
| 232 point numbers is machine-specific; it is the same as the range of the C | |
| 2028 | 233 data type @code{double} on the machine in question. If a |
| 234 multiple-precision arithmetic library is available on your platform, | |
| 235 support for bigfloats, that is, floating point numbers with arbitrary | |
| 2090 | 236 precision, may be compiled in to your XEmacs. The rest of this section |
| 2028 | 237 assumes that the bignum extension is @emph{not} available. The bigfloat |
| 238 extension and the user-visible differences in normal float arithmetic | |
| 239 are discussed in a separate section @ref{The Bignum Extension}. | |
| 428 | 240 |
| 241 The printed representation for floating point numbers requires either | |
| 242 a decimal point (with at least one digit following), an exponent, or | |
| 243 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, | |
| 244 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point | |
| 245 number whose value is 1500. They are all equivalent. You can also use | |
| 246 a minus sign to write negative floating point numbers, as in | |
| 247 @samp{-1.0}. | |
| 248 | |
| 249 @cindex IEEE floating point | |
| 250 @cindex positive infinity | |
| 251 @cindex negative infinity | |
| 252 @cindex infinity | |
| 253 @cindex NaN | |
| 254 Most modern computers support the IEEE floating point standard, which | |
| 255 provides for positive infinity and negative infinity as floating point | |
| 256 values. It also provides for a class of values called NaN or | |
| 257 ``not-a-number''; numerical functions return such values in cases where | |
| 258 there is no correct answer. For example, @code{(sqrt -1.0)} returns a | |
| 259 NaN. For practical purposes, there's no significant difference between | |
| 260 different NaN values in XEmacs Lisp, and there's no rule for precisely | |
| 261 which NaN value should be used in a particular case, so this manual | |
| 262 doesn't try to distinguish them. XEmacs Lisp has no read syntax for NaNs | |
| 263 or infinities; perhaps we should create a syntax in the future. | |
| 264 | |
| 265 You can use @code{logb} to extract the binary exponent of a floating | |
| 266 point number (or estimate the logarithm of an integer): | |
| 267 | |
| 268 @defun logb number | |
| 269 This function returns the binary exponent of @var{number}. More | |
| 270 precisely, the value is the logarithm of @var{number} base 2, rounded | |
| 271 down to an integer. | |
| 272 @end defun | |
| 273 | |
| 2028 | 274 The range of floats is available to Lisp programs: |
| 275 | |
| 276 @defvar most-positive-float | |
| 277 The fixed-precision floating-point-number closest in value to positive | |
| 278 infinity. | |
| 279 @end defvar | |
| 280 | |
| 281 @defvar most-negative-float | |
| 282 The fixed-precision floating point number closest in value to negative | |
| 283 infinity. | |
| 284 @end defvar | |
| 285 | |
| 286 @defvar least-positive-float | |
| 287 The positive float closest in value to 0. May not be normalized. | |
| 288 @end defvar | |
| 289 | |
| 290 @defvar least-negative-float | |
| 291 The positive float closest in value to 0. Must be normalized. | |
| 292 @end defvar | |
| 293 | |
| 294 @defvar least-positive-normalized-float | |
| 295 The negative float closest in value to 0. May not be normalized. | |
| 296 @end defvar | |
| 297 | |
| 298 @defvar least-negative-normalized-float | |
| 299 The negative float closest in value to 0. Must be normalized. | |
| 300 @end defvar | |
| 301 | |
| 302 Note that for floating point numbers there is an interesting limit on | |
| 303 how small they can get, as well as a limit on how big they can get. In | |
| 304 some representations, a floating point number is @dfn{normalized} if the | |
| 305 leading digit is non-zero. This allows representing numbers smaller | |
| 306 than the most-negative exponent can express, by having fractional | |
| 307 mantissas. This means that the number is less precise than a normalized | |
| 308 floating point number, so Lisp programs can detect loss of precision due | |
| 309 to unnormalized floats by checking whether the number is between | |
| 310 @code{least-positive-float} and @code{least-positive-normalized-float}. | |
| 311 | |
| 312 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
313 @node The Bignum Extension, Predicates on Numbers, Float Basics, Numbers |
| 2028 | 314 @section The Bignum Extension |
| 315 | |
| 316 In XEmacs 21.5.18, an extension was added by @email{james@@xemacs.org, | |
| 317 Jerry James} to allow linking with arbitrary-precision arithmetic | |
| 318 libraries if they are available on your platform. ``Arbitrary'' | |
| 319 precision means precisely what it says. Your ability to work with large | |
| 320 numbers is limited only by the amount of virtual memory (and time) you | |
| 321 can throw at them. | |
| 322 | |
|
5739
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
323 XEmacs supports the GNU Multiple Precision arithmetic library (GMP), |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
324 the Multiple Precision Integers and Rationals library (MPIR), and the |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
325 BSD Multiple Precision arithmetic library (MP). To enable bignum |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
326 support using GMP, MPIR, or MP, invoke configure with your usual options |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
327 and add @samp{--use-number-lib=gmp}, @samp{--use-number-lib=mpir}, or |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
328 @samp{--use-number-lib=mp}, respectively. The default is to disable |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
329 bignum support, but if you are using a script to automate the build |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
330 process, it may be convenient to explicitly disable support by |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
331 @emph{appending} @samp{--use-number-lib=no} to your invocation of |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
332 configure. GMP has an MP compatibility mode, but it is not recommended, |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
333 as there remain poorly understood bugs (even more so than for other |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
334 vendors' versions of MP). |
| 2028 | 335 |
|
5739
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
336 With GMP and MPIR, exact arithmetic with integers and ratios of |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
337 arbitrary precision and approximate (``floating point'') arithmetic of |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
338 arbitrary precision are implemented efficiently in the library. (Note |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
339 that numerical implementations are quite delicate and sensitive to |
| 2028 | 340 optimization. If the library was poorly optimized for your hardware, as |
| 341 is often the case with Linux distributions for 80x86, you may achieve | |
| 342 gains of @emph{several orders of magnitude} by rebuilding the MP | |
|
5739
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
343 library. See @uref{http://gmplib.org/gmpbench.html}.) The MP |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
344 implementation provides arbitrary precision integers. Ratios and |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
345 arbitrary precision floats are not available with MP. |
| 2028 | 346 |
| 2033 | 347 If your code needs to run correctly whether or not the feature is |
| 348 provided, you may test for the features @code{bignum}, @code{ratio}, and | |
| 349 @code{bigfloat}. | |
| 350 | |
| 2090 | 351 The XEmacs bignum facility implements the Common Lisp notions of |
| 352 @dfn{canonicalization} and @dfn{contagion}. Canonicalization means that | |
| 353 in exact (integer and ratio) arithmetic, a result of an operation is | |
| 354 always converted to the ``smallest'' type that can represent it | |
| 355 exactly. For exact numbers, the user only cares if efficiency is | |
| 356 extremely important; Lisp does not try to determine an order of | |
| 357 computation that avoids conversion to bignum (or ratio) even if one is | |
| 358 available. (Note that integers are never silently converted to | |
| 359 ratios: the result of @code{(/ 1 2)} is the integer @code{0}. You can | |
| 360 @emph{request} that a ratio be used if needed with @code{(div 1 2)}.) | |
| 361 | |
| 362 Since floating point arithmetic is inherently imprecise, numbers are | |
| 363 implicitly coerced to bigfloats only if other operands in the expression | |
| 364 are bigfloat, and bigfloats are only coerced to other numerical types by | |
| 365 explicit calls to the function @code{coerce}. | |
| 2028 | 366 |
| 367 @menu | |
| 368 * Bignum Basics:: Representation and range of integers. | |
| 369 * Ratio Basics:: Representation and range of rational numbers. | |
| 370 * Bigfloat Basics:: Representation and range of floating point. | |
| 2090 | 371 * Canonicalization and Contagion:: Automatic coercion to other types. |
| 2028 | 372 * Compatibility Issues:: Changes in fixed-precision arithmetic. |
| 373 @end menu | |
| 374 | |
| 375 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
376 @node Bignum Basics, Ratio Basics, The Bignum Extension, The Bignum Extension |
| 2028 | 377 @subsection Bignum Basics |
| 378 | |
| 379 In most cases, bignum support should be transparent to users and Lisp | |
| 380 programmers. A bignum-enabled XEmacs will automatically convert from | |
|
5739
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
381 fixnums to bignums and back in pure integer arithmetic, and for GMP and |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
382 MPIR, from floats to bigfloats. (Bigfloats must be explicitly coerced |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
383 to other types, even if they are exactly representable by less precise |
| 2028 | 384 types.) The Lisp reader and printer have been enhanced to handle |
| 385 bignums, as have the mathematical functions. Rationals (fixnums, | |
| 386 bignums, and ratios) are printed using the @samp{%d}, @samp{%o}, | |
| 387 @samp{%x}, and @samp{%u} format conversions. | |
| 388 | |
| 389 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
390 @node Ratio Basics, Bigfloat Basics, Bignum Basics, The Bignum Extension |
| 2028 | 391 @subsection Ratio Basics |
| 392 | |
|
5739
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
393 Ratios, when available, have the read syntax and print representation |
| 2028 | 394 @samp{3/5}. Like other rationals (fixnums and bignums), they are |
| 395 printed using the @samp{%d}, @samp{%o}, @samp{%x}, and @samp{%u} format | |
| 396 conversions. | |
| 397 | |
| 398 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
399 @node Bigfloat Basics, Canonicalization and Contagion, Ratio Basics, The Bignum Extension |
| 2028 | 400 @subsection Bigfloat Basics |
| 401 | |
| 402 Bigfloats, when available, have the same read syntax and print | |
| 403 representations as fixed-precision floats. | |
| 404 | |
| 2182 | 405 It is possible to make bigfloat the default floating point format by |
| 406 setting @code{default-float-precision} to a non-zero value. Precision | |
|
4678
b5e1d4f6b66f
Make #'floor, #'ceiling, #'round, #'truncate conform to Common Lisp.
Aidan Kehoe <kehoea@parhasard.net>
parents:
2182
diff
changeset
|
407 is given in bits, with a maximum precision of |
|
b5e1d4f6b66f
Make #'floor, #'ceiling, #'round, #'truncate conform to Common Lisp.
Aidan Kehoe <kehoea@parhasard.net>
parents:
2182
diff
changeset
|
408 @code{bigfloat-maximum-precision}. |
|
5739
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
409 |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
410 @example |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
411 (let* ((float1 (string-to-number "9999999999999999.99999999999999999999")) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
412 (default-float-precision 256) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
413 (float2 (string-to-number "9999999999999999.99999999999999999999"))) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
414 (+ (if (bigfloatp float1) 1 0) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
415 (if (bigfloatp float2) 2 0))) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
416 @result{} 2 |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
417 @end example |
| 2182 | 418 |
|
5739
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
419 @example |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
420 (let* ((float1 (float 999999999999999999999999999999999999999999999999999999)) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
421 (default-float-precision 256) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
422 (float2 (float 999999999999999999999999999999999999999999999999999999))) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
423 (princ float1) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
424 (terpri) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
425 (princ float2) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
426 (terpri)) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
427 @result{} 9.999999999999999e+53 |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
428 9.99999999999999999999999999999999999999999999999999999E53 |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
429 t |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
430 @end example |
| 2182 | 431 |
|
5739
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
432 Explicit type coercion is also available, although then the precision of |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
433 the bigfloat is no greater than the source type. |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
434 |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
435 @example |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
436 (coerce 999999999999999 'bigfloat) |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
437 @result{} 9.99999999999999E14 |
|
a2912073be85
Support bignums with MPIR. Add documentation on the bignum, ratio,
Jerry James <james@xemacs.org>
parents:
5252
diff
changeset
|
438 @end example |
| 2028 | 439 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
440 @node Canonicalization and Contagion, Compatibility Issues, Bigfloat Basics, The Bignum Extension |
| 2090 | 441 @subsection Canonicalization and Contagion |
| 442 | |
| 443 @dfn{Canonicalization} is a rule intended to enhance the time and space | |
| 444 efficiency of exact arithmetic. Because bignums and ratios are | |
| 445 implemented as record objects, they take up much more space than | |
| 446 fixnums, which are implemented as an immediate object. Conversions and | |
| 447 calls to the MP library also take time. So the implementation always | |
| 448 converts the result of exact arithmetic to the smallest representation | |
| 449 that can exactly represent the quantity. | |
| 450 | |
| 451 @example | |
| 452 (+ 3/4 5) | |
| 453 @result{} 23/4 | |
| 454 | |
| 455 (+ 3/4 1/4 2) | |
| 456 @result{} 3 | |
| 457 @end example | |
| 458 | |
| 459 Conversely, if an integer (read or computed) cannot be represented as a | |
| 460 fixnum, a bignum will be used. Integer division is a somewhat | |
| 461 exceptional case. Because it is useful and is the historical meaning of | |
| 462 the function @code{/}, a separate function @code{div} is provided. | |
| 463 @code{div} is identical to @code{/} except that when the rational result | |
| 464 is not an integer, it is represented exactly as a ratio. In both cases | |
| 465 if a rational result is an integer, it is automatically converted to the | |
| 466 appropriate integral representation. | |
| 467 | |
| 468 Note that the efficiency gain from canonicalization is likely to be | |
| 469 less than you might think. Experience with numerical analysis shows that | |
| 470 in very precise calculations, the required precision tends to increase. | |
| 471 Thus it is typically wasted effort to attempt to convert to smaller | |
| 472 representations, as the number is often reused and requires a larger | |
| 473 representation. However, XEmacs Lisp presumes that calculations using | |
| 474 bignums are the exception, so it applies canonicalization. | |
| 2028 | 475 |
| 476 @dfn{Contagion} is one way to address the requirement that an arithmetic | |
| 2090 | 477 operation should not fail because of differing types of the operands. |
| 478 Contagion is the idea that less precise operands are converted to the | |
| 479 more precise type, and then the operation is performed. While changing | |
| 480 precision is a delicate issue, contagion is so useful that XEmacs | |
| 481 performs it automatically. | |
| 2028 | 482 |
| 483 In XEmacs, the following rules of contagion are used: | |
| 484 | |
| 485 @c #### this probably wants names for each rule | |
| 486 @enumerate | |
| 487 @item | |
| 2090 | 488 If an expression mixes an integral type with a ratio, then the usual |
| 489 rules of rational arithmetic apply. (If the result of the expression | |
| 490 happens to be an integer, it will be canonicalized to integer.) | |
| 2028 | 491 |
| 492 @item | |
| 493 If an expression mixes a rational type (fixnum, bignum, or ratio) with a | |
| 494 float, the rational operand is converted to a float and the operation | |
| 495 performed if the result would fit in a float, otherwise both operands | |
| 496 are promoted to bigfloat, and the operation performed. | |
| 497 | |
| 498 @item | |
| 499 If an expression mixes any other type with a bigfloat, the other operand | |
| 500 is converted to bigfloat and the operation performed. | |
| 501 | |
| 502 @item | |
| 2090 | 503 If bigfloats of different precision are mixed, all are converted to the |
| 504 @emph{highest} precision, and the operation performed. | |
| 2028 | 505 @end enumerate |
| 506 | |
| 507 Note that there are no rules to canonicalize floats or bigfloats. This | |
| 508 might seem surprising, but in both cases information will be lost. Any | |
| 509 floating point representation is implicitly approximate. A conversion | |
| 510 to a rational type, even if it seems exact, loses this information. | |
| 511 More subtly, demoting a bigfloat to a smaller bigfloat or to a float | |
| 512 would lose information about the precision of the result, and thus some | |
| 513 information about the accuracy. Thus floating point numbers are always | |
| 514 already in canonical form. | |
| 515 | |
| 516 Of course the programmer can explicitly request canonicalization, or | |
| 517 more coercion to another type. Coercion uses the Common Lisp | |
| 518 compatibility function @code{coerce} from the @file{cl-extra.el} | |
| 519 library. A number can be explicitly converted to canonical form | |
| 520 according to the above rules using | |
| 521 | |
| 522 @defun canonicalize-number number | |
| 523 Return the canonical form of @var{number}. | |
| 524 @end defun | |
| 525 | |
| 2090 | 526 However, if we've done our job properly, this is always a no-op. That |
| 527 is, if you find a number in un-canonicalized form, please report it as a | |
| 528 bug. | |
| 529 | |
| 2028 | 530 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
531 @node Compatibility Issues, , Canonicalization and Contagion, The Bignum Extension |
| 2028 | 532 @subsection Compatibility Issues |
| 533 | |
| 534 @emph{Surgeon General's Warning}: The automatic conversions cannot be | |
| 535 disabled at runtime. Old functions will not produce ratios unless there | |
| 536 is a ratio operand, so there should be few surprises with type | |
| 537 conflicts (the contagion rules are quite natural for Lisp programmers | |
| 538 used to the behavior of integers and floats in pre-21.5.18 XEmacsen), | |
| 539 but they can't be ruled out. Also, if you work with extremely large | |
| 540 numbers, your machine may arbitrarily decide to hand you an unpleasant | |
| 541 surprise rather than a bignum. | |
| 542 | |
| 543 User-visible changes in behavior include (in probable order of annoyance) | |
| 544 | |
| 545 @itemize | |
| 546 @item | |
| 547 Arithmetic can cause a segfault, depending on your MP library. | |
| 548 | |
| 549 GMP by default allocates temporaries on the stack. If you run out of | |
| 550 stack space, you're dead; there is no way that we know of to reliably | |
| 551 detect this condition, because @samp{alloca} is typically implemented to | |
| 552 be @emph{fast} rather than robust. If you just need a little more | |
| 553 oomph, use a bigger stack (@emph{e.g.}, the @file{ulimit -s} command in | |
| 554 bash(1)). If you want robustness at the cost of speed, configure GMP | |
| 555 with @samp{--disable-alloca} and rebuild the GMP library. | |
| 556 | |
| 557 We do not know whether BSD MP uses @samp{alloca} or not. Please send | |
| 558 any information you have as a bug report (@kbd{M-x report-xemacs-bug | |
| 559 @key{RET}}), which will give us platform information. (We do know that | |
| 560 BSD MP implementations vary across vendors, but how much, we do not know | |
| 561 yet.) | |
| 562 | |
| 563 @item | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
564 Our documentation's terminology, and our API terminology, is not always |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
565 Common-Lisp-conforming. Many places use ``integer'' where ``fixnum'' |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
566 better reflects what the code accepts or produces; there are similar |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
567 issues for the varying types of floating point numbers. Since Emacs |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
568 Lisp has not had a ratio type before, there are no problems there. |
| 2028 | 569 |
| 570 @item | |
| 571 An atom with ratio read syntax now returns a number, not a symbol. | |
| 572 | |
| 573 @item | |
| 574 Many operations that used to cause a range error now succeed, with | |
| 575 intermediate results and return values coerced to bignums as needed. | |
| 576 | |
| 577 @item | |
| 578 The @samp{%u} format conversion will now give an error if its argument | |
| 579 is negative. (Without MP, it prints a number which Lisp can't read.) | |
| 580 @end itemize | |
| 581 | |
| 582 This is not a compatibility issue in the sense of specification, but | |
| 583 careless programmers who have taken advantage of the immediate | |
| 584 representation for numbers and written @code{(eq x y)} are in for a | |
| 585 surprise. This doesn't work with bignums, even if both arguments are | |
| 586 bignums! Arbitrary precision obviously requires consing new objects | |
| 587 because the objects are ``large'' and of variable size, and the | |
| 588 definition of @samp{eq} does not permit different objects to compare as | |
| 589 equal. Instead of @code{eq}, use @code{eql}, in which numbers of the | |
| 590 same type which have equal values compare equal, or @code{=}, which does | |
| 591 any necessary type coercions before comparing for equality | |
| 592 @ref{Comparison of Numbers}. | |
| 593 | |
| 594 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
595 @node Predicates on Numbers, Comparison of Numbers, The Bignum Extension, Numbers |
| 428 | 596 @section Type Predicates for Numbers |
| 597 | |
| 598 The functions in this section test whether the argument is a number or | |
| 2090 | 599 whether it is a certain sort of number. The functions which test for |
| 600 type can take any type of Lisp object as argument (the more general | |
| 601 predicates would not be of much use otherwise). However, the | |
| 602 @code{zerop} predicate requires a number as its argument, and the | |
| 603 @code{evenp}, and @code{oddp} predicates require integers as their | |
| 604 arguments. See also @code{integer-or-marker-p}, | |
| 605 @code{integer-char-or-marker-p}, @code{number-or-marker-p} and | |
| 606 @code{number-char-or-marker-p}, in @ref{Predicates on Markers}. | |
| 428 | 607 |
| 2090 | 608 @defun numberp object |
| 609 This predicate tests whether its argument is a number (either integer or | |
| 610 floating point), and returns @code{t} if so, @code{nil} otherwise. | |
| 611 @end defun | |
| 428 | 612 |
| 2090 | 613 @defun realp object |
| 614 @cindex numbers | |
| 615 The @code{realp} predicate tests to see whether @var{object} is a | |
| 616 rational or floating point number, and returns @code{t} if so, | |
| 617 @code{nil} otherwise. Currently equivalent to @code{numberp}. | |
| 618 @end defun | |
| 619 | |
| 620 @defun zerop number | |
| 621 This predicate tests whether its argument is zero, and returns @code{t} | |
| 622 if so, @code{nil} otherwise. The argument must be a number. | |
| 623 | |
| 624 These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}. | |
| 428 | 625 @end defun |
| 626 | |
| 627 @defun integerp object | |
| 628 This predicate tests whether its argument is an integer, and returns | |
| 629 @code{t} if so, @code{nil} otherwise. | |
| 630 @end defun | |
| 631 | |
| 2090 | 632 @defun oddp integer |
| 633 @cindex integers | |
| 634 The @code{oddp} predicate tests to see whether @var{integer} is odd, and | |
| 635 returns @code{t} if so, @code{nil} otherwise. @var{integer} must be an | |
| 636 integer. | |
| 637 @end defun | |
| 638 | |
| 639 @defun evenp integer | |
| 640 @cindex integers | |
| 641 The @code{evenp} predicate tests to see whether @var{integer} is even, | |
| 642 and returns @code{t} if so, @code{nil} otherwise. @var{integer} must be | |
| 643 an integer. | |
| 428 | 644 @end defun |
| 645 | |
| 646 @defun natnump object | |
| 647 @cindex natural numbers | |
| 648 The @code{natnump} predicate (whose name comes from the phrase | |
| 649 ``natural-number-p'') tests to see whether its argument is a nonnegative | |
| 650 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is | |
| 651 considered non-negative. | |
| 652 @end defun | |
| 653 | |
| 2090 | 654 @defun fixnump object |
| 655 @cindex integers | |
| 656 The @code{} predicate tests to see whether its argument is an integer | |
| 657 represented as a fixnum, and returns @code{t} if so, @code{nil} | |
| 658 otherwise. | |
| 659 @end defun | |
| 660 | |
| 661 @defun bignump object | |
| 662 @cindex integers | |
| 663 The @code{bignump} predicate tests to see whether @var{object} is an | |
| 664 integer represented as a bignum, and returns @code{t} if so, @code{nil} | |
| 665 otherwise. | |
| 666 @end defun | |
| 667 | |
| 668 @defun rationalp object | |
| 669 @cindex numbers | |
| 670 The @code{rationalp} predicate tests to see whether @var{object} is a | |
| 671 rational number, and returns @code{t} if so, @code{nil} otherwise. | |
| 672 @end defun | |
| 428 | 673 |
| 2090 | 674 @defun ratiop object |
| 675 @cindex ratios | |
| 676 The @code{ratiop} predicate tests to see whether @var{object} is a | |
| 677 number represented as a ratio, and returns @code{t} if so, @code{nil} | |
| 678 otherwise. | |
| 679 @end defun | |
| 680 | |
| 681 @defun floatingp object | |
| 682 @cindex floats | |
| 683 The @code{floatingp} predicate tests to see whether @var{object} is a | |
| 684 floating point number represented as a float or a bigfloat, and returns | |
| 685 @code{t} if so, @code{nil} otherwise. | |
| 428 | 686 @end defun |
| 687 | |
| 2090 | 688 @defun floatp object |
| 689 @cindex floats | |
| 690 This predicate tests whether its argument is a floating point | |
| 691 number and returns @code{t} if so, @code{nil} otherwise. | |
| 692 | |
| 693 @code{floatp} does not exist in Emacs versions 18 and earlier. If the | |
| 694 bignum extension is present, it returns @code{nil} for a bigfloat. | |
| 695 @end defun | |
| 696 | |
| 697 @defun bigfloatp object | |
| 698 @cindex floats | |
| 699 The @code{bigfloatp} predicate tests to see whether @var{object} is an | |
| 2091 | 700 floating point number represented as a bigfloat, and returns @code{t} if |
| 701 so, @code{nil} otherwise. | |
| 2090 | 702 @end defun |
| 703 | |
| 704 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
705 @node Comparison of Numbers, Numeric Conversions, Predicates on Numbers, Numbers |
| 428 | 706 @section Comparison of Numbers |
| 707 @cindex number equality | |
| 708 | |
| 709 To test numbers for numerical equality, you should normally use | |
| 2090 | 710 @code{=}, not @code{eq}. There can be many distinct floating point, |
| 711 bignum, and ratio number objects with the same numeric value. If you | |
| 712 use @code{eq} to compare them, then you test whether two values are the | |
| 713 same @emph{object}. By contrast, @code{=} compares only the numeric | |
| 714 values of the objects. | |
| 428 | 715 |
| 2028 | 716 In versions before 21.5.18, each integer value had a unique Lisp |
| 717 object in XEmacs Lisp. Therefore, @code{eq} was equivalent to @code{=} | |
| 718 where integers are concerned. Even with the introduction of bignums, it | |
| 719 is sometimes convenient to use @code{eq} for comparing an unknown value | |
| 720 with an integer, because @code{eq} does not report an error if the | |
| 721 unknown value is not a number---it accepts arguments of any type. By | |
| 722 contrast, @code{=} signals an error if the arguments are not numbers or | |
| 723 markers. However, it is a good idea to use @code{=} if you can, even | |
| 724 for comparing exact values, because two bignums or ratios with the same | |
| 725 value will often not be the same object. | |
| 428 | 726 |
| 2090 | 727 On the other hand, some functions, such as the string- and |
| 728 buffer-searching functions, will return an integer on success, but | |
| 729 something else (usually @code{nil}) on failure. If it is known what the | |
| 730 numerical subtype (float, bigfloat, or exact) of the returned object | |
| 731 will be if it is a number, then the predicate @code{eql} can be used for | |
| 732 comparison without signaling an error on some expected return values. | |
| 733 Because of canonicalization, @code{eql} can be used to compare a fixnum | |
| 734 value to something that might be a ratio; if the potential ratio value | |
| 735 is representable as a fixnum, it will be canonicalized to fixnum before | |
| 2091 | 736 comparing. However, although floats and bigfloats are of different |
| 737 types for the purpose of comparisons via @code{eql}, two bigfloats of | |
| 738 different @emph{precision} that are @code{=} will always be @code{eql}. | |
| 2090 | 739 |
| 740 @example | |
| 741 (eql 2 (string-match "ere" "there")) | |
| 742 @result{} t | |
| 743 | |
| 744 (eql 2 (string-match "ere" "three")) | |
| 745 @result{} nil | |
| 746 | |
| 747 (eql 2 2.0) | |
| 748 @result{} nil | |
| 749 | |
| 750 (= 2 (string-match "ere" "there")) | |
| 751 @result{} t | |
| 752 | |
| 753 (= 2 (string-match "ere" "three")) | |
| 754 @error{} Wrong type argument: number-char-or-marker-p, nil | |
| 755 | |
| 756 (= 2 2.0) | |
| 757 @result{} t | |
| 758 @end example | |
| 759 | |
| 760 | |
| 761 | |
| 428 | 762 There is another wrinkle: because floating point arithmetic is not |
| 763 exact, it is often a bad idea to check for equality of two floating | |
| 764 point values. Usually it is better to test for approximate equality. | |
| 765 Here's a function to do this: | |
| 766 | |
| 767 @example | |
| 768 (defconst fuzz-factor 1.0e-6) | |
| 769 (defun approx-equal (x y) | |
| 770 (or (and (= x 0) (= y 0)) | |
| 771 (< (/ (abs (- x y)) | |
| 772 (max (abs x) (abs y))) | |
| 773 fuzz-factor))) | |
| 774 @end example | |
| 775 | |
| 776 @cindex CL note---integers vrs @code{eq} | |
| 777 @quotation | |
| 778 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires | |
| 779 @code{=} because Common Lisp implements multi-word integers, and two | |
| 780 distinct integer objects can have the same numeric value. XEmacs Lisp | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
781 can have just one fixnum object for any given value because it has a |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
782 limited range of fixnum values. |
| 428 | 783 @end quotation |
| 784 | |
| 785 In addition to numbers, all of the following functions also accept | |
| 786 characters and markers as arguments, and treat them as their number | |
| 787 equivalents. | |
| 788 | |
| 789 @defun = number &rest more-numbers | |
| 790 This function returns @code{t} if all of its arguments are numerically | |
| 791 equal, @code{nil} otherwise. | |
| 792 | |
| 793 @example | |
| 794 (= 5) | |
| 795 @result{} t | |
| 796 (= 5 6) | |
| 797 @result{} nil | |
| 798 (= 5 5.0) | |
| 799 @result{} t | |
| 800 (= 5 5 6) | |
| 801 @result{} nil | |
| 802 @end example | |
| 803 @end defun | |
| 804 | |
| 805 @defun /= number &rest more-numbers | |
| 806 This function returns @code{t} if no two arguments are numerically | |
| 807 equal, @code{nil} otherwise. | |
| 808 | |
| 809 @example | |
| 810 (/= 5 6) | |
| 811 @result{} t | |
| 812 (/= 5 5 6) | |
| 813 @result{} nil | |
| 814 (/= 5 6 1) | |
| 815 @result{} t | |
| 816 @end example | |
| 817 @end defun | |
| 818 | |
| 819 @defun < number &rest more-numbers | |
| 820 This function returns @code{t} if the sequence of its arguments is | |
| 821 monotonically increasing, @code{nil} otherwise. | |
| 822 | |
| 823 @example | |
| 824 (< 5 6) | |
| 825 @result{} t | |
| 826 (< 5 6 6) | |
| 827 @result{} nil | |
| 828 (< 5 6 7) | |
| 829 @result{} t | |
| 830 @end example | |
| 831 @end defun | |
| 832 | |
| 833 @defun <= number &rest more-numbers | |
| 834 This function returns @code{t} if the sequence of its arguments is | |
| 835 monotonically nondecreasing, @code{nil} otherwise. | |
| 836 | |
| 837 @example | |
| 838 (<= 5 6) | |
| 839 @result{} t | |
| 840 (<= 5 6 6) | |
| 841 @result{} t | |
| 842 (<= 5 6 5) | |
| 843 @result{} nil | |
| 844 @end example | |
| 845 @end defun | |
| 846 | |
| 847 @defun > number &rest more-numbers | |
| 848 This function returns @code{t} if the sequence of its arguments is | |
| 849 monotonically decreasing, @code{nil} otherwise. | |
| 850 @end defun | |
| 851 | |
| 852 @defun >= number &rest more-numbers | |
| 853 This function returns @code{t} if the sequence of its arguments is | |
| 854 monotonically nonincreasing, @code{nil} otherwise. | |
| 855 @end defun | |
| 856 | |
| 857 @defun max number &rest more-numbers | |
| 858 This function returns the largest of its arguments. | |
| 859 | |
| 860 @example | |
| 861 (max 20) | |
| 862 @result{} 20 | |
| 863 (max 1 2.5) | |
| 864 @result{} 2.5 | |
| 865 (max 1 3 2.5) | |
| 866 @result{} 3 | |
| 867 @end example | |
| 868 @end defun | |
| 869 | |
| 870 @defun min number &rest more-numbers | |
| 871 This function returns the smallest of its arguments. | |
| 872 | |
| 873 @example | |
| 874 (min -4 1) | |
| 875 @result{} -4 | |
| 876 @end example | |
| 877 @end defun | |
| 878 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
879 @node Numeric Conversions, Arithmetic Operations, Comparison of Numbers, Numbers |
| 428 | 880 @section Numeric Conversions |
| 881 @cindex rounding in conversions | |
| 882 | |
| 883 To convert an integer to floating point, use the function @code{float}. | |
| 884 | |
| 885 @defun float number | |
| 886 This returns @var{number} converted to floating point. | |
| 887 If @var{number} is already a floating point number, @code{float} returns | |
| 888 it unchanged. | |
| 889 @end defun | |
| 890 | |
| 891 There are four functions to convert floating point numbers to integers; | |
| 892 they differ in how they round. These functions accept integer arguments | |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
893 also, and return such arguments unchanged. They return multiple values, |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
894 @pxref{(cl.info)Multiple values}. |
| 428 | 895 |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
896 All these functions take optional @var{divisor} arguments, and if this |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
897 argument is specified, the @var{number} argument is divided by |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
898 @var{divisor} before the calculation is made. An @code{arith-error} |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
899 results if @var{divisor} is 0. |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
900 |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
901 @defun truncate number &optional divisor |
| 428 | 902 This returns @var{number}, converted to an integer by rounding towards |
| 903 zero. | |
| 904 @end defun | |
| 905 | |
| 906 @defun floor number &optional divisor | |
| 907 This returns @var{number}, converted to an integer by rounding downward | |
| 908 (towards negative infinity). | |
| 909 @end defun | |
| 910 | |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
911 @defun ceiling number &optional divisor |
| 428 | 912 This returns @var{number}, converted to an integer by rounding upward |
| 913 (towards positive infinity). | |
| 914 @end defun | |
| 915 | |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
916 @defun round number &optional divisor |
| 428 | 917 This returns @var{number}, converted to an integer by rounding towards the |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
918 nearest integer. |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
919 |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
920 Rounding a value equidistant between two integers chooses the even |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
921 integer. GNU Emacs and older XEmacs did not guarantee this, and the |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
922 direction of rounding depended on the underlying machine and the C |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
923 implementation. |
| 428 | 924 @end defun |
| 925 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
926 @node Arithmetic Operations, Rounding Operations, Numeric Conversions, Numbers |
| 428 | 927 @section Arithmetic Operations |
| 928 | |
| 929 XEmacs Lisp provides the traditional four arithmetic operations: | |
| 930 addition, subtraction, multiplication, and division. Remainder and modulus | |
| 931 functions supplement the division functions. The functions to | |
| 932 add or subtract 1 are provided because they are traditional in Lisp and | |
| 933 commonly used. | |
| 934 | |
| 935 All of these functions except @code{%} return a floating point value | |
| 936 if any argument is floating. | |
| 937 | |
| 938 It is important to note that in XEmacs Lisp, arithmetic functions | |
| 939 do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
940 @minus{}134217728, depending on your hardware and whether your XEmacs |
|
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
941 supports bignums. |
| 428 | 942 |
| 444 | 943 @defun 1+ number |
| 944 This function returns @var{number} plus one. @var{number} may be a | |
| 945 number, character or marker. Markers and characters are converted to | |
| 946 integers. | |
| 947 | |
| 428 | 948 For example, |
| 949 | |
| 950 @example | |
| 951 (setq foo 4) | |
| 952 @result{} 4 | |
| 953 (1+ foo) | |
| 954 @result{} 5 | |
| 955 @end example | |
| 956 | |
| 957 This function is not analogous to the C operator @code{++}---it does not | |
| 958 increment a variable. It just computes a sum. Thus, if we continue, | |
| 959 | |
| 960 @example | |
| 961 foo | |
| 962 @result{} 4 | |
| 963 @end example | |
| 964 | |
| 965 If you want to increment the variable, you must use @code{setq}, | |
| 966 like this: | |
| 967 | |
| 968 @example | |
| 969 (setq foo (1+ foo)) | |
| 970 @result{} 5 | |
| 971 @end example | |
| 972 | |
| 973 Now that the @code{cl} package is always available from lisp code, a | |
| 974 more convenient and natural way to increment a variable is | |
| 975 @w{@code{(incf foo)}}. | |
| 976 @end defun | |
| 977 | |
| 444 | 978 @defun 1- number |
| 979 This function returns @var{number} minus one. @var{number} may be a | |
| 980 number, character or marker. Markers and characters are converted to | |
| 981 integers. | |
| 428 | 982 @end defun |
| 983 | |
| 984 @defun abs number | |
| 985 This returns the absolute value of @var{number}. | |
| 986 @end defun | |
| 987 | |
| 444 | 988 @defun + &rest numbers |
| 428 | 989 This function adds its arguments together. When given no arguments, |
| 990 @code{+} returns 0. | |
| 991 | |
| 444 | 992 If any of the arguments are characters or markers, they are first |
| 993 converted to integers. | |
| 994 | |
| 428 | 995 @example |
| 996 (+) | |
| 997 @result{} 0 | |
| 998 (+ 1) | |
| 999 @result{} 1 | |
| 1000 (+ 1 2 3 4) | |
| 1001 @result{} 10 | |
| 1002 @end example | |
| 1003 @end defun | |
| 1004 | |
| 444 | 1005 @defun - &optional number &rest other-numbers |
| 428 | 1006 The @code{-} function serves two purposes: negation and subtraction. |
| 1007 When @code{-} has a single argument, the value is the negative of the | |
| 1008 argument. When there are multiple arguments, @code{-} subtracts each of | |
| 444 | 1009 the @var{other-numbers} from @var{number}, cumulatively. If there are |
| 1010 no arguments, an error is signaled. | |
| 1011 | |
| 1012 If any of the arguments are characters or markers, they are first | |
| 1013 converted to integers. | |
| 428 | 1014 |
| 1015 @example | |
| 1016 (- 10 1 2 3 4) | |
| 1017 @result{} 0 | |
| 1018 (- 10) | |
| 1019 @result{} -10 | |
| 1020 (-) | |
| 1021 @result{} 0 | |
| 1022 @end example | |
| 1023 @end defun | |
| 1024 | |
| 444 | 1025 @defun * &rest numbers |
| 428 | 1026 This function multiplies its arguments together, and returns the |
| 1027 product. When given no arguments, @code{*} returns 1. | |
| 1028 | |
| 444 | 1029 If any of the arguments are characters or markers, they are first |
| 1030 converted to integers. | |
| 1031 | |
| 428 | 1032 @example |
| 1033 (*) | |
| 1034 @result{} 1 | |
| 1035 (* 1) | |
| 1036 @result{} 1 | |
| 1037 (* 1 2 3 4) | |
| 1038 @result{} 24 | |
| 1039 @end example | |
| 1040 @end defun | |
| 1041 | |
| 444 | 1042 @defun / dividend &rest divisors |
| 1043 The @code{/} function serves two purposes: inversion and division. When | |
| 1044 @code{/} has a single argument, the value is the inverse of the | |
| 1045 argument. When there are multiple arguments, @code{/} divides | |
| 1046 @var{dividend} by each of the @var{divisors}, cumulatively, returning | |
| 1047 the quotient. If there are no arguments, an error is signaled. | |
| 428 | 1048 |
| 444 | 1049 If none of the arguments are floats, then the result is an integer. |
| 428 | 1050 This means the result has to be rounded. On most machines, the result |
| 1051 is rounded towards zero after each division, but some machines may round | |
| 1052 differently with negative arguments. This is because the Lisp function | |
| 1053 @code{/} is implemented using the C division operator, which also | |
| 1054 permits machine-dependent rounding. As a practical matter, all known | |
| 1055 machines round in the standard fashion. | |
| 1056 | |
| 444 | 1057 If any of the arguments are characters or markers, they are first |
| 1058 converted to integers. | |
| 1059 | |
| 428 | 1060 @cindex @code{arith-error} in division |
| 1061 If you divide by 0, an @code{arith-error} error is signaled. | |
| 1062 (@xref{Errors}.) | |
| 1063 | |
| 1064 @example | |
| 1065 @group | |
| 1066 (/ 6 2) | |
| 1067 @result{} 3 | |
| 1068 @end group | |
| 1069 (/ 5 2) | |
| 1070 @result{} 2 | |
| 1071 (/ 25 3 2) | |
| 1072 @result{} 4 | |
| 444 | 1073 (/ 3.0) |
| 1074 @result{} 0.3333333333333333 | |
| 428 | 1075 (/ -17 6) |
| 1076 @result{} -2 | |
| 1077 @end example | |
| 1078 | |
| 1079 The result of @code{(/ -17 6)} could in principle be -3 on some | |
| 1080 machines. | |
| 1081 @end defun | |
| 1082 | |
| 1083 @defun % dividend divisor | |
| 1084 @cindex remainder | |
| 1085 This function returns the integer remainder after division of @var{dividend} | |
| 1086 by @var{divisor}. The arguments must be integers or markers. | |
| 1087 | |
| 1088 For negative arguments, the remainder is in principle machine-dependent | |
| 1089 since the quotient is; but in practice, all known machines behave alike. | |
| 1090 | |
| 1091 An @code{arith-error} results if @var{divisor} is 0. | |
| 1092 | |
| 1093 @example | |
| 1094 (% 9 4) | |
| 1095 @result{} 1 | |
| 1096 (% -9 4) | |
| 1097 @result{} -1 | |
| 1098 (% 9 -4) | |
| 1099 @result{} 1 | |
| 1100 (% -9 -4) | |
| 1101 @result{} -1 | |
| 1102 @end example | |
| 1103 | |
| 1104 For any two integers @var{dividend} and @var{divisor}, | |
| 1105 | |
| 1106 @example | |
| 1107 @group | |
| 1108 (+ (% @var{dividend} @var{divisor}) | |
| 1109 (* (/ @var{dividend} @var{divisor}) @var{divisor})) | |
| 1110 @end group | |
| 1111 @end example | |
| 1112 | |
| 1113 @noindent | |
| 1114 always equals @var{dividend}. | |
| 1115 @end defun | |
| 1116 | |
| 1117 @defun mod dividend divisor | |
| 1118 @cindex modulus | |
| 1119 This function returns the value of @var{dividend} modulo @var{divisor}; | |
| 1120 in other words, the remainder after division of @var{dividend} | |
| 1121 by @var{divisor}, but with the same sign as @var{divisor}. | |
| 1122 The arguments must be numbers or markers. | |
| 1123 | |
| 1124 Unlike @code{%}, @code{mod} returns a well-defined result for negative | |
| 1125 arguments. It also permits floating point arguments; it rounds the | |
| 1126 quotient downward (towards minus infinity) to an integer, and uses that | |
| 1127 quotient to compute the remainder. | |
| 1128 | |
| 1129 An @code{arith-error} results if @var{divisor} is 0. | |
| 1130 | |
| 1131 @example | |
| 1132 @group | |
| 1133 (mod 9 4) | |
| 1134 @result{} 1 | |
| 1135 @end group | |
| 1136 @group | |
| 1137 (mod -9 4) | |
| 1138 @result{} 3 | |
| 1139 @end group | |
| 1140 @group | |
| 1141 (mod 9 -4) | |
| 1142 @result{} -3 | |
| 1143 @end group | |
| 1144 @group | |
| 1145 (mod -9 -4) | |
| 1146 @result{} -1 | |
| 1147 @end group | |
| 1148 @group | |
| 1149 (mod 5.5 2.5) | |
| 1150 @result{} .5 | |
| 1151 @end group | |
| 1152 @end example | |
| 1153 | |
| 1154 For any two numbers @var{dividend} and @var{divisor}, | |
| 1155 | |
| 1156 @example | |
| 1157 @group | |
| 1158 (+ (mod @var{dividend} @var{divisor}) | |
| 1159 (* (floor @var{dividend} @var{divisor}) @var{divisor})) | |
| 1160 @end group | |
| 1161 @end example | |
| 1162 | |
| 1163 @noindent | |
| 1164 always equals @var{dividend}, subject to rounding error if either | |
| 1165 argument is floating point. For @code{floor}, see @ref{Numeric | |
| 1166 Conversions}. | |
| 1167 @end defun | |
| 1168 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
1169 @node Rounding Operations, Bitwise Operations, Arithmetic Operations, Numbers |
| 428 | 1170 @section Rounding Operations |
| 1171 @cindex rounding without conversion | |
| 1172 | |
| 1173 The functions @code{ffloor}, @code{fceiling}, @code{fround} and | |
| 1174 @code{ftruncate} take a floating point argument and return a floating | |
| 1175 point result whose value is a nearby integer. @code{ffloor} returns the | |
| 1176 nearest integer below; @code{fceiling}, the nearest integer above; | |
| 1177 @code{ftruncate}, the nearest integer in the direction towards zero; | |
| 1178 @code{fround}, the nearest integer. | |
| 1179 | |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1180 All these functions take optional @var{divisor} arguments, and if this |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1181 argument is specified, the @var{number} argument is divided by |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1182 @var{divisor} before the calculation is made. An @code{arith-error} |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1183 results if @var{divisor} is 0. Also, they return multiple values, |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1184 @pxref{(cl.info)Multiple values}; the second value is the remainder. |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1185 |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1186 @defun ffloor number &optional divisor |
| 444 | 1187 This function rounds @var{number} to the next lower integral value, and |
| 428 | 1188 returns that value as a floating point number. |
| 1189 @end defun | |
| 1190 | |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1191 @defun fceiling number &optional divisor |
| 444 | 1192 This function rounds @var{number} to the next higher integral value, and |
| 428 | 1193 returns that value as a floating point number. |
| 1194 @end defun | |
| 1195 | |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1196 @defun ftruncate number &optional divisor |
| 444 | 1197 This function rounds @var{number} towards zero to an integral value, and |
| 428 | 1198 returns that value as a floating point number. |
| 1199 @end defun | |
| 1200 | |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1201 @defun fround number &optional divisor |
| 444 | 1202 This function rounds @var{number} to the nearest integral value, |
| 428 | 1203 and returns that value as a floating point number. |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1204 |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1205 Rounding a value equidistant between two integral values chooses the |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1206 even value. While this is specified by Common Lisp, GNU Emacs and older |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1207 XEmacs did not make this guarantee, and the direction of rounding |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1208 depended on the underlying machine and the C implementation. |
| 428 | 1209 @end defun |
| 1210 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
1211 @node Bitwise Operations, Math Functions, Rounding Operations, Numbers |
| 428 | 1212 @section Bitwise Operations on Integers |
| 1213 | |
| 1214 In a computer, an integer is represented as a binary number, a | |
| 1215 sequence of @dfn{bits} (digits which are either zero or one). A bitwise | |
| 1216 operation acts on the individual bits of such a sequence. For example, | |
| 1217 @dfn{shifting} moves the whole sequence left or right one or more places, | |
| 1218 reproducing the same pattern ``moved over''. | |
| 1219 | |
| 1220 The bitwise operations in XEmacs Lisp apply only to integers. | |
| 1221 | |
| 1222 @defun lsh integer1 count | |
| 1223 @cindex logical shift | |
| 1224 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the | |
| 1225 bits in @var{integer1} to the left @var{count} places, or to the right | |
| 1226 if @var{count} is negative, bringing zeros into the vacated bits. If | |
| 1227 @var{count} is negative, @code{lsh} shifts zeros into the leftmost | |
| 1228 (most-significant) bit, producing a positive result even if | |
| 1229 @var{integer1} is negative. Contrast this with @code{ash}, below. | |
| 1230 | |
| 1231 Here are two examples of @code{lsh}, shifting a pattern of bits one | |
| 1232 place to the left. We show only the low-order eight bits of the binary | |
| 1233 pattern; the rest are all zero. | |
| 1234 | |
| 1235 @example | |
| 1236 @group | |
| 1237 (lsh 5 1) | |
| 1238 @result{} 10 | |
| 1239 ;; @r{Decimal 5 becomes decimal 10.} | |
| 1240 00000101 @result{} 00001010 | |
| 1241 | |
| 1242 (lsh 7 1) | |
| 1243 @result{} 14 | |
| 1244 ;; @r{Decimal 7 becomes decimal 14.} | |
| 1245 00000111 @result{} 00001110 | |
| 1246 @end group | |
| 1247 @end example | |
| 1248 | |
| 1249 @noindent | |
| 1250 As the examples illustrate, shifting the pattern of bits one place to | |
| 1251 the left produces a number that is twice the value of the previous | |
| 1252 number. | |
| 1253 | |
| 1254 Shifting a pattern of bits two places to the left produces results | |
| 1255 like this (with 8-bit binary numbers): | |
| 1256 | |
| 1257 @example | |
| 1258 @group | |
| 1259 (lsh 3 2) | |
| 1260 @result{} 12 | |
| 1261 ;; @r{Decimal 3 becomes decimal 12.} | |
| 444 | 1262 00000011 @result{} 00001100 |
| 428 | 1263 @end group |
| 1264 @end example | |
| 1265 | |
| 1266 On the other hand, shifting one place to the right looks like this: | |
| 1267 | |
| 1268 @example | |
| 1269 @group | |
| 1270 (lsh 6 -1) | |
| 1271 @result{} 3 | |
| 1272 ;; @r{Decimal 6 becomes decimal 3.} | |
| 444 | 1273 00000110 @result{} 00000011 |
| 428 | 1274 @end group |
| 1275 | |
| 1276 @group | |
| 1277 (lsh 5 -1) | |
| 1278 @result{} 2 | |
| 1279 ;; @r{Decimal 5 becomes decimal 2.} | |
| 444 | 1280 00000101 @result{} 00000010 |
| 428 | 1281 @end group |
| 1282 @end example | |
| 1283 | |
| 1284 @noindent | |
| 1285 As the example illustrates, shifting one place to the right divides the | |
| 1286 value of a positive integer by two, rounding downward. | |
| 1287 | |
| 1288 The function @code{lsh}, like all XEmacs Lisp arithmetic functions, does | |
| 1289 not check for overflow, so shifting left can discard significant bits | |
| 1290 and change the sign of the number. For example, left shifting | |
| 1291 134,217,727 produces @minus{}2 on a 28-bit machine: | |
| 1292 | |
| 1293 @example | |
| 1294 (lsh 134217727 1) ; @r{left shift} | |
| 1295 @result{} -2 | |
| 1296 @end example | |
| 1297 | |
| 1298 In binary, in the 28-bit implementation, the argument looks like this: | |
| 1299 | |
| 1300 @example | |
| 1301 @group | |
| 1302 ;; @r{Decimal 134,217,727} | |
| 444 | 1303 0111 1111 1111 1111 1111 1111 1111 |
| 428 | 1304 @end group |
| 1305 @end example | |
| 1306 | |
| 1307 @noindent | |
| 1308 which becomes the following when left shifted: | |
| 1309 | |
| 1310 @example | |
| 1311 @group | |
| 1312 ;; @r{Decimal @minus{}2} | |
| 444 | 1313 1111 1111 1111 1111 1111 1111 1110 |
| 428 | 1314 @end group |
| 1315 @end example | |
| 1316 @end defun | |
| 1317 | |
| 1318 @defun ash integer1 count | |
| 1319 @cindex arithmetic shift | |
| 1320 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} | |
| 1321 to the left @var{count} places, or to the right if @var{count} | |
| 1322 is negative. | |
| 1323 | |
| 1324 @code{ash} gives the same results as @code{lsh} except when | |
| 1325 @var{integer1} and @var{count} are both negative. In that case, | |
| 1326 @code{ash} puts ones in the empty bit positions on the left, while | |
| 1327 @code{lsh} puts zeros in those bit positions. | |
| 1328 | |
| 1329 Thus, with @code{ash}, shifting the pattern of bits one place to the right | |
| 1330 looks like this: | |
| 1331 | |
| 1332 @example | |
| 1333 @group | |
| 444 | 1334 (ash -6 -1) @result{} -3 |
| 428 | 1335 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} |
| 1336 1111 1111 1111 1111 1111 1111 1010 | |
| 444 | 1337 @result{} |
| 428 | 1338 1111 1111 1111 1111 1111 1111 1101 |
| 1339 @end group | |
| 1340 @end example | |
| 1341 | |
| 1342 In contrast, shifting the pattern of bits one place to the right with | |
| 1343 @code{lsh} looks like this: | |
| 1344 | |
| 1345 @example | |
| 1346 @group | |
| 1347 (lsh -6 -1) @result{} 134217725 | |
| 1348 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.} | |
| 1349 1111 1111 1111 1111 1111 1111 1010 | |
| 444 | 1350 @result{} |
| 428 | 1351 0111 1111 1111 1111 1111 1111 1101 |
| 1352 @end group | |
| 1353 @end example | |
| 1354 | |
| 1355 Here are other examples: | |
| 1356 | |
| 1357 @c !!! Check if lined up in smallbook format! XDVI shows problem | |
| 1358 @c with smallbook but not with regular book! --rjc 16mar92 | |
| 1359 @smallexample | |
| 1360 @group | |
| 1361 ; @r{ 28-bit binary values} | |
| 1362 | |
| 1363 (lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1364 @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100} | |
| 1365 @end group | |
| 1366 @group | |
| 1367 (ash 5 2) | |
| 1368 @result{} 20 | |
| 1369 (lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} | |
| 1370 @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100} | |
| 1371 (ash -5 2) | |
| 1372 @result{} -20 | |
| 1373 @end group | |
| 1374 @group | |
| 1375 (lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1376 @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001} | |
| 1377 @end group | |
| 1378 @group | |
| 1379 (ash 5 -2) | |
| 1380 @result{} 1 | |
| 1381 @end group | |
| 1382 @group | |
| 1383 (lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} | |
| 1384 @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110} | |
| 1385 @end group | |
| 1386 @group | |
| 1387 (ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} | |
| 1388 @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110} | |
| 1389 @end group | |
| 1390 @end smallexample | |
| 1391 @end defun | |
| 1392 | |
| 1393 @defun logand &rest ints-or-markers | |
| 1394 @cindex logical and | |
| 1395 @cindex bitwise and | |
| 1396 This function returns the ``logical and'' of the arguments: the | |
| 1397 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is | |
| 1398 set in all the arguments. (``Set'' means that the value of the bit is 1 | |
| 1399 rather than 0.) | |
| 1400 | |
| 1401 For example, using 4-bit binary numbers, the ``logical and'' of 13 and | |
| 1402 12 is 12: 1101 combined with 1100 produces 1100. | |
| 1403 In both the binary numbers, the leftmost two bits are set (i.e., they | |
| 1404 are 1's), so the leftmost two bits of the returned value are set. | |
| 1405 However, for the rightmost two bits, each is zero in at least one of | |
| 1406 the arguments, so the rightmost two bits of the returned value are 0's. | |
| 1407 | |
| 1408 @noindent | |
| 1409 Therefore, | |
| 1410 | |
| 1411 @example | |
| 1412 @group | |
| 1413 (logand 13 12) | |
| 1414 @result{} 12 | |
| 1415 @end group | |
| 1416 @end example | |
| 1417 | |
| 1418 If @code{logand} is not passed any argument, it returns a value of | |
| 1419 @minus{}1. This number is an identity element for @code{logand} | |
| 1420 because its binary representation consists entirely of ones. If | |
| 1421 @code{logand} is passed just one argument, it returns that argument. | |
| 1422 | |
| 1423 @smallexample | |
| 1424 @group | |
| 1425 ; @r{ 28-bit binary values} | |
| 1426 | |
| 1427 (logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} | |
| 1428 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} | |
| 1429 @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | |
| 1430 @end group | |
| 1431 | |
| 1432 @group | |
| 1433 (logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} | |
| 1434 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} | |
| 1435 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100} | |
| 1436 @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100} | |
| 1437 @end group | |
| 1438 | |
| 1439 @group | |
| 1440 (logand) | |
| 1441 @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111 1111} | |
| 1442 @end group | |
| 1443 @end smallexample | |
| 1444 @end defun | |
| 1445 | |
| 1446 @defun logior &rest ints-or-markers | |
| 1447 @cindex logical inclusive or | |
| 1448 @cindex bitwise or | |
| 1449 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit | |
| 1450 is set in the result if, and only if, the @var{n}th bit is set in at least | |
| 1451 one of the arguments. If there are no arguments, the result is zero, | |
| 1452 which is an identity element for this operation. If @code{logior} is | |
| 1453 passed just one argument, it returns that argument. | |
| 1454 | |
| 1455 @smallexample | |
| 1456 @group | |
| 1457 ; @r{ 28-bit binary values} | |
| 1458 | |
| 1459 (logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | |
| 1460 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1461 @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} | |
| 1462 @end group | |
| 1463 | |
| 1464 @group | |
| 1465 (logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | |
| 1466 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1467 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111} | |
| 1468 @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111} | |
| 1469 @end group | |
| 1470 @end smallexample | |
| 1471 @end defun | |
| 1472 | |
| 1473 @defun logxor &rest ints-or-markers | |
| 1474 @cindex bitwise exclusive or | |
| 1475 @cindex logical exclusive or | |
| 1476 This function returns the ``exclusive or'' of its arguments: the | |
| 1477 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is | |
| 1478 set in an odd number of the arguments. If there are no arguments, the | |
| 1479 result is 0, which is an identity element for this operation. If | |
| 1480 @code{logxor} is passed just one argument, it returns that argument. | |
| 1481 | |
| 1482 @smallexample | |
| 1483 @group | |
| 1484 ; @r{ 28-bit binary values} | |
| 1485 | |
| 1486 (logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | |
| 1487 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1488 @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001} | |
| 1489 @end group | |
| 1490 | |
| 1491 @group | |
| 1492 (logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | |
| 1493 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1494 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111} | |
| 1495 @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} | |
| 1496 @end group | |
| 1497 @end smallexample | |
| 1498 @end defun | |
| 1499 | |
| 1500 @defun lognot integer | |
| 1501 @cindex logical not | |
| 1502 @cindex bitwise not | |
| 1503 This function returns the logical complement of its argument: the @var{n}th | |
| 1504 bit is one in the result if, and only if, the @var{n}th bit is zero in | |
| 1505 @var{integer}, and vice-versa. | |
| 1506 | |
| 1507 @example | |
| 444 | 1508 (lognot 5) |
| 428 | 1509 @result{} -6 |
| 1510 ;; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1511 ;; @r{becomes} | |
| 1512 ;; -6 = @r{1111 1111 1111 1111 1111 1111 1010} | |
| 1513 @end example | |
| 1514 @end defun | |
| 1515 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
1516 @node Math Functions, Random Numbers, Bitwise Operations, Numbers |
| 428 | 1517 @section Standard Mathematical Functions |
| 1518 @cindex transcendental functions | |
| 1519 @cindex mathematical functions | |
| 1520 | |
| 1521 These mathematical functions are available if floating point is | |
| 1522 supported (which is the normal state of affairs). They allow integers | |
| 1523 as well as floating point numbers as arguments. | |
| 1524 | |
| 444 | 1525 @defun sin number |
| 1526 @defunx cos number | |
| 1527 @defunx tan number | |
| 428 | 1528 These are the ordinary trigonometric functions, with argument measured |
| 1529 in radians. | |
| 1530 @end defun | |
| 1531 | |
| 444 | 1532 @defun asin number |
| 1533 The value of @code{(asin @var{number})} is a number between @minus{}pi/2 | |
| 1534 and pi/2 (inclusive) whose sine is @var{number}; if, however, @var{number} | |
| 428 | 1535 is out of range (outside [-1, 1]), then the result is a NaN. |
| 1536 @end defun | |
| 1537 | |
| 444 | 1538 @defun acos number |
| 1539 The value of @code{(acos @var{number})} is a number between 0 and pi | |
| 1540 (inclusive) whose cosine is @var{number}; if, however, @var{number} | |
| 428 | 1541 is out of range (outside [-1, 1]), then the result is a NaN. |
| 1542 @end defun | |
| 1543 | |
| 444 | 1544 @defun atan number &optional number2 |
| 1545 The value of @code{(atan @var{number})} is a number between @minus{}pi/2 | |
| 1546 and pi/2 (exclusive) whose tangent is @var{number}. | |
| 1547 | |
| 1548 If optional argument @var{number2} is supplied, the function returns | |
| 1549 @code{atan2(@var{number},@var{number2})}. | |
| 428 | 1550 @end defun |
| 1551 | |
| 444 | 1552 @defun sinh number |
| 1553 @defunx cosh number | |
| 1554 @defunx tanh number | |
| 428 | 1555 These are the ordinary hyperbolic trigonometric functions. |
| 1556 @end defun | |
| 1557 | |
| 444 | 1558 @defun asinh number |
| 1559 @defunx acosh number | |
| 1560 @defunx atanh number | |
| 428 | 1561 These are the inverse hyperbolic trigonometric functions. |
| 1562 @end defun | |
| 1563 | |
| 444 | 1564 @defun exp number |
| 428 | 1565 This is the exponential function; it returns @i{e} to the power |
| 444 | 1566 @var{number}. @i{e} is a fundamental mathematical constant also called the |
| 428 | 1567 base of natural logarithms. |
| 1568 @end defun | |
| 1569 | |
| 444 | 1570 @defun log number &optional base |
| 1571 This function returns the logarithm of @var{number}, with base @var{base}. | |
| 1738 | 1572 If you don't specify @var{base}, the base @code{e} is used. If @var{number} |
| 428 | 1573 is negative, the result is a NaN. |
| 1574 @end defun | |
| 1575 | |
| 444 | 1576 @defun log10 number |
| 1577 This function returns the logarithm of @var{number}, with base 10. If | |
| 1578 @var{number} is negative, the result is a NaN. @code{(log10 @var{x})} | |
| 428 | 1579 @equiv{} @code{(log @var{x} 10)}, at least approximately. |
| 1580 @end defun | |
| 1581 | |
| 1582 @defun expt x y | |
| 1583 This function returns @var{x} raised to power @var{y}. If both | |
| 1584 arguments are integers and @var{y} is positive, the result is an | |
| 1585 integer; in this case, it is truncated to fit the range of possible | |
| 1586 integer values. | |
| 1587 @end defun | |
| 1588 | |
| 444 | 1589 @defun sqrt number |
| 1590 This returns the square root of @var{number}. If @var{number} is negative, | |
| 428 | 1591 the value is a NaN. |
| 1592 @end defun | |
| 1593 | |
| 444 | 1594 @defun cube-root number |
| 1595 This returns the cube root of @var{number}. | |
| 428 | 1596 @end defun |
| 1597 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5739
diff
changeset
|
1598 @node Random Numbers, , Math Functions, Numbers |
| 428 | 1599 @section Random Numbers |
| 1600 @cindex random numbers | |
| 1601 | |
| 1602 A deterministic computer program cannot generate true random numbers. | |
| 1603 For most purposes, @dfn{pseudo-random numbers} suffice. A series of | |
| 1604 pseudo-random numbers is generated in a deterministic fashion. The | |
| 1605 numbers are not truly random, but they have certain properties that | |
| 1606 mimic a random series. For example, all possible values occur equally | |
| 1607 often in a pseudo-random series. | |
| 1608 | |
| 1609 In XEmacs, pseudo-random numbers are generated from a ``seed'' number. | |
| 1610 Starting from any given seed, the @code{random} function always | |
| 1611 generates the same sequence of numbers. XEmacs always starts with the | |
| 1612 same seed value, so the sequence of values of @code{random} is actually | |
| 1613 the same in each XEmacs run! For example, in one operating system, the | |
| 1614 first call to @code{(random)} after you start XEmacs always returns | |
| 1615 -1457731, and the second one always returns -7692030. This | |
| 1616 repeatability is helpful for debugging. | |
| 1617 | |
| 2090 | 1618 If you want reasonably unpredictable random numbers, execute |
| 1619 @code{(random t)}. This chooses a new seed based on the current time of | |
| 1620 day and on XEmacs's process @sc{id} number. (This is not | |
| 1621 cryptographically strong, it's just hard for a @emph{human} to | |
| 1622 anticipate.) | |
| 428 | 1623 |
| 1624 @defun random &optional limit | |
| 1625 This function returns a pseudo-random integer. Repeated calls return a | |
| 1626 series of pseudo-random integers. | |
| 1627 | |
| 1628 If @var{limit} is a positive integer, the value is chosen to be | |
| 1629 nonnegative and less than @var{limit}. | |
| 1630 | |
| 1631 If @var{limit} is @code{t}, it means to choose a new seed based on the | |
| 1632 current time of day and on XEmacs's process @sc{id} number. | |
| 1633 @c "XEmacs'" is incorrect usage! | |
| 2090 | 1634 @end defun |
| 428 | 1635 |
| 2090 | 1636 The range of random is implementation-dependent. On any machine, the |
| 1637 result of @code{(random)} is an arbitrary fixnum, so on 32-bit | |
| 1638 architectures it is normally in the range -2^30 (inclusive) to +2^30 | |
| 1639 (exclusive). With the optional integer argument @var{limit}, the result | |
| 1640 is in the range 0 (inclusive) to @var{limit} (exclusive). Note this is | |
| 1641 regardless of the presence of the bignum extension. | |
| 1642 |