@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/numbers.info
@node Numbers, Strings and Characters, Lisp Data Types, Top
The range of values for an integer depends on the machine. The
minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
-@ifinfo
+@ifinfo
-2**27
@end ifinfo
-@tex
+@tex
$-2^{27}$
@end tex
-to
-@ifinfo
+to
+@ifinfo
2**27 - 1),
@end ifinfo
-@tex
+@tex
$2^{27}-1$),
@end tex
but some machines may provide a wider range. Many examples in this
do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
@minus{}134217728, depending on your hardware.
-@defun 1+ number-or-marker
-This function returns @var{number-or-marker} plus 1.
+@defun 1+ number
+This function returns @var{number} plus one. @var{number} may be a
+number, character or marker. Markers and characters are converted to
+integers.
+
For example,
@example
@w{@code{(incf foo)}}.
@end defun
-@defun 1- number-or-marker
-This function returns @var{number-or-marker} minus 1.
+@defun 1- number
+This function returns @var{number} minus one. @var{number} may be a
+number, character or marker. Markers and characters are converted to
+integers.
@end defun
@defun abs number
This returns the absolute value of @var{number}.
@end defun
-@defun + &rest numbers-or-markers
+@defun + &rest numbers
This function adds its arguments together. When given no arguments,
@code{+} returns 0.
+If any of the arguments are characters or markers, they are first
+converted to integers.
+
@example
(+)
@result{} 0
@end example
@end defun
-@defun - &optional number-or-marker &rest other-numbers-or-markers
+@defun - &optional number &rest other-numbers
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.
+the @var{other-numbers} from @var{number}, cumulatively. If there are
+no arguments, an error is signaled.
+
+If any of the arguments are characters or markers, they are first
+converted to integers.
@example
(- 10 1 2 3 4)
@end example
@end defun
-@defun * &rest numbers-or-markers
+@defun * &rest numbers
This function multiplies its arguments together, and returns the
product. When given no arguments, @code{*} returns 1.
+If any of the arguments are characters or markers, they are first
+converted to integers.
+
@example
(*)
@result{} 1
@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.
+@defun / dividend &rest divisors
+The @code{/} function serves two purposes: inversion and division. When
+@code{/} has a single argument, the value is the inverse of the
+argument. When there are multiple arguments, @code{/} divides
+@var{dividend} by each of the @var{divisors}, cumulatively, returning
+the quotient. If there are no arguments, an error is signaled.
-If all the arguments are integers, then the result is an integer too.
+If none of the arguments are floats, then the result is an integer.
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
permits machine-dependent rounding. As a practical matter, all known
machines round in the standard fashion.
+If any of the arguments are characters or markers, they are first
+converted to integers.
+
@cindex @code{arith-error} in division
If you divide by 0, an @code{arith-error} error is signaled.
(@xref{Errors}.)
@result{} 2
(/ 25 3 2)
@result{} 4
+(/ 3.0)
+ @result{} 0.3333333333333333
(/ -17 6)
@result{} -2
@end example
@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
+@defun ffloor number
+This function rounds @var{number} 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
+@defun fceiling number
+This function rounds @var{number} 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
+@defun ftruncate number
+This function rounds @var{number} 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,
+@defun fround number
+This function rounds @var{number} to the nearest integral value,
and returns that value as a floating point number.
@end defun
(lsh 3 2)
@result{} 12
;; @r{Decimal 3 becomes decimal 12.}
-00000011 @result{} 00001100
+00000011 @result{} 00001100
@end group
@end example
(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
@example
@group
;; @r{Decimal 134,217,727}
-0111 1111 1111 1111 1111 1111 1111
+0111 1111 1111 1111 1111 1111 1111
@end group
@end example
@example
@group
;; @r{Decimal @minus{}2}
-1111 1111 1111 1111 1111 1111 1110
+1111 1111 1111 1111 1111 1111 1110
@end group
@end example
@end defun
@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{}
+ @result{}
1111 1111 1111 1111 1111 1111 1101
@end group
@end example
(lsh -6 -1) @result{} 134217725
;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
1111 1111 1111 1111 1111 1111 1010
- @result{}
+ @result{}
0111 1111 1111 1111 1111 1111 1101
@end group
@end example
@var{integer}, and vice-versa.
@example
-(lognot 5)
+(lognot 5)
@result{} -6
;; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
;; @r{becomes}
supported (which is the normal state of affairs). They allow integers
as well as floating point numbers as arguments.
-@defun sin arg
-@defunx cos arg
-@defunx tan arg
+@defun sin number
+@defunx cos number
+@defunx tan number
These are the ordinary trigonometric functions, with argument measured
in radians.
@end defun
-@defun asin arg
-The value of @code{(asin @var{arg})} is a number between @minus{}pi/2
-and pi/2 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
+@defun asin number
+The value of @code{(asin @var{number})} is a number between @minus{}pi/2
+and pi/2 (inclusive) whose sine is @var{number}; if, however, @var{number}
is out of range (outside [-1, 1]), then the result is a NaN.
@end defun
-@defun acos arg
-The value of @code{(acos @var{arg})} is a number between 0 and pi
-(inclusive) whose cosine is @var{arg}; if, however, @var{arg}
+@defun acos number
+The value of @code{(acos @var{number})} is a number between 0 and pi
+(inclusive) whose cosine is @var{number}; if, however, @var{number}
is out of range (outside [-1, 1]), then the result is a NaN.
@end defun
-@defun atan arg
-The value of @code{(atan @var{arg})} is a number between @minus{}pi/2
-and pi/2 (exclusive) whose tangent is @var{arg}.
+@defun atan number &optional number2
+The value of @code{(atan @var{number})} is a number between @minus{}pi/2
+and pi/2 (exclusive) whose tangent is @var{number}.
+
+If optional argument @var{number2} is supplied, the function returns
+@code{atan2(@var{number},@var{number2})}.
@end defun
-@defun sinh arg
-@defunx cosh arg
-@defunx tanh arg
+@defun sinh number
+@defunx cosh number
+@defunx tanh number
These are the ordinary hyperbolic trigonometric functions.
@end defun
-@defun asinh arg
-@defunx acosh arg
-@defunx atanh arg
+@defun asinh number
+@defunx acosh number
+@defunx atanh number
These are the inverse hyperbolic trigonometric functions.
@end defun
-@defun exp arg
+@defun exp number
This is the exponential function; it returns @i{e} to the power
-@var{arg}. @i{e} is a fundamental mathematical constant also called the
+@var{number}. @i{e} is a fundamental mathematical constant also called the
base of natural logarithms.
@end defun
-@defun log arg &optional base
-This function returns the logarithm of @var{arg}, with base @var{base}.
-If you don't specify @var{base}, the base @var{e} is used. If @var{arg}
+@defun log number &optional base
+This function returns the logarithm of @var{number}, with base @var{base}.
+If you don't specify @var{base}, the base @code{e} is used. If @var{number}
is negative, the result is a NaN.
@end defun
-@ignore
-@defun expm1 arg
-This function returns @code{(1- (exp @var{arg}))}, but it is more
-accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
-is close to 1.
-@end defun
-
-@defun log1p arg
-This function returns @code{(log (1+ @var{arg}))}, but it is more
-accurate than that when @var{arg} is so small that adding 1 to it would
-lose accuracy.
-@end defun
-@end ignore
-
-@defun log10 arg
-This function returns the logarithm of @var{arg}, with base 10. If
-@var{arg} is negative, the result is a NaN. @code{(log10 @var{x})}
+@defun log10 number
+This function returns the logarithm of @var{number}, with base 10. If
+@var{number} is negative, the result is a NaN. @code{(log10 @var{x})}
@equiv{} @code{(log @var{x} 10)}, at least approximately.
@end defun
integer values.
@end defun
-@defun sqrt arg
-This returns the square root of @var{arg}. If @var{arg} is negative,
+@defun sqrt number
+This returns the square root of @var{number}. If @var{number} is negative,
the value is a NaN.
@end defun
-@defun cube-root arg
-This returns the cube root of @var{arg}.
+@defun cube-root number
+This returns the cube root of @var{number}.
@end defun
@node Random Numbers