X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/94b00316b8909d64003a181b76c98c6210c139ad..8e7a9a24c7ad18e977c85607775a1da53b2bd4d8:/lispref/numbers.texi diff --git a/lispref/numbers.texi b/lispref/numbers.texi index 6bcd9b1c6c..3cbc1a7ae1 100644 --- a/lispref/numbers.texi +++ b/lispref/numbers.texi @@ -1,6 +1,7 @@ @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 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005, 2006 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 @@ -12,15 +13,11 @@ @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 is multiplied by 1.5. Floating point values are not +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. - 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. @@ -30,7 +27,7 @@ where Emacs does not support them. * 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. +* Math Functions:: Trig, exponential and logarithmic functions. * Random Numbers:: Obtaining random integers, predictable or not. @end menu @@ -39,22 +36,22 @@ where Emacs does not support them. @section Integer Basics The range of values for an integer depends on the machine. The -minimum range is @minus{}134217728 to 134217727 (28 bits; i.e., -@ifinfo --2**27 -@end ifinfo -@tex -$-2^{27}$ +minimum range is @minus{}268435456 to 268435455 (29 bits; i.e., +@ifnottex +-2**28 +@end ifnottex +@tex +@math{-2^{28}} @end tex -to -@ifinfo -2**27 - 1), -@end ifinfo -@tex -$2^{27}-1$), +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 28 bits. +chapter assume an integer has 29 bits. @cindex overflow The Lisp reader reads an integer as a sequence of digits with optional @@ -65,19 +62,41 @@ initial sign and optional final period. 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 268435457 ; @r{Also the integer 1, due to overflow.} + 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 28-bit binary, the decimal integer 5 looks like this: + In 29-bit binary, the decimal integer 5 looks like this: @example -0000 0000 0000 0000 0000 0000 0101 +0 0000 0000 0000 0000 0000 0000 0101 @end example @noindent @@ -87,12 +106,12 @@ 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 1111 +1 1111 1111 1111 1111 1111 1111 1111 @end example @noindent @cindex two's complement -@minus{}1 is represented as 28 ones. (This is called @dfn{two's +@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 @@ -100,70 +119,90 @@ complement} notation.) @minus{}5 looks like this: @example -1111 1111 1111 1111 1111 1111 1011 +1 1111 1111 1111 1111 1111 1111 1011 @end example - In this implementation, the largest 28-bit binary integer is the -decimal integer 134,217,727. In binary, it looks like this: + In this implementation, the largest 29-bit binary integer value is +268,435,455 in decimal. In binary, it looks like this: @example -0111 1111 1111 1111 1111 1111 1111 +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 134,217,727, the value is the -negative integer @minus{}134,217,728: +outside their range, when you add 1 to 268,435,455, the value is the +negative integer @minus{}268,435,456: @example -(+ 1 134217727) - @result{} -134217728 - @result{} 1000 0000 0000 0000 0000 0000 0000 +(+ 1 268435455) + @result{} -268435456 + @result{} 1 0000 0000 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 + 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. -@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 +@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 -@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 + 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 IEEE floating point standard, which -provides for positive infinity and negative infinity as floating point + 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{(sqrt -1.0)} returns a +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 this manual -doesn't try to distinguish them. Emacs Lisp has no read syntax for NaNs -or infinities; perhaps we should create a syntax in the future. +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): @@ -172,18 +211,24 @@ point number (or estimate the logarithm of an integer): 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 - 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}. + 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 @@ -217,7 +262,7 @@ considered non-negative. 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)}. +@code{(zerop x)} is equivalent to @code{(= x 0)}. @end defun @node Comparison of Numbers @@ -232,7 +277,7 @@ compare them, then you test whether two values are the same of the objects. At present, each integer value has a unique Lisp object in Emacs Lisp. -Therefore, @code{eq} is equivalent @code{=} where integers are +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 @@ -241,6 +286,12 @@ 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. @@ -249,9 +300,10 @@ 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)) + (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} @@ -268,6 +320,13 @@ 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 numberic 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. @@ -298,6 +357,8 @@ otherwise. @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) @@ -305,12 +366,14 @@ This function returns the largest of its arguments. (max 1 2.5) @result{} 2.5 (max 1 3 2.5) - @result{} 3 + @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) @@ -318,6 +381,10 @@ This function returns the smallest of its arguments. @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 @@ -331,32 +398,84 @@ 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 +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, @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. +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 +@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 +@defun round number &optional divisor This returns @var{number}, converted to an integer by rounding towards the -nearest integer. +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 @@ -371,9 +490,9 @@ 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. + 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. @@ -386,8 +505,8 @@ For example, @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, +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 @@ -407,13 +526,9 @@ like this: 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. +@code{+} returns 0. @example (+) @@ -425,13 +540,12 @@ This function adds its arguments together. When given no arguments, @end example @end defun -@defun - &optional number-or-marker &rest other-numbers-or-markers +@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{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. +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) @@ -445,8 +559,7 @@ function does not check for overflow. @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. +product. When given no arguments, @code{*} returns 1. @example (*) @@ -473,14 +586,24 @@ 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}.) +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 (/ -17 6) @@ -540,16 +663,26 @@ 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}, @@ -562,15 +695,16 @@ For any two numbers @var{dividend} and @var{divisor}, @end example @noindent -always equals @var{dividend}, subject to rounding error if -either argument is floating point. +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 +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; @@ -640,36 +774,7 @@ 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. -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 8,388,607 -produces @minus{}2 on a 24-bit machine: - -@example -(lsh 8388607 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, in the 28-bit implementation, the argument looks like this: - -@example -@group -;; @r{Decimal 134.217,727} -0111 1111 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 1111 1110 -@end group -@end example - -Shifting the pattern of bits two places to the left produces results +Shifting a pattern of bits two places to the left produces results like this (with 8-bit binary numbers): @example @@ -677,32 +782,60 @@ like this (with 8-bit binary numbers): (lsh 3 2) @result{} 12 ;; @r{Decimal 3 becomes decimal 12.} -00000011 @result{} 00001100 +00000011 @result{} 00001100 @end group @end example -On the other hand, shifting the pattern of bits one place to the right -looks like this: +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 +00000110 @result{} 00000011 @end group @group (lsh 5 -1) @result{} 2 ;; @r{Decimal 5 becomes decimal 2.} -00000101 @result{} 00000010 +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 -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. +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 @@ -713,19 +846,19 @@ 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. +@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 +(ash -6 -1) @result{} -3 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1111 1111 1111 1111 1111 1111 1010 - @result{} -1111 1111 1111 1111 1111 1111 1101 +1 1111 1111 1111 1111 1111 1111 1010 + @result{} +1 1111 1111 1111 1111 1111 1111 1101 @end group @end example @@ -734,11 +867,11 @@ In contrast, shifting the pattern of bits one place to the right with @example @group -(lsh -6 -1) @result{} 134217725 -;; @r{Decimal @minus{}6 becomes decimal 134,217,725.} -1111 1111 1111 1111 1111 1111 1010 - @result{} -0111 1111 1111 1111 1111 1111 1101 +(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 @@ -748,34 +881,34 @@ Here are other examples: @c with smallbook but not with regular book! --rjc 16mar92 @smallexample @group - ; @r{ 28-bit binary values} + ; @r{ 29-bit binary values} -(lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100} +(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{1111 1111 1111 1111 1111 1111 1011} - @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100} +(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{0000 0000 0000 0000 0000 0000 0101} - @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001} +(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{1111 1111 1111 1111 1111 1111 1011} - @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110} +(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{1111 1111 1111 1111 1111 1111 1011} - @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110} +(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 @@ -812,23 +945,23 @@ because its binary representation consists entirely of ones. If @smallexample @group - ; @r{ 28-bit binary values} + ; @r{ 29-bit binary values} -(logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} - ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} - @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} +(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{0000 0000 0000 0000 0000 0000 1110} - ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} - ; 4 = @r{0000 0000 0000 0000 0000 0000 0100} - @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100} +(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{1111 1111 1111 1111 1111 1111 1111} + @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111} @end group @end smallexample @end defun @@ -844,18 +977,18 @@ passed just one argument, it returns that argument. @smallexample @group - ; @r{ 28-bit binary values} + ; @r{ 29-bit binary values} -(logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} +(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{0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - ; 7 = @r{0000 0000 0000 0000 0000 0000 0111} - @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111} +(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 @@ -871,18 +1004,18 @@ result is 0, which is an identity element for this operation. If @smallexample @group - ; @r{ 28-bit binary values} + ; @r{ 29-bit binary values} -(logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001} +(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{0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - ; 7 = @r{0000 0000 0000 0000 0000 0000 0111} - @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} +(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 @@ -895,22 +1028,21 @@ 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) +(lognot 5) @result{} -6 -;; 5 = @r{0000 0000 0000 0000 0000 0000 0101} +;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} ;; @r{becomes} -;; -6 = @r{1111 1111 1111 1111 1111 1111 1010} +;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010} @end example @end defun -@node Transcendental Functions -@section Transcendental Functions +@node Math Functions +@section Standard Mathematical 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. + These mathematical functions allow integers as well as floating point +numbers as arguments. @defun sin arg @defunx cos arg @@ -920,32 +1052,87 @@ 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. +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 [-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 pi -(inclusive) whose cosine is @var{arg}; if, however, @var{arg} -is out of range (outside [-1, 1]), then the result is a NaN. +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 [-1, 1]), it signals a @code{domain-error} error. @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}. +@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 @i{e} to the power -@var{arg}. @i{e} is a fundamental mathematical constant also called the -base of natural logarithms. +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 @var{e} is used. If @var{arg} -is negative, the result is a NaN. +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 @@ -964,20 +1151,20 @@ lose accuracy. @defun log10 arg This function returns the logarithm of @var{arg}, with base 10. If -@var{arg} is negative, the result is a NaN. @code{(log10 @var{x})} -@equiv{} @code{(log @var{x} 10)}, at least approximately. +@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, it is truncated to fit the range of possible -integer values. +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, -the value is a NaN. +it signals a @code{domain-error} error. @end defun @node Random Numbers @@ -1000,23 +1187,26 @@ 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. +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 @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 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 @sc{id} number. +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