Mercurial > hg > xemacs-beta
annotate man/lispref/numbers.texi @ 4792:95b04754ea8c
Make #'equalp more compatible with CL; add a compiler macro, test & doc it.
lisp/ChangeLog addition:
2009-11-08 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (cl-string-vector-equalp)
(cl-bit-vector-vector-equalp, cl-vector-array-equalp)
(cl-hash-table-contents-equalp): New functions, to implement
equalp treating arrays with identical contents as equivalent, as
specified by Common Lisp.
(equalp): Revise this function to implement array equivalence,
and the hash-table equalp behaviour specified by CL.
* cl-macs.el (equalp): Add a compiler macro for this function,
used when one of the arguments is constant, and as such, its type
is known at compile time.
man/ChangeLog addition:
2009-11-08 Aidan Kehoe <kehoea@parhasard.net>
* lispref/objects.texi (Equality Predicates):
Document #'equalp here, as well as #'equal and #'eq.
tests/ChangeLog addition:
2009-12-31 Aidan Kehoe <kehoea@parhasard.net>
* automated/lisp-tests.el:
Test much of the functionality of equalp; add a pointer to Paul
Dietz' ANSI test suite for this function, converted to Emacs
Lisp. Not including the tests themselves in XEmacs because who
owns the copyright on the files is unclear and the GCL people
didn't respond to my queries.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Thu, 31 Dec 2009 15:09:41 +0000 |
| 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 |