Mercurial > emacs
comparison lispref/numbers.texi @ 88155:d7ddb3e565de
sync with trunk
author | Henrik Enberg <henrik.enberg@telia.com> |
---|---|
date | Mon, 16 Jan 2006 00:03:54 +0000 |
parents | 23a1cea22d13 |
children |
comparison
equal
deleted
inserted
replaced
88154:8ce476d3ba36 | 88155:d7ddb3e565de |
---|---|
1 @c -*-texinfo-*- | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | 2 @c This is part of the GNU Emacs Lisp Reference Manual. |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, |
4 @c Free Software Foundation, Inc. | 4 @c 2004, 2005 Free Software Foundation, Inc. |
5 @c See the file elisp.texi for copying conditions. | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/numbers | 6 @setfilename ../info/numbers |
7 @node Numbers, Strings and Characters, Lisp Data Types, Top | 7 @node Numbers, Strings and Characters, Lisp Data Types, Top |
8 @chapter Numbers | 8 @chapter Numbers |
9 @cindex integers | 9 @cindex integers |
34 @node Integer Basics | 34 @node Integer Basics |
35 @comment node-name, next, previous, up | 35 @comment node-name, next, previous, up |
36 @section Integer Basics | 36 @section Integer Basics |
37 | 37 |
38 The range of values for an integer depends on the machine. The | 38 The range of values for an integer depends on the machine. The |
39 minimum range is @minus{}134217728 to 134217727 (28 bits; i.e., | 39 minimum range is @minus{}268435456 to 268435455 (29 bits; i.e., |
40 @ifnottex | 40 @ifnottex |
41 -2**27 | 41 -2**28 |
42 @end ifnottex | 42 @end ifnottex |
43 @tex | 43 @tex |
44 @math{-2^{27}} | 44 @math{-2^{28}} |
45 @end tex | 45 @end tex |
46 to | 46 to |
47 @ifnottex | 47 @ifnottex |
48 2**27 - 1), | 48 2**28 - 1), |
49 @end ifnottex | 49 @end ifnottex |
50 @tex | 50 @tex |
51 @math{2^{27}-1}), | 51 @math{2^{28}-1}), |
52 @end tex | 52 @end tex |
53 but some machines may provide a wider range. Many examples in this | 53 but some machines may provide a wider range. Many examples in this |
54 chapter assume an integer has 28 bits. | 54 chapter assume an integer has 29 bits. |
55 @cindex overflow | 55 @cindex overflow |
56 | 56 |
57 The Lisp reader reads an integer as a sequence of digits with optional | 57 The Lisp reader reads an integer as a sequence of digits with optional |
58 initial sign and optional final period. | 58 initial sign and optional final period. |
59 | 59 |
60 @example | 60 @example |
61 1 ; @r{The integer 1.} | 61 1 ; @r{The integer 1.} |
62 1. ; @r{The integer 1.} | 62 1. ; @r{The integer 1.} |
63 +1 ; @r{Also the integer 1.} | 63 +1 ; @r{Also the integer 1.} |
64 -1 ; @r{The integer @minus{}1.} | 64 -1 ; @r{The integer @minus{}1.} |
65 268435457 ; @r{Also the integer 1, due to overflow.} | 65 536870913 ; @r{Also the integer 1, due to overflow.} |
66 0 ; @r{The integer 0.} | 66 0 ; @r{The integer 0.} |
67 -0 ; @r{The integer 0.} | 67 -0 ; @r{The integer 0.} |
68 @end example | 68 @end example |
69 | 69 |
70 @cindex integers in specific radix | 70 @cindex integers in specific radix |
71 @cindex radix for reading an integer | 71 @cindex radix for reading an integer |
72 @cindex base for reading an integer | 72 @cindex base for reading an integer |
73 In addition, the Lisp reader recognizes a syntax for integers in | 73 @cindex hex numbers |
74 bases other than 10: @samp{#B@var{integer}} reads @var{integer} in | 74 @cindex octal numbers |
75 binary (radix 2), @samp{#O@var{integer}} reads @var{integer} in octal | 75 @cindex reading numbers in hex, octal, and binary |
76 (radix 8), @samp{#X@var{integer}} reads @var{integer} in hexadecimal | 76 The syntax for integers in bases other than 10 uses @samp{#} |
77 (radix 16), and @samp{#@var{radix}r@var{integer}} reads @var{integer} | 77 followed by a letter that specifies the radix: @samp{b} for binary, |
78 in radix @var{radix} (where @var{radix} is between 2 and 36, | 78 @samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to |
79 inclusively). Case is not significant for the letter after @samp{#} | 79 specify radix @var{radix}. Case is not significant for the letter |
80 (@samp{B}, @samp{O}, etc.) that denotes the radix. | 80 that specifies the radix. Thus, @samp{#b@var{integer}} reads |
81 @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads | |
82 @var{integer} in radix @var{radix}. Allowed values of @var{radix} run | |
83 from 2 to 36. For example: | |
84 | |
85 @example | |
86 #b101100 @result{} 44 | |
87 #o54 @result{} 44 | |
88 #x2c @result{} 44 | |
89 #24r1k @result{} 44 | |
90 @end example | |
81 | 91 |
82 To understand how various functions work on integers, especially the | 92 To understand how various functions work on integers, especially the |
83 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to | 93 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to |
84 view the numbers in their binary form. | 94 view the numbers in their binary form. |
85 | 95 |
86 In 28-bit binary, the decimal integer 5 looks like this: | 96 In 29-bit binary, the decimal integer 5 looks like this: |
87 | 97 |
88 @example | 98 @example |
89 0000 0000 0000 0000 0000 0000 0101 | 99 0 0000 0000 0000 0000 0000 0000 0101 |
90 @end example | 100 @end example |
91 | 101 |
92 @noindent | 102 @noindent |
93 (We have inserted spaces between groups of 4 bits, and two spaces | 103 (We have inserted spaces between groups of 4 bits, and two spaces |
94 between groups of 8 bits, to make the binary integer easier to read.) | 104 between groups of 8 bits, to make the binary integer easier to read.) |
95 | 105 |
96 The integer @minus{}1 looks like this: | 106 The integer @minus{}1 looks like this: |
97 | 107 |
98 @example | 108 @example |
99 1111 1111 1111 1111 1111 1111 1111 | 109 1 1111 1111 1111 1111 1111 1111 1111 |
100 @end example | 110 @end example |
101 | 111 |
102 @noindent | 112 @noindent |
103 @cindex two's complement | 113 @cindex two's complement |
104 @minus{}1 is represented as 28 ones. (This is called @dfn{two's | 114 @minus{}1 is represented as 29 ones. (This is called @dfn{two's |
105 complement} notation.) | 115 complement} notation.) |
106 | 116 |
107 The negative integer, @minus{}5, is creating by subtracting 4 from | 117 The negative integer, @minus{}5, is creating by subtracting 4 from |
108 @minus{}1. In binary, the decimal integer 4 is 100. Consequently, | 118 @minus{}1. In binary, the decimal integer 4 is 100. Consequently, |
109 @minus{}5 looks like this: | 119 @minus{}5 looks like this: |
110 | 120 |
111 @example | 121 @example |
112 1111 1111 1111 1111 1111 1111 1011 | 122 1 1111 1111 1111 1111 1111 1111 1011 |
113 @end example | 123 @end example |
114 | 124 |
115 In this implementation, the largest 28-bit binary integer value is | 125 In this implementation, the largest 29-bit binary integer value is |
116 134,217,727 in decimal. In binary, it looks like this: | 126 268,435,455 in decimal. In binary, it looks like this: |
117 | 127 |
118 @example | 128 @example |
119 0111 1111 1111 1111 1111 1111 1111 | 129 0 1111 1111 1111 1111 1111 1111 1111 |
120 @end example | 130 @end example |
121 | 131 |
122 Since the arithmetic functions do not check whether integers go | 132 Since the arithmetic functions do not check whether integers go |
123 outside their range, when you add 1 to 134,217,727, the value is the | 133 outside their range, when you add 1 to 268,435,455, the value is the |
124 negative integer @minus{}134,217,728: | 134 negative integer @minus{}268,435,456: |
125 | 135 |
126 @example | 136 @example |
127 (+ 1 134217727) | 137 (+ 1 268435455) |
128 @result{} -134217728 | 138 @result{} -268435456 |
129 @result{} 1000 0000 0000 0000 0000 0000 0000 | 139 @result{} 1 0000 0000 0000 0000 0000 0000 0000 |
130 @end example | 140 @end example |
131 | 141 |
132 Many of the functions described in this chapter accept markers for | 142 Many of the functions described in this chapter accept markers for |
133 arguments in place of numbers. (@xref{Markers}.) Since the actual | 143 arguments in place of numbers. (@xref{Markers}.) Since the actual |
134 arguments to such functions may be either numbers or markers, we often | 144 arguments to such functions may be either numbers or markers, we often |
135 give these arguments the name @var{number-or-marker}. When the argument | 145 give these arguments the name @var{number-or-marker}. When the argument |
136 value is a marker, its position value is used and its buffer is ignored. | 146 value is a marker, its position value is used and its buffer is ignored. |
147 | |
148 @defvar most-positive-fixnum | |
149 The value of this variable is the largest integer that Emacs Lisp | |
150 can handle. | |
151 @end defvar | |
152 | |
153 @defvar most-negative-fixnum | |
154 The value of this variable is the smallest integer that Emacs Lisp can | |
155 handle. It is negative. | |
156 @end defvar | |
137 | 157 |
138 @node Float Basics | 158 @node Float Basics |
139 @section Floating Point Basics | 159 @section Floating Point Basics |
140 | 160 |
141 Floating point numbers are useful for representing numbers that are | 161 Floating point numbers are useful for representing numbers that are |
148 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and | 168 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and |
149 @samp{.15e4} are five ways of writing a floating point number whose | 169 @samp{.15e4} are five ways of writing a floating point number whose |
150 value is 1500. They are all equivalent. You can also use a minus sign | 170 value is 1500. They are all equivalent. You can also use a minus sign |
151 to write negative floating point numbers, as in @samp{-1.0}. | 171 to write negative floating point numbers, as in @samp{-1.0}. |
152 | 172 |
153 @cindex IEEE floating point | 173 @cindex @acronym{IEEE} floating point |
154 @cindex positive infinity | 174 @cindex positive infinity |
155 @cindex negative infinity | 175 @cindex negative infinity |
156 @cindex infinity | 176 @cindex infinity |
157 @cindex NaN | 177 @cindex NaN |
158 Most modern computers support the IEEE floating point standard, which | 178 Most modern computers support the @acronym{IEEE} floating point standard, |
159 provides for positive infinity and negative infinity as floating point | 179 which provides for positive infinity and negative infinity as floating point |
160 values. It also provides for a class of values called NaN or | 180 values. It also provides for a class of values called NaN or |
161 ``not-a-number''; numerical functions return such values in cases where | 181 ``not-a-number''; numerical functions return such values in cases where |
162 there is no correct answer. For example, @code{(sqrt -1.0)} returns a | 182 there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a |
163 NaN. For practical purposes, there's no significant difference between | 183 NaN. For practical purposes, there's no significant difference between |
164 different NaN values in Emacs Lisp, and there's no rule for precisely | 184 different NaN values in Emacs Lisp, and there's no rule for precisely |
165 which NaN value should be used in a particular case, so Emacs Lisp | 185 which NaN value should be used in a particular case, so Emacs Lisp |
166 doesn't try to distinguish them. Here are the read syntaxes for | 186 doesn't try to distinguish them (but it does report the sign, if you |
167 these special floating point values: | 187 print it). Here are the read syntaxes for these special floating |
188 point values: | |
168 | 189 |
169 @table @asis | 190 @table @asis |
170 @item positive infinity | 191 @item positive infinity |
171 @samp{1.0e+INF} | 192 @samp{1.0e+INF} |
172 @item negative infinity | 193 @item negative infinity |
173 @samp{-1.0e+INF} | 194 @samp{-1.0e+INF} |
174 @item Not-a-number | 195 @item Not-a-number |
175 @samp{0.0e+NaN}. | 196 @samp{0.0e+NaN} or @samp{-0.0e+NaN}. |
176 @end table | 197 @end table |
177 | 198 |
178 In addition, the value @code{-0.0} is distinguishable from ordinary | 199 To test whether a floating point value is a NaN, compare it with |
179 zero in IEEE floating point (although @code{equal} and @code{=} consider | 200 itself using @code{=}. That returns @code{nil} for a NaN, and |
180 them equal values). | 201 @code{t} for any other floating point value. |
202 | |
203 The value @code{-0.0} is distinguishable from ordinary zero in | |
204 @acronym{IEEE} floating point, but Emacs Lisp @code{equal} and | |
205 @code{=} consider them equal values. | |
181 | 206 |
182 You can use @code{logb} to extract the binary exponent of a floating | 207 You can use @code{logb} to extract the binary exponent of a floating |
183 point number (or estimate the logarithm of an integer): | 208 point number (or estimate the logarithm of an integer): |
184 | 209 |
185 @defun logb number | 210 @defun logb number |
196 @end defun | 221 @end defun |
197 | 222 |
198 @node Predicates on Numbers | 223 @node Predicates on Numbers |
199 @section Type Predicates for Numbers | 224 @section Type Predicates for Numbers |
200 | 225 |
201 The functions in this section test whether the argument is a number or | 226 The functions in this section test for numbers, or for a specific |
202 whether it is a certain sort of number. The functions @code{integerp} | 227 type of number. The functions @code{integerp} and @code{floatp} can |
203 and @code{floatp} can take any type of Lisp object as argument (the | 228 take any type of Lisp object as argument (they would not be of much |
204 predicates would not be of much use otherwise); but the @code{zerop} | 229 use otherwise), but the @code{zerop} predicate requires a number as |
205 predicate requires a number as its argument. See also | 230 its argument. See also @code{integer-or-marker-p} and |
206 @code{integer-or-marker-p} and @code{number-or-marker-p}, in | 231 @code{number-or-marker-p}, in @ref{Predicates on Markers}. |
207 @ref{Predicates on Markers}. | |
208 | 232 |
209 @defun floatp object | 233 @defun floatp object |
210 This predicate tests whether its argument is a floating point | 234 This predicate tests whether its argument is a floating point |
211 number and returns @code{t} if so, @code{nil} otherwise. | 235 number and returns @code{t} if so, @code{nil} otherwise. |
212 | 236 |
236 | 260 |
237 @defun zerop number | 261 @defun zerop number |
238 This predicate tests whether its argument is zero, and returns @code{t} | 262 This predicate tests whether its argument is zero, and returns @code{t} |
239 if so, @code{nil} otherwise. The argument must be a number. | 263 if so, @code{nil} otherwise. The argument must be a number. |
240 | 264 |
241 These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}. | 265 @code{(zerop x)} is equivalent to @code{(= x 0)}. |
242 @end defun | 266 @end defun |
243 | 267 |
244 @node Comparison of Numbers | 268 @node Comparison of Numbers |
245 @section Comparison of Numbers | 269 @section Comparison of Numbers |
246 @cindex number equality | 270 @cindex number equality |
260 type. By contrast, @code{=} signals an error if the arguments are not | 284 type. By contrast, @code{=} signals an error if the arguments are not |
261 numbers or markers. However, it is a good idea to use @code{=} if you | 285 numbers or markers. However, it is a good idea to use @code{=} if you |
262 can, even for comparing integers, just in case we change the | 286 can, even for comparing integers, just in case we change the |
263 representation of integers in a future Emacs version. | 287 representation of integers in a future Emacs version. |
264 | 288 |
265 Sometimes it is useful to compare numbers with @code{equal}; it treats | 289 Sometimes it is useful to compare numbers with @code{equal}; it |
266 two numbers as equal if they have the same data type (both integers, or | 290 treats two numbers as equal if they have the same data type (both |
267 both floating point) and the same value. By contrast, @code{=} can | 291 integers, or both floating point) and the same value. By contrast, |
268 treat an integer and a floating point number as equal. | 292 @code{=} can treat an integer and a floating point number as equal. |
293 @xref{Equality Predicates}. | |
269 | 294 |
270 There is another wrinkle: because floating point arithmetic is not | 295 There is another wrinkle: because floating point arithmetic is not |
271 exact, it is often a bad idea to check for equality of two floating | 296 exact, it is often a bad idea to check for equality of two floating |
272 point values. Usually it is better to test for approximate equality. | 297 point values. Usually it is better to test for approximate equality. |
273 Here's a function to do this: | 298 Here's a function to do this: |
293 @defun = number-or-marker1 number-or-marker2 | 318 @defun = number-or-marker1 number-or-marker2 |
294 This function tests whether its arguments are numerically equal, and | 319 This function tests whether its arguments are numerically equal, and |
295 returns @code{t} if so, @code{nil} otherwise. | 320 returns @code{t} if so, @code{nil} otherwise. |
296 @end defun | 321 @end defun |
297 | 322 |
323 @defun eql value1 value2 | |
324 This function acts like @code{eq} except when both arguments are | |
325 numbers. It compares numbers by type and numberic value, so that | |
326 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and | |
327 @code{(eql 1 1)} both return @code{t}. | |
328 @end defun | |
329 | |
298 @defun /= number-or-marker1 number-or-marker2 | 330 @defun /= number-or-marker1 number-or-marker2 |
299 This function tests whether its arguments are numerically equal, and | 331 This function tests whether its arguments are numerically equal, and |
300 returns @code{t} if they are not, and @code{nil} if they are. | 332 returns @code{t} if they are not, and @code{nil} if they are. |
301 @end defun | 333 @end defun |
302 | 334 |
323 otherwise. | 355 otherwise. |
324 @end defun | 356 @end defun |
325 | 357 |
326 @defun max number-or-marker &rest numbers-or-markers | 358 @defun max number-or-marker &rest numbers-or-markers |
327 This function returns the largest of its arguments. | 359 This function returns the largest of its arguments. |
328 If any of the argument is floating-point, the value is returned | 360 If any of the arguments is floating-point, the value is returned |
329 as floating point, even if it was given as an integer. | 361 as floating point, even if it was given as an integer. |
330 | 362 |
331 @example | 363 @example |
332 (max 20) | 364 (max 20) |
333 @result{} 20 | 365 @result{} 20 |
338 @end example | 370 @end example |
339 @end defun | 371 @end defun |
340 | 372 |
341 @defun min number-or-marker &rest numbers-or-markers | 373 @defun min number-or-marker &rest numbers-or-markers |
342 This function returns the smallest of its arguments. | 374 This function returns the smallest of its arguments. |
343 If any of the argument is floating-point, the value is returned | 375 If any of the arguments is floating-point, the value is returned |
344 as floating point, even if it was given as an integer. | 376 as floating point, even if it was given as an integer. |
345 | 377 |
346 @example | 378 @example |
347 (min -4 1) | 379 (min -4 1) |
348 @result{} -4 | 380 @result{} -4 |
364 If @var{number} is already a floating point number, @code{float} returns | 396 If @var{number} is already a floating point number, @code{float} returns |
365 it unchanged. | 397 it unchanged. |
366 @end defun | 398 @end defun |
367 | 399 |
368 There are four functions to convert floating point numbers to integers; | 400 There are four functions to convert floating point numbers to integers; |
369 they differ in how they round. These functions accept integer arguments | 401 they differ in how they round. All accept an argument @var{number} |
370 also, and return such arguments unchanged. | 402 and an optional argument @var{divisor}. Both arguments may be |
371 | 403 integers or floating point numbers. @var{divisor} may also be |
372 @defun truncate number | 404 @code{nil}. If @var{divisor} is @code{nil} or omitted, these |
405 functions convert @var{number} to an integer, or return it unchanged | |
406 if it already is an integer. If @var{divisor} is non-@code{nil}, they | |
407 divide @var{number} by @var{divisor} and convert the result to an | |
408 integer. An @code{arith-error} results if @var{divisor} is 0. | |
409 | |
410 @defun truncate number &optional divisor | |
373 This returns @var{number}, converted to an integer by rounding towards | 411 This returns @var{number}, converted to an integer by rounding towards |
374 zero. | 412 zero. |
375 | 413 |
376 @example | 414 @example |
377 (truncate 1.2) | 415 (truncate 1.2) |
387 | 425 |
388 @defun floor number &optional divisor | 426 @defun floor number &optional divisor |
389 This returns @var{number}, converted to an integer by rounding downward | 427 This returns @var{number}, converted to an integer by rounding downward |
390 (towards negative infinity). | 428 (towards negative infinity). |
391 | 429 |
392 If @var{divisor} is specified, @code{floor} divides @var{number} by | 430 If @var{divisor} is specified, this uses the kind of division |
393 @var{divisor} and then converts to an integer; this uses the kind of | 431 operation that corresponds to @code{mod}, rounding downward. |
394 division operation that corresponds to @code{mod}, rounding downward. | |
395 An @code{arith-error} results if @var{divisor} is 0. | |
396 | 432 |
397 @example | 433 @example |
398 (floor 1.2) | 434 (floor 1.2) |
399 @result{} 1 | 435 @result{} 1 |
400 (floor 1.7) | 436 (floor 1.7) |
406 (floor 5.99 3) | 442 (floor 5.99 3) |
407 @result{} 1 | 443 @result{} 1 |
408 @end example | 444 @end example |
409 @end defun | 445 @end defun |
410 | 446 |
411 @defun ceiling number | 447 @defun ceiling number &optional divisor |
412 This returns @var{number}, converted to an integer by rounding upward | 448 This returns @var{number}, converted to an integer by rounding upward |
413 (towards positive infinity). | 449 (towards positive infinity). |
414 | 450 |
415 @example | 451 @example |
416 (ceiling 1.2) | 452 (ceiling 1.2) |
422 (ceiling -1.7) | 458 (ceiling -1.7) |
423 @result{} -1 | 459 @result{} -1 |
424 @end example | 460 @end example |
425 @end defun | 461 @end defun |
426 | 462 |
427 @defun round number | 463 @defun round number &optional divisor |
428 This returns @var{number}, converted to an integer by rounding towards the | 464 This returns @var{number}, converted to an integer by rounding towards the |
429 nearest integer. Rounding a value equidistant between two integers | 465 nearest integer. Rounding a value equidistant between two integers |
430 may choose the integer closer to zero, or it may prefer an even integer, | 466 may choose the integer closer to zero, or it may prefer an even integer, |
431 depending on your machine. | 467 depending on your machine. |
432 | 468 |
453 | 489 |
454 All of these functions except @code{%} return a floating point value | 490 All of these functions except @code{%} return a floating point value |
455 if any argument is floating. | 491 if any argument is floating. |
456 | 492 |
457 It is important to note that in Emacs Lisp, arithmetic functions | 493 It is important to note that in Emacs Lisp, arithmetic functions |
458 do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to | 494 do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to |
459 @minus{}134217728, depending on your hardware. | 495 @minus{}268435456, depending on your hardware. |
460 | 496 |
461 @defun 1+ number-or-marker | 497 @defun 1+ number-or-marker |
462 This function returns @var{number-or-marker} plus 1. | 498 This function returns @var{number-or-marker} plus 1. |
463 For example, | 499 For example, |
464 | 500 |
550 machines round in the standard fashion. | 586 machines round in the standard fashion. |
551 | 587 |
552 @cindex @code{arith-error} in division | 588 @cindex @code{arith-error} in division |
553 If you divide an integer by 0, an @code{arith-error} error is signaled. | 589 If you divide an integer by 0, an @code{arith-error} error is signaled. |
554 (@xref{Errors}.) Floating point division by zero returns either | 590 (@xref{Errors}.) Floating point division by zero returns either |
555 infinity or a NaN if your machine supports IEEE floating point; | 591 infinity or a NaN if your machine supports @acronym{IEEE} floating point; |
556 otherwise, it signals an @code{arith-error} error. | 592 otherwise, it signals an @code{arith-error} error. |
557 | 593 |
558 @example | 594 @example |
559 @group | 595 @group |
560 (/ 6 2) | 596 (/ 6 2) |
773 value of a positive integer by two, rounding downward. | 809 value of a positive integer by two, rounding downward. |
774 | 810 |
775 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does | 811 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does |
776 not check for overflow, so shifting left can discard significant bits | 812 not check for overflow, so shifting left can discard significant bits |
777 and change the sign of the number. For example, left shifting | 813 and change the sign of the number. For example, left shifting |
778 134,217,727 produces @minus{}2 on a 28-bit machine: | 814 268,435,455 produces @minus{}2 on a 29-bit machine: |
779 | 815 |
780 @example | 816 @example |
781 (lsh 134217727 1) ; @r{left shift} | 817 (lsh 268435455 1) ; @r{left shift} |
782 @result{} -2 | 818 @result{} -2 |
783 @end example | 819 @end example |
784 | 820 |
785 In binary, in the 28-bit implementation, the argument looks like this: | 821 In binary, in the 29-bit implementation, the argument looks like this: |
786 | 822 |
787 @example | 823 @example |
788 @group | 824 @group |
789 ;; @r{Decimal 134,217,727} | 825 ;; @r{Decimal 268,435,455} |
790 0111 1111 1111 1111 1111 1111 1111 | 826 0 1111 1111 1111 1111 1111 1111 1111 |
791 @end group | 827 @end group |
792 @end example | 828 @end example |
793 | 829 |
794 @noindent | 830 @noindent |
795 which becomes the following when left shifted: | 831 which becomes the following when left shifted: |
796 | 832 |
797 @example | 833 @example |
798 @group | 834 @group |
799 ;; @r{Decimal @minus{}2} | 835 ;; @r{Decimal @minus{}2} |
800 1111 1111 1111 1111 1111 1111 1110 | 836 1 1111 1111 1111 1111 1111 1111 1110 |
801 @end group | 837 @end group |
802 @end example | 838 @end example |
803 @end defun | 839 @end defun |
804 | 840 |
805 @defun ash integer1 count | 841 @defun ash integer1 count |
818 | 854 |
819 @example | 855 @example |
820 @group | 856 @group |
821 (ash -6 -1) @result{} -3 | 857 (ash -6 -1) @result{} -3 |
822 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} | 858 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} |
823 1111 1111 1111 1111 1111 1111 1010 | 859 1 1111 1111 1111 1111 1111 1111 1010 |
824 @result{} | 860 @result{} |
825 1111 1111 1111 1111 1111 1111 1101 | 861 1 1111 1111 1111 1111 1111 1111 1101 |
826 @end group | 862 @end group |
827 @end example | 863 @end example |
828 | 864 |
829 In contrast, shifting the pattern of bits one place to the right with | 865 In contrast, shifting the pattern of bits one place to the right with |
830 @code{lsh} looks like this: | 866 @code{lsh} looks like this: |
831 | 867 |
832 @example | 868 @example |
833 @group | 869 @group |
834 (lsh -6 -1) @result{} 134217725 | 870 (lsh -6 -1) @result{} 268435453 |
835 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.} | 871 ;; @r{Decimal @minus{}6 becomes decimal 268,435,453.} |
836 1111 1111 1111 1111 1111 1111 1010 | 872 1 1111 1111 1111 1111 1111 1111 1010 |
837 @result{} | 873 @result{} |
838 0111 1111 1111 1111 1111 1111 1101 | 874 0 1111 1111 1111 1111 1111 1111 1101 |
839 @end group | 875 @end group |
840 @end example | 876 @end example |
841 | 877 |
842 Here are other examples: | 878 Here are other examples: |
843 | 879 |
844 @c !!! Check if lined up in smallbook format! XDVI shows problem | 880 @c !!! Check if lined up in smallbook format! XDVI shows problem |
845 @c with smallbook but not with regular book! --rjc 16mar92 | 881 @c with smallbook but not with regular book! --rjc 16mar92 |
846 @smallexample | 882 @smallexample |
847 @group | 883 @group |
848 ; @r{ 28-bit binary values} | 884 ; @r{ 29-bit binary values} |
849 | 885 |
850 (lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | 886 (lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
851 @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100} | 887 @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100} |
852 @end group | 888 @end group |
853 @group | 889 @group |
854 (ash 5 2) | 890 (ash 5 2) |
855 @result{} 20 | 891 @result{} 20 |
856 (lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} | 892 (lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} |
857 @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100} | 893 @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100} |
858 (ash -5 2) | 894 (ash -5 2) |
859 @result{} -20 | 895 @result{} -20 |
860 @end group | 896 @end group |
861 @group | 897 @group |
862 (lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | 898 (lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
863 @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001} | 899 @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001} |
864 @end group | 900 @end group |
865 @group | 901 @group |
866 (ash 5 -2) | 902 (ash 5 -2) |
867 @result{} 1 | 903 @result{} 1 |
868 @end group | 904 @end group |
869 @group | 905 @group |
870 (lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} | 906 (lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} |
871 @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110} | 907 @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110} |
872 @end group | 908 @end group |
873 @group | 909 @group |
874 (ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} | 910 (ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} |
875 @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110} | 911 @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110} |
876 @end group | 912 @end group |
877 @end smallexample | 913 @end smallexample |
878 @end defun | 914 @end defun |
879 | 915 |
880 @defun logand &rest ints-or-markers | 916 @defun logand &rest ints-or-markers |
907 because its binary representation consists entirely of ones. If | 943 because its binary representation consists entirely of ones. If |
908 @code{logand} is passed just one argument, it returns that argument. | 944 @code{logand} is passed just one argument, it returns that argument. |
909 | 945 |
910 @smallexample | 946 @smallexample |
911 @group | 947 @group |
912 ; @r{ 28-bit binary values} | 948 ; @r{ 29-bit binary values} |
913 | 949 |
914 (logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} | 950 (logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} |
915 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} | 951 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} |
916 @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | 952 @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} |
917 @end group | 953 @end group |
918 | 954 |
919 @group | 955 @group |
920 (logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} | 956 (logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} |
921 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} | 957 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} |
922 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100} | 958 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} |
923 @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100} | 959 @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} |
924 @end group | 960 @end group |
925 | 961 |
926 @group | 962 @group |
927 (logand) | 963 (logand) |
928 @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111 1111} | 964 @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111} |
929 @end group | 965 @end group |
930 @end smallexample | 966 @end smallexample |
931 @end defun | 967 @end defun |
932 | 968 |
933 @defun logior &rest ints-or-markers | 969 @defun logior &rest ints-or-markers |
939 which is an identity element for this operation. If @code{logior} is | 975 which is an identity element for this operation. If @code{logior} is |
940 passed just one argument, it returns that argument. | 976 passed just one argument, it returns that argument. |
941 | 977 |
942 @smallexample | 978 @smallexample |
943 @group | 979 @group |
944 ; @r{ 28-bit binary values} | 980 ; @r{ 29-bit binary values} |
945 | 981 |
946 (logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | 982 (logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} |
947 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | 983 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
948 @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} | 984 @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} |
949 @end group | 985 @end group |
950 | 986 |
951 @group | 987 @group |
952 (logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | 988 (logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} |
953 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | 989 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
954 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111} | 990 ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} |
955 @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111} | 991 @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111} |
956 @end group | 992 @end group |
957 @end smallexample | 993 @end smallexample |
958 @end defun | 994 @end defun |
959 | 995 |
960 @defun logxor &rest ints-or-markers | 996 @defun logxor &rest ints-or-markers |
966 result is 0, which is an identity element for this operation. If | 1002 result is 0, which is an identity element for this operation. If |
967 @code{logxor} is passed just one argument, it returns that argument. | 1003 @code{logxor} is passed just one argument, it returns that argument. |
968 | 1004 |
969 @smallexample | 1005 @smallexample |
970 @group | 1006 @group |
971 ; @r{ 28-bit binary values} | 1007 ; @r{ 29-bit binary values} |
972 | 1008 |
973 (logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | 1009 (logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} |
974 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | 1010 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
975 @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001} | 1011 @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001} |
976 @end group | 1012 @end group |
977 | 1013 |
978 @group | 1014 @group |
979 (logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} | 1015 (logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} |
980 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | 1016 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
981 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111} | 1017 ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} |
982 @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} | 1018 @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} |
983 @end group | 1019 @end group |
984 @end smallexample | 1020 @end smallexample |
985 @end defun | 1021 @end defun |
986 | 1022 |
987 @defun lognot integer | 1023 @defun lognot integer |
992 @var{integer}, and vice-versa. | 1028 @var{integer}, and vice-versa. |
993 | 1029 |
994 @example | 1030 @example |
995 (lognot 5) | 1031 (lognot 5) |
996 @result{} -6 | 1032 @result{} -6 |
997 ;; 5 = @r{0000 0000 0000 0000 0000 0000 0101} | 1033 ;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
998 ;; @r{becomes} | 1034 ;; @r{becomes} |
999 ;; -6 = @r{1111 1111 1111 1111 1111 1111 1010} | 1035 ;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010} |
1000 @end example | 1036 @end example |
1001 @end defun | 1037 @end defun |
1002 | 1038 |
1003 @node Math Functions | 1039 @node Math Functions |
1004 @section Standard Mathematical Functions | 1040 @section Standard Mathematical Functions |
1028 pi/2 | 1064 pi/2 |
1029 @end ifnottex | 1065 @end ifnottex |
1030 @tex | 1066 @tex |
1031 @math{\pi/2} | 1067 @math{\pi/2} |
1032 @end tex | 1068 @end tex |
1033 (inclusive) whose sine is @var{arg}; if, however, @var{arg} | 1069 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of |
1034 is out of range (outside [-1, 1]), then the result is a NaN. | 1070 range (outside [-1, 1]), it signals a @code{domain-error} error. |
1035 @end defun | 1071 @end defun |
1036 | 1072 |
1037 @defun acos arg | 1073 @defun acos arg |
1038 The value of @code{(acos @var{arg})} is a number between 0 and | 1074 The value of @code{(acos @var{arg})} is a number between 0 and |
1039 @ifnottex | 1075 @ifnottex |
1040 pi | 1076 pi |
1041 @end ifnottex | 1077 @end ifnottex |
1042 @tex | 1078 @tex |
1043 @math{\pi} | 1079 @math{\pi} |
1044 @end tex | 1080 @end tex |
1045 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} | 1081 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out |
1046 is out of range (outside [-1, 1]), then the result is a NaN. | 1082 of range (outside [-1, 1]), it signals a @code{domain-error} error. |
1047 @end defun | 1083 @end defun |
1048 | 1084 |
1049 @defun atan y &optional x | 1085 @defun atan y &optional x |
1050 The value of @code{(atan @var{y})} is a number between | 1086 The value of @code{(atan @var{y})} is a number between |
1051 @ifnottex | 1087 @ifnottex |
1093 @math{e} | 1129 @math{e} |
1094 @end tex | 1130 @end tex |
1095 @ifnottex | 1131 @ifnottex |
1096 @i{e} | 1132 @i{e} |
1097 @end ifnottex | 1133 @end ifnottex |
1098 is used. If @var{arg} | 1134 is used. If @var{arg} is negative, it signals a @code{domain-error} |
1099 is negative, the result is a NaN. | 1135 error. |
1100 @end defun | 1136 @end defun |
1101 | 1137 |
1102 @ignore | 1138 @ignore |
1103 @defun expm1 arg | 1139 @defun expm1 arg |
1104 This function returns @code{(1- (exp @var{arg}))}, but it is more | 1140 This function returns @code{(1- (exp @var{arg}))}, but it is more |
1113 @end defun | 1149 @end defun |
1114 @end ignore | 1150 @end ignore |
1115 | 1151 |
1116 @defun log10 arg | 1152 @defun log10 arg |
1117 This function returns the logarithm of @var{arg}, with base 10. If | 1153 This function returns the logarithm of @var{arg}, with base 10. If |
1118 @var{arg} is negative, the result is a NaN. @code{(log10 @var{x})} | 1154 @var{arg} is negative, it signals a @code{domain-error} error. |
1119 @equiv{} @code{(log @var{x} 10)}, at least approximately. | 1155 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least |
1156 approximately. | |
1120 @end defun | 1157 @end defun |
1121 | 1158 |
1122 @defun expt x y | 1159 @defun expt x y |
1123 This function returns @var{x} raised to power @var{y}. If both | 1160 This function returns @var{x} raised to power @var{y}. If both |
1124 arguments are integers and @var{y} is positive, the result is an | 1161 arguments are integers and @var{y} is positive, the result is an |
1125 integer; in this case, it is truncated to fit the range of possible | 1162 integer; in this case, overflow causes truncation, so watch out. |
1126 integer values. | |
1127 @end defun | 1163 @end defun |
1128 | 1164 |
1129 @defun sqrt arg | 1165 @defun sqrt arg |
1130 This returns the square root of @var{arg}. If @var{arg} is negative, | 1166 This returns the square root of @var{arg}. If @var{arg} is negative, |
1131 the value is a NaN. | 1167 it signals a @code{domain-error} error. |
1132 @end defun | 1168 @end defun |
1133 | 1169 |
1134 @node Random Numbers | 1170 @node Random Numbers |
1135 @section Random Numbers | 1171 @section Random Numbers |
1136 @cindex random numbers | 1172 @cindex random numbers |
1151 -1457731, and the second one always returns -7692030. This | 1187 -1457731, and the second one always returns -7692030. This |
1152 repeatability is helpful for debugging. | 1188 repeatability is helpful for debugging. |
1153 | 1189 |
1154 If you want random numbers that don't always come out the same, execute | 1190 If you want random numbers that don't always come out the same, execute |
1155 @code{(random t)}. This chooses a new seed based on the current time of | 1191 @code{(random t)}. This chooses a new seed based on the current time of |
1156 day and on Emacs's process @sc{id} number. | 1192 day and on Emacs's process @acronym{ID} number. |
1157 | 1193 |
1158 @defun random &optional limit | 1194 @defun random &optional limit |
1159 This function returns a pseudo-random integer. Repeated calls return a | 1195 This function returns a pseudo-random integer. Repeated calls return a |
1160 series of pseudo-random integers. | 1196 series of pseudo-random integers. |
1161 | 1197 |
1162 If @var{limit} is a positive integer, the value is chosen to be | 1198 If @var{limit} is a positive integer, the value is chosen to be |
1163 nonnegative and less than @var{limit}. | 1199 nonnegative and less than @var{limit}. |
1164 | 1200 |
1165 If @var{limit} is @code{t}, it means to choose a new seed based on the | 1201 If @var{limit} is @code{t}, it means to choose a new seed based on the |
1166 current time of day and on Emacs's process @sc{id} number. | 1202 current time of day and on Emacs's process @acronym{ID} number. |
1167 @c "Emacs'" is incorrect usage! | 1203 @c "Emacs'" is incorrect usage! |
1168 | 1204 |
1169 On some machines, any integer representable in Lisp may be the result | 1205 On some machines, any integer representable in Lisp may be the result |
1170 of @code{random}. On other machines, the result can never be larger | 1206 of @code{random}. On other machines, the result can never be larger |
1171 than a certain maximum or less than a certain (negative) minimum. | 1207 than a certain maximum or less than a certain (negative) minimum. |
1172 @end defun | 1208 @end defun |
1209 | |
1210 @ignore | |
1211 arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e | |
1212 @end ignore |