Mercurial > hg > xemacs-beta
annotate man/lispref/numbers.texi @ 4885:6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
lisp/ChangeLog addition:
2010-01-24 Aidan Kehoe <kehoea@parhasard.net>
Correct the semantics of #'member*, #'eql, #'assoc* in the
presence of bignums; change the integerp byte code to fixnump
semantics.
* bytecomp.el (fixnump, integerp, byte-compile-integerp):
Change the integerp byte code to fixnump; add a byte-compile
method to integerp using fixnump and numberp and avoiding a
funcall most of the time, since in the non-core contexts where
integerp is used, it's mostly distinguishing between fixnums and
things that are not numbers at all.
* byte-optimize.el (side-effect-free-fns, byte-after-unbind-ops)
(byte-compile-side-effect-and-error-free-ops):
Replace the integerp bytecode with fixnump; add fixnump to the
side-effect-free-fns. Add the other extended number type
predicates to the list in passing.
* obsolete.el (floatp-safe): Mark this as obsolete.
* cl.el (eql): Go into more detail in the docstring here. Don't
bother checking whether both arguments are numbers; one is enough,
#'equal will fail correctly if they have distinct types.
(subst): Replace a call to #'integerp (deciding whether to use
#'memq or not) with one to #'fixnump.
Delete most-positive-fixnum, most-negative-fixnum from this file;
they're now always in C, so they can't be modified from Lisp.
* cl-seq.el (member*, assoc*, rassoc*):
Correct these functions in the presence of bignums.
* cl-macs.el (cl-make-type-test): The type test for a fixnum is
now fixnump. Ditch floatp-safe, use floatp instead.
(eql): Correct this compiler macro in the presence of bignums.
(assoc*): Correct this compiler macro in the presence of bignums.
* simple.el (undo):
Change #'integerp to #'fixnump here, since we use #'delq with the
same value as ELT a few lines down.
src/ChangeLog addition:
2010-01-24 Aidan Kehoe <kehoea@parhasard.net>
Fix problems with #'eql, extended number types, and the hash table
implementation; change the Bintegerp bytecode to fixnump semantics
even on bignum builds, since #'integerp can have a fast
implementation in terms of #'fixnump for most of its extant uses,
but not vice-versa.
* lisp.h: Always #include number.h; we want the macros provided in
it, even if the various number types are not available.
* number.h (NON_FIXNUM_NUMBER_P): New macro, giving 1 when its
argument is of non-immediate number type. Equivalent to FLOATP if
WITH_NUMBER_TYPES is not defined.
* elhash.c (lisp_object_eql_equal, lisp_object_eql_hash):
Use NON_FIXNUM_NUMBER_P in these functions, instead of FLOATP,
giving more correct behaviour in the presence of the extended
number types.
* bytecode.c (Bfixnump, execute_optimized_program):
Rename Bintegerp to Bfixnump; change its semantics to reflect the
new name on builds with bignum support.
* data.c (Ffixnump, Fintegerp, syms_of_data, vars_of_data):
Always make #'fixnump available, even on non-BIGNUM builds;
always implement #'integerp in this file, even on BIGNUM builds.
Move most-positive-fixnum, most-negative-fixnum here from
number.c, so they are Lisp constants even on builds without number
types, and attempts to change or bind them error.
Use the NUMBERP and INTEGERP macros even on builds without
extended number types.
* data.c (fixnum_char_or_marker_to_int):
Rename this function from integer_char_or_marker_to_int, to better
reflect the arguments it accepts.
* number.c (Fevenp, Foddp, syms_of_number):
Never provide #'integerp in this file. Remove #'oddp,
#'evenp; their implementations are overridden by those in cl.el.
* number.c (vars_of_number):
most-positive-fixnum, most-negative-fixnum are no longer here.
man/ChangeLog addition:
2010-01-23 Aidan Kehoe <kehoea@parhasard.net>
Generally: be careful to say fixnum, not integer, when talking
about fixed-precision integral types. I'm sure I've missed
instances, both here and in the docstrings, but this is a decent
start.
* lispref/text.texi (Columns):
Document where only fixnums, not integers generally, are accepted.
(Registers):
Remove some ancient char-int confoundance here.
* lispref/strings.texi (Creating Strings, Creating Strings):
Be more exact in describing where fixnums but not integers in
general are accepted.
(Creating Strings): Use a more contemporary example to illustrate
how concat deals with lists including integers about #xFF. Delete
some obsolete documentation on same.
(Char Table Types): Document that only fixnums are accepted as
values in syntax tables.
* lispref/searching.texi (String Search, Search and Replace):
Be exact in describing where fixnums but not integers in general
are accepted.
* lispref/range-tables.texi (Range Tables): Be exact in describing
them; only fixnums are accepted to describe ranges.
* lispref/os.texi (Killing XEmacs, User Identification)
(Time of Day, Time Conversion):
Be more exact about using fixnum where only fixed-precision
integers are accepted.
* lispref/objects.texi (Integer Type): Be more exact (and
up-to-date) about the possible values for
integers. Cross-reference to documentation of the bignum extension.
(Equality Predicates):
(Range Table Type):
(Array Type): Use fixnum, not integer, to describe a
fixed-precision integer.
(Syntax Table Type): Correct some English syntax here.
* lispref/numbers.texi (Numbers): Change the phrasing here to use
fixnum to mean the fixed-precision integers normal in emacs.
Document that our terminology deviates from that of Common Lisp,
and that we're working on it.
(Compatibility Issues): Reiterate the Common Lisp versus Emacs
Lisp compatibility issues.
(Comparison of Numbers, Arithmetic Operations):
* lispref/commands.texi (Command Loop Info, Working With Events):
* lispref/buffers.texi (Modification Time):
Be more exact in describing where fixnums but not integers in
general are accepted.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Sun, 24 Jan 2010 15:21:27 +0000 |
| parents | b5e1d4f6b66f |
| children | 378a34562cbe |
| 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 | |
| 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 | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4678
diff
changeset
|
917 @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
|
918 supports bignums. |
| 428 | 919 |
| 444 | 920 @defun 1+ number |
| 921 This function returns @var{number} plus one. @var{number} may be a | |
| 922 number, character or marker. Markers and characters are converted to | |
| 923 integers. | |
| 924 | |
| 428 | 925 For example, |
| 926 | |
| 927 @example | |
| 928 (setq foo 4) | |
| 929 @result{} 4 | |
| 930 (1+ foo) | |
| 931 @result{} 5 | |
| 932 @end example | |
| 933 | |
| 934 This function is not analogous to the C operator @code{++}---it does not | |
| 935 increment a variable. It just computes a sum. Thus, if we continue, | |
| 936 | |
| 937 @example | |
| 938 foo | |
| 939 @result{} 4 | |
| 940 @end example | |
| 941 | |
| 942 If you want to increment the variable, you must use @code{setq}, | |
| 943 like this: | |
| 944 | |
| 945 @example | |
| 946 (setq foo (1+ foo)) | |
| 947 @result{} 5 | |
| 948 @end example | |
| 949 | |
| 950 Now that the @code{cl} package is always available from lisp code, a | |
| 951 more convenient and natural way to increment a variable is | |
| 952 @w{@code{(incf foo)}}. | |
| 953 @end defun | |
| 954 | |
| 444 | 955 @defun 1- number |
| 956 This function returns @var{number} minus one. @var{number} may be a | |
| 957 number, character or marker. Markers and characters are converted to | |
| 958 integers. | |
| 428 | 959 @end defun |
| 960 | |
| 961 @defun abs number | |
| 962 This returns the absolute value of @var{number}. | |
| 963 @end defun | |
| 964 | |
| 444 | 965 @defun + &rest numbers |
| 428 | 966 This function adds its arguments together. When given no arguments, |
| 967 @code{+} returns 0. | |
| 968 | |
| 444 | 969 If any of the arguments are characters or markers, they are first |
| 970 converted to integers. | |
| 971 | |
| 428 | 972 @example |
| 973 (+) | |
| 974 @result{} 0 | |
| 975 (+ 1) | |
| 976 @result{} 1 | |
| 977 (+ 1 2 3 4) | |
| 978 @result{} 10 | |
| 979 @end example | |
| 980 @end defun | |
| 981 | |
| 444 | 982 @defun - &optional number &rest other-numbers |
| 428 | 983 The @code{-} function serves two purposes: negation and subtraction. |
| 984 When @code{-} has a single argument, the value is the negative of the | |
| 985 argument. When there are multiple arguments, @code{-} subtracts each of | |
| 444 | 986 the @var{other-numbers} from @var{number}, cumulatively. If there are |
| 987 no arguments, an error is signaled. | |
| 988 | |
| 989 If any of the arguments are characters or markers, they are first | |
| 990 converted to integers. | |
| 428 | 991 |
| 992 @example | |
| 993 (- 10 1 2 3 4) | |
| 994 @result{} 0 | |
| 995 (- 10) | |
| 996 @result{} -10 | |
| 997 (-) | |
| 998 @result{} 0 | |
| 999 @end example | |
| 1000 @end defun | |
| 1001 | |
| 444 | 1002 @defun * &rest numbers |
| 428 | 1003 This function multiplies its arguments together, and returns the |
| 1004 product. When given no arguments, @code{*} returns 1. | |
| 1005 | |
| 444 | 1006 If any of the arguments are characters or markers, they are first |
| 1007 converted to integers. | |
| 1008 | |
| 428 | 1009 @example |
| 1010 (*) | |
| 1011 @result{} 1 | |
| 1012 (* 1) | |
| 1013 @result{} 1 | |
| 1014 (* 1 2 3 4) | |
| 1015 @result{} 24 | |
| 1016 @end example | |
| 1017 @end defun | |
| 1018 | |
| 444 | 1019 @defun / dividend &rest divisors |
| 1020 The @code{/} function serves two purposes: inversion and division. When | |
| 1021 @code{/} has a single argument, the value is the inverse of the | |
| 1022 argument. When there are multiple arguments, @code{/} divides | |
| 1023 @var{dividend} by each of the @var{divisors}, cumulatively, returning | |
| 1024 the quotient. If there are no arguments, an error is signaled. | |
| 428 | 1025 |
| 444 | 1026 If none of the arguments are floats, then the result is an integer. |
| 428 | 1027 This means the result has to be rounded. On most machines, the result |
| 1028 is rounded towards zero after each division, but some machines may round | |
| 1029 differently with negative arguments. This is because the Lisp function | |
| 1030 @code{/} is implemented using the C division operator, which also | |
| 1031 permits machine-dependent rounding. As a practical matter, all known | |
| 1032 machines round in the standard fashion. | |
| 1033 | |
| 444 | 1034 If any of the arguments are characters or markers, they are first |
| 1035 converted to integers. | |
| 1036 | |
| 428 | 1037 @cindex @code{arith-error} in division |
| 1038 If you divide by 0, an @code{arith-error} error is signaled. | |
| 1039 (@xref{Errors}.) | |
| 1040 | |
| 1041 @example | |
| 1042 @group | |
| 1043 (/ 6 2) | |
| 1044 @result{} 3 | |
| 1045 @end group | |
| 1046 (/ 5 2) | |
| 1047 @result{} 2 | |
| 1048 (/ 25 3 2) | |
| 1049 @result{} 4 | |
| 444 | 1050 (/ 3.0) |
| 1051 @result{} 0.3333333333333333 | |
| 428 | 1052 (/ -17 6) |
| 1053 @result{} -2 | |
| 1054 @end example | |
| 1055 | |
| 1056 The result of @code{(/ -17 6)} could in principle be -3 on some | |
| 1057 machines. | |
| 1058 @end defun | |
| 1059 | |
| 1060 @defun % dividend divisor | |
| 1061 @cindex remainder | |
| 1062 This function returns the integer remainder after division of @var{dividend} | |
| 1063 by @var{divisor}. The arguments must be integers or markers. | |
| 1064 | |
| 1065 For negative arguments, the remainder is in principle machine-dependent | |
| 1066 since the quotient is; but in practice, all known machines behave alike. | |
| 1067 | |
| 1068 An @code{arith-error} results if @var{divisor} is 0. | |
| 1069 | |
| 1070 @example | |
| 1071 (% 9 4) | |
| 1072 @result{} 1 | |
| 1073 (% -9 4) | |
| 1074 @result{} -1 | |
| 1075 (% 9 -4) | |
| 1076 @result{} 1 | |
| 1077 (% -9 -4) | |
| 1078 @result{} -1 | |
| 1079 @end example | |
| 1080 | |
| 1081 For any two integers @var{dividend} and @var{divisor}, | |
| 1082 | |
| 1083 @example | |
| 1084 @group | |
| 1085 (+ (% @var{dividend} @var{divisor}) | |
| 1086 (* (/ @var{dividend} @var{divisor}) @var{divisor})) | |
| 1087 @end group | |
| 1088 @end example | |
| 1089 | |
| 1090 @noindent | |
| 1091 always equals @var{dividend}. | |
| 1092 @end defun | |
| 1093 | |
| 1094 @defun mod dividend divisor | |
| 1095 @cindex modulus | |
| 1096 This function returns the value of @var{dividend} modulo @var{divisor}; | |
| 1097 in other words, the remainder after division of @var{dividend} | |
| 1098 by @var{divisor}, but with the same sign as @var{divisor}. | |
| 1099 The arguments must be numbers or markers. | |
| 1100 | |
| 1101 Unlike @code{%}, @code{mod} returns a well-defined result for negative | |
| 1102 arguments. It also permits floating point arguments; it rounds the | |
| 1103 quotient downward (towards minus infinity) to an integer, and uses that | |
| 1104 quotient to compute the remainder. | |
| 1105 | |
| 1106 An @code{arith-error} results if @var{divisor} is 0. | |
| 1107 | |
| 1108 @example | |
| 1109 @group | |
| 1110 (mod 9 4) | |
| 1111 @result{} 1 | |
| 1112 @end group | |
| 1113 @group | |
| 1114 (mod -9 4) | |
| 1115 @result{} 3 | |
| 1116 @end group | |
| 1117 @group | |
| 1118 (mod 9 -4) | |
| 1119 @result{} -3 | |
| 1120 @end group | |
| 1121 @group | |
| 1122 (mod -9 -4) | |
| 1123 @result{} -1 | |
| 1124 @end group | |
| 1125 @group | |
| 1126 (mod 5.5 2.5) | |
| 1127 @result{} .5 | |
| 1128 @end group | |
| 1129 @end example | |
| 1130 | |
| 1131 For any two numbers @var{dividend} and @var{divisor}, | |
| 1132 | |
| 1133 @example | |
| 1134 @group | |
| 1135 (+ (mod @var{dividend} @var{divisor}) | |
| 1136 (* (floor @var{dividend} @var{divisor}) @var{divisor})) | |
| 1137 @end group | |
| 1138 @end example | |
| 1139 | |
| 1140 @noindent | |
| 1141 always equals @var{dividend}, subject to rounding error if either | |
| 1142 argument is floating point. For @code{floor}, see @ref{Numeric | |
| 1143 Conversions}. | |
| 1144 @end defun | |
| 1145 | |
| 1146 @node Rounding Operations | |
| 1147 @section Rounding Operations | |
| 1148 @cindex rounding without conversion | |
| 1149 | |
| 1150 The functions @code{ffloor}, @code{fceiling}, @code{fround} and | |
| 1151 @code{ftruncate} take a floating point argument and return a floating | |
| 1152 point result whose value is a nearby integer. @code{ffloor} returns the | |
| 1153 nearest integer below; @code{fceiling}, the nearest integer above; | |
| 1154 @code{ftruncate}, the nearest integer in the direction towards zero; | |
| 1155 @code{fround}, the nearest integer. | |
| 1156 | |
| 444 | 1157 @defun ffloor number |
| 1158 This function rounds @var{number} to the next lower integral value, and | |
| 428 | 1159 returns that value as a floating point number. |
| 1160 @end defun | |
| 1161 | |
| 444 | 1162 @defun fceiling number |
| 1163 This function rounds @var{number} to the next higher integral value, and | |
| 428 | 1164 returns that value as a floating point number. |
| 1165 @end defun | |
| 1166 | |
| 444 | 1167 @defun ftruncate number |
| 1168 This function rounds @var{number} towards zero to an integral value, and | |
| 428 | 1169 returns that value as a floating point number. |
| 1170 @end defun | |
| 1171 | |
| 444 | 1172 @defun fround number |
| 1173 This function rounds @var{number} to the nearest integral value, | |
| 428 | 1174 and returns that value as a floating point number. |
| 1175 @end defun | |
| 1176 | |
| 1177 @node Bitwise Operations | |
| 1178 @section Bitwise Operations on Integers | |
| 1179 | |
| 1180 In a computer, an integer is represented as a binary number, a | |
| 1181 sequence of @dfn{bits} (digits which are either zero or one). A bitwise | |
| 1182 operation acts on the individual bits of such a sequence. For example, | |
| 1183 @dfn{shifting} moves the whole sequence left or right one or more places, | |
| 1184 reproducing the same pattern ``moved over''. | |
| 1185 | |
| 1186 The bitwise operations in XEmacs Lisp apply only to integers. | |
| 1187 | |
| 1188 @defun lsh integer1 count | |
| 1189 @cindex logical shift | |
| 1190 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the | |
| 1191 bits in @var{integer1} to the left @var{count} places, or to the right | |
| 1192 if @var{count} is negative, bringing zeros into the vacated bits. If | |
| 1193 @var{count} is negative, @code{lsh} shifts zeros into the leftmost | |
| 1194 (most-significant) bit, producing a positive result even if | |
| 1195 @var{integer1} is negative. Contrast this with @code{ash}, below. | |
| 1196 | |
| 1197 Here are two examples of @code{lsh}, shifting a pattern of bits one | |
| 1198 place to the left. We show only the low-order eight bits of the binary | |
| 1199 pattern; the rest are all zero. | |
| 1200 | |
| 1201 @example | |
| 1202 @group | |
| 1203 (lsh 5 1) | |
| 1204 @result{} 10 | |
| 1205 ;; @r{Decimal 5 becomes decimal 10.} | |
| 1206 00000101 @result{} 00001010 | |
| 1207 | |
| 1208 (lsh 7 1) | |
| 1209 @result{} 14 | |
| 1210 ;; @r{Decimal 7 becomes decimal 14.} | |
| 1211 00000111 @result{} 00001110 | |
| 1212 @end group | |
| 1213 @end example | |
| 1214 | |
| 1215 @noindent | |
| 1216 As the examples illustrate, shifting the pattern of bits one place to | |
| 1217 the left produces a number that is twice the value of the previous | |
| 1218 number. | |
| 1219 | |
| 1220 Shifting a pattern of bits two places to the left produces results | |
| 1221 like this (with 8-bit binary numbers): | |
| 1222 | |
| 1223 @example | |
| 1224 @group | |
| 1225 (lsh 3 2) | |
| 1226 @result{} 12 | |
| 1227 ;; @r{Decimal 3 becomes decimal 12.} | |
| 444 | 1228 00000011 @result{} 00001100 |
| 428 | 1229 @end group |
| 1230 @end example | |
| 1231 | |
| 1232 On the other hand, shifting one place to the right looks like this: | |
| 1233 | |
| 1234 @example | |
| 1235 @group | |
| 1236 (lsh 6 -1) | |
| 1237 @result{} 3 | |
| 1238 ;; @r{Decimal 6 becomes decimal 3.} | |
| 444 | 1239 00000110 @result{} 00000011 |
| 428 | 1240 @end group |
| 1241 | |
| 1242 @group | |
| 1243 (lsh 5 -1) | |
| 1244 @result{} 2 | |
| 1245 ;; @r{Decimal 5 becomes decimal 2.} | |
| 444 | 1246 00000101 @result{} 00000010 |
| 428 | 1247 @end group |
| 1248 @end example | |
| 1249 | |
| 1250 @noindent | |
| 1251 As the example illustrates, shifting one place to the right divides the | |
| 1252 value of a positive integer by two, rounding downward. | |
| 1253 | |
| 1254 The function @code{lsh}, like all XEmacs Lisp arithmetic functions, does | |
| 1255 not check for overflow, so shifting left can discard significant bits | |
| 1256 and change the sign of the number. For example, left shifting | |
| 1257 134,217,727 produces @minus{}2 on a 28-bit machine: | |
| 1258 | |
| 1259 @example | |
| 1260 (lsh 134217727 1) ; @r{left shift} | |
| 1261 @result{} -2 | |
| 1262 @end example | |
| 1263 | |
| 1264 In binary, in the 28-bit implementation, the argument looks like this: | |
| 1265 | |
| 1266 @example | |
| 1267 @group | |
| 1268 ;; @r{Decimal 134,217,727} | |
| 444 | 1269 0111 1111 1111 1111 1111 1111 1111 |
| 428 | 1270 @end group |
| 1271 @end example | |
| 1272 | |
| 1273 @noindent | |
| 1274 which becomes the following when left shifted: | |
| 1275 | |
| 1276 @example | |
| 1277 @group | |
| 1278 ;; @r{Decimal @minus{}2} | |
| 444 | 1279 1111 1111 1111 1111 1111 1111 1110 |
| 428 | 1280 @end group |
| 1281 @end example | |
| 1282 @end defun | |
| 1283 | |
| 1284 @defun ash integer1 count | |
| 1285 @cindex arithmetic shift | |
| 1286 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} | |
| 1287 to the left @var{count} places, or to the right if @var{count} | |
| 1288 is negative. | |
| 1289 | |
| 1290 @code{ash} gives the same results as @code{lsh} except when | |
| 1291 @var{integer1} and @var{count} are both negative. In that case, | |
| 1292 @code{ash} puts ones in the empty bit positions on the left, while | |
| 1293 @code{lsh} puts zeros in those bit positions. | |
| 1294 | |
| 1295 Thus, with @code{ash}, shifting the pattern of bits one place to the right | |
| 1296 looks like this: | |
| 1297 | |
| 1298 @example | |
| 1299 @group | |
| 444 | 1300 (ash -6 -1) @result{} -3 |
| 428 | 1301 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} |
| 1302 1111 1111 1111 1111 1111 1111 1010 | |
| 444 | 1303 @result{} |
| 428 | 1304 1111 1111 1111 1111 1111 1111 1101 |
| 1305 @end group | |
| 1306 @end example | |
| 1307 | |
| 1308 In contrast, shifting the pattern of bits one place to the right with | |
| 1309 @code{lsh} looks like this: | |
| 1310 | |
| 1311 @example | |
| 1312 @group | |
| 1313 (lsh -6 -1) @result{} 134217725 | |
| 1314 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.} | |
| 1315 1111 1111 1111 1111 1111 1111 1010 | |
| 444 | 1316 @result{} |
| 428 | 1317 0111 1111 1111 1111 1111 1111 1101 |
| 1318 @end group | |
| 1319 @end example | |
| 1320 | |
| 1321 Here are other examples: | |
| 1322 | |
| 1323 @c !!! Check if lined up in smallbook format! XDVI shows problem | |
| 1324 @c with smallbook but not with regular book! --rjc 16mar92 | |
| 1325 @smallexample | |
| 1326 @group | |
| 1327 ; @r{ 28-bit binary values} | |
| 1328 | |
| 1329 (lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1330 @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100} | |
| 1331 @end group | |
| 1332 @group | |
| 1333 (ash 5 2) | |
| 1334 @result{} 20 | |
| 1335 (lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} | |
| 1336 @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100} | |
| 1337 (ash -5 2) | |
| 1338 @result{} -20 | |
| 1339 @end group | |
| 1340 @group | |
| 1341 (lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1342 @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001} | |
| 1343 @end group | |
| 1344 @group | |
| 1345 (ash 5 -2) | |
| 1346 @result{} 1 | |
| 1347 @end group | |
| 1348 @group | |
| 1349 (lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} | |
| 1350 @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110} | |
| 1351 @end group | |
| 1352 @group | |
| 1353 (ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} | |
| 1354 @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110} | |
| 1355 @end group | |
| 1356 @end smallexample | |
| 1357 @end defun | |
| 1358 | |
| 1359 @defun logand &rest ints-or-markers | |
| 1360 @cindex logical and | |
| 1361 @cindex bitwise and | |
| 1362 This function returns the ``logical and'' of the arguments: the | |
| 1363 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is | |
| 1364 set in all the arguments. (``Set'' means that the value of the bit is 1 | |
| 1365 rather than 0.) | |
| 1366 | |
| 1367 For example, using 4-bit binary numbers, the ``logical and'' of 13 and | |
| 1368 12 is 12: 1101 combined with 1100 produces 1100. | |
| 1369 In both the binary numbers, the leftmost two bits are set (i.e., they | |
| 1370 are 1's), so the leftmost two bits of the returned value are set. | |
| 1371 However, for the rightmost two bits, each is zero in at least one of | |
| 1372 the arguments, so the rightmost two bits of the returned value are 0's. | |
| 1373 | |
| 1374 @noindent | |
| 1375 Therefore, | |
| 1376 | |
| 1377 @example | |
| 1378 @group | |
| 1379 (logand 13 12) | |
| 1380 @result{} 12 | |
| 1381 @end group | |
| 1382 @end example | |
| 1383 | |
| 1384 If @code{logand} is not passed any argument, it returns a value of | |
| 1385 @minus{}1. This number is an identity element for @code{logand} | |
| 1386 because its binary representation consists entirely of ones. If | |
| 1387 @code{logand} is passed just one argument, it returns that argument. | |
| 1388 | |
| 1389 @smallexample | |
| 1390 @group | |
| 1391 ; @r{ 28-bit binary values} | |
| 1392 | |
| 1393 (logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} | |
| 1394 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} | |
| 1395 @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | |
| 1396 @end group | |
| 1397 | |
| 1398 @group | |
| 1399 (logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} | |
| 1400 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} | |
| 1401 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100} | |
| 1402 @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100} | |
| 1403 @end group | |
| 1404 | |
| 1405 @group | |
| 1406 (logand) | |
| 1407 @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111 1111} | |
| 1408 @end group | |
| 1409 @end smallexample | |
| 1410 @end defun | |
| 1411 | |
| 1412 @defun logior &rest ints-or-markers | |
| 1413 @cindex logical inclusive or | |
| 1414 @cindex bitwise or | |
| 1415 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit | |
| 1416 is set in the result if, and only if, the @var{n}th bit is set in at least | |
| 1417 one of the arguments. If there are no arguments, the result is zero, | |
| 1418 which is an identity element for this operation. If @code{logior} is | |
| 1419 passed just one argument, it returns that argument. | |
| 1420 | |
| 1421 @smallexample | |
| 1422 @group | |
| 1423 ; @r{ 28-bit binary values} | |
| 1424 | |
| 1425 (logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | |
| 1426 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1427 @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} | |
| 1428 @end group | |
| 1429 | |
| 1430 @group | |
| 1431 (logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | |
| 1432 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1433 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111} | |
| 1434 @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111} | |
| 1435 @end group | |
| 1436 @end smallexample | |
| 1437 @end defun | |
| 1438 | |
| 1439 @defun logxor &rest ints-or-markers | |
| 1440 @cindex bitwise exclusive or | |
| 1441 @cindex logical exclusive or | |
| 1442 This function returns the ``exclusive or'' of its arguments: the | |
| 1443 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is | |
| 1444 set in an odd number of the arguments. If there are no arguments, the | |
| 1445 result is 0, which is an identity element for this operation. If | |
| 1446 @code{logxor} is passed just one argument, it returns that argument. | |
| 1447 | |
| 1448 @smallexample | |
| 1449 @group | |
| 1450 ; @r{ 28-bit binary values} | |
| 1451 | |
| 1452 (logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | |
| 1453 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1454 @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001} | |
| 1455 @end group | |
| 1456 | |
| 1457 @group | |
| 1458 (logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | |
| 1459 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1460 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111} | |
| 1461 @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} | |
| 1462 @end group | |
| 1463 @end smallexample | |
| 1464 @end defun | |
| 1465 | |
| 1466 @defun lognot integer | |
| 1467 @cindex logical not | |
| 1468 @cindex bitwise not | |
| 1469 This function returns the logical complement of its argument: the @var{n}th | |
| 1470 bit is one in the result if, and only if, the @var{n}th bit is zero in | |
| 1471 @var{integer}, and vice-versa. | |
| 1472 | |
| 1473 @example | |
| 444 | 1474 (lognot 5) |
| 428 | 1475 @result{} -6 |
| 1476 ;; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | |
| 1477 ;; @r{becomes} | |
| 1478 ;; -6 = @r{1111 1111 1111 1111 1111 1111 1010} | |
| 1479 @end example | |
| 1480 @end defun | |
| 1481 | |
| 1482 @node Math Functions | |
| 1483 @section Standard Mathematical Functions | |
| 1484 @cindex transcendental functions | |
| 1485 @cindex mathematical functions | |
| 1486 | |
| 1487 These mathematical functions are available if floating point is | |
| 1488 supported (which is the normal state of affairs). They allow integers | |
| 1489 as well as floating point numbers as arguments. | |
| 1490 | |
| 444 | 1491 @defun sin number |
| 1492 @defunx cos number | |
| 1493 @defunx tan number | |
| 428 | 1494 These are the ordinary trigonometric functions, with argument measured |
| 1495 in radians. | |
| 1496 @end defun | |
| 1497 | |
| 444 | 1498 @defun asin number |
| 1499 The value of @code{(asin @var{number})} is a number between @minus{}pi/2 | |
| 1500 and pi/2 (inclusive) whose sine is @var{number}; if, however, @var{number} | |
| 428 | 1501 is out of range (outside [-1, 1]), then the result is a NaN. |
| 1502 @end defun | |
| 1503 | |
| 444 | 1504 @defun acos number |
| 1505 The value of @code{(acos @var{number})} is a number between 0 and pi | |
| 1506 (inclusive) whose cosine is @var{number}; if, however, @var{number} | |
| 428 | 1507 is out of range (outside [-1, 1]), then the result is a NaN. |
| 1508 @end defun | |
| 1509 | |
| 444 | 1510 @defun atan number &optional number2 |
| 1511 The value of @code{(atan @var{number})} is a number between @minus{}pi/2 | |
| 1512 and pi/2 (exclusive) whose tangent is @var{number}. | |
| 1513 | |
| 1514 If optional argument @var{number2} is supplied, the function returns | |
| 1515 @code{atan2(@var{number},@var{number2})}. | |
| 428 | 1516 @end defun |
| 1517 | |
| 444 | 1518 @defun sinh number |
| 1519 @defunx cosh number | |
| 1520 @defunx tanh number | |
| 428 | 1521 These are the ordinary hyperbolic trigonometric functions. |
| 1522 @end defun | |
| 1523 | |
| 444 | 1524 @defun asinh number |
| 1525 @defunx acosh number | |
| 1526 @defunx atanh number | |
| 428 | 1527 These are the inverse hyperbolic trigonometric functions. |
| 1528 @end defun | |
| 1529 | |
| 444 | 1530 @defun exp number |
| 428 | 1531 This is the exponential function; it returns @i{e} to the power |
| 444 | 1532 @var{number}. @i{e} is a fundamental mathematical constant also called the |
| 428 | 1533 base of natural logarithms. |
| 1534 @end defun | |
| 1535 | |
| 444 | 1536 @defun log number &optional base |
| 1537 This function returns the logarithm of @var{number}, with base @var{base}. | |
| 1738 | 1538 If you don't specify @var{base}, the base @code{e} is used. If @var{number} |
| 428 | 1539 is negative, the result is a NaN. |
| 1540 @end defun | |
| 1541 | |
| 444 | 1542 @defun log10 number |
| 1543 This function returns the logarithm of @var{number}, with base 10. If | |
| 1544 @var{number} is negative, the result is a NaN. @code{(log10 @var{x})} | |
| 428 | 1545 @equiv{} @code{(log @var{x} 10)}, at least approximately. |
| 1546 @end defun | |
| 1547 | |
| 1548 @defun expt x y | |
| 1549 This function returns @var{x} raised to power @var{y}. If both | |
| 1550 arguments are integers and @var{y} is positive, the result is an | |
| 1551 integer; in this case, it is truncated to fit the range of possible | |
| 1552 integer values. | |
| 1553 @end defun | |
| 1554 | |
| 444 | 1555 @defun sqrt number |
| 1556 This returns the square root of @var{number}. If @var{number} is negative, | |
| 428 | 1557 the value is a NaN. |
| 1558 @end defun | |
| 1559 | |
| 444 | 1560 @defun cube-root number |
| 1561 This returns the cube root of @var{number}. | |
| 428 | 1562 @end defun |
| 1563 | |
| 1564 @node Random Numbers | |
| 1565 @section Random Numbers | |
| 1566 @cindex random numbers | |
| 1567 | |
| 1568 A deterministic computer program cannot generate true random numbers. | |
| 1569 For most purposes, @dfn{pseudo-random numbers} suffice. A series of | |
| 1570 pseudo-random numbers is generated in a deterministic fashion. The | |
| 1571 numbers are not truly random, but they have certain properties that | |
| 1572 mimic a random series. For example, all possible values occur equally | |
| 1573 often in a pseudo-random series. | |
| 1574 | |
| 1575 In XEmacs, pseudo-random numbers are generated from a ``seed'' number. | |
| 1576 Starting from any given seed, the @code{random} function always | |
| 1577 generates the same sequence of numbers. XEmacs always starts with the | |
| 1578 same seed value, so the sequence of values of @code{random} is actually | |
| 1579 the same in each XEmacs run! For example, in one operating system, the | |
| 1580 first call to @code{(random)} after you start XEmacs always returns | |
| 1581 -1457731, and the second one always returns -7692030. This | |
| 1582 repeatability is helpful for debugging. | |
| 1583 | |
| 2090 | 1584 If you want reasonably unpredictable random numbers, execute |
| 1585 @code{(random t)}. This chooses a new seed based on the current time of | |
| 1586 day and on XEmacs's process @sc{id} number. (This is not | |
| 1587 cryptographically strong, it's just hard for a @emph{human} to | |
| 1588 anticipate.) | |
| 428 | 1589 |
| 1590 @defun random &optional limit | |
| 1591 This function returns a pseudo-random integer. Repeated calls return a | |
| 1592 series of pseudo-random integers. | |
| 1593 | |
| 1594 If @var{limit} is a positive integer, the value is chosen to be | |
| 1595 nonnegative and less than @var{limit}. | |
| 1596 | |
| 1597 If @var{limit} is @code{t}, it means to choose a new seed based on the | |
| 1598 current time of day and on XEmacs's process @sc{id} number. | |
| 1599 @c "XEmacs'" is incorrect usage! | |
| 2090 | 1600 @end defun |
| 428 | 1601 |
| 2090 | 1602 The range of random is implementation-dependent. On any machine, the |
| 1603 result of @code{(random)} is an arbitrary fixnum, so on 32-bit | |
| 1604 architectures it is normally in the range -2^30 (inclusive) to +2^30 | |
| 1605 (exclusive). With the optional integer argument @var{limit}, the result | |
| 1606 is in the range 0 (inclusive) to @var{limit} (exclusive). Note this is | |
| 1607 regardless of the presence of the bignum extension. | |
| 1608 |