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