diff options
author | Richard M. Stallman <rms@gnu.org> | 1994-03-24 17:24:15 +0000 |
---|---|---|
committer | Richard M. Stallman <rms@gnu.org> | 1994-03-24 17:24:15 +0000 |
commit | e6512bcf1f9ef48cfcf96bb4d5f93e109a784c09 (patch) | |
tree | 96ed817d7834e1c2186e3c97d1f9f7c621814b5e /lispref/numbers.texi | |
parent | 253bce3d6b1e47f793159bc25cb340259269e784 (diff) |
Initial revision
Diffstat (limited to 'lispref/numbers.texi')
-rw-r--r-- | lispref/numbers.texi | 1030 |
1 files changed, 1030 insertions, 0 deletions
diff --git a/lispref/numbers.texi b/lispref/numbers.texi new file mode 100644 index 0000000000..f2e0a7df07 --- /dev/null +++ b/lispref/numbers.texi @@ -0,0 +1,1030 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/numbers +@node Numbers, Strings and Characters, Types of Lisp Object, Top +@chapter Numbers +@cindex integers +@cindex numbers + + GNU Emacs supports two numeric data types: @dfn{integers} and +@dfn{floating point numbers}. Integers are whole numbers such as +@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point +numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or +2.71828. They can also be expressed in an exponential notation as well: +thus, 1.5e2 equals 150; in this example, @samp{e2} stands for ten to the +second power, and is multiplied by 1.5. Floating point values are not +exact; they have a fixed, limited amount of precision. + + Support for floating point numbers is a new feature in Emacs 19, and it +is controlled by a separate compilation option, so you may encounter a site +where Emacs does not support them. + +@menu +* Integer Basics:: Representation and range of integers. +* Float Basics:: Representation and range of floating point. +* Predicates on Numbers:: Testing for numbers. +* Comparison of Numbers:: Equality and inequality predicates. +* Numeric Conversions:: Converting float to integer and vice versa. +* Arithmetic Operations:: How to add, subtract, multiply and divide. +* Rounding Operations:: Explicitly rounding floating point numbers. +* Bitwise Operations:: Logical and, or, not, shifting. +* Transcendental Functions:: Trig, exponential and logarithmic functions. +* Random Numbers:: Obtaining random integers, predictable or not. +@end menu + +@node Integer Basics +@comment node-name, next, previous, up +@section Integer Basics + + The range of values for an integer depends on the machine. The +range is @minus{}8388608 to 8388607 (24 bits; i.e., +@ifinfo +-2**23 +@end ifinfo +@tex +$-2^{23}$ +@end tex +to +@ifinfo +2**23 - 1) +@end ifinfo +@tex +$2^{23}-1$) +@end tex +on most machines, but on others it is @minus{}16777216 to 16777215 (25 +bits), or @minus{}33554432 to 33554431 (26 bits). Many examples in this +chapter assume an integer has 24 bits. +@cindex overflow + + The Lisp reader reads an integer as a sequence of digits with optional +initial sign and optional final period. + +@example + 1 ; @r{The integer 1.} + 1. ; @r{The integer 1.} ++1 ; @r{Also the integer 1.} +-1 ; @r{The integer @minus{}1.} + 16777217 ; @r{Also the integer 1, due to overflow.} + 0 ; @r{The integer 0.} +-0 ; @r{The integer 0.} +@end example + + To understand how various functions work on integers, especially the +bitwise operators (@pxref{Bitwise Operations}), it is often helpful to +view the numbers in their binary form. + + In 24 bit binary, the decimal integer 5 looks like this: + +@example +0000 0000 0000 0000 0000 0101 +@end example + +@noindent +(We have inserted spaces between groups of 4 bits, and two spaces +between groups of 8 bits, to make the binary integer easier to read.) + + The integer @minus{}1 looks like this: + +@example +1111 1111 1111 1111 1111 1111 +@end example + +@noindent +@cindex two's complement +@minus{}1 is represented as 24 ones. (This is called @dfn{two's +complement} notation.) + + The negative integer, @minus{}5, is creating by subtracting 4 from +@minus{}1. In binary, the decimal integer 4 is 100. Consequently, +@minus{}5 looks like this: + +@example +1111 1111 1111 1111 1111 1011 +@end example + + In this implementation, the largest 24 bit binary integer is the +decimal integer 8,388,607. In binary, it looks like this: + +@example +0111 1111 1111 1111 1111 1111 +@end example + + Since the arithmetic functions do not check whether integers go +outside their range, when you add 1 to 8,388,607, the value is negative +integer @minus{}8,388,608: + +@example +(+ 1 8388607) + @result{} -8388608 + @result{} 1000 0000 0000 0000 0000 0000 +@end example + + Many of the following functions accept markers for arguments as well +as integers. (@xref{Markers}.) More precisely, the actual arguments to +such functions may be either integers or markers, which is why we often +give these arguments the name @var{int-or-marker}. When the argument +value is a marker, its position value is used and its buffer is ignored. + +@ignore + In version 19, except where @emph{integer} is specified as an +argument, all of the functions for markers and integers also work for +floating point numbers. +@end ignore + +@node Float Basics +@section Floating Point Basics + +@cindex @code{LISP_FLOAT_TYPE} configuration macro + Emacs version 19 supports floating point numbers, if compiled with the +macro @code{LISP_FLOAT_TYPE} defined. The precise range of floating +point numbers is machine-specific; it is the same as the range of the C +data type @code{double} on the machine in question. + + The printed representation for floating point numbers requires either +a decimal point (with at least one digit following), an exponent, or +both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, +@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point +number whose value is 1500. They are all equivalent. You can also use +a minus sign to write negative floating point numbers, as in +@samp{-1.0}. + +@cindex IEEE floating point +@cindex positive infinity +@cindex negative infinity +@cindex infinity +@cindex NaN + Most modern computers support the IEEE floating point standard, which +provides for positive infinity and negative infinity as floating point +values. It also provides for a value called NaN or ``not-a-number'' +which is the result you get from numerical functions in cases where +there is no correct answer. For example, @code{(sqrt -1.0)} returns +NaN. There is no read syntax for NaN or infinities; perhaps we should +create a syntax in the future. + + You can use @code{logb} to extract the binary exponent of a floating +point number (or estimate the logarithm of an integer): + +@defun logb number +This function returns the binary exponent of @var{number}. More +precisely, the value is the logarithm of @var{number} base 2, rounded +down to an integer. +@end defun + +@node Predicates on Numbers +@section Type Predicates for Numbers + + The functions in this section test whether the argument is a number or +whether it is a certain sort of number. The functions @code{integerp} +and @code{floatp} can take any type of Lisp object as argument (the +predicates would not be of much use otherwise); but the @code{zerop} +predicate requires a number as its argument. See also +@code{integer-or-marker-p} and @code{number-or-marker-p}, in +@ref{Predicates on Markers}. + +@defun floatp object +This predicate tests whether its argument is a floating point +number and returns @code{t} if so, @code{nil} otherwise. + +@code{floatp} does not exist in Emacs versions 18 and earlier. +@end defun + +@defun integerp object +This predicate tests whether its argument is an integer, and returns +@code{t} if so, @code{nil} otherwise. +@end defun + +@defun numberp object +This predicate tests whether its argument is a number (either integer or +floating point), and returns @code{t} if so, @code{nil} otherwise. +@end defun + +@defun natnump object +@cindex natural numbers +The @code{natnump} predicate (whose name comes from the phrase +``natural-number-p'') tests to see whether its argument is a nonnegative +integer, and returns @code{t} if so, @code{nil} otherwise. 0 is +considered non-negative. + +Markers are not converted to integers, hence @code{natnump} of a marker +is always @code{nil}. + +People have pointed out that this function is misnamed, because the term +``natural number'' is usually understood as excluding zero. We are open +to suggestions for a better name to use in a future version. +@end defun + +@defun zerop number +This predicate tests whether its argument is zero, and returns @code{t} +if so, @code{nil} otherwise. The argument must be a number. + +These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}. +@end defun + +@node Comparison of Numbers +@section Comparison of Numbers +@cindex number equality + + Floating point numbers in Emacs Lisp actually take up storage, and +there can be many distinct floating point number objects with the same +numeric value. If you use @code{eq} to compare them, then you test +whether two values are the same @emph{object}. If you want to test for +numerical equality, use @code{=}. + + If you use @code{eq} to compare two integers, it always returns +@code{t} if they have the same value. This is sometimes useful, because +@code{eq} accepts arguments of any type and never causes an error, +whereas @code{=} signals an error if the arguments are not numbers or +markers. However, it is a good idea to use @code{=} if you can, even +for comparing integers, just in case we change the representation of +integers in a future Emacs version. + + There is another wrinkle: because floating point arithmetic is not +exact, it is often a bad idea to check for equality of two floating +point values. Usually it is better to test for approximate equality. +Here's a function to do this: + +@example +(defvar fuzz-factor 1.0e-6) +(defun approx-equal (x y) + (< (/ (abs (- x y)) + (max (abs x) (abs y))) + fuzz-factor)) +@end example + +@cindex CL note---integers vrs @code{eq} +@quotation +@b{Common Lisp note:} comparing numbers in Common Lisp always requires +@code{=} because Common Lisp implements multi-word integers, and two +distinct integer objects can have the same numeric value. Emacs Lisp +can have just one integer object for any given value because it has a +limited range of integer values. +@end quotation + +@defun = number-or-marker1 number-or-marker2 +This function tests whether its arguments are numerically equal, and +returns @code{t} if so, @code{nil} otherwise. +@end defun + +@defun /= number-or-marker1 number-or-marker2 +This function tests whether its arguments are numerically equal, and +returns @code{t} if they are not, and @code{nil} if they are. +@end defun + +@defun < number-or-marker1 number-or-marker2 +This function tests whether its first argument is strictly less than +its second argument. It returns @code{t} if so, @code{nil} otherwise. +@end defun + +@defun <= number-or-marker1 number-or-marker2 +This function tests whether its first argument is less than or equal +to its second argument. It returns @code{t} if so, @code{nil} +otherwise. +@end defun + +@defun > number-or-marker1 number-or-marker2 +This function tests whether its first argument is strictly greater +than its second argument. It returns @code{t} if so, @code{nil} +otherwise. +@end defun + +@defun >= number-or-marker1 number-or-marker2 +This function tests whether its first argument is greater than or +equal to its second argument. It returns @code{t} if so, @code{nil} +otherwise. +@end defun + +@defun max number-or-marker &rest numbers-or-markers +This function returns the largest of its arguments. + +@example +(max 20) + @result{} 20 +(max 1 2.5) + @result{} 2.5 +(max 1 3 2.5) + @result{} 3 +@end example +@end defun + +@defun min number-or-marker &rest numbers-or-markers +This function returns the smallest of its arguments. + +@example +(min -4 1) + @result{} -4 +@end example +@end defun + +@node Numeric Conversions +@section Numeric Conversions +@cindex rounding in conversions + +To convert an integer to floating point, use the function @code{float}. + +@defun float number +This returns @var{number} converted to floating point. +If @var{number} is already a floating point number, @code{float} returns +it unchanged. +@end defun + +There are four functions to convert floating point numbers to integers; +they differ in how they round. These functions accept integer arguments +also, and return such arguments unchanged. + +@defun truncate number +This returns @var{number}, converted to an integer by rounding towards +zero. +@end defun + +@defun floor number &optional divisor +This returns @var{number}, converted to an integer by rounding downward +(towards negative infinity). + +If @var{divisor} is specified, @var{number} is divided by @var{divisor} +before the floor is taken; this is the division operation that +corresponds to @code{mod}. An @code{arith-error} results if +@var{divisor} is 0. +@end defun + +@defun ceiling number +This returns @var{number}, converted to an integer by rounding upward +(towards positive infinity). +@end defun + +@defun round number +This returns @var{number}, converted to an integer by rounding towards the +nearest integer. +@end defun + +@node Arithmetic Operations +@section Arithmetic Operations + + Emacs Lisp provides the traditional four arithmetic operations: +addition, subtraction, multiplication, and division. Remainder and modulus +functions supplement the division functions. The functions to +add or subtract 1 are provided because they are traditional in Lisp and +commonly used. + + All of these functions except @code{%} return a floating point value +if any argument is floating. + + It is important to note that in GNU Emacs Lisp, arithmetic functions +do not check for overflow. Thus @code{(1+ 8388607)} may evaluate to +@minus{}8388608, depending on your hardware. + +@defun 1+ number-or-marker +This function returns @var{number-or-marker} plus 1. +For example, + +@example +(setq foo 4) + @result{} 4 +(1+ foo) + @result{} 5 +@end example + +This function is not analogous to the C operator @code{++}---it does +not increment a variable. It just computes a sum. Thus, + +@example +foo + @result{} 4 +@end example + +If you want to increment the variable, you must use @code{setq}, +like this: + +@example +(setq foo (1+ foo)) + @result{} 5 +@end example +@end defun + +@defun 1- number-or-marker +This function returns @var{number-or-marker} minus 1. +@end defun + +@defun abs number +This returns the absolute value of @var{number}. +@end defun + +@defun + &rest numbers-or-markers +This function adds its arguments together. When given no arguments, +@code{+} returns 0. It does not check for overflow. + +@example +(+) + @result{} 0 +(+ 1) + @result{} 1 +(+ 1 2 3 4) + @result{} 10 +@end example +@end defun + +@defun - &optional number-or-marker &rest other-numbers-or-markers +The @code{-} function serves two purposes: negation and subtraction. +When @code{-} has a single argument, the value is the negative of the +argument. When there are multiple arguments, @code{-} subtracts each of +the @var{other-numbers-or-markers} from @var{number-or-marker}, +cumulatively. If there are no arguments, the result is 0. This +function does not check for overflow. + +@example +(- 10 1 2 3 4) + @result{} 0 +(- 10) + @result{} -10 +(-) + @result{} 0 +@end example +@end defun + +@defun * &rest numbers-or-markers +This function multiplies its arguments together, and returns the +product. When given no arguments, @code{*} returns 1. It does +not check for overflow. + +@example +(*) + @result{} 1 +(* 1) + @result{} 1 +(* 1 2 3 4) + @result{} 24 +@end example +@end defun + +@defun / dividend divisor &rest divisors +This function divides @var{dividend} by @var{divisors} and returns the +quotient. If there are additional arguments @var{divisors}, then it +divides @var{dividend} by each divisor in turn. Each argument may be a +number or a marker. + +If all the arguments are integers, then the result is an integer too. +This means the result has to be rounded. On most machines, the result +is rounded towards zero after each division, but some machines may round +differently with negative arguments. This is because the Lisp function +@code{/} is implemented using the C division operator, which also +permits machine-dependent rounding. As a practical matter, all known +machines round in the standard fashion. + +@cindex @code{arith-error} in division +If you divide by 0, an @code{arith-error} error is signaled. +(@xref{Errors}.) + +@example +(/ 6 2) + @result{} 3 +(/ 5 2) + @result{} 2 +(/ 25 3 2) + @result{} 4 +(/ -17 6) + @result{} -2 +@end example + +The result of @code{(/ -17 6)} could in principle be -3 on some +machines. +@end defun + +@defun % dividend divisor +@cindex remainder +This function returns the integer remainder after division of @var{dividend} +by @var{divisor}. The arguments must be integers or markers. + +For negative arguments, the remainder is in principle machine-dependent +since the quotient is; but in practice, all known machines behave alike. + +An @code{arith-error} results if @var{divisor} is 0. + +@example +(% 9 4) + @result{} 1 +(% -9 4) + @result{} -1 +(% 9 -4) + @result{} 1 +(% -9 -4) + @result{} -1 +@end example + +For any two integers @var{dividend} and @var{divisor}, + +@example +@group +(+ (% @var{dividend} @var{divisor}) + (* (/ @var{dividend} @var{divisor}) @var{divisor})) +@end group +@end example + +@noindent +always equals @var{dividend}. +@end defun + +@defun mod dividend divisor +@cindex modulus +This function returns the value of @var{dividend} modulo @var{divisor}; +in other words, the remainder after division of @var{dividend} +by @var{divisor}, but with the same sign as @var{divisor}. +The arguments must be numbers or markers. + +Unlike @code{%}, @code{mod} returns a well-defined result for negative +arguments. It also permits floating point arguments; it rounds the +quotient downward (towards minus infinity) to an integer, and uses that +quotient to compute the remainder. + +An @code{arith-error} results if @var{divisor} is 0. + +@example +(mod 9 4) + @result{} 1 +(mod -9 4) + @result{} 3 +(mod 9 -4) + @result{} -3 +(mod -9 -4) + @result{} -1 +(mod 5.5 2.5) + @result{} .5 +@end example + +For any two numbers @var{dividend} and @var{divisor}, + +@example +@group +(+ (mod @var{dividend} @var{divisor}) + (* (floor @var{dividend} @var{divisor}) @var{divisor})) +@end group +@end example + +@noindent +always equals @var{dividend}, subject to rounding error if +either argument is floating point. +@end defun + +@node Rounding Operations +@section Rounding Operations +@cindex rounding without conversion + +The functions @code{ffloor}, @code{fceil}, @code{fround} and +@code{ftruncate} take a floating point argument and return a floating +point result whose value is a nearby integer. @code{ffloor} returns the +nearest integer below; @code{fceil}, the nearest integer above; +@code{ftrucate}, the nearest integer in the direction towards zero; +@code{fround}, the nearest integer. + +@defun ffloor float +This function rounds @var{float} to the next lower integral value, and +returns that value as a floating point number. +@end defun + +@defun fceil float +This function rounds @var{float} to the next higher integral value, and +returns that value as a floating point number. +@end defun + +@defun ftrunc float +This function rounds @var{float} towards zero to an integral value, and +returns that value as a floating point number. +@end defun + +@defun fround float +This function rounds @var{float} to the nearest integral value, +and returns that value as a floating point number. +@end defun + +@node Bitwise Operations +@section Bitwise Operations on Integers + + In a computer, an integer is represented as a binary number, a +sequence of @dfn{bits} (digits which are either zero or one). A bitwise +operation acts on the individual bits of such a sequence. For example, +@dfn{shifting} moves the whole sequence left or right one or more places, +reproducing the same pattern ``moved over''. + + The bitwise operations in Emacs Lisp apply only to integers. + +@defun lsh integer1 count +@cindex logical shift +@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the +bits in @var{integer1} to the left @var{count} places, or to the +right if @var{count} is negative. If @var{count} is negative, +@code{lsh} shifts zeros into the most-significant bit, producing a +positive result even if @var{integer1} is negative. Contrast this with +@code{ash}, below. + +Thus, the decimal number 5 is the binary number 00000101. Shifted once +to the left, with a zero put in the one's place, the number becomes +00001010, decimal 10. + +Here are two examples of shifting the pattern of bits one place to the +left. Since the contents of the rightmost place has been moved one +place to the left, a value has to be inserted into the rightmost place. +With @code{lsh}, a zero is placed into the rightmost place. (These +examples show only the low-order eight bits of the binary pattern; the +rest are all zero.) + +@example +@group +(lsh 5 1) + @result{} 10 +;; @r{Decimal 5 becomes decimal 10.} +00000101 @result{} 00001010 + +(lsh 7 1) + @result{} 14 +;; @r{Decimal 7 becomes decimal 14.} +00000111 @result{} 00001110 +@end group +@end example + +@noindent +As the examples illustrate, shifting the pattern of bits one place to +the left produces a number that is twice the value of the previous +number. + +Note, however that functions do not check for overflow, and a returned +value may be negative (and in any case, no more than a 24 bit value) +when an integer is sufficiently left shifted. + +For example, left shifting 8,388,607 produces @minus{}2: + +@example +(lsh 8388607 1) ; @r{left shift} + @result{} -2 +@end example + +In binary, in the 24 bit implementation, the numbers looks like this: + +@example +@group +;; @r{Decimal 8,388,607} +0111 1111 1111 1111 1111 1111 +@end group +@end example + +@noindent +which becomes the following when left shifted: + +@example +@group +;; @r{Decimal @minus{}2} +1111 1111 1111 1111 1111 1110 +@end group +@end example + +Shifting the pattern of bits two places to the left produces results +like this (with 8-bit binary numbers): + +@example +@group +(lsh 3 2) + @result{} 12 +;; @r{Decimal 3 becomes decimal 12.} +00000011 @result{} 00001100 +@end group +@end example + +On the other hand, shifting the pattern of bits one place to the right +looks like this: + +@example +@group +(lsh 6 -1) + @result{} 3 +;; @r{Decimal 6 becomes decimal 3.} +00000110 @result{} 00000011 +@end group + +@group +(lsh 5 -1) + @result{} 2 +;; @r{Decimal 5 becomes decimal 2.} +00000101 @result{} 00000010 +@end group +@end example + +@noindent +As the example illustrates, shifting the pattern of bits one place to +the right divides the value of the binary number by two, rounding downward. +@end defun + +@defun ash integer1 count +@cindex arithmetic shift +@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} +to the left @var{count} places, or to the right if @var{count} +is negative. + +@code{ash} gives the same results as @code{lsh} except when +@var{integer1} and @var{count} are both negative. In that case, +@code{ash} puts a one in the leftmost position, while @code{lsh} puts +a zero in the leftmost position. + +Thus, with @code{ash}, shifting the pattern of bits one place to the right +looks like this: + +@example +@group +(ash -6 -1) @result{} -3 +;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} +1111 1111 1111 1111 1111 1010 + @result{} +1111 1111 1111 1111 1111 1101 +@end group +@end example + +In contrast, shifting the pattern of bits one place to the right with +@code{lsh} looks like this: + +@example +@group +(lsh -6 -1) @result{} 8388605 +;; @r{Decimal @minus{}6 becomes decimal 8,388,605.} +1111 1111 1111 1111 1111 1010 + @result{} +0111 1111 1111 1111 1111 1101 +@end group +@end example + +@noindent +In this case, the 1 in the leftmost position is shifted one place to the +right, and a zero is shifted into the leftmost position. + +Here are other examples: + +@c !!! Check if lined up in smallbook format! XDVI shows problem +@c with smallbook but not with regular book! --rjc 16mar92 +@smallexample +@group + ; @r{ 24-bit binary values} + +(lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0101} + @result{} 20 ; 20 = @r{0000 0000 0000 0000 0001 0100} +@end group +@group +(ash 5 2) + @result{} 20 +(lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1011} + @result{} -20 ; -20 = @r{1111 1111 1111 1111 1110 1100} +(ash -5 2) + @result{} -20 +@end group +@group +(lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0101} + @result{} 1 ; 1 = @r{0000 0000 0000 0000 0000 0001} +@end group +@group +(ash 5 -2) + @result{} 1 +@end group +@group +(lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1011} + @result{} 4194302 ; @r{0011 1111 1111 1111 1111 1110} +@end group +@group +(ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1011} + @result{} -2 ; -2 = @r{1111 1111 1111 1111 1111 1110} +@end group +@end smallexample +@end defun + +@defun logand &rest ints-or-markers +@cindex logical and +@cindex bitwise and +This function returns the ``logical and'' of the arguments: the +@var{n}th bit is set in the result if, and only if, the @var{n}th bit is +set in all the arguments. (``Set'' means that the value of the bit is 1 +rather than 0.) + +For example, using 4-bit binary numbers, the ``logical and'' of 13 and +12 is 12: 1101 combined with 1100 produces 1100. + +In both the binary numbers, the leftmost two bits are set (i.e., they +are 1's), so the leftmost two bits of the returned value are set. +However, for the rightmost two bits, each is zero in at least one of +the arguments, so the rightmost two bits of the returned value are 0's. + +@noindent +Therefore, + +@example +@group +(logand 13 12) + @result{} 12 +@end group +@end example + +If @code{logand} is not passed any argument, it returns a value of +@minus{}1. This number is an identity element for @code{logand} +because its binary representation consists entirely of ones. If +@code{logand} is passed just one argument, it returns that argument. + +@smallexample +@group + ; @r{ 24-bit binary values} + +(logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 1110} + ; 13 = @r{0000 0000 0000 0000 0000 1101} + @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 1100} +@end group + +@group +(logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 1110} + ; 13 = @r{0000 0000 0000 0000 0000 1101} + ; 4 = @r{0000 0000 0000 0000 0000 0100} + @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0100} +@end group + +@group +(logand) + @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111} +@end group +@end smallexample +@end defun + +@defun logior &rest ints-or-markers +@cindex logical inclusive or +@cindex bitwise or +This function returns the ``inclusive or'' of its arguments: the @var{n}th bit +is set in the result if, and only if, the @var{n}th bit is set in at least +one of the arguments. If there are no arguments, the result is zero, +which is an identity element for this operation. If @code{logior} is +passed just one argument, it returns that argument. + +@smallexample +@group + ; @r{ 24-bit binary values} + +(logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 1100} + ; 5 = @r{0000 0000 0000 0000 0000 0101} + @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 1101} +@end group + +@group +(logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 1100} + ; 5 = @r{0000 0000 0000 0000 0000 0101} + ; 7 = @r{0000 0000 0000 0000 0000 0111} + @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 1111} +@end group +@end smallexample +@end defun + +@defun logxor &rest ints-or-markers +@cindex bitwise exclusive or +@cindex logical exclusive or +This function returns the ``exclusive or'' of its arguments: the +@var{n}th bit is set in the result if, and only if, the @var{n}th bit +is set in an odd number of the arguments. If there are no arguments, +the result is 0. If @code{logxor} is passed just one argument, it returns +that argument. + +@smallexample +@group + ; @r{ 24-bit binary values} + +(logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 1100} + ; 5 = @r{0000 0000 0000 0000 0000 0101} + @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 1001} +@end group + +@group +(logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 1100} + ; 5 = @r{0000 0000 0000 0000 0000 0101} + ; 7 = @r{0000 0000 0000 0000 0000 0111} + @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 1110} +@end group +@end smallexample +@end defun + +@defun lognot integer +@cindex logical not +@cindex bitwise not +This function returns the logical complement of its argument: the @var{n}th +bit is one in the result if, and only if, the @var{n}th bit is zero in +@var{integer}, and vice-versa. + +@example +(lognot 5) + @result{} -6 +;; 5 = @r{0000 0000 0000 0000 0000 0101} +;; @r{becomes} +;; -6 = @r{1111 1111 1111 1111 1111 1010} +@end example +@end defun + +@node Transcendental Functions +@section Transcendental Functions +@cindex transcendental functions +@cindex mathematical functions + +These mathematical functions are available if floating point is +supported. They allow integers as well as floating point numbers +as arguments. + +@defun sin arg +@defunx cos arg +@defunx tan arg +These are the ordinary trigonometric functions, with argument measured +in radians. +@end defun + +@defun asin arg +The value of @code{(asin @var{arg})} is a number between @minus{} pi / 2 +and pi / 2 (inclusive) whose sine is @var{arg}; if, however, @var{arg} +is out of range (outside [-1, 1]), then the result is a NaN. +@end defun + +@defun acos arg +The value of @code{(acos @var{arg})} is a number between 0 and pi +(inclusive) whose cosine is @var{arg}; if, however, @var{arg} +is out of range (outside [-1, 1]), then the result is a NaN. +@end defun + +@defun atan arg +The value of @code{(atan @var{arg})} is a number between @minus{} pi / 2 +and pi / 2 (exclusive) whose tangent is @var{arg}. +@end defun + +@defun exp arg +This is the exponential function; it returns @i{e} to the power +@var{arg}. @i{e} is a fundamental mathematical constant also called the +base of natural logarithms. +@end defun + +@defun log arg &optional base +This function returns the logarithm of @var{arg}, with base @var{base}. +If you don't specify @var{base}, the base @var{e} is used. If @var{arg} +is negative, the result is a NaN. +@end defun + +@ignore +@defun expm1 arg +This function returns @code{(1- (exp @var{arg}))}, but it is more +accurate than that when @var{arg} is negative and @code{(exp @var{arg})} +is close to 1. +@end defun + +@defun log1p arg +This function returns @code{(log (1+ @var{arg}))}, but it is more +accurate than that when @var{arg} is so small that adding 1 to it would +lose accuracy. +@end defun +@end ignore + +@defun log10 arg +This function returns the logarithm of @var{arg}, with base 10. If +@var{arg} is negative, the result is a NaN. +@end defun + +@defun expt x y +This function returns @var{x} raised to power @var{y}. +@end defun + +@defun sqrt arg +This returns the square root of @var{arg}. If @var{arg} is negative, +the value is a NaN. +@end defun + +@node Random Numbers +@section Random Numbers +@cindex random numbers + +A deterministic computer program cannot generate true random numbers. +For most purposes, @dfn{pseudo-random numbers} suffice. A series of +pseudo-random numbers is generated in a deterministic fashion. The +numbers are not truly random, but they have certain properties that +mimic a random series. For example, all possible values occur equally +often in a pseudo-random series. + +In Emacs, pseudo-random numbers are generated from a ``seed'' number. +Starting from any given seed, the @code{random} function always +generates the same sequence of numbers. Emacs always starts with the +same seed value, so the sequence of values of @code{random} is actually +the same in each Emacs run! For example, in one operating system, the +first call to @code{(random)} after you start Emacs always returns +-1457731, and the second one always returns -7692030. This +repeatability is helpful for debugging. + +If you want truly unpredictable random numbers, execute @code{(random +t)}. This chooses a new seed based on the current time of day and on +Emacs's process @sc{id} number. + +@defun random &optional limit +This function returns a pseudo-random integer. Repeated calls return a +series of pseudo-random integers. + +If @var{limit} is @code{nil}, then the value may in principle be any +integer. If @var{limit} is a positive integer, the value is chosen to +be nonnegative and less than @var{limit} (only in Emacs 19). + +If @var{limit} is @code{t}, it means to choose a new seed based on the +current time of day and on Emacs's process @sc{id} number. +@c "Emacs'" is incorrect usage! + +On some machines, any integer representable in Lisp may be the result +of @code{random}. On other machines, the result can never be larger +than a certain maximum or less than a certain (negative) minimum. +@end defun |