@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 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
+@node Numbers, Strings and Characters, Lisp Data Types, Top
@chapter Numbers
@cindex integers
@cindex numbers
@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
+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.
* 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
@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}$
+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**23 - 1)
-@end ifinfo
-@tex
-$2^{23}-1$)
+to
+@ifnottex
+2**28 - 1),
+@end ifnottex
+@tex
+@math{2^{28}-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.
+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
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.}
+ 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 24 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 0101
+0 0000 0000 0000 0000 0000 0000 0101
@end example
@noindent
The integer @minus{}1 looks like this:
@example
-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 24 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
@minus{}5 looks like this:
@example
-1111 1111 1111 1111 1111 1011
+1 1111 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:
+ 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
+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 8,388,607, the value is negative
-integer @minus{}8,388,608:
+outside their range, when you add 1 to 268,435,455, the value is the
+negative integer @minus{}268,435,456:
@example
-(+ 1 8388607)
- @result{} -8388608
- @result{} 1000 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
-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.
+ 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):
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
floating point), and returns @code{t} if so, @code{nil} otherwise.
@end defun
-@defun natnump object
+@defun wholenump 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
+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.
-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.
+@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.
-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
@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.
+ 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
@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}
@quotation
-@b{Common Lisp note:} comparing numbers in Common Lisp always requires
+@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
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.
@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)
(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)
@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
@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
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.
@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
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
(+)
@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)
@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
(*)
@end defun
@defun / dividend divisor &rest divisors
-This function divides @var{dividend} by @var{divisors} and returns the
+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.
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)
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},
@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{fceil}, @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{fceil}, the nearest integer above;
-@code{ftrucate}, the nearest integer in the direction towards zero;
+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
returns that value as a floating point number.
@end defun
-@defun fceil float
+@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 ftrunc float
+@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 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.)
+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
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
+Shifting a pattern of bits two places to the left produces results
like this (with 8-bit binary numbers):
@example
(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
@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 1010
- @result{}
-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
@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
+(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
-@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}
+ ; @r{ 29-bit binary values}
-(lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0101}
- @result{} 20 ; 20 = @r{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 1011}
- @result{} -20 ; -20 = @r{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 0101}
- @result{} 1 ; 1 = @r{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 1011}
- @result{} 4194302 ; @r{0011 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 1011}
- @result{} -2 ; -2 = @r{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
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
@smallexample
@group
- ; @r{ 24-bit binary values}
+ ; @r{ 29-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}
+(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 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}
+(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}
+ @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111}
@end group
@end smallexample
@end defun
@smallexample
@group
- ; @r{ 24-bit binary values}
+ ; @r{ 29-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}
+(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 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}
+(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
@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.
+@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{ 24-bit binary values}
+ ; @r{ 29-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}
+(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 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}
+(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
@var{integer}, and vice-versa.
@example
-(lognot 5)
+(lognot 5)
@result{} -6
-;; 5 = @r{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 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
@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
@defun log10 arg
This function returns the logarithm of @var{arg}, with base 10. If
-@var{arg} is negative, the result is a NaN.
+@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}.
+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,
-the value is a NaN.
+it signals a @code{domain-error} error.
@end defun
@node Random Numbers
-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
HCoop / bpt / emacs.git / blobdiff