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