diff options
Diffstat (limited to 'lispref/numbers.texi')
| -rw-r--r-- | lispref/numbers.texi | 1030 |
1 files changed, 0 insertions, 1030 deletions
diff --git a/lispref/numbers.texi b/lispref/numbers.texi deleted file mode 100644 index f2e0a7df07a..00000000000 --- a/lispref/numbers.texi +++ /dev/null @@ -1,1030 +0,0 @@ -@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 |