Mercurial > emacs
annotate lispref/numbers.texi @ 56026:bb6720f21c54
Revision: miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-396
Tweak arch tagging to make build/install-in-place less annoying
Previously, autoconf-created Makefiles and the like would contain
duplicate taglines (unfortunately, autoconf doesn't seem to have a
`strip in generated file' comment mechanism) leading to conflicts, and
installing in place would create unknown directories and copies of
source directories (leading to conflicts with the source directories).
This changeset makes all autoconf-processed files use explicit id-tags
and adds .arch-inventory entries to ignore installation directories.
author | Miles Bader <miles@gnu.org> |
---|---|
date | Fri, 11 Jun 2004 02:39:51 +0000 |
parents | a603854deb89 |
children | 2a4a771d6699 |
rev | line source |
---|---|
6510 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003 |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
4 @c Free Software Foundation, Inc. |
6510 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/numbers | |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
7 @node Numbers, Strings and Characters, Lisp Data Types, Top |
6510 | 8 @chapter Numbers |
9 @cindex integers | |
10 @cindex numbers | |
11 | |
12 GNU Emacs supports two numeric data types: @dfn{integers} and | |
13 @dfn{floating point numbers}. Integers are whole numbers such as | |
14 @minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point | |
15 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
16 2.71828. They can also be expressed in exponential notation: 1.5e2 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
17 equals 150; in this example, @samp{e2} stands for ten to the second |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
18 power, and that is multiplied by 1.5. Floating point values are not |
6510 | 19 exact; they have a fixed, limited amount of precision. |
20 | |
21 @menu | |
22 * Integer Basics:: Representation and range of integers. | |
23 * Float Basics:: Representation and range of floating point. | |
24 * Predicates on Numbers:: Testing for numbers. | |
25 * Comparison of Numbers:: Equality and inequality predicates. | |
26 * Numeric Conversions:: Converting float to integer and vice versa. | |
27 * Arithmetic Operations:: How to add, subtract, multiply and divide. | |
28 * Rounding Operations:: Explicitly rounding floating point numbers. | |
29 * Bitwise Operations:: Logical and, or, not, shifting. | |
11230
c6b70cdf844e
Don't call the special math functions "transcendental".
Richard M. Stallman <rms@gnu.org>
parents:
10558
diff
changeset
|
30 * Math Functions:: Trig, exponential and logarithmic functions. |
6510 | 31 * Random Numbers:: Obtaining random integers, predictable or not. |
32 @end menu | |
33 | |
34 @node Integer Basics | |
35 @comment node-name, next, previous, up | |
36 @section Integer Basics | |
37 | |
38 The range of values for an integer depends on the machine. The | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
39 minimum range is @minus{}268435456 to 268435455 (29 bits; i.e., |
27193 | 40 @ifnottex |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
41 -2**28 |
27193 | 42 @end ifnottex |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
43 @tex |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
44 @math{-2^{28}} |
6510 | 45 @end tex |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
46 to |
27193 | 47 @ifnottex |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
48 2**28 - 1), |
27193 | 49 @end ifnottex |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
50 @tex |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
51 @math{2^{28}-1}), |
6510 | 52 @end tex |
10558
fbfd717ff79b
Fix integer width changes.
Richard M. Stallman <rms@gnu.org>
parents:
10306
diff
changeset
|
53 but some machines may provide a wider range. Many examples in this |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
54 chapter assume an integer has 29 bits. |
6510 | 55 @cindex overflow |
56 | |
57 The Lisp reader reads an integer as a sequence of digits with optional | |
58 initial sign and optional final period. | |
59 | |
60 @example | |
61 1 ; @r{The integer 1.} | |
62 1. ; @r{The integer 1.} | |
63 +1 ; @r{Also the integer 1.} | |
64 -1 ; @r{The integer @minus{}1.} | |
52901
dcdfe0849845
(Integer Basics): Update overflow example.
Luc Teirlinck <teirllm@auburn.edu>
parents:
52886
diff
changeset
|
65 536870913 ; @r{Also the integer 1, due to overflow.} |
6510 | 66 0 ; @r{The integer 0.} |
67 -0 ; @r{The integer 0.} | |
68 @end example | |
69 | |
39198
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
70 @cindex integers in specific radix |
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
71 @cindex radix for reading an integer |
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
72 @cindex base for reading an integer |
52863
a6d4edb94e8e
(Integer Basics): Add index entries for reading
Eli Zaretskii <eliz@gnu.org>
parents:
52401
diff
changeset
|
73 @cindex hex numbers |
a6d4edb94e8e
(Integer Basics): Add index entries for reading
Eli Zaretskii <eliz@gnu.org>
parents:
52401
diff
changeset
|
74 @cindex octal numbers |
a6d4edb94e8e
(Integer Basics): Add index entries for reading
Eli Zaretskii <eliz@gnu.org>
parents:
52401
diff
changeset
|
75 @cindex reading numbers in hex, octal, and binary |
39198
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
76 In addition, the Lisp reader recognizes a syntax for integers in |
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
77 bases other than 10: @samp{#B@var{integer}} reads @var{integer} in |
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
78 binary (radix 2), @samp{#O@var{integer}} reads @var{integer} in octal |
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
79 (radix 8), @samp{#X@var{integer}} reads @var{integer} in hexadecimal |
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
80 (radix 16), and @samp{#@var{radix}r@var{integer}} reads @var{integer} |
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
81 in radix @var{radix} (where @var{radix} is between 2 and 36, |
48700 | 82 inclusively). Case is not significant for the letter after @samp{#} |
39198
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
83 (@samp{B}, @samp{O}, etc.) that denotes the radix. |
634358ff84a4
(Integer Basics): Document CL style read syntax for
Eli Zaretskii <eliz@gnu.org>
parents:
38787
diff
changeset
|
84 |
6510 | 85 To understand how various functions work on integers, especially the |
86 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to | |
87 view the numbers in their binary form. | |
88 | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
89 In 29-bit binary, the decimal integer 5 looks like this: |
6510 | 90 |
91 @example | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
92 0 0000 0000 0000 0000 0000 0000 0101 |
6510 | 93 @end example |
94 | |
95 @noindent | |
96 (We have inserted spaces between groups of 4 bits, and two spaces | |
97 between groups of 8 bits, to make the binary integer easier to read.) | |
98 | |
99 The integer @minus{}1 looks like this: | |
100 | |
101 @example | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
102 1 1111 1111 1111 1111 1111 1111 1111 |
6510 | 103 @end example |
104 | |
105 @noindent | |
106 @cindex two's complement | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
107 @minus{}1 is represented as 29 ones. (This is called @dfn{two's |
6510 | 108 complement} notation.) |
109 | |
110 The negative integer, @minus{}5, is creating by subtracting 4 from | |
111 @minus{}1. In binary, the decimal integer 4 is 100. Consequently, | |
112 @minus{}5 looks like this: | |
113 | |
114 @example | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
115 1 1111 1111 1111 1111 1111 1111 1011 |
6510 | 116 @end example |
117 | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
118 In this implementation, the largest 29-bit binary integer value is |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
119 268,435,455 in decimal. In binary, it looks like this: |
6510 | 120 |
121 @example | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
122 0 1111 1111 1111 1111 1111 1111 1111 |
6510 | 123 @end example |
124 | |
125 Since the arithmetic functions do not check whether integers go | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
126 outside their range, when you add 1 to 268,435,455, the value is the |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
127 negative integer @minus{}268,435,456: |
6510 | 128 |
129 @example | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
130 (+ 1 268435455) |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
131 @result{} -268435456 |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
132 @result{} 1 0000 0000 0000 0000 0000 0000 0000 |
6510 | 133 @end example |
134 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
135 Many of the functions described in this chapter accept markers for |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
136 arguments in place of numbers. (@xref{Markers}.) Since the actual |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
137 arguments to such functions may be either numbers or markers, we often |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
138 give these arguments the name @var{number-or-marker}. When the argument |
6510 | 139 value is a marker, its position value is used and its buffer is ignored. |
140 | |
51920
8177e11a3638
(Integer Basics): Add most-positive-fixnum, most-negative-fixnum.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
141 @defvar most-positive-fixnum |
8177e11a3638
(Integer Basics): Add most-positive-fixnum, most-negative-fixnum.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
142 The value of this variable is the largest integer that Emacs Lisp |
8177e11a3638
(Integer Basics): Add most-positive-fixnum, most-negative-fixnum.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
143 can handle. |
8177e11a3638
(Integer Basics): Add most-positive-fixnum, most-negative-fixnum.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
144 @end defvar |
8177e11a3638
(Integer Basics): Add most-positive-fixnum, most-negative-fixnum.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
145 |
8177e11a3638
(Integer Basics): Add most-positive-fixnum, most-negative-fixnum.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
146 @defvar most-negative-fixnum |
8177e11a3638
(Integer Basics): Add most-positive-fixnum, most-negative-fixnum.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
147 The value of this variable is the smallest integer that Emacs Lisp can |
8177e11a3638
(Integer Basics): Add most-positive-fixnum, most-negative-fixnum.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
148 handle. It is negative. |
8177e11a3638
(Integer Basics): Add most-positive-fixnum, most-negative-fixnum.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
149 @end defvar |
8177e11a3638
(Integer Basics): Add most-positive-fixnum, most-negative-fixnum.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
150 |
6510 | 151 @node Float Basics |
152 @section Floating Point Basics | |
153 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
154 Floating point numbers are useful for representing numbers that are |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
155 not integral. The precise range of floating point numbers is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
156 machine-specific; it is the same as the range of the C data type |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
157 @code{double} on the machine you are using. |
6510 | 158 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
159 The read-syntax for floating point numbers requires either a decimal |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
160 point (with at least one digit following), an exponent, or both. For |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
161 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
162 @samp{.15e4} are five ways of writing a floating point number whose |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
163 value is 1500. They are all equivalent. You can also use a minus sign |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
164 to write negative floating point numbers, as in @samp{-1.0}. |
6510 | 165 |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52901
diff
changeset
|
166 @cindex @acronym{IEEE} floating point |
6510 | 167 @cindex positive infinity |
168 @cindex negative infinity | |
169 @cindex infinity | |
170 @cindex NaN | |
53044
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
171 Most modern computers support the @acronym{IEEE} floating point standard, |
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
172 which provides for positive infinity and negative infinity as floating point |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
173 values. It also provides for a class of values called NaN or |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
174 ``not-a-number''; numerical functions return such values in cases where |
53465
a603854deb89
(Math Functions): sqrt reports a domain-error
Andreas Schwab <schwab@suse.de>
parents:
53432
diff
changeset
|
175 there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
176 NaN. For practical purposes, there's no significant difference between |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
177 different NaN values in Emacs Lisp, and there's no rule for precisely |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
178 which NaN value should be used in a particular case, so Emacs Lisp |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
179 doesn't try to distinguish them. Here are the read syntaxes for |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
180 these special floating point values: |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
181 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
182 @table @asis |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
183 @item positive infinity |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
184 @samp{1.0e+INF} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
185 @item negative infinity |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
186 @samp{-1.0e+INF} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
187 @item Not-a-number |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
188 @samp{0.0e+NaN}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
189 @end table |
6510 | 190 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
191 In addition, the value @code{-0.0} is distinguishable from ordinary |
53044
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
192 zero in @acronym{IEEE} floating point (although @code{equal} and |
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
193 @code{=} consider them equal values). |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
194 |
6510 | 195 You can use @code{logb} to extract the binary exponent of a floating |
196 point number (or estimate the logarithm of an integer): | |
197 | |
198 @defun logb number | |
199 This function returns the binary exponent of @var{number}. More | |
200 precisely, the value is the logarithm of @var{number} base 2, rounded | |
201 down to an integer. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
202 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
203 @example |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
204 (logb 10) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
205 @result{} 3 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
206 (logb 10.0e20) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
207 @result{} 69 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
208 @end example |
6510 | 209 @end defun |
210 | |
211 @node Predicates on Numbers | |
212 @section Type Predicates for Numbers | |
213 | |
214 The functions in this section test whether the argument is a number or | |
215 whether it is a certain sort of number. The functions @code{integerp} | |
216 and @code{floatp} can take any type of Lisp object as argument (the | |
217 predicates would not be of much use otherwise); but the @code{zerop} | |
218 predicate requires a number as its argument. See also | |
219 @code{integer-or-marker-p} and @code{number-or-marker-p}, in | |
220 @ref{Predicates on Markers}. | |
221 | |
222 @defun floatp object | |
223 This predicate tests whether its argument is a floating point | |
224 number and returns @code{t} if so, @code{nil} otherwise. | |
225 | |
226 @code{floatp} does not exist in Emacs versions 18 and earlier. | |
227 @end defun | |
228 | |
229 @defun integerp object | |
230 This predicate tests whether its argument is an integer, and returns | |
231 @code{t} if so, @code{nil} otherwise. | |
232 @end defun | |
233 | |
234 @defun numberp object | |
235 This predicate tests whether its argument is a number (either integer or | |
236 floating point), and returns @code{t} if so, @code{nil} otherwise. | |
237 @end defun | |
238 | |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
239 @defun wholenump object |
6510 | 240 @cindex natural numbers |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
241 The @code{wholenump} predicate (whose name comes from the phrase |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
242 ``whole-number-p'') tests to see whether its argument is a nonnegative |
6510 | 243 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is |
244 considered non-negative. | |
245 | |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
246 @findex natnump |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
247 @code{natnump} is an obsolete synonym for @code{wholenump}. |
6510 | 248 @end defun |
249 | |
250 @defun zerop number | |
251 This predicate tests whether its argument is zero, and returns @code{t} | |
252 if so, @code{nil} otherwise. The argument must be a number. | |
253 | |
254 These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}. | |
255 @end defun | |
256 | |
257 @node Comparison of Numbers | |
258 @section Comparison of Numbers | |
259 @cindex number equality | |
260 | |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
261 To test numbers for numerical equality, you should normally use |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
262 @code{=}, not @code{eq}. There can be many distinct floating point |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
263 number objects with the same numeric value. If you use @code{eq} to |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
264 compare them, then you test whether two values are the same |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
265 @emph{object}. By contrast, @code{=} compares only the numeric values |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
266 of the objects. |
6510 | 267 |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
268 At present, each integer value has a unique Lisp object in Emacs Lisp. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
269 Therefore, @code{eq} is equivalent to @code{=} where integers are |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
270 concerned. It is sometimes convenient to use @code{eq} for comparing an |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
271 unknown value with an integer, because @code{eq} does not report an |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
272 error if the unknown value is not a number---it accepts arguments of any |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
273 type. By contrast, @code{=} signals an error if the arguments are not |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
274 numbers or markers. However, it is a good idea to use @code{=} if you |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
275 can, even for comparing integers, just in case we change the |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
276 representation of integers in a future Emacs version. |
6510 | 277 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
278 Sometimes it is useful to compare numbers with @code{equal}; it treats |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
279 two numbers as equal if they have the same data type (both integers, or |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
280 both floating point) and the same value. By contrast, @code{=} can |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
281 treat an integer and a floating point number as equal. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
282 |
6510 | 283 There is another wrinkle: because floating point arithmetic is not |
284 exact, it is often a bad idea to check for equality of two floating | |
285 point values. Usually it is better to test for approximate equality. | |
286 Here's a function to do this: | |
287 | |
288 @example | |
289 (defvar fuzz-factor 1.0e-6) | |
290 (defun approx-equal (x y) | |
12098 | 291 (or (and (= x 0) (= y 0)) |
292 (< (/ (abs (- x y)) | |
293 (max (abs x) (abs y))) | |
294 fuzz-factor))) | |
6510 | 295 @end example |
296 | |
297 @cindex CL note---integers vrs @code{eq} | |
298 @quotation | |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
299 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires |
6510 | 300 @code{=} because Common Lisp implements multi-word integers, and two |
301 distinct integer objects can have the same numeric value. Emacs Lisp | |
302 can have just one integer object for any given value because it has a | |
303 limited range of integer values. | |
304 @end quotation | |
305 | |
306 @defun = number-or-marker1 number-or-marker2 | |
307 This function tests whether its arguments are numerically equal, and | |
308 returns @code{t} if so, @code{nil} otherwise. | |
309 @end defun | |
310 | |
311 @defun /= number-or-marker1 number-or-marker2 | |
312 This function tests whether its arguments are numerically equal, and | |
313 returns @code{t} if they are not, and @code{nil} if they are. | |
314 @end defun | |
315 | |
316 @defun < number-or-marker1 number-or-marker2 | |
317 This function tests whether its first argument is strictly less than | |
318 its second argument. It returns @code{t} if so, @code{nil} otherwise. | |
319 @end defun | |
320 | |
321 @defun <= number-or-marker1 number-or-marker2 | |
322 This function tests whether its first argument is less than or equal | |
323 to its second argument. It returns @code{t} if so, @code{nil} | |
324 otherwise. | |
325 @end defun | |
326 | |
327 @defun > number-or-marker1 number-or-marker2 | |
328 This function tests whether its first argument is strictly greater | |
329 than its second argument. It returns @code{t} if so, @code{nil} | |
330 otherwise. | |
331 @end defun | |
332 | |
333 @defun >= number-or-marker1 number-or-marker2 | |
334 This function tests whether its first argument is greater than or | |
335 equal to its second argument. It returns @code{t} if so, @code{nil} | |
336 otherwise. | |
337 @end defun | |
338 | |
339 @defun max number-or-marker &rest numbers-or-markers | |
340 This function returns the largest of its arguments. | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
341 If any of the argument is floating-point, the value is returned |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
342 as floating point, even if it was given as an integer. |
6510 | 343 |
344 @example | |
345 (max 20) | |
346 @result{} 20 | |
347 (max 1 2.5) | |
348 @result{} 2.5 | |
349 (max 1 3 2.5) | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
350 @result{} 3.0 |
6510 | 351 @end example |
352 @end defun | |
353 | |
354 @defun min number-or-marker &rest numbers-or-markers | |
355 This function returns the smallest of its arguments. | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
356 If any of the argument is floating-point, the value is returned |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
357 as floating point, even if it was given as an integer. |
6510 | 358 |
359 @example | |
360 (min -4 1) | |
361 @result{} -4 | |
362 @end example | |
363 @end defun | |
364 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
365 @defun abs number |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
366 This function returns the absolute value of @var{number}. |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
367 @end defun |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
368 |
6510 | 369 @node Numeric Conversions |
370 @section Numeric Conversions | |
371 @cindex rounding in conversions | |
372 | |
373 To convert an integer to floating point, use the function @code{float}. | |
374 | |
375 @defun float number | |
376 This returns @var{number} converted to floating point. | |
377 If @var{number} is already a floating point number, @code{float} returns | |
378 it unchanged. | |
379 @end defun | |
380 | |
381 There are four functions to convert floating point numbers to integers; | |
53044
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
382 they differ in how they round. All accept an argument @var{number} |
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
383 and an optional argument @var{divisor}. Both arguments may be |
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
384 integers or floating point numbers. @var{divisor} may also be |
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
385 @code{nil}. If @var{divisor} is @code{nil} or omitted, these |
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
386 functions convert @var{number} to an integer, or return it unchanged |
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
387 if it already is an integer. If @var{divisor} is non-@code{nil}, they |
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
388 divide @var{number} by @var{divisor} and convert the result to an |
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
389 integer. An @code{arith-error} results if @var{divisor} is 0. |
6510 | 390 |
53044
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
391 @defun truncate number &optional divisor |
6510 | 392 This returns @var{number}, converted to an integer by rounding towards |
393 zero. | |
38787
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
394 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
395 @example |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
396 (truncate 1.2) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
397 @result{} 1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
398 (truncate 1.7) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
399 @result{} 1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
400 (truncate -1.2) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
401 @result{} -1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
402 (truncate -1.7) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
403 @result{} -1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
404 @end example |
6510 | 405 @end defun |
406 | |
407 @defun floor number &optional divisor | |
408 This returns @var{number}, converted to an integer by rounding downward | |
409 (towards negative infinity). | |
410 | |
53044
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
411 If @var{divisor} is specified, this uses the kind of division |
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
412 operation that corresponds to @code{mod}, rounding downward. |
38787
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
413 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
414 @example |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
415 (floor 1.2) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
416 @result{} 1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
417 (floor 1.7) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
418 @result{} 1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
419 (floor -1.2) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
420 @result{} -2 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
421 (floor -1.7) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
422 @result{} -2 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
423 (floor 5.99 3) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
424 @result{} 1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
425 @end example |
6510 | 426 @end defun |
427 | |
53044
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
428 @defun ceiling number &optional divisor |
6510 | 429 This returns @var{number}, converted to an integer by rounding upward |
430 (towards positive infinity). | |
38787
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
431 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
432 @example |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
433 (ceiling 1.2) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
434 @result{} 2 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
435 (ceiling 1.7) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
436 @result{} 2 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
437 (ceiling -1.2) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
438 @result{} -1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
439 (ceiling -1.7) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
440 @result{} -1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
441 @end example |
6510 | 442 @end defun |
443 | |
53044
aa36f3c0f66e
(Numeric Conversions): Not just `floor', but also `truncate',
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
444 @defun round number &optional divisor |
6510 | 445 This returns @var{number}, converted to an integer by rounding towards the |
12098 | 446 nearest integer. Rounding a value equidistant between two integers |
447 may choose the integer closer to zero, or it may prefer an even integer, | |
448 depending on your machine. | |
38787
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
449 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
450 @example |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
451 (round 1.2) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
452 @result{} 1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
453 (round 1.7) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
454 @result{} 2 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
455 (round -1.2) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
456 @result{} -1 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
457 (round -1.7) |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
458 @result{} -2 |
4d77816c7cad
Add examples for floor, ceiling, truncate, round.
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
459 @end example |
6510 | 460 @end defun |
461 | |
462 @node Arithmetic Operations | |
463 @section Arithmetic Operations | |
464 | |
465 Emacs Lisp provides the traditional four arithmetic operations: | |
466 addition, subtraction, multiplication, and division. Remainder and modulus | |
467 functions supplement the division functions. The functions to | |
468 add or subtract 1 are provided because they are traditional in Lisp and | |
469 commonly used. | |
470 | |
471 All of these functions except @code{%} return a floating point value | |
472 if any argument is floating. | |
473 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
474 It is important to note that in Emacs Lisp, arithmetic functions |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
475 do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
476 @minus{}268435456, depending on your hardware. |
6510 | 477 |
478 @defun 1+ number-or-marker | |
479 This function returns @var{number-or-marker} plus 1. | |
480 For example, | |
481 | |
482 @example | |
483 (setq foo 4) | |
484 @result{} 4 | |
485 (1+ foo) | |
486 @result{} 5 | |
487 @end example | |
488 | |
12098 | 489 This function is not analogous to the C operator @code{++}---it does not |
490 increment a variable. It just computes a sum. Thus, if we continue, | |
6510 | 491 |
492 @example | |
493 foo | |
494 @result{} 4 | |
495 @end example | |
496 | |
497 If you want to increment the variable, you must use @code{setq}, | |
498 like this: | |
499 | |
500 @example | |
501 (setq foo (1+ foo)) | |
502 @result{} 5 | |
503 @end example | |
504 @end defun | |
505 | |
506 @defun 1- number-or-marker | |
507 This function returns @var{number-or-marker} minus 1. | |
508 @end defun | |
509 | |
510 @defun + &rest numbers-or-markers | |
511 This function adds its arguments together. When given no arguments, | |
12098 | 512 @code{+} returns 0. |
6510 | 513 |
514 @example | |
515 (+) | |
516 @result{} 0 | |
517 (+ 1) | |
518 @result{} 1 | |
519 (+ 1 2 3 4) | |
520 @result{} 10 | |
521 @end example | |
522 @end defun | |
523 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
524 @defun - &optional number-or-marker &rest more-numbers-or-markers |
6510 | 525 The @code{-} function serves two purposes: negation and subtraction. |
526 When @code{-} has a single argument, the value is the negative of the | |
527 argument. When there are multiple arguments, @code{-} subtracts each of | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
528 the @var{more-numbers-or-markers} from @var{number-or-marker}, |
12098 | 529 cumulatively. If there are no arguments, the result is 0. |
6510 | 530 |
531 @example | |
532 (- 10 1 2 3 4) | |
533 @result{} 0 | |
534 (- 10) | |
535 @result{} -10 | |
536 (-) | |
537 @result{} 0 | |
538 @end example | |
539 @end defun | |
540 | |
541 @defun * &rest numbers-or-markers | |
542 This function multiplies its arguments together, and returns the | |
12098 | 543 product. When given no arguments, @code{*} returns 1. |
6510 | 544 |
545 @example | |
546 (*) | |
547 @result{} 1 | |
548 (* 1) | |
549 @result{} 1 | |
550 (* 1 2 3 4) | |
551 @result{} 24 | |
552 @end example | |
553 @end defun | |
554 | |
555 @defun / dividend divisor &rest divisors | |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
556 This function divides @var{dividend} by @var{divisor} and returns the |
6510 | 557 quotient. If there are additional arguments @var{divisors}, then it |
558 divides @var{dividend} by each divisor in turn. Each argument may be a | |
559 number or a marker. | |
560 | |
561 If all the arguments are integers, then the result is an integer too. | |
562 This means the result has to be rounded. On most machines, the result | |
563 is rounded towards zero after each division, but some machines may round | |
564 differently with negative arguments. This is because the Lisp function | |
565 @code{/} is implemented using the C division operator, which also | |
566 permits machine-dependent rounding. As a practical matter, all known | |
567 machines round in the standard fashion. | |
568 | |
569 @cindex @code{arith-error} in division | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
570 If you divide an integer by 0, an @code{arith-error} error is signaled. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
571 (@xref{Errors}.) Floating point division by zero returns either |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52901
diff
changeset
|
572 infinity or a NaN if your machine supports @acronym{IEEE} floating point; |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
573 otherwise, it signals an @code{arith-error} error. |
6510 | 574 |
575 @example | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
576 @group |
6510 | 577 (/ 6 2) |
578 @result{} 3 | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
579 @end group |
6510 | 580 (/ 5 2) |
581 @result{} 2 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
582 (/ 5.0 2) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
583 @result{} 2.5 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
584 (/ 5 2.0) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
585 @result{} 2.5 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
586 (/ 5.0 2.0) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
587 @result{} 2.5 |
6510 | 588 (/ 25 3 2) |
589 @result{} 4 | |
590 (/ -17 6) | |
591 @result{} -2 | |
592 @end example | |
593 | |
594 The result of @code{(/ -17 6)} could in principle be -3 on some | |
595 machines. | |
596 @end defun | |
597 | |
598 @defun % dividend divisor | |
599 @cindex remainder | |
600 This function returns the integer remainder after division of @var{dividend} | |
601 by @var{divisor}. The arguments must be integers or markers. | |
602 | |
603 For negative arguments, the remainder is in principle machine-dependent | |
604 since the quotient is; but in practice, all known machines behave alike. | |
605 | |
606 An @code{arith-error} results if @var{divisor} is 0. | |
607 | |
608 @example | |
609 (% 9 4) | |
610 @result{} 1 | |
611 (% -9 4) | |
612 @result{} -1 | |
613 (% 9 -4) | |
614 @result{} 1 | |
615 (% -9 -4) | |
616 @result{} -1 | |
617 @end example | |
618 | |
619 For any two integers @var{dividend} and @var{divisor}, | |
620 | |
621 @example | |
622 @group | |
623 (+ (% @var{dividend} @var{divisor}) | |
624 (* (/ @var{dividend} @var{divisor}) @var{divisor})) | |
625 @end group | |
626 @end example | |
627 | |
628 @noindent | |
629 always equals @var{dividend}. | |
630 @end defun | |
631 | |
632 @defun mod dividend divisor | |
633 @cindex modulus | |
634 This function returns the value of @var{dividend} modulo @var{divisor}; | |
635 in other words, the remainder after division of @var{dividend} | |
636 by @var{divisor}, but with the same sign as @var{divisor}. | |
637 The arguments must be numbers or markers. | |
638 | |
639 Unlike @code{%}, @code{mod} returns a well-defined result for negative | |
640 arguments. It also permits floating point arguments; it rounds the | |
641 quotient downward (towards minus infinity) to an integer, and uses that | |
642 quotient to compute the remainder. | |
643 | |
644 An @code{arith-error} results if @var{divisor} is 0. | |
645 | |
646 @example | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
647 @group |
6510 | 648 (mod 9 4) |
649 @result{} 1 | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
650 @end group |
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
651 @group |
6510 | 652 (mod -9 4) |
653 @result{} 3 | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
654 @end group |
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
655 @group |
6510 | 656 (mod 9 -4) |
657 @result{} -3 | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
658 @end group |
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
659 @group |
6510 | 660 (mod -9 -4) |
661 @result{} -1 | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
662 @end group |
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
663 @group |
6510 | 664 (mod 5.5 2.5) |
665 @result{} .5 | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
666 @end group |
6510 | 667 @end example |
668 | |
669 For any two numbers @var{dividend} and @var{divisor}, | |
670 | |
671 @example | |
672 @group | |
673 (+ (mod @var{dividend} @var{divisor}) | |
674 (* (floor @var{dividend} @var{divisor}) @var{divisor})) | |
675 @end group | |
676 @end example | |
677 | |
678 @noindent | |
12098 | 679 always equals @var{dividend}, subject to rounding error if either |
680 argument is floating point. For @code{floor}, see @ref{Numeric | |
681 Conversions}. | |
6510 | 682 @end defun |
683 | |
684 @node Rounding Operations | |
685 @section Rounding Operations | |
686 @cindex rounding without conversion | |
687 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
688 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and |
6510 | 689 @code{ftruncate} take a floating point argument and return a floating |
690 point result whose value is a nearby integer. @code{ffloor} returns the | |
8017 | 691 nearest integer below; @code{fceiling}, the nearest integer above; |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
692 @code{ftruncate}, the nearest integer in the direction towards zero; |
6510 | 693 @code{fround}, the nearest integer. |
694 | |
695 @defun ffloor float | |
696 This function rounds @var{float} to the next lower integral value, and | |
697 returns that value as a floating point number. | |
698 @end defun | |
699 | |
8017 | 700 @defun fceiling float |
6510 | 701 This function rounds @var{float} to the next higher integral value, and |
702 returns that value as a floating point number. | |
703 @end defun | |
704 | |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
705 @defun ftruncate float |
6510 | 706 This function rounds @var{float} towards zero to an integral value, and |
707 returns that value as a floating point number. | |
708 @end defun | |
709 | |
710 @defun fround float | |
711 This function rounds @var{float} to the nearest integral value, | |
712 and returns that value as a floating point number. | |
713 @end defun | |
714 | |
715 @node Bitwise Operations | |
716 @section Bitwise Operations on Integers | |
717 | |
718 In a computer, an integer is represented as a binary number, a | |
719 sequence of @dfn{bits} (digits which are either zero or one). A bitwise | |
720 operation acts on the individual bits of such a sequence. For example, | |
721 @dfn{shifting} moves the whole sequence left or right one or more places, | |
722 reproducing the same pattern ``moved over''. | |
723 | |
724 The bitwise operations in Emacs Lisp apply only to integers. | |
725 | |
726 @defun lsh integer1 count | |
727 @cindex logical shift | |
728 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the | |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
729 bits in @var{integer1} to the left @var{count} places, or to the right |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
730 if @var{count} is negative, bringing zeros into the vacated bits. If |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
731 @var{count} is negative, @code{lsh} shifts zeros into the leftmost |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
732 (most-significant) bit, producing a positive result even if |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
733 @var{integer1} is negative. Contrast this with @code{ash}, below. |
6510 | 734 |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
735 Here are two examples of @code{lsh}, shifting a pattern of bits one |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
736 place to the left. We show only the low-order eight bits of the binary |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
737 pattern; the rest are all zero. |
6510 | 738 |
739 @example | |
740 @group | |
741 (lsh 5 1) | |
742 @result{} 10 | |
743 ;; @r{Decimal 5 becomes decimal 10.} | |
744 00000101 @result{} 00001010 | |
745 | |
746 (lsh 7 1) | |
747 @result{} 14 | |
748 ;; @r{Decimal 7 becomes decimal 14.} | |
749 00000111 @result{} 00001110 | |
750 @end group | |
751 @end example | |
752 | |
753 @noindent | |
754 As the examples illustrate, shifting the pattern of bits one place to | |
755 the left produces a number that is twice the value of the previous | |
756 number. | |
757 | |
12098 | 758 Shifting a pattern of bits two places to the left produces results |
759 like this (with 8-bit binary numbers): | |
760 | |
761 @example | |
762 @group | |
763 (lsh 3 2) | |
764 @result{} 12 | |
765 ;; @r{Decimal 3 becomes decimal 12.} | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
766 00000011 @result{} 00001100 |
12098 | 767 @end group |
768 @end example | |
769 | |
770 On the other hand, shifting one place to the right looks like this: | |
771 | |
772 @example | |
773 @group | |
774 (lsh 6 -1) | |
775 @result{} 3 | |
776 ;; @r{Decimal 6 becomes decimal 3.} | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
777 00000110 @result{} 00000011 |
12098 | 778 @end group |
779 | |
780 @group | |
781 (lsh 5 -1) | |
782 @result{} 2 | |
783 ;; @r{Decimal 5 becomes decimal 2.} | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
784 00000101 @result{} 00000010 |
12098 | 785 @end group |
786 @end example | |
787 | |
788 @noindent | |
789 As the example illustrates, shifting one place to the right divides the | |
790 value of a positive integer by two, rounding downward. | |
791 | |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
792 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
793 not check for overflow, so shifting left can discard significant bits |
12067 | 794 and change the sign of the number. For example, left shifting |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
795 268,435,455 produces @minus{}2 on a 29-bit machine: |
6510 | 796 |
797 @example | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
798 (lsh 268435455 1) ; @r{left shift} |
6510 | 799 @result{} -2 |
800 @end example | |
801 | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
802 In binary, in the 29-bit implementation, the argument looks like this: |
6510 | 803 |
804 @example | |
805 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
806 ;; @r{Decimal 268,435,455} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
807 0 1111 1111 1111 1111 1111 1111 1111 |
6510 | 808 @end group |
809 @end example | |
810 | |
811 @noindent | |
812 which becomes the following when left shifted: | |
813 | |
814 @example | |
815 @group | |
816 ;; @r{Decimal @minus{}2} | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
817 1 1111 1111 1111 1111 1111 1111 1110 |
6510 | 818 @end group |
819 @end example | |
820 @end defun | |
821 | |
822 @defun ash integer1 count | |
823 @cindex arithmetic shift | |
824 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} | |
825 to the left @var{count} places, or to the right if @var{count} | |
826 is negative. | |
827 | |
828 @code{ash} gives the same results as @code{lsh} except when | |
829 @var{integer1} and @var{count} are both negative. In that case, | |
12098 | 830 @code{ash} puts ones in the empty bit positions on the left, while |
831 @code{lsh} puts zeros in those bit positions. | |
6510 | 832 |
833 Thus, with @code{ash}, shifting the pattern of bits one place to the right | |
834 looks like this: | |
835 | |
836 @example | |
837 @group | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
838 (ash -6 -1) @result{} -3 |
6510 | 839 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
840 1 1111 1111 1111 1111 1111 1111 1010 |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
841 @result{} |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
842 1 1111 1111 1111 1111 1111 1111 1101 |
6510 | 843 @end group |
844 @end example | |
845 | |
846 In contrast, shifting the pattern of bits one place to the right with | |
847 @code{lsh} looks like this: | |
848 | |
849 @example | |
850 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
851 (lsh -6 -1) @result{} 268435453 |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
852 ;; @r{Decimal @minus{}6 becomes decimal 268,435,453.} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
853 1 1111 1111 1111 1111 1111 1111 1010 |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
854 @result{} |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
855 0 1111 1111 1111 1111 1111 1111 1101 |
6510 | 856 @end group |
857 @end example | |
858 | |
859 Here are other examples: | |
860 | |
861 @c !!! Check if lined up in smallbook format! XDVI shows problem | |
862 @c with smallbook but not with regular book! --rjc 16mar92 | |
863 @smallexample | |
864 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
865 ; @r{ 29-bit binary values} |
6510 | 866 |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
867 (lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
868 @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100} |
6510 | 869 @end group |
870 @group | |
871 (ash 5 2) | |
872 @result{} 20 | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
873 (lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
874 @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100} |
6510 | 875 (ash -5 2) |
876 @result{} -20 | |
877 @end group | |
878 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
879 (lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
880 @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001} |
6510 | 881 @end group |
882 @group | |
883 (ash 5 -2) | |
884 @result{} 1 | |
885 @end group | |
886 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
887 (lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
888 @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110} |
6510 | 889 @end group |
890 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
891 (ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
892 @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110} |
6510 | 893 @end group |
894 @end smallexample | |
895 @end defun | |
896 | |
897 @defun logand &rest ints-or-markers | |
898 @cindex logical and | |
899 @cindex bitwise and | |
900 This function returns the ``logical and'' of the arguments: the | |
901 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is | |
902 set in all the arguments. (``Set'' means that the value of the bit is 1 | |
903 rather than 0.) | |
904 | |
905 For example, using 4-bit binary numbers, the ``logical and'' of 13 and | |
906 12 is 12: 1101 combined with 1100 produces 1100. | |
907 In both the binary numbers, the leftmost two bits are set (i.e., they | |
908 are 1's), so the leftmost two bits of the returned value are set. | |
909 However, for the rightmost two bits, each is zero in at least one of | |
910 the arguments, so the rightmost two bits of the returned value are 0's. | |
911 | |
912 @noindent | |
913 Therefore, | |
914 | |
915 @example | |
916 @group | |
917 (logand 13 12) | |
918 @result{} 12 | |
919 @end group | |
920 @end example | |
921 | |
922 If @code{logand} is not passed any argument, it returns a value of | |
923 @minus{}1. This number is an identity element for @code{logand} | |
924 because its binary representation consists entirely of ones. If | |
925 @code{logand} is passed just one argument, it returns that argument. | |
926 | |
927 @smallexample | |
928 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
929 ; @r{ 29-bit binary values} |
6510 | 930 |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
931 (logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
932 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
933 @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} |
6510 | 934 @end group |
935 | |
936 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
937 (logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
938 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
939 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
940 @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} |
6510 | 941 @end group |
942 | |
943 @group | |
944 (logand) | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
945 @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111} |
6510 | 946 @end group |
947 @end smallexample | |
948 @end defun | |
949 | |
950 @defun logior &rest ints-or-markers | |
951 @cindex logical inclusive or | |
952 @cindex bitwise or | |
953 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit | |
954 is set in the result if, and only if, the @var{n}th bit is set in at least | |
955 one of the arguments. If there are no arguments, the result is zero, | |
956 which is an identity element for this operation. If @code{logior} is | |
957 passed just one argument, it returns that argument. | |
958 | |
959 @smallexample | |
960 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
961 ; @r{ 29-bit binary values} |
6510 | 962 |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
963 (logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
964 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
965 @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} |
6510 | 966 @end group |
967 | |
968 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
969 (logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
970 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
971 ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
972 @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111} |
6510 | 973 @end group |
974 @end smallexample | |
975 @end defun | |
976 | |
977 @defun logxor &rest ints-or-markers | |
978 @cindex bitwise exclusive or | |
979 @cindex logical exclusive or | |
980 This function returns the ``exclusive or'' of its arguments: the | |
7115
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
981 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
982 set in an odd number of the arguments. If there are no arguments, the |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
983 result is 0, which is an identity element for this operation. If |
9a9e88e65617
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6510
diff
changeset
|
984 @code{logxor} is passed just one argument, it returns that argument. |
6510 | 985 |
986 @smallexample | |
987 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
988 ; @r{ 29-bit binary values} |
6510 | 989 |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
990 (logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
991 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
992 @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001} |
6510 | 993 @end group |
994 | |
995 @group | |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
996 (logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
997 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
998 ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} |
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
999 @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} |
6510 | 1000 @end group |
1001 @end smallexample | |
1002 @end defun | |
1003 | |
1004 @defun lognot integer | |
1005 @cindex logical not | |
1006 @cindex bitwise not | |
1007 This function returns the logical complement of its argument: the @var{n}th | |
1008 bit is one in the result if, and only if, the @var{n}th bit is zero in | |
1009 @var{integer}, and vice-versa. | |
1010 | |
1011 @example | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48700
diff
changeset
|
1012 (lognot 5) |
6510 | 1013 @result{} -6 |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
1014 ;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} |
6510 | 1015 ;; @r{becomes} |
52886
3a30e4cd22e9
Update for extra bit of integer range.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
52863
diff
changeset
|
1016 ;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010} |
6510 | 1017 @end example |
1018 @end defun | |
1019 | |
11230
c6b70cdf844e
Don't call the special math functions "transcendental".
Richard M. Stallman <rms@gnu.org>
parents:
10558
diff
changeset
|
1020 @node Math Functions |
c6b70cdf844e
Don't call the special math functions "transcendental".
Richard M. Stallman <rms@gnu.org>
parents:
10558
diff
changeset
|
1021 @section Standard Mathematical Functions |
6510 | 1022 @cindex transcendental functions |
1023 @cindex mathematical functions | |
1024 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1025 These mathematical functions allow integers as well as floating point |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1026 numbers as arguments. |
6510 | 1027 |
1028 @defun sin arg | |
1029 @defunx cos arg | |
1030 @defunx tan arg | |
1031 These are the ordinary trigonometric functions, with argument measured | |
1032 in radians. | |
1033 @end defun | |
1034 | |
1035 @defun asin arg | |
25454 | 1036 The value of @code{(asin @var{arg})} is a number between |
27193 | 1037 @ifnottex |
25454 | 1038 @minus{}pi/2 |
27193 | 1039 @end ifnottex |
25454 | 1040 @tex |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1041 @math{-\pi/2} |
25454 | 1042 @end tex |
1043 and | |
27193 | 1044 @ifnottex |
25454 | 1045 pi/2 |
27193 | 1046 @end ifnottex |
25454 | 1047 @tex |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1048 @math{\pi/2} |
25454 | 1049 @end tex |
53432
7dd1ab1ebb2c
(Math Functions): asin, acos, log, log10 report domain-error errors.
Richard M. Stallman <rms@gnu.org>
parents:
53044
diff
changeset
|
1050 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of |
7dd1ab1ebb2c
(Math Functions): asin, acos, log, log10 report domain-error errors.
Richard M. Stallman <rms@gnu.org>
parents:
53044
diff
changeset
|
1051 range (outside [-1, 1]), it signals a @code{domain-error} error. |
6510 | 1052 @end defun |
1053 | |
1054 @defun acos arg | |
25454 | 1055 The value of @code{(acos @var{arg})} is a number between 0 and |
27193 | 1056 @ifnottex |
25454 | 1057 pi |
27193 | 1058 @end ifnottex |
25454 | 1059 @tex |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1060 @math{\pi} |
25454 | 1061 @end tex |
53432
7dd1ab1ebb2c
(Math Functions): asin, acos, log, log10 report domain-error errors.
Richard M. Stallman <rms@gnu.org>
parents:
53044
diff
changeset
|
1062 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out |
7dd1ab1ebb2c
(Math Functions): asin, acos, log, log10 report domain-error errors.
Richard M. Stallman <rms@gnu.org>
parents:
53044
diff
changeset
|
1063 of range (outside [-1, 1]), it signals a @code{domain-error} error. |
6510 | 1064 @end defun |
1065 | |
43414
90f3a1f6ee84
(Math Functions): Document the optional second arg of atan.
Eli Zaretskii <eliz@gnu.org>
parents:
39198
diff
changeset
|
1066 @defun atan y &optional x |
90f3a1f6ee84
(Math Functions): Document the optional second arg of atan.
Eli Zaretskii <eliz@gnu.org>
parents:
39198
diff
changeset
|
1067 The value of @code{(atan @var{y})} is a number between |
27193 | 1068 @ifnottex |
25454 | 1069 @minus{}pi/2 |
27193 | 1070 @end ifnottex |
25454 | 1071 @tex |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1072 @math{-\pi/2} |
25454 | 1073 @end tex |
1074 and | |
27193 | 1075 @ifnottex |
25454 | 1076 pi/2 |
27193 | 1077 @end ifnottex |
25454 | 1078 @tex |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1079 @math{\pi/2} |
25454 | 1080 @end tex |
43414
90f3a1f6ee84
(Math Functions): Document the optional second arg of atan.
Eli Zaretskii <eliz@gnu.org>
parents:
39198
diff
changeset
|
1081 (exclusive) whose tangent is @var{y}. If the optional second |
90f3a1f6ee84
(Math Functions): Document the optional second arg of atan.
Eli Zaretskii <eliz@gnu.org>
parents:
39198
diff
changeset
|
1082 argument @var{x} is given, the value of @code{(atan y x)} is the |
90f3a1f6ee84
(Math Functions): Document the optional second arg of atan.
Eli Zaretskii <eliz@gnu.org>
parents:
39198
diff
changeset
|
1083 angle in radians between the vector @code{[@var{x}, @var{y}]} and the |
90f3a1f6ee84
(Math Functions): Document the optional second arg of atan.
Eli Zaretskii <eliz@gnu.org>
parents:
39198
diff
changeset
|
1084 @code{X} axis. |
6510 | 1085 @end defun |
1086 | |
1087 @defun exp arg | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1088 This is the exponential function; it returns |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1089 @tex |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1090 @math{e} |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1091 @end tex |
27193 | 1092 @ifnottex |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1093 @i{e} |
27193 | 1094 @end ifnottex |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1095 to the power @var{arg}. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1096 @tex |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1097 @math{e} |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1098 @end tex |
27193 | 1099 @ifnottex |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1100 @i{e} |
27193 | 1101 @end ifnottex |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1102 is a fundamental mathematical constant also called the base of natural |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1103 logarithms. |
6510 | 1104 @end defun |
1105 | |
1106 @defun log arg &optional base | |
1107 This function returns the logarithm of @var{arg}, with base @var{base}. | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1108 If you don't specify @var{base}, the base |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1109 @tex |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1110 @math{e} |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1111 @end tex |
27193 | 1112 @ifnottex |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1113 @i{e} |
27193 | 1114 @end ifnottex |
53432
7dd1ab1ebb2c
(Math Functions): asin, acos, log, log10 report domain-error errors.
Richard M. Stallman <rms@gnu.org>
parents:
53044
diff
changeset
|
1115 is used. If @var{arg} is negative, it signals a @code{domain-error} |
7dd1ab1ebb2c
(Math Functions): asin, acos, log, log10 report domain-error errors.
Richard M. Stallman <rms@gnu.org>
parents:
53044
diff
changeset
|
1116 error. |
6510 | 1117 @end defun |
1118 | |
1119 @ignore | |
1120 @defun expm1 arg | |
1121 This function returns @code{(1- (exp @var{arg}))}, but it is more | |
1122 accurate than that when @var{arg} is negative and @code{(exp @var{arg})} | |
1123 is close to 1. | |
1124 @end defun | |
1125 | |
1126 @defun log1p arg | |
1127 This function returns @code{(log (1+ @var{arg}))}, but it is more | |
1128 accurate than that when @var{arg} is so small that adding 1 to it would | |
1129 lose accuracy. | |
1130 @end defun | |
1131 @end ignore | |
1132 | |
1133 @defun log10 arg | |
1134 This function returns the logarithm of @var{arg}, with base 10. If | |
53432
7dd1ab1ebb2c
(Math Functions): asin, acos, log, log10 report domain-error errors.
Richard M. Stallman <rms@gnu.org>
parents:
53044
diff
changeset
|
1135 @var{arg} is negative, it signals a @code{domain-error} error. |
7dd1ab1ebb2c
(Math Functions): asin, acos, log, log10 report domain-error errors.
Richard M. Stallman <rms@gnu.org>
parents:
53044
diff
changeset
|
1136 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least |
7dd1ab1ebb2c
(Math Functions): asin, acos, log, log10 report domain-error errors.
Richard M. Stallman <rms@gnu.org>
parents:
53044
diff
changeset
|
1137 approximately. |
6510 | 1138 @end defun |
1139 | |
1140 @defun expt x y | |
10306
89f8d7f3bd73
Integers now at least 28 bits.
Richard M. Stallman <rms@gnu.org>
parents:
8017
diff
changeset
|
1141 This function returns @var{x} raised to power @var{y}. If both |
89f8d7f3bd73
Integers now at least 28 bits.
Richard M. Stallman <rms@gnu.org>
parents:
8017
diff
changeset
|
1142 arguments are integers and @var{y} is positive, the result is an |
89f8d7f3bd73
Integers now at least 28 bits.
Richard M. Stallman <rms@gnu.org>
parents:
8017
diff
changeset
|
1143 integer; in this case, it is truncated to fit the range of possible |
89f8d7f3bd73
Integers now at least 28 bits.
Richard M. Stallman <rms@gnu.org>
parents:
8017
diff
changeset
|
1144 integer values. |
6510 | 1145 @end defun |
1146 | |
1147 @defun sqrt arg | |
1148 This returns the square root of @var{arg}. If @var{arg} is negative, | |
53465
a603854deb89
(Math Functions): sqrt reports a domain-error
Andreas Schwab <schwab@suse.de>
parents:
53432
diff
changeset
|
1149 it signals a @code{domain-error} error. |
6510 | 1150 @end defun |
1151 | |
1152 @node Random Numbers | |
1153 @section Random Numbers | |
1154 @cindex random numbers | |
1155 | |
1156 A deterministic computer program cannot generate true random numbers. | |
1157 For most purposes, @dfn{pseudo-random numbers} suffice. A series of | |
1158 pseudo-random numbers is generated in a deterministic fashion. The | |
1159 numbers are not truly random, but they have certain properties that | |
1160 mimic a random series. For example, all possible values occur equally | |
1161 often in a pseudo-random series. | |
1162 | |
1163 In Emacs, pseudo-random numbers are generated from a ``seed'' number. | |
1164 Starting from any given seed, the @code{random} function always | |
1165 generates the same sequence of numbers. Emacs always starts with the | |
1166 same seed value, so the sequence of values of @code{random} is actually | |
1167 the same in each Emacs run! For example, in one operating system, the | |
1168 first call to @code{(random)} after you start Emacs always returns | |
1169 -1457731, and the second one always returns -7692030. This | |
1170 repeatability is helpful for debugging. | |
1171 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1172 If you want random numbers that don't always come out the same, execute |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1173 @code{(random t)}. This chooses a new seed based on the current time of |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52901
diff
changeset
|
1174 day and on Emacs's process @acronym{ID} number. |
6510 | 1175 |
1176 @defun random &optional limit | |
1177 This function returns a pseudo-random integer. Repeated calls return a | |
1178 series of pseudo-random integers. | |
1179 | |
12067 | 1180 If @var{limit} is a positive integer, the value is chosen to be |
12098 | 1181 nonnegative and less than @var{limit}. |
6510 | 1182 |
1183 If @var{limit} is @code{t}, it means to choose a new seed based on the | |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52901
diff
changeset
|
1184 current time of day and on Emacs's process @acronym{ID} number. |
6510 | 1185 @c "Emacs'" is incorrect usage! |
1186 | |
1187 On some machines, any integer representable in Lisp may be the result | |
1188 of @code{random}. On other machines, the result can never be larger | |
1189 than a certain maximum or less than a certain (negative) minimum. | |
1190 @end defun | |
52401 | 1191 |
1192 @ignore | |
1193 arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e | |
1194 @end ignore |