Mercurial > emacs
changeset 84091:d90005c20551
Move here from ../../lispref
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:22:23 +0000 |
| parents | e7e0d9a379c7 |
| children | e2f141bee28a |
| files | doc/lispref/numbers.texi |
| diffstat | 1 files changed, 1211 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispref/numbers.texi Thu Sep 06 04:22:23 2007 +0000 @@ -0,0 +1,1211 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/numbers +@node Numbers, Strings and Characters, Lisp Data Types, 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 exponential notation: 1.5e2 +equals 150; in this example, @samp{e2} stands for ten to the second +power, and that is multiplied by 1.5. Floating point values are not +exact; they have a fixed, limited amount of precision. + +@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. +* Math 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 +minimum range is @minus{}268435456 to 268435455 (29 bits; i.e., +@ifnottex +-2**28 +@end ifnottex +@tex +@math{-2^{28}} +@end tex +to +@ifnottex +2**28 - 1), +@end ifnottex +@tex +@math{2^{28}-1}), +@end tex +but some machines may provide a wider range. Many examples in this +chapter assume an integer has 29 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.} + 536870913 ; @r{Also the integer 1, due to overflow.} + 0 ; @r{The integer 0.} +-0 ; @r{The integer 0.} +@end example + +@cindex integers in specific radix +@cindex radix for reading an integer +@cindex base for reading an integer +@cindex hex numbers +@cindex octal numbers +@cindex reading numbers in hex, octal, and binary + The syntax for integers in bases other than 10 uses @samp{#} +followed by a letter that specifies the radix: @samp{b} for binary, +@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to +specify radix @var{radix}. Case is not significant for the letter +that specifies the radix. Thus, @samp{#b@var{integer}} reads +@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads +@var{integer} in radix @var{radix}. Allowed values of @var{radix} run +from 2 to 36. For example: + +@example +#b101100 @result{} 44 +#o54 @result{} 44 +#x2c @result{} 44 +#24r1k @result{} 44 +@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 29-bit binary, the decimal integer 5 looks like this: + +@example +0 0000 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 +1 1111 1111 1111 1111 1111 1111 1111 +@end example + +@noindent +@cindex two's complement +@minus{}1 is represented as 29 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 +1 1111 1111 1111 1111 1111 1111 1011 +@end example + + In this implementation, the largest 29-bit binary integer value is +268,435,455 in decimal. In binary, it looks like this: + +@example +0 1111 1111 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 268,435,455, the value is the +negative integer @minus{}268,435,456: + +@example +(+ 1 268435455) + @result{} -268435456 + @result{} 1 0000 0000 0000 0000 0000 0000 0000 +@end example + + Many of the functions described in this chapter accept markers for +arguments in place of numbers. (@xref{Markers}.) Since the actual +arguments to such functions may be either numbers or markers, we often +give these arguments the name @var{number-or-marker}. When the argument +value is a marker, its position value is used and its buffer is ignored. + +@defvar most-positive-fixnum +The value of this variable is the largest integer that Emacs Lisp +can handle. +@end defvar + +@defvar most-negative-fixnum +The value of this variable is the smallest integer that Emacs Lisp can +handle. It is negative. +@end defvar + +@node Float Basics +@section Floating Point Basics + + Floating point numbers are useful for representing numbers that are +not integral. 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 you are using. + + The read-syntax 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 @acronym{IEEE} floating point +@cindex positive infinity +@cindex negative infinity +@cindex infinity +@cindex NaN + Most modern computers support the @acronym{IEEE} floating point standard, +which provides for positive infinity and negative infinity as floating point +values. It also provides for a class of values called NaN or +``not-a-number''; numerical functions return such values in cases where +there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a +NaN. For practical purposes, there's no significant difference between +different NaN values in Emacs Lisp, and there's no rule for precisely +which NaN value should be used in a particular case, so Emacs Lisp +doesn't try to distinguish them (but it does report the sign, if you +print it). Here are the read syntaxes for these special floating +point values: + +@table @asis +@item positive infinity +@samp{1.0e+INF} +@item negative infinity +@samp{-1.0e+INF} +@item Not-a-number +@samp{0.0e+NaN} or @samp{-0.0e+NaN}. +@end table + + To test whether a floating point value is a NaN, compare it with +itself using @code{=}. That returns @code{nil} for a NaN, and +@code{t} for any other floating point value. + + The value @code{-0.0} is distinguishable from ordinary zero in +@acronym{IEEE} floating point, but Emacs Lisp @code{equal} and +@code{=} consider them equal values. + + 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. + +@example +(logb 10) + @result{} 3 +(logb 10.0e20) + @result{} 69 +@end example +@end defun + +@node Predicates on Numbers +@section Type Predicates for Numbers +@cindex predicates for numbers + + The functions in this section test for numbers, or for a specific +type of number. The functions @code{integerp} and @code{floatp} can +take any type of Lisp object as argument (they 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 wholenump object +@cindex natural numbers +The @code{wholenump} predicate (whose name comes from the phrase +``whole-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. + +@findex natnump +@code{natnump} is an obsolete synonym for @code{wholenump}. +@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. + +@code{(zerop x)} is equivalent to @code{(= x 0)}. +@end defun + +@node Comparison of Numbers +@section Comparison of Numbers +@cindex number comparison +@cindex comparing numbers + + To test numbers for numerical equality, you should normally use +@code{=}, not @code{eq}. 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}. By contrast, @code{=} compares only the numeric values +of the objects. + + At present, each integer value has a unique Lisp object in Emacs Lisp. +Therefore, @code{eq} is equivalent to @code{=} where integers are +concerned. It is sometimes convenient to use @code{eq} for comparing an +unknown value with an integer, because @code{eq} does not report an +error if the unknown value is not a number---it accepts arguments of any +type. By contrast, @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. + + Sometimes it is useful to compare numbers with @code{equal}; it +treats two numbers as equal if they have the same data type (both +integers, or both floating point) and the same value. By contrast, +@code{=} can treat an integer and a floating point number as equal. +@xref{Equality Predicates}. + + 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) + (or (and (= x 0) (= y 0)) + (< (/ (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 eql value1 value2 +This function acts like @code{eq} except when both arguments are +numbers. It compares numbers by type and numeric value, so that +@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and +@code{(eql 1 1)} both return @code{t}. +@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. +If any of the arguments is floating-point, the value is returned +as floating point, even if it was given as an integer. + +@example +(max 20) + @result{} 20 +(max 1 2.5) + @result{} 2.5 +(max 1 3 2.5) + @result{} 3.0 +@end example +@end defun + +@defun min number-or-marker &rest numbers-or-markers +This function returns the smallest of its arguments. +If any of the arguments is floating-point, the value is returned +as floating point, even if it was given as an integer. + +@example +(min -4 1) + @result{} -4 +@end example +@end defun + +@defun abs number +This function returns the absolute value of @var{number}. +@end defun + +@node Numeric Conversions +@section Numeric Conversions +@cindex rounding in conversions +@cindex number conversions +@cindex converting numbers + +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. All accept an argument @var{number} +and an optional argument @var{divisor}. Both arguments may be +integers or floating point numbers. @var{divisor} may also be +@code{nil}. If @var{divisor} is @code{nil} or omitted, these +functions convert @var{number} to an integer, or return it unchanged +if it already is an integer. If @var{divisor} is non-@code{nil}, they +divide @var{number} by @var{divisor} and convert the result to an +integer. An @code{arith-error} results if @var{divisor} is 0. + +@defun truncate number &optional divisor +This returns @var{number}, converted to an integer by rounding towards +zero. + +@example +(truncate 1.2) + @result{} 1 +(truncate 1.7) + @result{} 1 +(truncate -1.2) + @result{} -1 +(truncate -1.7) + @result{} -1 +@end example +@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, this uses the kind of division +operation that corresponds to @code{mod}, rounding downward. + +@example +(floor 1.2) + @result{} 1 +(floor 1.7) + @result{} 1 +(floor -1.2) + @result{} -2 +(floor -1.7) + @result{} -2 +(floor 5.99 3) + @result{} 1 +@end example +@end defun + +@defun ceiling number &optional divisor +This returns @var{number}, converted to an integer by rounding upward +(towards positive infinity). + +@example +(ceiling 1.2) + @result{} 2 +(ceiling 1.7) + @result{} 2 +(ceiling -1.2) + @result{} -1 +(ceiling -1.7) + @result{} -1 +@end example +@end defun + +@defun round number &optional divisor +This returns @var{number}, converted to an integer by rounding towards the +nearest integer. Rounding a value equidistant between two integers +may choose the integer closer to zero, or it may prefer an even integer, +depending on your machine. + +@example +(round 1.2) + @result{} 1 +(round 1.7) + @result{} 2 +(round -1.2) + @result{} -1 +(round -1.7) + @result{} -2 +@end example +@end defun + +@node Arithmetic Operations +@section Arithmetic Operations +@cindex 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 Emacs Lisp, arithmetic functions +do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to +@minus{}268435456, 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, if we continue, + +@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 + &rest numbers-or-markers +This function adds its arguments together. When given no arguments, +@code{+} returns 0. + +@example +(+) + @result{} 0 +(+ 1) + @result{} 1 +(+ 1 2 3 4) + @result{} 10 +@end example +@end defun + +@defun - &optional number-or-marker &rest more-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{more-numbers-or-markers} from @var{number-or-marker}, +cumulatively. If there are no arguments, the result is 0. + +@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. + +@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{divisor} 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 an integer by 0, an @code{arith-error} error is signaled. +(@xref{Errors}.) Floating point division by zero returns either +infinity or a NaN if your machine supports @acronym{IEEE} floating point; +otherwise, it signals an @code{arith-error} error. + +@example +@group +(/ 6 2) + @result{} 3 +@end group +(/ 5 2) + @result{} 2 +(/ 5.0 2) + @result{} 2.5 +(/ 5 2.0) + @result{} 2.5 +(/ 5.0 2.0) + @result{} 2.5 +(/ 25 3 2) + @result{} 4 +@group +(/ -17 6) + @result{} -2 @r{(could in theory be @minus{}3 on some machines)} +@end group +@end example +@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 +@group +(mod 9 4) + @result{} 1 +@end group +@group +(mod -9 4) + @result{} 3 +@end group +@group +(mod 9 -4) + @result{} -3 +@end group +@group +(mod -9 -4) + @result{} -1 +@end group +@group +(mod 5.5 2.5) + @result{} .5 +@end group +@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. For @code{floor}, see @ref{Numeric +Conversions}. +@end defun + +@node Rounding Operations +@section Rounding Operations +@cindex rounding without conversion + +The functions @code{ffloor}, @code{fceiling}, @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{fceiling}, the nearest integer above; +@code{ftruncate}, 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 fceiling float +This function rounds @var{float} to the next higher integral value, and +returns that value as a floating point number. +@end defun + +@defun ftruncate 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 +@cindex bitwise arithmetic +@cindex logical arithmetic + + 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, bringing zeros into the vacated bits. If +@var{count} is negative, @code{lsh} shifts zeros into the leftmost +(most-significant) bit, producing a positive result even if +@var{integer1} is negative. Contrast this with @code{ash}, below. + +Here are two examples of @code{lsh}, shifting a pattern of bits one +place to the left. We 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. + +Shifting a 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 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 one place to the right divides the +value of a positive integer by two, rounding downward. + +The function @code{lsh}, like all Emacs Lisp arithmetic functions, does +not check for overflow, so shifting left can discard significant bits +and change the sign of the number. For example, left shifting +268,435,455 produces @minus{}2 on a 29-bit machine: + +@example +(lsh 268435455 1) ; @r{left shift} + @result{} -2 +@end example + +In binary, in the 29-bit implementation, the argument looks like this: + +@example +@group +;; @r{Decimal 268,435,455} +0 1111 1111 1111 1111 1111 1111 1111 +@end group +@end example + +@noindent +which becomes the following when left shifted: + +@example +@group +;; @r{Decimal @minus{}2} +1 1111 1111 1111 1111 1111 1111 1110 +@end group +@end example +@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 ones in the empty bit positions on the left, while +@code{lsh} puts zeros in those bit positions. + +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.} +1 1111 1111 1111 1111 1111 1111 1010 + @result{} +1 1111 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{} 268435453 +;; @r{Decimal @minus{}6 becomes decimal 268,435,453.} +1 1111 1111 1111 1111 1111 1111 1010 + @result{} +0 1111 1111 1111 1111 1111 1111 1101 +@end group +@end example + +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{ 29-bit binary values} + +(lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} + @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100} +@end group +@group +(ash 5 2) + @result{} 20 +(lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} + @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100} +(ash -5 2) + @result{} -20 +@end group +@group +(lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} + @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001} +@end group +@group +(ash 5 -2) + @result{} 1 +@end group +@group +(lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} + @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110} +@end group +@group +(ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} + @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110} +@end group +@end smallexample +@end defun + +@defun logand &rest ints-or-markers +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{ 29-bit binary values} + +(logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} + ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} + @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} +@end group + +@group +(logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} + ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} + ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} + @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} +@end group + +@group +(logand) + @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111} +@end group +@end smallexample +@end defun + +@defun logior &rest ints-or-markers +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{ 29-bit binary values} + +(logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} + ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} + @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} +@end group + +@group +(logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} + ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} + ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} + @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111} +@end group +@end smallexample +@end defun + +@defun logxor &rest ints-or-markers +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, which is an identity element for this operation. If +@code{logxor} is passed just one argument, it returns that argument. + +@smallexample +@group + ; @r{ 29-bit binary values} + +(logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} + ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} + @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001} +@end group + +@group +(logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} + ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} + ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} + @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} +@end group +@end smallexample +@end defun + +@defun lognot integer +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{0 0000 0000 0000 0000 0000 0000 0101} +;; @r{becomes} +;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010} +@end example +@end defun + +@node Math Functions +@section Standard Mathematical Functions +@cindex transcendental functions +@cindex mathematical functions +@cindex floating-point functions + + These mathematical functions 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 +@ifnottex +@minus{}pi/2 +@end ifnottex +@tex +@math{-\pi/2} +@end tex +and +@ifnottex +pi/2 +@end ifnottex +@tex +@math{\pi/2} +@end tex +(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of +range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. +@end defun + +@defun acos arg +The value of @code{(acos @var{arg})} is a number between 0 and +@ifnottex +pi +@end ifnottex +@tex +@math{\pi} +@end tex +(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out +of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. +@end defun + +@defun atan y &optional x +The value of @code{(atan @var{y})} is a number between +@ifnottex +@minus{}pi/2 +@end ifnottex +@tex +@math{-\pi/2} +@end tex +and +@ifnottex +pi/2 +@end ifnottex +@tex +@math{\pi/2} +@end tex +(exclusive) whose tangent is @var{y}. If the optional second +argument @var{x} is given, the value of @code{(atan y x)} is the +angle in radians between the vector @code{[@var{x}, @var{y}]} and the +@code{X} axis. +@end defun + +@defun exp arg +This is the exponential function; it returns +@tex +@math{e} +@end tex +@ifnottex +@i{e} +@end ifnottex +to the power @var{arg}. +@tex +@math{e} +@end tex +@ifnottex +@i{e} +@end ifnottex +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 +@tex +@math{e} +@end tex +@ifnottex +@i{e} +@end ifnottex +is used. If @var{arg} is negative, it signals a @code{domain-error} +error. +@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, it signals a @code{domain-error} error. +@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least +approximately. +@end defun + +@defun expt x y +This function returns @var{x} raised to power @var{y}. If both +arguments are integers and @var{y} is positive, the result is an +integer; in this case, overflow causes truncation, so watch out. +@end defun + +@defun sqrt arg +This returns the square root of @var{arg}. If @var{arg} is negative, +it signals a @code{domain-error} error. +@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 +@minus{}1457731, and the second one always returns @minus{}7692030. This +repeatability is helpful for debugging. + +If you want random numbers that don't always come out the same, execute +@code{(random t)}. This chooses a new seed based on the current time of +day and on Emacs's process @acronym{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 a positive integer, the value is chosen to be +nonnegative and less than @var{limit}. + +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 @acronym{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 + +@ignore + arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e +@end ignore