Mercurial > hg > xemacs-beta

comparison man/lispref/numbers.texi @ 2028:2ba4f06a264d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2004-04-19 08:02:27 by stephent] texi doc improvements <87zn98wg4q.fsf@tleepslib.sk.tsukuba.ac.jp>
author stephent
date Mon, 19 Apr 2004 08:02:38 +0000
parents f43f9ca6c7d9
children cc89c76c4b17
comparison
equal deleted inserted replaced
2027:71477bc21fe8 2028:2ba4f06a264d
6 @node Numbers, Strings and Characters, Lisp Data Types, Top 6 @node Numbers, Strings and Characters, Lisp Data Types, Top
7 @chapter Numbers 7 @chapter Numbers
8 @cindex integers 8 @cindex integers
9 @cindex numbers 9 @cindex numbers
10 10
11 XEmacs supports two numeric data types: @dfn{integers} and 11 XEmacs supports two to five numeric data types. @dfn{Integers} and
12 @dfn{floating point numbers}. Integers are whole numbers such as 12 @dfn{floating point numbers} are always supported. As a build-time
13 @minus{}3, 0, #b0111, #xFEED, #o744. Their values are exact. The 13 option, @dfn{bignums}, @dfn{ratios}, and @dfn{bigfloats} may be
14 enabled on some platforms.
15
16 Integers, which are what Common Lisp calls
17 @dfn{fixnums}, are whole numbers such as @minus{}3, 0, #b0111, #xFEED,
18 #o744. Their values are exact, and their range is limited. The
14 number prefixes `#b', `#o', and `#x' are supported to represent numbers 19 number prefixes `#b', `#o', and `#x' are supported to represent numbers
15 in binary, octal, and hexadecimal notation (or radix). Floating point 20 in binary, octal, and hexadecimal notation (or radix). Floating point
16 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or 21 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
17 2.71828. They can also be expressed in exponential notation: 1.5e2 22 2.71828. They can also be expressed in exponential notation: 1.5e2
18 equals 150; in this example, @samp{e2} stands for ten to the second 23 equals 150; in this example, @samp{e2} stands for ten to the second
19 power, and is multiplied by 1.5. Floating point values are not exact; 24 power, and is multiplied by 1.5. Floating point values are not exact;
20 they have a fixed, limited amount of precision. 25 they have a fixed, limited amount of precision.
21 26
27 Bignums are arbitrary precision integers. When supported, XEmacs can
28 handle any integral calculations you have enough virtual memory to
29 store. (More precisely, on current architectures the representation
30 allows integers whose storage would exhaust the address space.) They
31 are notated in the same way as other integers (fixnums). XEmacs
32 automatically converts results of computations from fixnum to bignum,
33 and back, depending on the storage required to represent the number.
34 Thus use of bignums are entirely transparent to the user, except for a
35 few special applications that expect overflows. Ratios are rational
36 numbers with arbitrary precision. (In theory fixed-size rationals could
37 be supported, but for almost all applications floats are a reasonable
38 substitute for fixed-precision rationals.) They are notated in the
39 usual way with the solidus, for example 5/3 or @minus{}22/7. Bigfloats
40 are floating point numbers with arbitrary precision. Unlike integers,
41 which are always infinitely precise if they can be represented, floating
42 point numbers are inherently imprecise. Therefore XEmacs automatically
43 converts @emph{from float to bigfloat} when floats and bigfloats are
44 mixed in an expression, but a bigfloat will never be converted to a
45 float unless the user explicitly coerces the value. Nor will the result
46 of a float operation be converted to bigfloat, except for ``contagion''
47 from another operand that is already a bigfloat.
48
49 Note that the term ``integer'' is used throughout the XEmacs
50 documentation and code to mean ``fixnum''. This is inconsistent with
51 Common Lisp, and likely to cause confusion. Similarly, ``float'' is
52 used to mean ``fixed precision floating point number'', and the Common
53 Lisp distinctions among @dfn{short-floats}, @dfn{long-floats}, and
54 bigfloats are not reflected in XEmacs terminology.
55
22 @menu 56 @menu
23 * Integer Basics:: Representation and range of integers. 57 * Integer Basics:: Representation and range of integers.
24 * Float Basics:: Representation and range of floating point. 58 * Rational Basics:: Representation and range of rational numbers.
59 * Float Basics:: Representation and range of floating point.
60 * The Bignum Extension:: Arbitrary precision integers, ratios, and floats.
25 * Predicates on Numbers:: Testing for numbers. 61 * Predicates on Numbers:: Testing for numbers.
26 * Comparison of Numbers:: Equality and inequality predicates. 62 * Comparison of Numbers:: Equality and inequality predicates.
27 * Numeric Conversions:: Converting float to integer and vice versa. 63 * Numeric Conversions:: Converting float to integer and vice versa.
28 * Arithmetic Operations:: How to add, subtract, multiply and divide. 64 * Arithmetic Operations:: How to add, subtract, multiply and divide.
29 * Rounding Operations:: Explicitly rounding floating point numbers. 65 * Rounding Operations:: Explicitly rounding floating point numbers.
30 * Bitwise Operations:: Logical and, or, not, shifting. 66 * Bitwise Operations:: Logical and, or, not, shifting.
31 * Math Functions:: Trig, exponential and logarithmic functions. 67 * Math Functions:: Trig, exponential and logarithmic functions.
32 * Random Numbers:: Obtaining random integers, predictable or not. 68 * Random Numbers:: Obtaining random integers, predictable or not.
33 @end menu 69 @end menu
34 70
35 @node Integer Basics 71 @node Integer Basics
36 @section Integer Basics 72 @section Integer Basics
37 73
38 The range of values for an integer depends on the machine. The 74 The range of values for an integer depends on the machine. If a
39 minimum range is @minus{}134217728 to 134217727 (28 bits; i.e., 75 multiple-precision arithmetic library is available on your platform,
76 support for bignums, that is, integers with arbitrary precision, maybe
77 compiled in to your XEmacs. The rest of this section assumes that the
78 bignum extension is @emph{not} available. The bignum extension and the
79 user-visible differences in normal integer arithmetic are discussed in a
80 separate section @ref{The Bignum Extension}.
81
82 The minimum range is @minus{}1073741824 to 1073741823 (31 bits; i.e.,
40 @ifinfo 83 @ifinfo
41 -2**27 84 -2**30
42 @end ifinfo 85 @end ifinfo
43 @tex 86 @tex
44 $-2^{27}$ 87 $-2^{30}$
45 @end tex 88 @end tex
46 to 89 to
47 @ifinfo 90 @ifinfo
48 2**27 - 1), 91 2**30 - 1),
49 @end ifinfo 92 @end ifinfo
50 @tex 93 @tex
51 $2^{27}-1$), 94 $2^{30}-1$),
52 @end tex 95 @end tex
53 but some machines may provide a wider range. Many examples in this 96 but some machines may provide a wider range. Many examples in this
54 chapter assume an integer has 28 bits. 97 chapter assume an integer has 31 bits.
55 @cindex overflow 98 @cindex overflow
99
100 The range of fixnums is available to Lisp programs:
101
102 @defvar most-positive-fixnum
103 The fixed-precision integer closest in value to positive infinity.
104 @end defvar
105
106 @defvar most-negative-fixnum
107 The fixed-precision integer closest in value to negative infinity.
108 @end defvar
109
110 Here is a common idiom to temporarily suppress garbage collection:
111 @example
112 (garbage-collect)
113 (let ((gc-cons-threshold most-positive-fixnum))
114 ;; allocation-intensive computation
115 )
116 (garbage-collect)
117 @end example
56 118
57 The Lisp reader reads an integer as a sequence of digits with optional 119 The Lisp reader reads an integer as a sequence of digits with optional
58 initial sign and optional final period. 120 initial sign and optional final period.
59 121
60 @example 122 @example
61 1 ; @r{The integer 1.} 123 1 ; @r{The integer 1.}
62 1. ; @r{The integer 1.} 124 1. ; @r{The integer 1.}
63 +1 ; @r{Also the integer 1.} 125 +1 ; @r{Also the integer 1.}
64 -1 ; @r{The integer @minus{}1.} 126 -1 ; @r{The integer @minus{}1.}
65 268435457 ; @r{Also the integer 1, due to overflow.} 127 2147483648 ; @r{Read error, due to overflow.}
66 0 ; @r{The integer 0.} 128 0 ; @r{The integer 0.}
67 -0 ; @r{The integer 0.} 129 -0 ; @r{The integer 0.}
68 @end example 130 @end example
69 131
70 To understand how various functions work on integers, especially the 132 To understand how various functions work on integers, especially the
71 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to 133 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
72 view the numbers in their binary form. 134 view the numbers in their binary form.
73 135
74 In 28-bit binary, the decimal integer 5 looks like this: 136 In 31-bit binary, the decimal integer 5 looks like this:
75 137
76 @example 138 @example
77 0000 0000 0000 0000 0000 0000 0101 139 000 0000 0000 0000 0000 0000 0000 0101
78 @end example 140 @end example
79 141
80 @noindent 142 @noindent
81 (We have inserted spaces between groups of 4 bits, and two spaces 143 (We have inserted spaces between groups of 4 bits, and two spaces
82 between groups of 8 bits, to make the binary integer easier to read.) 144 between groups of 8 bits, to make the binary integer easier to read.)
83 145
84 The integer @minus{}1 looks like this: 146 The integer @minus{}1 looks like this:
85 147
86 @example 148 @example
87 1111 1111 1111 1111 1111 1111 1111 149 111 1111 1111 1111 1111 1111 1111 1111
88 @end example 150 @end example
89 151
90 @noindent 152 @noindent
91 @cindex two's complement 153 @cindex two's complement
92 @minus{}1 is represented as 28 ones. (This is called @dfn{two's 154 @minus{}1 is represented as 31 ones. (This is called @dfn{two's
93 complement} notation.) 155 complement} notation.)
94 156
95 The negative integer, @minus{}5, is creating by subtracting 4 from 157 The negative integer, @minus{}5, is creating by subtracting 4 from
96 @minus{}1. In binary, the decimal integer 4 is 100. Consequently, 158 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
97 @minus{}5 looks like this: 159 @minus{}5 looks like this:
98 160
99 @example 161 @example
100 1111 1111 1111 1111 1111 1111 1011 162 111 1111 1111 1111 1111 1111 1111 1011
101 @end example 163 @end example
102 164
103 In this implementation, the largest 28-bit binary integer is the 165 In this implementation, the largest 31-bit binary integer is the
104 decimal integer 134,217,727. In binary, it looks like this: 166 decimal integer 1,073,741,823. In binary, it looks like this:
105 167
106 @example 168 @example
107 0111 1111 1111 1111 1111 1111 1111 169 011 1111 1111 1111 1111 1111 1111 1111
108 @end example 170 @end example
109 171
110 Since the arithmetic functions do not check whether integers go 172 Since the arithmetic functions do not check whether integers go
111 outside their range, when you add 1 to 134,217,727, the value is the 173 outside their range, when you add 1 to 1,073,741,823, the value is the
112 negative integer @minus{}134,217,728: 174 negative integer @minus{}1,073,741,824:
113 175
114 @example 176 @example
115 (+ 1 134217727) 177 (+ 1 1073741823)
116 @result{} -134217728 178 @result{} -1073741824
117 @result{} 1000 0000 0000 0000 0000 0000 0000 179 @result{} 100 0000 0000 0000 0000 0000 0000 0000
118 @end example 180 @end example
119 181
120 Many of the following functions accept markers for arguments as well 182 Many of the arithmetic functions accept markers for arguments as well
121 as integers. (@xref{Markers}.) More precisely, the actual arguments to 183 as integers. (@xref{Markers}.) More precisely, the actual arguments to
122 such functions may be either integers or markers, which is why we often 184 such functions may be either integers or markers, which is why we often
123 give these arguments the name @var{int-or-marker}. When the argument 185 give these arguments the name @var{int-or-marker}. When the argument
124 value is a marker, its position value is used and its buffer is ignored. 186 value is a marker, its position value is used and its buffer is ignored.
125 187
127 In version 19, except where @emph{integer} is specified as an 189 In version 19, except where @emph{integer} is specified as an
128 argument, all of the functions for markers and integers also work for 190 argument, all of the functions for markers and integers also work for
129 floating point numbers. 191 floating point numbers.
130 @end ignore 192 @end ignore
131 193
194
195 @node Ratio Basics
196 @section Ratio Basics
197
198 Ratios (built-in rational numbers) are available only when the bignum
199 extension is built into your XEmacs. This facility is new and
200 experimental. It is discussed in a separate section for convenience of
201 updating the documentation @ref{The Bignum Extension}.
202
203
132 @node Float Basics 204 @node Float Basics
133 @section Floating Point Basics 205 @section Floating Point Basics
134 206
135 XEmacs supports floating point numbers. The precise range of floating 207 XEmacs supports floating point numbers. The precise range of floating
136 point numbers is machine-specific; it is the same as the range of the C 208 point numbers is machine-specific; it is the same as the range of the C
137 data type @code{double} on the machine in question. 209 data type @code{double} on the machine in question. If a
210 multiple-precision arithmetic library is available on your platform,
211 support for bigfloats, that is, floating point numbers with arbitrary
212 precision, maybe compiled in to your XEmacs. The rest of this section
213 assumes that the bignum extension is @emph{not} available. The bigfloat
214 extension and the user-visible differences in normal float arithmetic
215 are discussed in a separate section @ref{The Bignum Extension}.
138 216
139 The printed representation for floating point numbers requires either 217 The printed representation for floating point numbers requires either
140 a decimal point (with at least one digit following), an exponent, or 218 a decimal point (with at least one digit following), an exponent, or
141 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, 219 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
142 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point 220 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
167 This function returns the binary exponent of @var{number}. More 245 This function returns the binary exponent of @var{number}. More
168 precisely, the value is the logarithm of @var{number} base 2, rounded 246 precisely, the value is the logarithm of @var{number} base 2, rounded
169 down to an integer. 247 down to an integer.
170 @end defun 248 @end defun
171 249
250 The range of floats is available to Lisp programs:
251
252 @defvar most-positive-float
253 The fixed-precision floating-point-number closest in value to positive
254 infinity.
255 @end defvar
256
257 @defvar most-negative-float
258 The fixed-precision floating point number closest in value to negative
259 infinity.
260 @end defvar
261
262 @defvar least-positive-float
263 The positive float closest in value to 0. May not be normalized.
264 @end defvar
265
266 @defvar least-negative-float
267 The positive float closest in value to 0. Must be normalized.
268 @end defvar
269
270 @defvar least-positive-normalized-float
271 The negative float closest in value to 0. May not be normalized.
272 @end defvar
273
274 @defvar least-negative-normalized-float
275 The negative float closest in value to 0. Must be normalized.
276 @end defvar
277
278 Note that for floating point numbers there is an interesting limit on
279 how small they can get, as well as a limit on how big they can get. In
280 some representations, a floating point number is @dfn{normalized} if the
281 leading digit is non-zero. This allows representing numbers smaller
282 than the most-negative exponent can express, by having fractional
283 mantissas. This means that the number is less precise than a normalized
284 floating point number, so Lisp programs can detect loss of precision due
285 to unnormalized floats by checking whether the number is between
286 @code{least-positive-float} and @code{least-positive-normalized-float}.
287
288
289 @node The Bignum Extension
290 @section The Bignum Extension
291
292 In XEmacs 21.5.18, an extension was added by @email{james@@xemacs.org,
293 Jerry James} to allow linking with arbitrary-precision arithmetic
294 libraries if they are available on your platform. ``Arbitrary''
295 precision means precisely what it says. Your ability to work with large
296 numbers is limited only by the amount of virtual memory (and time) you
297 can throw at them.
298
299 As of 09 April 2004, support for the GNU Multiple Precision
300 arithmetic library (GMP) is nearly complete, and support for the BSD
301 Multiple Precision arithmetic library (MP) is being debugged. To enable
302 bignum support using GMP (respectively MP), invoke configure with your
303 usual options, and add @samp{--use-number-lib=gmp} (respectively
304 @samp{--use-number-lib=mp}). The default is to disable bignum support,
305 but if you are using a script to automate the build process, it may be
306 convenient to explicitly disable support by @emph{appending}
307 @samp{--use-number-lib=no} to your invocation of configure. GMP has an
308 MP compatibility mode, but it is not recommended, as there remain poorly
309 understood bugs (even more so than for other vendors' versions of MP).
310
311 With GMP, exact arithmetic with integers and ratios of arbitrary
312 precision and approximate (``floating point'') arithmetic of arbitrary
313 precision are implemented efficiently in the library. (Note that
314 numerical implementations are quite delicate and sensitive to
315 optimization. If the library was poorly optimized for your hardware, as
316 is often the case with Linux distributions for 80x86, you may achieve
317 gains of @emph{several orders of magnitude} by rebuilding the MP
318 library. See @uref{http://www.swox.com/gmp/gmp-speed.html}.) The MP
319 implementation provides arbitrary precision integers, but ratios were
320 implemented by the XEmacs implementer, Jerry James, who is not a
321 numerical analyst. Arbitrary precision floats are not available with
322 MP.
323
324 The XEmacs bignum facility implements the Common Lisp notion of
325 @dfn{contagion}, so that integers are always represented using the
326 ``smallest'' representation that is exact, and integral ratios are
327 converted to integers. Since floating point arithmetic is inherently
328 imprecise, numbers are implicitly coerced to bigfloats only if other
329 operands in the expression are bigfloat, and bigfloats are only coerced
330 to other numerical types by explicit calls to the function @code{coerce}.
331
332 Bignum support is incomplete. If you would like to help with bignum
333 support, especially on BSD MP, please subscribe to the
334 @uref{http://www.xemacs.org/Lists/#xemacs-beta, XEmacs Beta mailing
335 list}, and book up on @file{number-gmp.h} and @file{number-mp.h}. Jerry
336 has promised to write internals documentation eventually, but if your
337 skills run more to analysis and documentation than to writing new code,
338 feel free to fill in the gap!
339
340 @menu
341 * Bignum Basics:: Representation and range of integers.
342 * Ratio Basics:: Representation and range of rational numbers.
343 * Bigfloat Basics:: Representation and range of floating point.
344 * Contagion and Canonicalization:: Automatic coercion to other types.
345 * Compatibility Issues:: Changes in fixed-precision arithmetic.
346 @end menu
347
348
349 @node Bignum Basics
350 @subsection Bignum Basics
351
352 In most cases, bignum support should be transparent to users and Lisp
353 programmers. A bignum-enabled XEmacs will automatically convert from
354 fixnums to bignums and back in pure integer arithmetic, and for GNU MP,
355 from floats to bigfloats. (Bigfloats must be explicitly coerced to
356 other types, even if they are exactly representable by less precise
357 types.) The Lisp reader and printer have been enhanced to handle
358 bignums, as have the mathematical functions. Rationals (fixnums,
359 bignums, and ratios) are printed using the @samp{%d}, @samp{%o},
360 @samp{%x}, and @samp{%u} format conversions.
361
362
363 @node Ratio Basics
364 @subsection Ratio Basics
365
366 Ratios, when available have the read syntax and print representation
367 @samp{3/5}. Like other rationals (fixnums and bignums), they are
368 printed using the @samp{%d}, @samp{%o}, @samp{%x}, and @samp{%u} format
369 conversions.
370
371
372 @node Bigfloat Basics
373 @subsection Bigfloat Basics
374
375 Bigfloats, when available, have the same read syntax and print
376 representations as fixed-precision floats.
377
378
379 @node Contagion and Canonicalization
380 @subsection Contagion
381
382 @dfn{Contagion} is one way to address the requirement that an arithmetic
383 operation should not fail because of differing types of the operands, or
384 insufficient precision in the representation. With bignum support, we
385 can represent @code{(+ most-positive-fixnum most-positive-fixnum)} (or
386 @code{(* most-positive-fixnum most-positive-fixnum)}, for that matter)
387 @emph{exactly}. There should be no overflow or ``wrap-around,'' and the
388 computation should not be interrupted by an error. Contagion is the
389 idea that less precise operands are converted to the more precise type,
390 and then the operation is performed. This involves no loss of
391 information, and therefore it is safe to do it automatically.
392
393 In XEmacs, the following rules of contagion are used:
394
395 @c #### this probably wants names for each rule
396 @enumerate
397 @item
398 If a fixnum operation would overflow or underflow, the operands are
399 promoted to bignums and the operation is performed.
400
401 @item
402 If a fixnum and a bignum are the operands, the fixnum is promoted to
403 bignum, and the operation is performed.
404
405 @c #### seems plausible
406 @item
407 If a float operation would overflow or underflow (@emph{i.e.}, produce
408 an unrepresentably small but non-zero result), the operands are
409 converted to bigfloats and the operation performed.
410
411 @c #### seems likely....
412 @item
413 If an expression mixes a rational type (fixnum, bignum, or ratio) with a
414 float, the rational operand is converted to a float and the operation
415 performed if the result would fit in a float, otherwise both operands
416 are promoted to bigfloat, and the operation performed.
417
418 @item
419 If an expression mixes any other type with a bigfloat, the other operand
420 is converted to bigfloat and the operation performed.
421 @end enumerate
422
423 Note that there is @emph{no} contagion with ratios. Integer-to-integer
424 arithmetic with truncation or rounding is useful, and familiar.
425 Therefore instead of converting the result of @code{/} to ratio if it is
426 non-integral, the traditional definition is maintained, and a new
427 function @code{div} is provided to give a ratio result if a division
428 does not come out evenly.
429
430 On the other hand, the representation of arbitrary precision numbers is
431 inefficient in both space and time. The principle of
432 @dfn{canonicalization} addresses this issue. The idea of
433 canonicalization is that when no information is lost, the representation
434 should be demoted to the more efficient (smaller) representation. Note
435 that the inefficiency is likely to be greater than you might think.
436 Experience with numerical analysis shows that in very precise
437 calculations, precision tends to increase. Thus it is typically wasted
438 effort to attempt to convert to smaller representations, as the number
439 is often reused and requires a larger representation. However, XEmacs
440 Lisp presumes that calculations using bignums are the exception, so it
441 applies canonicalization. The rules are
442
443 @enumerate
444 @item
445 If a ratio is integral, demote it to a bignum. (In XEmacs Lisp all
446 ratios are arbitrary precision numbers.)
447
448 @item
449 If a bignum is small enough to fit in a fixnum, demote it to fixnum.
450 @end enumerate
451
452 Note that there are no rules to canonicalize floats or bigfloats. This
453 might seem surprising, but in both cases information will be lost. Any
454 floating point representation is implicitly approximate. A conversion
455 to a rational type, even if it seems exact, loses this information.
456 More subtly, demoting a bigfloat to a smaller bigfloat or to a float
457 would lose information about the precision of the result, and thus some
458 information about the accuracy. Thus floating point numbers are always
459 already in canonical form.
460
461 Of course the programmer can explicitly request canonicalization, or
462 more coercion to another type. Coercion uses the Common Lisp
463 compatibility function @code{coerce} from the @file{cl-extra.el}
464 library. A number can be explicitly converted to canonical form
465 according to the above rules using
466
467 @defun canonicalize-number number
468 Return the canonical form of @var{number}.
469 @end defun
470
471
472 @node Compatibility Issues
473 @subsection Compatibility Issues
474
475 @emph{Surgeon General's Warning}: The automatic conversions cannot be
476 disabled at runtime. Old functions will not produce ratios unless there
477 is a ratio operand, so there should be few surprises with type
478 conflicts (the contagion rules are quite natural for Lisp programmers
479 used to the behavior of integers and floats in pre-21.5.18 XEmacsen),
480 but they can't be ruled out. Also, if you work with extremely large
481 numbers, your machine may arbitrarily decide to hand you an unpleasant
482 surprise rather than a bignum.
483
484 User-visible changes in behavior include (in probable order of annoyance)
485
486 @itemize
487 @item
488 Arithmetic can cause a segfault, depending on your MP library.
489
490 GMP by default allocates temporaries on the stack. If you run out of
491 stack space, you're dead; there is no way that we know of to reliably
492 detect this condition, because @samp{alloca} is typically implemented to
493 be @emph{fast} rather than robust. If you just need a little more
494 oomph, use a bigger stack (@emph{e.g.}, the @file{ulimit -s} command in
495 bash(1)). If you want robustness at the cost of speed, configure GMP
496 with @samp{--disable-alloca} and rebuild the GMP library.
497
498 We do not know whether BSD MP uses @samp{alloca} or not. Please send
499 any information you have as a bug report (@kbd{M-x report-xemacs-bug
500 @key{RET}}), which will give us platform information. (We do know that
501 BSD MP implementations vary across vendors, but how much, we do not know
502 yet.)
503
504 @item
505 Terminology is not Common-Lisp-conforming. For example, ``integer'' for
506 Emacs Lisp means what Common Lisp calls ``fixnum''. This issue is being
507 investigated, but the use of ``integer'' for fixnum is pervasive and may
508 cause backward-compatibility and GNU-Emacs-compatibility problems.
509 There are similar issues for floating point numbers. Since Emacs Lisp
510 has not had a ratio type before, there should be no problems there.
511
512 @item
513 An atom with ratio read syntax now returns a number, not a symbol.
514
515 @item
516 Many operations that used to cause a range error now succeed, with
517 intermediate results and return values coerced to bignums as needed.
518
519 @item
520 The @samp{%u} format conversion will now give an error if its argument
521 is negative. (Without MP, it prints a number which Lisp can't read.)
522 @end itemize
523
524 This is not a compatibility issue in the sense of specification, but
525 careless programmers who have taken advantage of the immediate
526 representation for numbers and written @code{(eq x y)} are in for a
527 surprise. This doesn't work with bignums, even if both arguments are
528 bignums! Arbitrary precision obviously requires consing new objects
529 because the objects are ``large'' and of variable size, and the
530 definition of @samp{eq} does not permit different objects to compare as
531 equal. Instead of @code{eq}, use @code{eql}, in which numbers of the
532 same type which have equal values compare equal, or @code{=}, which does
533 any necessary type coercions before comparing for equality
534 @ref{Comparison of Numbers}.
535
536
172 @node Predicates on Numbers 537 @node Predicates on Numbers
173 @section Type Predicates for Numbers 538 @section Type Predicates for Numbers
174 539
175 The functions in this section test whether the argument is a number or 540 The functions in this section test whether the argument is a number or
176 whether it is a certain sort of number. The functions @code{integerp} 541 whether it is a certain sort of number. The functions @code{integerp}
222 number objects with the same numeric value. If you use @code{eq} to 587 number objects with the same numeric value. If you use @code{eq} to
223 compare them, then you test whether two values are the same 588 compare them, then you test whether two values are the same
224 @emph{object}. By contrast, @code{=} compares only the numeric values 589 @emph{object}. By contrast, @code{=} compares only the numeric values
225 of the objects. 590 of the objects.
226 591
227 At present, each integer value has a unique Lisp object in XEmacs Lisp. 592 In versions before 21.5.18, each integer value had a unique Lisp
228 Therefore, @code{eq} is equivalent to @code{=} where integers are 593 object in XEmacs Lisp. Therefore, @code{eq} was equivalent to @code{=}
229 concerned. It is sometimes convenient to use @code{eq} for comparing an 594 where integers are concerned. Even with the introduction of bignums, it
230 unknown value with an integer, because @code{eq} does not report an 595 is sometimes convenient to use @code{eq} for comparing an unknown value
231 error if the unknown value is not a number---it accepts arguments of any 596 with an integer, because @code{eq} does not report an error if the
232 type. By contrast, @code{=} signals an error if the arguments are not 597 unknown value is not a number---it accepts arguments of any type. By
233 numbers or markers. However, it is a good idea to use @code{=} if you 598 contrast, @code{=} signals an error if the arguments are not numbers or
234 can, even for comparing integers, just in case we change the 599 markers. However, it is a good idea to use @code{=} if you can, even
235 representation of integers in a future XEmacs version. 600 for comparing exact values, because two bignums or ratios with the same
601 value will often not be the same object.
236 602
237 There is another wrinkle: because floating point arithmetic is not 603 There is another wrinkle: because floating point arithmetic is not
238 exact, it is often a bad idea to check for equality of two floating 604 exact, it is often a bad idea to check for equality of two floating
239 point values. Usually it is better to test for approximate equality. 605 point values. Usually it is better to test for approximate equality.
240 Here's a function to do this: 606 Here's a function to do this: