@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 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
@c @chapter Numbers
@chapter $B?t(B
@c @cindex integers
@c @cindex numbers
@cindex $B@0?t(B
@cindex $B?t(B

@c   GNU Emacs supports two numeric data types: @dfn{integers} and
@c @dfn{floating point numbers}.  Integers are whole numbers such as
@c @minus{}3, 0, 7, 13, and 511.  Their values are exact.  Floating point
@c numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
@c 2.71828.  They can also be expressed in exponential notation: 1.5e2
@c equals 150; in this example, @samp{e2} stands for ten to the second
@c power, and that is multiplied by 1.5.  Floating point values are not
@c exact; they have a fixed, limited amount of precision.
GNU Emacs$B$G$O(B2$B<oN`$N?tCM%G!<%?$r07$($^$9!#(B
@dfn{$B@0?t(B}$B!J(Bintegers$B!K$H(B@dfn{$BIbF0>.?tE@?t(B}$B!J(Bfloating point numbers$B!K$G$9!#(B
$B@0?t$O!"(B@minus{}3$B!"(B0$B!"(B7$B!"(B13$B!"(B511$B$N$h$&$J$A$g$&$I$N?t$G$9!#(B
$B$3$l$i$NCM$O@53N$G$9!#(B
$BIbF0>.?tE@?t$O!"(B@minus{}4.5$B!"(B0.0$B!"(B2.71828$B$N$h$&$K>.?tIt$,$"$k?t$G$9!#(B
$B$3$l$i$O;X?tI=5-$GI=$7$^$9!#(B
$B$?$H$($P!"(B1.5e2$B$O(B150$B$KEy$7$$$N$G$9!#(B
$B$3$NNc$N(B@samp{e2}$B$O(B10$B$N(B2$B>h$rI=$7!"$=$l$r(B1.5$BG\$7$^$9!#(B
$BIbF0>.?tE@?t$NCM$O87L)$G$O$"$j$^$;$s!#(B
$B$3$l$i$N@:EY$K$ODj$^$C$?8B3&$,$"$j$^$9!#(B

@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
@c @section Integer Basics
@section $B@0?t$N4pK\(B

@c   The range of values for an integer depends on the machine.  The
@c minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
$B@0?t$NCM$NHO0O$O7W;;5!$K0MB8$7$^$9!#(B
$B:G>.$NHO0O$O!"(B@minus{}134217728$B$+$i(B134217727$B$^$G!J(B28$B%S%C%HD9!"$D$^$j(B
@ifinfo 
-2**27
@end ifinfo
@tex 
$-2^{27}$
@end tex
@c to 
$B$+$i(B
@ifinfo 
@c 2**27 - 1),
2**27 - 1$B!K$G$9$,!"(B
@end ifinfo
@tex 
%c $2^{27}-1$),
$2^{27}-1$$B!K$G$9$,!"(B
@end tex
@c but some machines may provide a wider range.  Many examples in this
@c chapter assume an integer has 28 bits.
$B$3$l$h$j9-$$HO0O$r07$($k7W;;5!$b$"$j$^$9!#(B
$BK\>O$NB?$/$NNcBj$G$O!"@0?t$O(B28$BD9%S%C%H$G$"$k$H2>Dj$7$^$9!#(B
@c @cindex overflow
@cindex $B7e0n$l(B
@cindex $B%*!<%P%U%m!<(B

@c   The Lisp reader reads an integer as a sequence of digits with optional
@c initial sign and optional final period.
Lisp$B%j!<%@$O!"(B
$B@hF,$KId9f$,$"$C$F$b$h$/!":G8e$K%T%j%*%I$,$"$C$F$b$h$$!"(B
$B?t;z$NNs$H$7$F@0?t$rFI$_<h$j$^$9!#(B

@example
@c  1               ; @r{The integer 1.}
@c  1.              ; @r{The integer 1.}
@c +1               ; @r{Also the integer 1.}
@c -1               ; @r{The integer @minus{}1.}
@c  268435457       ; @r{Also the integer 1, due to overflow.}
@c  0               ; @r{The integer 0.}
@c -0               ; @r{The integer 0.}
 1               ; @r{$B@0?t(B1}
 1.              ; @r{$B@0?t(B1}
+1               ; @r{$B$3$l$b@0?t(B1}
-1               ; @r{$B@0?t(B@minus{}1}
 268435457       ; @r{$B7e0n$l$N$?$a!"$3$l$b@0?t(B1}
 0               ; @r{$B@0?t(B0}
-0               ; @r{$B@0?t(B0}
@end example

@c   To understand how various functions work on integers, especially the
@c bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
@c view the numbers in their binary form.
$B@0?t$r07$&$5$^$6$^$J4X?t$rM}2r$9$k$K$O!"(B
$BFC$K%S%C%H1i;;!J(B@pxref{Bitwise Operations}$B!K$rM}2r$9$k$K$O!"(B
$B?t$r(B2$B?JI=8=$G9M$($k$H$h$$$G$9!#(B

@c   In 28-bit binary, the decimal integer 5 looks like this:
28$B%S%C%HD9$N(B2$B?JI=8=$G$O!"(B10$B?J@0?t(B5$B$O$D$.$N$h$&$K$J$j$^$9!#(B

@example
0000  0000 0000  0000 0000  0000 0101
@end example

@noindent
@c (We have inserted spaces between groups of 4 bits, and two spaces
@c between groups of 8 bits, to make the binary integer easier to read.)
$B!J(B4$B%S%C%H$N$^$H$^$j$4$H$K6uGr$r(B1$B8D!"(B
8$B%S%C%H$N$^$H$^$j$4$H$K6uGr$r(B2$B8DA^F~$7$F!"FI$_$d$9$/$9$k!#!K(B

@c   The integer @minus{}1 looks like this:
$B@0?t(B@minus{}1$B$O$D$.$N$h$&$K$J$j$^$9!#(B

@example
1111  1111 1111  1111 1111  1111 1111
@end example

@noindent
@c @cindex two's complement
@cindex 2$B$NJd?t(B
@c @minus{}1 is represented as 28 ones.  (This is called @dfn{two's
@c complement} notation.)
@minus{}1$B$O!"(B28$B8D$N(B1$B$GI=8=$5$l$^$9!#(B
$B!J$3$l$r(B@dfn{2$B$NJd?t(B}$B!J(Btwo's complement$B!KI=5-$H8F$V!#!K(B

@c   The negative integer, @minus{}5, is creating by subtracting 4 from
@c @minus{}1.  In binary, the decimal integer 4 is 100.  Consequently,
@c @minus{}5 looks like this:
$BIi$N?t(B@minus{}5$B$O!"(B@minus{}1$B$+$i(B4$B$r0z$$$F:n$l$^$9!#(B
10$B?J?t(B4$B$O!"(B2$B?JI=5-$G$O(B100$B$G$9!#(B
$B$7$?$,$C$F!"(B@minus{}5$B$O!"$D$.$N$h$&$K$J$j$^$9!#(B

@example
1111  1111 1111  1111 1111  1111 1011
@end example

@c   In this implementation, the largest 28-bit binary integer value is
@c 134,217,727 in decimal.  In binary, it looks like this:
$B$3$N<BAu$G$O!"(B28$B%S%C%HD9$N(B2$B?J@0?t$N:GBgCM$O!"(B
10$B?J$G(B134,217,727$B$K$J$j$^$9!#(B
2$B?JI=5-$G$O!"$D$.$N$h$&$K$J$j$^$9!#(B

@example
0111  1111 1111  1111 1111  1111 1111
@end example

@c   Since the arithmetic functions do not check whether integers go
@c outside their range, when you add 1 to 134,217,727, the value is the
@c negative integer @minus{}134,217,728:
$B;;=Q4X?t$O!"@0?t$,$=$NHO0O30$K=P$?$+$I$&$+8!::$7$J$$$N$G!"(B
134,217,727$B$K(B1$B$rB-$9$H!"CM$OIi$N?t(B@minus{}134,217,728$B$K$J$j$^$9!#(B

@example
(+ 1 134217727)
     @result{} -134217728
     @result{} 1000  0000 0000  0000 0000  0000 0000
@end example

@c   Many of the functions described in this chapter accept markers for
@c arguments in place of numbers.  (@xref{Markers}.)  Since the actual
@c arguments to such functions may be either numbers or markers, we often
@c give these arguments the name @var{number-or-marker}.  When the argument
@c value is a marker, its position value is used and its buffer is ignored.
$BK\>O$G=R$Y$kB?$/$N4X?t$O!"?t$N0z?t$H$7$F%^!<%+$r<u$1IU$1$^$9!#(B
$B!J(B@pxref{Markers}$B!K!#(B
$B$=$N$h$&$J4X?t$N<B:]$N0z?t$O?t$+%^!<%+$G$"$k$N$G!"(B
$B$=$l$i$N0z?t$r$7$P$7$P(B@var{number-or-marker}$B$H$$$&L>A0$G=q$-$^$9!#(B
$B0z?t$NCM$,%^!<%+$G$"$k$H$-$K$O!"$=$N0LCV$NCM$r;H$$%P%C%U%!$OL5;k$7$^$9!#(B

@node Float Basics
@c @section Floating Point Basics
@section $BIbF0>.?tE@?t$N4pK\(B

@c   Floating point numbers are useful for representing numbers that are
@c not integral.  The precise range of floating point numbers is
@c machine-specific; it is the same as the range of the C data type
@c @code{double} on the machine you are using.
$BIbF0>.?tE@?t$O!"@0?t$G$O$J$$?t$rI=8=$9$k$N$KJXMx$G$9!#(B
$BIbF0>.?tE@?t$N@53N$JHO0O$O7W;;5!$K0MB8$7$^$9!#(B
$B;HMQ$7$F$$$k7W;;5!$N(BC$B8@8l$N%G!<%?7?(B@code{double}$B$NHO0O$HF1$8$G$9!#(B

@c   The read-syntax for floating point numbers requires either a decimal
@c point (with at least one digit following), an exponent, or both.  For
@c example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
@c @samp{.15e4} are five ways of writing a floating point number whose
@c value is 1500.  They are all equivalent.  You can also use a minus sign
@c to write negative floating point numbers, as in @samp{-1.0}.
$BIbF0>.?tE@?t$NF~NO9=J8$O!">.?tE@!J$KB3$1$F(B1$B7e0J>e$N>.?tIt!K$^$?$O;X?t!"(B
$B$"$k$$$O!"$=$NN>J}$,I,MW$G$9!#(B
$B$?$H$($P!"(B@samp{1500.0}$B!"(B@samp{15e2}$B!"(B@samp{15.0e2}$B!"(B
@samp{1.5e3}$B!"(B@samp{.15e4}$B$O!"F1$8(B1500$B$H$$$&CM$N(B
$BIbF0>.?tE@?t$r=q$-I=$9(B5$B$D$NJ}K!$G$9!#(B
$B$I$l$b!"$^$C$?$/Ey2A$G$9!#(B
$BIi$NIbF0>.?tE@?t$r=q$/$K$O!"(B@samp{-1.0}$B$N$h$&$K%^%$%J%9Id9f$r;H$$$^$9!#(B

@c @cindex IEEE floating point
@c @cindex positive infinity
@c @cindex negative infinity
@c @cindex infinity
@c @cindex NaN
@cindex IEEE$BIbF0>.?tE@?t(B
@cindex $B@5$NL58BBg(B
@cindex $BIi$NL58BBg(B
@cindex $BL58BBg(B
@cindex NaN$B!JHs?tCM!K(B
@cindex $BHs?tCM!"(BNaN
@c    Most modern computers support the IEEE floating point standard, which
@c provides for positive infinity and negative infinity as floating point
@c values.  It also provides for a class of values called NaN or
@c ``not-a-number''; numerical functions return such values in cases where
@c there is no correct answer.  For example, @code{(sqrt -1.0)} returns a
@c NaN.  For practical purposes, there's no significant difference between
@c different NaN values in Emacs Lisp, and there's no rule for precisely
@c which NaN value should be used in a particular case, so Emacs Lisp
@c doesn't try to distinguish them.  Here are the read syntaxes for
@c these special floating point values:
$B8=Be$N7W;;5!$O(BIEEE$B$NIbF0>.?tE@?t5,3J$K4p$E$$$F$$$^$9!#(B
$B$3$N5,3J$G$O!"IbF0>.?tE@?t$NCM$K$O@5$NL58BBg$HIi$NL58BBg$,$"$j$^$9!#(B
$B$^$?!"(BNaN$B$9$J$o$A!XHs?tCM!Y!J(Bnot-a-number$B!K$H8F$P$l$kCM$N<oN`$b$"$j$^$9!#(B
$B;;=Q4X?t$O!"@5$7$$Ez$($,$J$$$H$-$K$O!"$3$N$h$&$JCM$rJV$7$^$9!#(B
$B$?$H$($P!"(B@code{(sqrt -1.0)}$B$O(BNaN$B$rJV$7$^$9!#(B
$B<BMQE*$K$O!"(BEmacs Lisp$B$G$O0[$J$k(BNaN$B$NCM$K=EMW$J0c$$$O$J$/!"(B
$BFCDj$N>lLL$G@53N$K$O$I$N(BNaN$B$NCM$r;H$&$+$N5,B'$b$J$$$N$G!"(B
Emacs Lisp$B$G$O$=$l$i$r6hJL$7$h$&$H$O$7$^$;$s!#(B
$BIbF0>.?tE@?t$NF~NO9=J8$O$D$.$N$H$*$j$G$9!#(B

@table @asis
@c @item positive infinity
@item $B@5$NL58BBg(B
@samp{1.0e+INF}
@c @item negative infinity
@item $BIi$NL58BBg(B
@samp{-1.0e+INF}
@c @item Not-a-number
@item $BHs?tCM(B
@c @samp{0.0e+NaN}.
@samp{0.0e+NaN}$B!#(B
@end table

@c   In addition, the value @code{-0.0} is distinguishable from ordinary
@c zero in IEEE floating point (although @code{equal} and @code{=} consider
@c them equal values).
$B$5$i$K!"(BIEEE$B$NIbF0>.?tE@?t$G$OCM(B@code{-0.0}$B$rIaDL$N%<%m$H6hJL$7$^$9(B
$B!J$7$+$7!"(B@code{equal}$B$H(B@code{=}$B$O!"$3$l$i$rEy$7$$CM$H07$&!K!#(B

@c   You can use @code{logb} to extract the binary exponent of a floating
@c point number (or estimate the logarithm of an integer):
$BIbF0>.?tE@?t$N(B2$B?J;X?t$r<h$j=P$9$K$O!J$"$k$$$O!"@0?t$NBP?t$rM=B,$9$k$K$O!K!"(B
@code{logb}$B$r;H$$$^$9!#(B

@defun logb number
@c This function returns the binary exponent of @var{number}.  More
@c precisely, the value is the logarithm of @var{number} base 2, rounded
@c down to an integer.
$B$3$N4X?t$O(B@var{number}$B$N(B2$B?J;X?t$rJV$9!#(B
$B$h$j@53N$K$O!"$=$NCM$O(B@var{number}$B$N(B2$B$rDl$H$9$kBP?t$r@0?t$K@Z$j2<$2$?$b$N!#(B

@example
(logb 10)
     @result{} 3
(logb 10.0e20)
     @result{} 69
@end example
@end defun

@node Predicates on Numbers
@c @section Type Predicates for Numbers
@section $B?t8~$1$N7?=R8l(B

@c   The functions in this section test whether the argument is a number or
@c whether it is a certain sort of number.  The functions @code{integerp}
@c and @code{floatp} can take any type of Lisp object as argument (the
@c predicates would not be of much use otherwise); but the @code{zerop}
@c predicate requires a number as its argument.  See also
@c @code{integer-or-marker-p} and @code{number-or-marker-p}, in
@c @ref{Predicates on Markers}.
$BK\@a$N4X?t$O!"0z?t$,?t$G$"$k$+!"$H$+!"FCDj$N<oN`$N?t$G$"$k$+8!::$7$^$9!#(B
$B4X?t(B@code{integerp}$B$H(B@code{floatp}$B$O(B
$B0z?t$H$7$FG$0U$N7?$N(BLisp$B%*%V%8%'%/%H$r<h$j$^$9(B
$B!J$5$b$J$$$H!"=R8l$NMxMQ2ACM$,$J$$!K!#(B
$B$7$+$7!"=R8l(B@code{zerop}$B$N0z?t$K$O?t$,I,MW$G$9!#(B
@ref{Predicates on Markers}$B$N(B
@code{integer-or-marker-p}$B$H(B@code{number-or-marker-p}$B$b(B
$B;2>H$7$F$/$@$5$$!#(B

@defun floatp object
@c This predicate tests whether its argument is a floating point
@c number and returns @code{t} if so, @code{nil} otherwise.
$B$3$N=R8l$O!"0z?t$,IbF0>.?tE@?t$+$I$&$+D4$Y!"(B
$B$=$&$J$i$P(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B

@c @code{floatp} does not exist in Emacs versions 18 and earlier.
Emacs 18$B0JA0$NHG$K$O(B@code{floatp}$B$O$J$$!#(B
@end defun

@defun integerp object
@c This predicate tests whether its argument is an integer, and returns
@c @code{t} if so, @code{nil} otherwise.
$B$3$N=R8l$O!"0z?t$,@0?t$+$I$&$+D4$Y!"(B
$B$=$&$J$i$P(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@defun numberp object
@c This predicate tests whether its argument is a number (either integer or
@c floating point), and returns @code{t} if so, @code{nil} otherwise.
$B$3$N=R8l$O!"0z?t$,?t!J@0?t$+IbF0>.?tE@?t!K$+$I$&$+D4$Y!"(B
$B$=$&$J$i$P(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@defun wholenump object
@c @cindex natural numbers
@cindex $B<+A3?t(B
@c The @code{wholenump} predicate (whose name comes from the phrase
@c ``whole-number-p'') tests to see whether its argument is a nonnegative
@c integer, and returns @code{t} if so, @code{nil} otherwise.  0 is
@c considered non-negative.
$B!J!X(Bwhole-number-p$B!Y$+$i$-$F$$$kL>A0$N!K=R8l(B@code{wholenump}$B$O!"(B
$B0z?t$,HsIi@0?t$+$I$&$+D4$Y!"(B
$B$=$&$J$i$P(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
0$B$OHsIi@0?t$H$7$F07$&!#(B

@findex natnump
@c @code{natnump} is an obsolete synonym for @code{wholenump}.
@code{natnump}$B$O!"(B@code{wholenump}$B$NGQ$l$?F15A8l!#(B
@end defun

@defun zerop number
@c This predicate tests whether its argument is zero, and returns @code{t}
@c if so, @code{nil} otherwise.  The argument must be a number.
$B$3$N=R8l$O!"0z?t$,(B0$B$+$I$&$+D4$Y!"(B
$B$=$&$J$i$P(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
$B0z?t$O?t$G$"$k$3$H!#(B

@c These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
$B$D$.$N(B2$B$D$N%U%)!<%`$OEy2A!#(B
@code{(zerop x)} @equiv{} @code{(= x 0)}$B!#(B
@end defun

@node Comparison of Numbers
@c @section Comparison of Numbers
@section $B?t$NHf3S(B
@c @cindex number equality
@cindex $B?t$NF1CM@-(B
@cindex $BF1CM@-!"?t(B

@c   To test numbers for numerical equality, you should normally use
@c @code{=}, not @code{eq}.  There can be many distinct floating point
@c number objects with the same numeric value.  If you use @code{eq} to
@c compare them, then you test whether two values are the same
@c @emph{object}.  By contrast, @code{=} compares only the numeric values
@c of the objects.
2$B$D$N?t$,?tCME*$KEy$7$$$+$I$&$+D4$Y$k$K$O!"IaDL!"(B
@code{eq}$B$G$O$J$/(B@code{=}$B$r;H$&$Y$-$G$9!#(B
$B?tCME*$K$OEy$7$$B?$/$N0[$J$kIbF0>.?tE@?t$,B8:_$7$($^$9!#(B
$B$=$l$i$NHf3S$K(B@code{eq}$B$r;H$&$H!"(B
2$B$D$NCM$,F10l(B@emph{$B%*%V%8%'%/%H(B}$B$+$I$&$+D4$Y$k$3$H$K$J$j$^$9!#(B
$BBP>HE*$K!"(B@code{=}$B$O%*%V%8%'%/%H$N?tCM$@$1$rHf3S$7$^$9!#(B

@c   At present, each integer value has a unique Lisp object in Emacs Lisp.
@c Therefore, @code{eq} is equivalent to @code{=} where integers are
@c concerned.  It is sometimes convenient to use @code{eq} for comparing an
@c unknown value with an integer, because @code{eq} does not report an
@c error if the unknown value is not a number---it accepts arguments of any
@c type.  By contrast, @code{=} signals an error if the arguments are not
@c numbers or markers.  However, it is a good idea to use @code{=} if you
@c can, even for comparing integers, just in case we change the
@c representation of integers in a future Emacs version.
$B8=;~E@$G$O!"(BEmacs Lisp$B$K$*$$$F!"3F@0?tCM$O0l0U$J(BLisp$B%*%V%8%'%/%H$G$9!#(B
$B$7$?$,$C$F!"@0?t$K8B$l$P(B@code{eq}$B$O(B@code{=}$B$HEy2A$G$9!#(B
$BL$CN$NCM$H@0?t$rHf3S$9$k$?$a$K(B@code{eq}$B$r;H$&$HJXMx$J>lLL$,$"$j$^$9!#(B
$B$H$$$&$N$O!"(B@code{eq}$B$OG$0U$N7?$N0z?t$r<u$1IU$1$k$N$G!"(B
@code{eq}$B$OL$CN$NCM$,?t$G$J$/$F$b%(%i!<$rJs9p$7$J$$$+$i$G$9!#(B
$BBP>HE*$K!"(B@code{=}$B$O!"0z?t$,?t$d%^!<%+$G$J$$$H!"%(%i!<$rDLCN$7$^$9!#(B
$B$7$+$7$J$,$i!"(BEmacs$B$N>-Mh$NHG$G@0?t$NI=8=J}K!$rJQ99$9$k>l9g$KHw$($F!"(B
$B@0?t$rHf3S$9$k$H$-$G$"$C$F$b!"2DG=$J$i$P!"(B@code{=}$B$r;H$&$[$&$,$h$$$G$7$g$&!#(B

@c   Sometimes it is useful to compare numbers with @code{equal}; it treats
@c two numbers as equal if they have the same data type (both integers, or
@c both floating point) and the same value.  By contrast, @code{=} can
@c treat an integer and a floating point number as equal.
@code{equal}$B$G?t$rHf3S$7$?$[$&$,JXMx$J$3$H$b$"$j$^$9!#(B
@code{equal}$B$O!"(B2$B$D$N?t$,F1$8%G!<%?7?(B
$B!J$I$A$i$b@0?t$G$"$k$+!"$I$A$i$bIbF0>.?tE@?t$G$"$k!K$G!"(B
$BF1$8CM$G$"$l$P!"(B2$B$D$N?t$rEy$7$$$H07$$$^$9!#(B
$B0lJ}!"(B@code{=}$B$O!"@0?t$HIbF0>.?tE@?t$,Ey$7$$$3$H$r07$($^$9!#(B

@c   There is another wrinkle: because floating point arithmetic is not
@c exact, it is often a bad idea to check for equality of two floating
@c point values.  Usually it is better to test for approximate equality.
@c Here's a function to do this:
$BJL$N$3$H$,$i$b$"$j$^$9!#(B
$BIbF0>.?tE@?t1i;;$O87L)$G$O$J$$$N$G!"(B
2$B$D$NIbF0>.?tE@?t$,Ey$7$$$+$I$&$+D4$Y$k$N$O@5$7$/$"$j$^$;$s!#(B
$BIaDL!"6a;wE*$KEy$7$$$3$H$rD4$Y$k$[$&$,$h$$$N$G$9!#(B
$B$D$.$N4X?t$O$=$N$h$&$K$7$^$9!#(B

@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

@c @cindex CL note---integers vrs @code{eq}
@cindex CL$B$K4X$7$?Cm0U!]!]@0?t$H(B@code{eq}
@quotation
@c @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
@c @code{=} because Common Lisp implements multi-word integers, and two
@c distinct integer objects can have the same numeric value.  Emacs Lisp
@c can have just one integer object for any given value because it has a
@c limited range of integer values.
@b{Common Lisp$B$K4X$7$?Cm0U!'(B}@code{ }
Common Lisp$B$G$O!"?t$NHf3S$K$O$D$M$K(B@code{=}$B$r;H$&I,MW$,$"$k!#(B
$B$H$$$&$N$O!"(BCommon Lisp$B$G$OJ#?t%o!<%I$N@0?t$r<BAu$7$F$$$k$?$a!"(B
2$B$D$N0[$J$k@0?t%*%V%8%'%/%H$,F1$8?tCM$rI=$9$3$H$,$"$j$($k!#(B
Emacs Lisp$B$G$O!"@0?tCM$NHO0O$,@)8B$5$l$F$$$k$?$a!"(B
$BG$0U$NCM$N@0?t%*%V%8%'%/%H$O$=$l$>$l(B1$B$D$7$+$J$$!#(B
@end quotation

@defun = number-or-marker1 number-or-marker2
@c This function tests whether its arguments are numerically equal, and
@c returns @code{t} if so, @code{nil} otherwise.
$B$3$N4X?t$O!"0z?t$,?tCME*$KEy$7$$$+D4$Y!"(B
$B$=$&$J$i$P(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@defun /= number-or-marker1 number-or-marker2
@c This function tests whether its arguments are numerically equal, and
@c returns @code{t} if they are not, and @code{nil} if they are.
$B$3$N4X?t$O!"0z?t$,?tCME*$KEy$7$$$+D4$Y!"(B
$BEy$7$/$J$1$l$P(B@code{t}$B$rJV$7!"Ey$7$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@defun <  number-or-marker1 number-or-marker2
@c This function tests whether its first argument is strictly less than
@c its second argument.  It returns @code{t} if so, @code{nil} otherwise.
$B$3$N4X?t$O!"Bh(B1$B0z?t$,Bh(B2$B0z?t$h$j>.$5$$$+D4$Y!"(B
$B$=$&$J$i$P(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@defun <=  number-or-marker1 number-or-marker2
@c This function tests whether its first argument is less than or equal
@c to its second argument.  It returns @code{t} if so, @code{nil}
@c otherwise.
$B$3$N4X?t$O!"Bh(B1$B0z?t$,Bh(B2$B0z?t$h$j>.$5$$$+!"$"$k$$$O!"Ey$7$$$+D4$Y!"(B
$B$=$&$J$i$P(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@defun >  number-or-marker1 number-or-marker2
@c This function tests whether its first argument is strictly greater
@c than its second argument.  It returns @code{t} if so, @code{nil}
@c otherwise.
$B$3$N4X?t$O!"Bh(B1$B0z?t$,Bh(B2$B0z?t$h$jBg$-$$$+D4$Y!"(B
$B$=$&$J$i$P(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@defun >=  number-or-marker1 number-or-marker2
@c This function tests whether its first argument is greater than or
@c equal to its second argument.  It returns @code{t} if so, @code{nil}
@c otherwise.
$B$3$N4X?t$O!"Bh(B1$B0z?t$,Bh(B2$B0z?t$h$jBg$-$$$+!"$"$k$$$O!"Ey$7$$$+D4$Y!"(B
$B$=$&$J$i$P(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@defun max number-or-marker &rest numbers-or-markers
@c This function returns the largest of its arguments.
$B$3$N4X?t$O!"0z?t$NCf$G:GBg$N$b$N$rJV$9!#(B

@example
(max 20)
     @result{} 20
(max 1 2.5)
     @result{} 2.5
(max 1 3 2.5)
     @result{} 3
@end example
@end defun

@defun min number-or-marker &rest numbers-or-markers
@c This function returns the smallest of its arguments.
$B$3$N4X?t$O!"0z?t$NCf$G:G>.$N$b$N$rJV$9!#(B

@example
(min -4 1)
     @result{} -4
@end example
@end defun

@defun abs number
@c This function returns the absolute value of @var{number}.
$B$3$N4X?t$O!"(B@var{number}$B$N@dBPCM$rJV$9!#(B
@end defun

@node Numeric Conversions
@c @section Numeric Conversions
@section $B?t$NJQ49(B
@c @cindex rounding in conversions
@cindex $B4]$aJQ49(B

@c To convert an integer to floating point, use the function @code{float}.
$B@0?t$rIbF0>.?tE@?t$KJQ49$9$k$K$O!"(B
$B4X?t(B@code{float}$B$r;H$$$^$9!#(B

@defun float number
@c This returns @var{number} converted to floating point.
@c If @var{number} is already a floating point number, @code{float} returns
@c it unchanged.
$B$3$N4X?t$O!"IbF0>.?tE@?t$KJQ49$7$?(B@var{number}$B$rJV$9!#(B
@var{number}$B$,$9$G$KIbF0>.?tE@?t$J$i$P!"(B
@code{float}$B$O(B@var{number}$B$rJQ99$;$:$KJV$9!#(B
@end defun

@c There are four functions to convert floating point numbers to integers;
@c they differ in how they round.  These functions accept integer arguments
@c also, and return such arguments unchanged.
$BIbF0>.?tE@?t$r@0?t$KJQ49$9$k4X?t$O(B4$B$D$"$j$^$9!#(B
$B$3$l$i$N4X?t$O!"@0?t$b0z?t$K<h$j$^$9$,!"@0?t0z?t$OJQ99$;$:$KJV$7$^$9!#(B

@defun truncate number
@c This returns @var{number}, converted to an integer by rounding towards
@c zero.
$B$3$l$O!"(B0$B$K8~$1$F@Z$j<N$F$F@0?t$KJQ49$7$?(B@var{number}$B$rJV$9!#(B
@end defun

@defun floor number &optional divisor
@c This returns @var{number}, converted to an integer by rounding downward
@c (towards negative infinity).
$B$3$l$O!"!JIi$NL58BBg$K8~$1$F!K@Z$j2<$2$F@0?t$KJQ49$7$?(B@var{number}$B$rJV$9!#(B

@c If @var{divisor} is specified, @var{number} is divided by @var{divisor}
@c before the floor is taken; this uses the kind of division operation that
@c corresponds to @code{mod}, rounding downward.  An @code{arith-error}
@c results if @var{divisor} is 0.
@var{divisor}$B$r;XDj$9$k$H!"@Z$j2<$2$k$^$($K(B
@var{number}$B$r(B@var{divisor}$B$G=|;;$9$k!#(B
$B$3$l$K$O!"(B@code{mod}$B$KBP1~$7$?=|;;$r;H$$@Z$j2<$2$k!#(B
@var{divisor}$B$,(B0$B$G$"$k$H!"7k2L$O(B@code{arith-error}$B$K$J$k!#(B
@end defun

@defun ceiling number
@c This returns @var{number}, converted to an integer by rounding upward
@c (towards positive infinity).
$B$3$l$O!"!J@5$NL58BBg$K8~$1$F!K@Z$j>e$2$F@0?t$KJQ49$7$?(B@var{number}$B$rJV$9!#(B
@end defun

@defun round number
@c This returns @var{number}, converted to an integer by rounding towards the
@c nearest integer.  Rounding a value equidistant between two integers
@c may choose the integer closer to zero, or it may prefer an even integer,
@c depending on your machine.
$B$3$l$O!"$b$C$H$b6a$$@0?t$K4]$a$F@0?t$KJQ49$7$?(B@var{number}$B$rJV$9!#(B
2$B$D$N@0?t$KEy5wN%$K$"$kCM$r4]$a$k>l9g$K$O!"(B
$B;HMQ$7$F$$$k7W;;5!$K0MB8$7$F!"%<%m$K6a$$$[$&$N@0?t$rA*$V$+6v?t$rA*$V!#(B
@end defun

@node Arithmetic Operations
@c @section Arithmetic Operations
@section $B;;=Q1i;;(B

@c   Emacs Lisp provides the traditional four arithmetic operations:
@c addition, subtraction, multiplication, and division.  Remainder and modulus
@c functions supplement the division functions.  The functions to
@c add or subtract 1 are provided because they are traditional in Lisp and
@c commonly used.
Emacs Lisp$B$K$O!"EAE}E*$J;MB'1i;;!"2C;;!"8:;;!">h;;!"=|;;$,$"$j$^$9!#(B
$B=|;;4X?t$rJd$&!"M>$j$H>jM>$N4X?t$b$"$j$^$9!#(B
Lisp$B$NEAE}$G$b$"$j!"$^$?!"B?MQ$9$k$N$G!"(B1$B$r2C;;$7$?$j8:;;$9$k4X?t$b$"$j$^$9!#(B

@c   All of these functions except @code{%} return a floating point value
@c if any argument is floating.
$B$3$l$i$N4X?t$O!"(B@code{%}$B$r=|$$$F!"0z?t$,(B1$B$D$G$bIbF0>.?tE@?t$G$"$k$H!"(B
$BIbF0>.?tE@?t$rJV$7$^$9!#(B

@c   It is important to note that in Emacs Lisp, arithmetic functions
@c do not check for overflow.  Thus @code{(1+ 134217727)} may evaluate to
@c @minus{}134217728, depending on your hardware.
Emacs Lisp$B$G$O!";;=Q4X?t$O7e0n$l!J%*!<%P%U%m!<!K$r8!::$7$J$$$3$H$K(B
$BCm0U$7$F$/$@$5$$!#(B
$B$D$^$j!"FI<T$N7W;;5!$K0MB8$7$^$9$,!"(B
@code{(1+ 134217727)}$B$rI>2A$9$k$H(B@minus{}134217728$B$K$J$k>l9g$b$"$j$^$9!#(B

@defun 1+ number-or-marker
@c This function returns @var{number-or-marker} plus 1.
@c For example,
$B$3$N4X?t$O!"(B@var{number-or-marker}$BB-$9(B1$B$rJV$9!#(B

@example
(setq foo 4)
     @result{} 4
(1+ foo)
     @result{} 5
@end example

@c This function is not analogous to the C operator @code{++}---it does not
@c increment a variable.  It just computes a sum.  Thus, if we continue,
$B$3$N4X?t$O(BC$B8@8l$N1i;;;R(B@code{++}$B$NN`;w$G$O$J$$!#(B
$B$D$^$j!"JQ?t$rA}2C$7$J$$!#(B
$B$7$?$,$C$F!"$D$.$N$h$&$K$J$k!#(B

@example
foo
     @result{} 4
@end example

@c If you want to increment the variable, you must use @code{setq},
@c like this:
$BJQ?t$rA}2C$9$k$K$O!"$D$.$N$h$&$K(B@code{setq}$B$r;H$&I,MW$,$"$k!#(B

@example
(setq foo (1+ foo))
     @result{} 5
@end example
@end defun

@defun 1- number-or-marker
@c This function returns @var{number-or-marker} minus 1.
$B$3$N4X?t$O!"(B@var{number-or-marker}$B0z$/(B1$B$rJV$9!#(B
@end defun

@defun + &rest numbers-or-markers
@c This function adds its arguments together.  When given no arguments,
@c @code{+} returns 0.
$B$3$N4X?t$O!"0z?t$r$9$Y$F2C;;$9$k!#(B
$B0z?t$r;XDj$7$J$$$H(B@code{+}$B$O(B0$B$rJV$9!#(B

@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
@c The @code{-} function serves two purposes: negation and subtraction.
@c When @code{-} has a single argument, the value is the negative of the
@c argument.  When there are multiple arguments, @code{-} subtracts each of
@c the @var{more-numbers-or-markers} from @var{number-or-marker},
@c cumulatively.  If there are no arguments, the result is 0.
$B4X?t(B@code{-}$B$O!"(B2$B$D$NLr3d!"$D$^$j!"Id9fH?E>$H8:;;$r2L$?$9!#(B
@code{-}$B$K(B1$B$D$N0z?t$r;XDj$9$k$H!"(B
$B$=$NCM$O!"0z?t$NId9f$rH?E>$7$?$b$N$G$"$k!#(B
$BJ#?t8D$N0z?t$r;XDj$9$k$H!"(B@code{-}$B$O!"(B
@var{number-or-marker}$B$+$i(B@var{more-numbers-or-markers}$B$N(B1$B$D(B1$B$D$r8:;;$9$k!#(B
$B0z?t$r;XDj$7$J$$$H7k2L$O(B0$B$G$"$k!#(B

@example
(- 10 1 2 3 4)
     @result{} 0
(- 10)
     @result{} -10
(-)
     @result{} 0
@end example
@end defun

@defun * &rest numbers-or-markers
@c This function multiplies its arguments together, and returns the
@c product.  When given no arguments, @code{*} returns 1.
$B$3$N4X?t$O!"0z?t$r$9$Y$F3]$19g$o$;$?>h;;7k2L$rJV$9!#(B
$B0z?t$r;XDj$7$J$$$H(B@code{*}$B$O(B1$B$rJV$9!#(B

@example
(*)
     @result{} 1
(* 1)
     @result{} 1
(* 1 2 3 4)
     @result{} 24
@end example
@end defun

@defun / dividend divisor &rest divisors
@c This function divides @var{dividend} by @var{divisor} and returns the
@c quotient.  If there are additional arguments @var{divisors}, then it
@c divides @var{dividend} by each divisor in turn.  Each argument may be a
@c number or a marker.
$B$3$N4X?t$O!"(B@var{dividend}$B$r(B@var{divisor}$B$G=|$7>&$rJV$9!#(B
$BDI2C$N0z?t(B@var{divisors}$B$r;XDj$7$F$"$k$H!"(B
@var{dividend}$B$r(B@var{divisors}$B$N(B1$B$D(B1$B$D$G=|$9!#(B
$B3F0z?t$O?t$+%^!<%+$G$"$k!#(B

@c If all the arguments are integers, then the result is an integer too.
@c This means the result has to be rounded.  On most machines, the result
@c is rounded towards zero after each division, but some machines may round
@c differently with negative arguments.  This is because the Lisp function
@c @code{/} is implemented using the C division operator, which also
@c permits machine-dependent rounding.  As a practical matter, all known
@c machines round in the standard fashion.
$B$9$Y$F$N0z?t$,@0?t$G$"$k>l9g!"7k2L$b@0?t$H$J$k!#(B
$B$D$^$j!"7k2L$O@Z$j<N$F$K$J$k!#(B
$B$[$H$s$I$N7W;;5!$G$O3F=|;;$N7k2L$O(B0$B$K8~$1$F@Z$j<N$F$K$J$k$,!"(B
$BIi$N0z?t$rJL$NJ}K!$G4]$a$k7W;;5!$b$"$k!#(B
$B$3$l$O!"(BLisp$B4X?t(B@code{/}$B$r(BC$B8@8l$N=|;;1i;;;R$G<BAu$7$F$$$k$+$i$G$"$j!"(B
C$B8@8l$N=|;;1i;;;R$G$O7W;;5!0MB8$K4]$a$k$3$H$r5v$7$F$$$k$+$i$G$"$k!#(B
$B<BMQ>e!"$9$Y$F$N4{CN$N7W;;5!$OI8=`E*$JJ}K!$G4]$a$k!#(B

@c @cindex @code{arith-error} in division
@cindex $B=|;;$N(B@code{arith-error}
@cindex @code{arith-error}$B!"=|;;(B
@c If you divide an integer by 0, an @code{arith-error} error is signaled.
@c (@xref{Errors}.)  Floating point division by zero returns either
@c infinity or a NaN if your machine supports IEEE floating point;
@c otherwise, it signals an @code{arith-error} error.
$B@0?t$r(B0$B$G=|;;$9$k$H!"%(%i!<(B@code{arith-error}$B$rDLCN$9$k!#(B
$B!J(B@pxref{Errors}$B!#!K(B
$BIbF0>.?tE@?t$r(B0$B$G=|;;$9$k$H!"(BIEEE$BIbF0>.?tE@?t$r;H$&7W;;5!$G$O!"(B
$BL58BBg$+(BNaN$B$rJV$9!#(B
$B$5$b$J$1$l$P%(%i!<(B@code{arith-error}$B$rDLCN$9$k!#(B

@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)
     @result{} -2
@end example

@c The result of @code{(/ -17 6)} could in principle be -3 on some
@c machines.
$B86M}E*$K$O!"(B@code{(/ -17 6)}$B$,(B-3$B$K$J$k7W;;5!$b$"$k!#(B
@end defun

@defun % dividend divisor
@c @cindex remainder
@cindex $BM>$j(B
@c This function returns the integer remainder after division of @var{dividend}
@c by @var{divisor}.  The arguments must be integers or markers.
$B$3$N4X?t$O!"(B@var{dividend}$B$r(B@var{divisor}$B$G=|$7$?$"$H$N@0?t$NM>$j$rJV$9!#(B
$B0z?t$O@0?t$+%^!<%+$G$"$kI,MW$,$"$k!#(B

@c For negative arguments, the remainder is in principle machine-dependent
@c since the quotient is; but in practice, all known machines behave alike.
$BIi$N0z?t$G$O!"M>$j$O86M}E*$K7W;;5!0MB8$G$"$k!#(B
$B<BMQ>e!"$9$Y$F$N4{CN$N7W;;5!$OF1$8$h$&$K$U$k$^$&!#(B

@c An @code{arith-error} results if @var{divisor} is 0.
@var{divisor}$B$,(B0$B$G$"$k$H(B@code{arith-error}$B$K$J$k!#(B

@example
(% 9 4)
     @result{} 1
(% -9 4)
     @result{} -1
(% 9 -4)
     @result{} 1
(% -9 -4)
     @result{} -1
@end example

@c For any two integers @var{dividend} and @var{divisor},
2$B$D$NG$0U$N@0?t(B@var{dividend}$B$H(B@var{divisor}$B$K$*$$$F!"(B

@example
@group
(+ (% @var{dividend} @var{divisor})
   (* (/ @var{dividend} @var{divisor}) @var{divisor}))
@end group
@end example

@noindent
@c always equals @var{dividend}.
$B$O!"$D$M$K(B@var{dividend}$B$KEy$7$$!#(B
@end defun

@defun mod dividend divisor
@c @cindex modulus
@cindex $B>jM>(B
@c This function returns the value of @var{dividend} modulo @var{divisor};
@c in other words, the remainder after division of @var{dividend}
@c by @var{divisor}, but with the same sign as @var{divisor}.
@c The arguments must be numbers or markers.
$B$3$N4X?t$O!"(B@var{dividend}$B$N(B@var{divisor}$B$K$h$k>jM>$rJV$9!#(B
$B$$$$$+$($l$P!"(B@var{dividend}$B$r(B@var{divisor}$B$G=|$7$?M>$j$rJV$9!#(B
$B$?$@$7!"$=$NId9f$O(B@var{divisor}$B$HF1$8!#(B
$B0z?t$O?t$+%^!<%+$G$"$kI,MW$,$"$k!#(B

@c Unlike @code{%}, @code{mod} returns a well-defined result for negative
@c arguments.  It also permits floating point arguments; it rounds the
@c quotient downward (towards minus infinity) to an integer, and uses that
@c quotient to compute the remainder.
@code{%}$B$H0c$$!"(B
@code{mod}$B$OIi$N0z?t$KBP$7$F$b87L)$KDj5A$5$l$?7k2L$rJV$9!#(B
$BIbF0>.?tE@$N0z?t$b5v$9!#(B
$B>&$r!JIi$NL58BBg$K8~$1$F!K@Z$j2<$2$F@0?t$K$7!"(B
$B$=$N>&$rMQ$$$FM>$j$r7W;;$9$k!#(B

@c An @code{arith-error} results if @var{divisor} is 0.
@var{divisor}$B$,(B0$B$G$"$k$H(B@code{arith-error}$B$K$J$k!#(B

@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

@c For any two numbers @var{dividend} and @var{divisor},
2$B$D$NG$0U$N@0?t(B@var{dividend}$B$H(B@var{divisor}$B$K$*$$$F!"(B

@example
@group
(+ (mod @var{dividend} @var{divisor})
   (* (floor @var{dividend} @var{divisor}) @var{divisor}))
@end group
@end example

@noindent
@c always equals @var{dividend}, subject to rounding error if either
@c argument is floating point.  For @code{floor}, see @ref{Numeric
@c Conversions}.
$B$O!"$D$M$K(B@var{dividend}$B$KEy$7$$!#(B
$B$?$@$7!"$I$A$i$+$N0z?t$,IbF0>.?tE@?t$N>l9g$K$O!"(B
$B4]$a8m:9$NHO0OFb$GEy$7$$!#(B
@code{floor}$B$K$D$$$F$O!"(B@ref{Numeric Conversions}$B$r;2>H!#(B
@end defun

@node Rounding Operations
@c @section Rounding Operations
@section $B4]$a1i;;(B
@c @cindex rounding without conversion
@cindex $BJQ49$;$:$K4]$a$k(B
@cindex $B4]$a$k(B

@c The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
@c @code{ftruncate} take a floating point argument and return a floating
@c point result whose value is a nearby integer.  @code{ffloor} returns the
@c nearest integer below; @code{fceiling}, the nearest integer above;
@c @code{ftruncate}, the nearest integer in the direction towards zero;
@c @code{fround}, the nearest integer.
$B4X?t!"(B@code{ffloor}$B!"(B@code{fceiling}$B!"(B@code{fround}$B!"(B@code{ftruncate}$B$O!"(B
$BIbF0>.?tE@?t0z?t$r<u$1<h$j!"$=$NCM$K6a$$@0?t$rCM$H$9$kIbF0>.?tE@?t$rJV$7$^$9!#(B
@code{ffloor}$B$O!"$b$C$H$b6a$$$h$j>.$5$J@0?t$rJV$7$^$9!#(B
@code{fceiling}$B$O!"$b$C$H$b6a$$$h$jBg$-$J@0?t$rJV$7$^$9!#(B
@code{ftruncate}$B$O!"(B0$B$K8~$1$F@Z$j<N$F$?$b$C$H$b6a$$@0?t$rJV$7$^$9!#(B
@code{fround}$B$O!"$b$C$H$b6a$$@0?t$rJV$7$^$9!#(B

@defun ffloor float
@c This function rounds @var{float} to the next lower integral value, and
@c returns that value as a floating point number.
$B$3$N4X?t$O!"(B@var{float}$B$r$3$l$h$j>.$5$J@0?tCM$K@Z$j2<$2!"(B
$B$=$NCM$rIbF0>.?tE@?t$H$7$FJV$9!#(B
@end defun

@defun fceiling float
@c This function rounds @var{float} to the next higher integral value, and
@c returns that value as a floating point number.
$B$3$N4X?t$O!"(B@var{float}$B$r$3$l$h$jBg$-$J@0?tCM$K@Z$j>e$2!"(B
$B$=$NCM$rIbF0>.?tE@?t$H$7$FJV$9!#(B
@end defun

@defun ftruncate float
@c This function rounds @var{float} towards zero to an integral value, and
@c returns that value as a floating point number.
$B$3$N4X?t$O!"(B@var{float}$B$r(B0$B$K8~$1$F@0?tCM$K@Z$j<N$F!"(B
$B$=$NCM$rIbF0>.?tE@?t$H$7$FJV$9!#(B
@end defun

@defun fround float
@c This function rounds @var{float} to the nearest integral value,
@c and returns that value as a floating point number.
$B$3$N4X?t$O!"(B@var{float}$B$r$b$C$H$b6a$$@0?tCM$K4]$a!"(B
$B$=$NCM$rIbF0>.?tE@?t$H$7$FJV$9!#(B
@end defun

@node Bitwise Operations
@c @section Bitwise Operations on Integers
@section $B@0?t$N%S%C%H1i;;(B

@c   In a computer, an integer is represented as a binary number, a
@c sequence of @dfn{bits} (digits which are either zero or one).  A bitwise
@c operation acts on the individual bits of such a sequence.  For example,
@c @dfn{shifting} moves the whole sequence left or right one or more places,
@c reproducing the same pattern ``moved over''.
$B7W;;5!FbIt$G$O!"@0?t$O(B2$B?J?t!"$D$^$j!"(B
@dfn{$B%S%C%H(B}$B!J(Bbit$B!"3F7e$O(B0$B$+(B1$B!KNs$GI=8=$5$l$^$9!#(B
$B%S%C%H1i;;$O!"$=$N$h$&$J%S%C%HNs$N3F%S%C%H$4$H$K:nMQ$7$^$9!#(B
$B$?$H$($P!"(B@dfn{$B%7%U%H(B}$B!J(Bshifting$B!K$O!"%S%C%HNs$rA4BN$H$7$F:8$d1&$K(B
1$B7e0J>e0\F0$7$F!"$=$N!X0\F08e$N!Y%Q%?!<%s$r7k2L$H$7$^$9!#(B

@c   The bitwise operations in Emacs Lisp apply only to integers.
Emacs Lisp$B$K$*$1$k%S%C%H1i;;$O@0?t$K8B$j$^$9!#(B

@defun lsh integer1 count
@c @cindex logical shift
@cindex $BO@M}%7%U%H(B
@c @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
@c bits in @var{integer1} to the left @var{count} places, or to the right
@c if @var{count} is negative, bringing zeros into the vacated bits.  If
@c @var{count} is negative, @code{lsh} shifts zeros into the leftmost
@c (most-significant) bit, producing a positive result even if
@c @var{integer1} is negative.  Contrast this with @code{ash}, below.
@dfn{$BO@M}%7%U%H(B}$B!J(Blogical shift$B!K$NN,$+$i$-$F$$$k(B@code{lsh}$B$O!"(B
@var{integer1}$B$N%S%C%HNs$r(B@var{count}$B7e:8$X!"(B
$B$"$k$$$O!"(B@var{count}$B$,Ii$J$i$P1&$X$:$i$7!"6u$$$?%S%C%H$K$O(B0$B$r5M$a$k!#(B
@var{count}$B$,Ii$G$"$l$P!"(B@code{lsh}$B$O:G:8!J:G>e0L!K%S%C%H$K(B0$B$r5M$a!"(B
@var{integer1}$B$,Ii$G$"$C$F$b7k2L$O@5$K$J$k!#(B
$B$3$l$HBP>HE*$J$N$,2<$N(B@code{ash}$B!#(B

@c Here are two examples of @code{lsh}, shifting a pattern of bits one
@c place to the left.  We show only the low-order eight bits of the binary
@c pattern; the rest are all zero.
@code{lsh}$B$NNc$r(B2$B$D<($9!#(B
$B%S%C%H%Q%?!<%s$r(B1$B7e:8$X$:$i$9!#(B
$B%S%C%H%Q%?!<%s$N>e0L%S%C%H$O$9$Y$F(B0$B$J$N$G2<0L(B8$B%S%C%H$@$1$r<($9!#(B

@example
@group
(lsh 5 1)
     @result{} 10
@c ;; @r{Decimal 5 becomes decimal 10.}
;; @r{10$B?J?t(B5$B$O!"(B 10$B?J?t(B10$B$K$J$k(B}
00000101 @result{} 00001010

(lsh 7 1)
     @result{} 14
@c ;; @r{Decimal 7 becomes decimal 14.}
;; @r{10$B?J?t(B7$B$O!"(B10$B?J?t(B14$B$K$J$k(B}
00000111 @result{} 00001110
@end group
@end example

@noindent
@c As the examples illustrate, shifting the pattern of bits one place to
@c the left produces a number that is twice the value of the previous
@c number.
$BNc$+$i$o$+$k$h$&$K!"%S%C%H%Q%?!<%s$r(B1$B7e:8$X$:$i$9$H!"(B
$B$b$H$N?tCM$N(B2$BG\$N?t$K$J$k!#(B

@c Shifting a pattern of bits two places to the left produces results
@c like this (with 8-bit binary numbers):
$B%S%C%H%Q%?!<%s$r(B2$B7e:8$X$:$i$9$H!"!J(B8$B%S%C%HD9$N(B2$B?J?t$G$O!K$D$.$N$h$&$K$J$k!#(B

@example
@group
(lsh 3 2)
     @result{} 12
@c ;; @r{Decimal 3 becomes decimal 12.}
;; @r{10$B?J?t(B3$B$O!"(B10$B?J?t(B12$B$K$J$k(B}
00000011 @result{} 00001100       
@end group
@end example

@c On the other hand, shifting one place to the right looks like this:
$B0lJ}!"1&$X$:$i$9$H$D$.$N$h$&$K$J$k!#(B

@example
@group
(lsh 6 -1)
     @result{} 3
@c ;; @r{Decimal 6 becomes decimal 3.}
;; @r{10$B?J?t(B6$B$O!"(B10$B?J?t(B3$B$K$J$k(B}
00000110 @result{} 00000011       
@end group

@group
(lsh 5 -1)
     @result{} 2
@c ;; @r{Decimal 5 becomes decimal 2.}
;; @r{10$B?J?t(B5$B$O!"(B10$B?J?t(B2$B$K$J$k(B}
00000101 @result{} 00000010       
@end group
@end example

@noindent
@c As the example illustrates, shifting one place to the right divides the
@c value of a positive integer by two, rounding downward.
$BNc$+$i$o$+$k$h$&$K!"%S%C%H%Q%?!<%s$r(B1$B7e1&$X$:$i$9$H!"(B
$B@5$N@0?t$N?t$r(B2$B$G=|$7$F@Z$j2<$2$k!#(B

@c The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
@c not check for overflow, so shifting left can discard significant bits
@c and change the sign of the number.  For example, left shifting
@c 134,217,727 produces @minus{}2 on a 28-bit machine:
Emacs Lisp$B$N$9$Y$F$N;;=Q4X?t$HF1MM$K!"(B
$B4X?t(B@code{lsh}$B$O7e0n$l!J%*!<%P%U%m!<!K$r8!::$7$J$$$N$G!"(B
$B:8$X$:$i$9$H>e0L%S%C%H$r<N$F$5$j?t$NId9f$rJQ$($F$7$^$&$3$H$,$"$k!#(B
$B$?$H$($P!"(B28$B%S%C%HD9$N7W;;5!$G$O!"(B
134,217,727$B$r:8$X$:$i$9$H(B@minus{}2$B$K$J$k!#(B

@example
@c (lsh 134217727 1)          ; @r{left shift}
(lsh 134217727 1)          ; @r{$B:8%7%U%H(B}
     @result{} -2
@end example

@c In binary, in the 28-bit implementation, the argument looks like this:
28$B%S%C%HD9$N<BAu$N(B2$B?J?t$G$O!"0z?t$O$D$.$N$h$&$K$J$C$F$$$k!#(B

@example
@group
@c ;; @r{Decimal 134,217,727}
;; @r{10$B?J?t(B134,217,727}
0111  1111 1111  1111 1111  1111 1111         
@end group
@end example

@noindent
@c which becomes the following when left shifted:
$B$3$l$r:8$X$:$i$9$H!"$D$.$N$h$&$K$J$k(B

@example
@group
@c ;; @r{Decimal @minus{}2}
;; @r{10$B?J?t(B@minus{}2}
1111  1111 1111  1111 1111  1111 1110         
@end group
@end example
@end defun

@defun ash integer1 count
@c @cindex arithmetic shift
@cindex $B;;=Q%7%U%H(B
@c @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
@c to the left @var{count} places, or to the right if @var{count}
@c is negative.
@code{ash}$B!J(B@dfn{$B;;=Q%7%U%H(B}$B!J(Barithmetic shift$B!K!K$O!"(B
@var{integer1}$B$N%S%C%H$r(B@var{count}$B7e:8$X!"$"$k$$$O!"(B
@var{count}$B$,Ii$J$i$P1&$X$:$i$9!#(B

@c @code{ash} gives the same results as @code{lsh} except when
@c @var{integer1} and @var{count} are both negative.  In that case,
@c @code{ash} puts ones in the empty bit positions on the left, while
@c @code{lsh} puts zeros in those bit positions.
@code{ash}$B$O(B@code{lsh}$B$HF1$87k2L$K$J$k$,!"(B
@var{integer1}$B$H(B@var{count}$B$NN><T$,Ii$N>l9g$r=|$/!#(B
$B$3$N>l9g!"(B@code{ash}$B$O:8$N6u$$$?%S%C%H$K$O(B1$B$rF~$l$k$,!"(B
@code{lsh}$B$O$=$N$h$&$J%S%C%H$K$O(B0$B$rF~$l$k!#(B

@c Thus, with @code{ash}, shifting the pattern of bits one place to the right
@c looks like this:
$B$7$?$,$C$F!"(B@code{ash}$B$G%S%C%H%Q%?!<%s$r(B1$B7e1&$X$:$i$9$H$D$.$N$h$&$K$J$k!#(B

@example
@group
(ash -6 -1) @result{} -3            
@c ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
;; @r{10$B?J?t(B@minus{}6$B$O!"(B10$B?J?t(B@minus{}3$B$K$J$k(B}
1111  1111 1111  1111 1111  1111 1010
     @result{} 
1111  1111 1111  1111 1111  1111 1101
@end group
@end example

@c In contrast, shifting the pattern of bits one place to the right with
@c @code{lsh} looks like this:
$BBP>HE*$K!"(B@code{lsh}$B$G%S%C%H%Q%?!<%s$r(B1$B7e1&$X$:$i$9$H$D$.$N$h$&$K$J$k!#(B

@example
@group
(lsh -6 -1) @result{} 134217725
@c ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
;; @r{10$B?J?t(B@minus{}6$B$O!"(B10$B?J?t(B134,217,725$B$K$J$k(B}
1111  1111 1111  1111 1111  1111 1010
     @result{} 
0111  1111 1111  1111 1111  1111 1101
@end group
@end example

@c Here are other examples:
$BB>$NNc$r0J2<$K$7$a$9!#(B

@c !!! Check if lined up in smallbook format!  XDVI shows problem
@c     with smallbook but not with regular book! --rjc 16mar92
@smallexample
@group
@c                    ;  @r{             28-bit binary values}
                   ;  @r{             28$B%S%C%H(B2$B?JCM(B}

(lsh 5 2)          ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
     @result{} 20         ;      =  @r{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}
(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}
@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}
@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}
@end group
@end smallexample
@end defun

@defun logand &rest ints-or-markers
@c @cindex logical and
@c @cindex bitwise and
@cindex $BO@M}@Q(B
@cindex $B%S%C%H$4$H$NO@M}@Q(B
@c This function returns the ``logical and'' of the arguments: the
@c @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
@c set in all the arguments.  (``Set'' means that the value of the bit is 1
@c rather than 0.)
$B$3$N4X?t$O0z?t$N!XO@M}@Q!Y$rJV$9!#(B
$B$D$^$j!"$9$Y$F$N0z?t$N(B@var{n}$BHVL\$N%S%C%H$,(B1$B$G$"$k>l9g$K8B$j!"(B
$B7k2L$N(B@var{n}$BHVL\$N%S%C%H$b(B1$B$K$J$k!#(B

@c For example, using 4-bit binary numbers, the ``logical and'' of 13 and
@c 12 is 12: 1101 combined with 1100 produces 1100.
@c In both the binary numbers, the leftmost two bits are set (i.e., they
@c are 1's), so the leftmost two bits of the returned value are set.
@c However, for the rightmost two bits, each is zero in at least one of
@c the arguments, so the rightmost two bits of the returned value are 0's.
$B$?$H$($P!"(B4$B%S%C%H$N(B2$B?J?t$G9M$($k$H!"(B
13$B$H(B12$B$N!XO@M}@Q!Y$O(B12$B$K$J$k!#(B
$B$D$^$j!"(B1101$B$K(B1100$B$rAH$_9g$o$;$k$H(B1100$B$K$J$k!#(B
$B$I$A$i$N(B2$B?J?t$b:G:8$N(B2$B%S%C%H$O(B1$B$J$N$G!"La$jCM$N:G:8$N(B2$B%S%C%H$b(B1$B$K$J$k!#(B
$B$7$+$7!":G1&$N(B2$B%S%C%H$O!"0lJ}$N0z?t$G$O$=$l$>$l$,(B0$B$J$N$G!"(B
$BLa$jCM$N:G1&$N(B2$B%S%C%H$b(B0$B$K$J$k!#(B

@noindent
@c Therefore,
$B$7$?$,$C$F!"$D$.$N$H$*$j!#(B

@example
@group
(logand 13 12)
     @result{} 12
@end group
@end example

@c If @code{logand} is not passed any argument, it returns a value of
@c @minus{}1.  This number is an identity element for @code{logand}
@c because its binary representation consists entirely of ones.  If
@c @code{logand} is passed just one argument, it returns that argument.
@code{logand}$B$K$^$C$?$/0z?t$r;XDj$7$J$$$HCM(B@minus{}1$B$rJV$9!#(B
$B$3$N?t$O(B2$B?JI=8=$G$O$9$Y$F(B1$B$@$1$J$N$G!"(B
@code{logand}$B$N91Ey85$G$"$k!#(B
@code{logand}$B$K0z?t$r(B1$B$D$@$1;XDj$9$k$H$=$N0z?t$rJV$9!#(B

@smallexample
@group
@c                    ; @r{               28-bit binary values}
                   ; @r{               28$B%S%C%H(B2$B?JCM(B}

(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}
@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}
@end group

@group
(logand)
     @result{} -1         ; -1  =  @r{1111  1111 1111  1111 1111  1111 1111}
@end group
@end smallexample
@end defun

@defun logior &rest ints-or-markers
@c @cindex logical inclusive or
@cindex $BO@M}OB(B
@c @cindex bitwise or
@cindex $B%S%C%H$4$H$NO@M}OB(B
@c This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
@c is set in the result if, and only if, the @var{n}th bit is set in at least
@c one of the arguments.  If there are no arguments, the result is zero,
@c which is an identity element for this operation.  If @code{logior} is
@c passed just one argument, it returns that argument.
$B$3$N4X?t$O0z?t$N!XO@M}OB!Y$rJV$9!#(B
$B$D$^$j!">/$J$/$H$b$I$l$+(B1$B$D$N0z?t$N(B@var{n}$BHVL\$N%S%C%H$,(B1$B$G$"$k>l9g$K8B$j!"(B
$B7k2L$N(B@var{n}$BHVL\$N%S%C%H$b(B1$B$K$J$k!#(B
$B0z?t$r;XDj$7$J$$$H(B0$B$rJV$9$,!"$3$l$O$3$N1i;;$N91Ey85$G$"$k!#(B
@code{logior}$B$K0z?t$r(B1$B$D$@$1;XDj$9$k$H$=$N0z?t$rJV$9!#(B

@smallexample
@group
@c                    ; @r{              28-bit binary values}
                   ; @r{               28$B%S%C%H(B2$B?JCM(B}

(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}
@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}
@end group
@end smallexample
@end defun

@defun logxor &rest ints-or-markers
@c @cindex bitwise exclusive or
@c @cindex logical exclusive or
@cindex $B%S%C%H$4$H$NGSB>E*O@M}OB(B
@cindex $BGSB>E*O@M}OB(B
@c This function returns the ``exclusive or'' of its arguments: the
@c @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
@c set in an odd number of the arguments.  If there are no arguments, the
@c result is 0, which is an identity element for this operation.  If
@c @code{logxor} is passed just one argument, it returns that argument.
$B$3$N4X?t$O0z?t$N!XGSB>E*O@M}OB!Y$rJV$9!#(B
$B$D$^$j!"0z?t$N(B@var{n}$BHVL\$N%S%C%H$,(B1$B$G$"$k$b$N$,4q?t8D$N>l9g$K8B$j!"(B
$B7k2L$N(B@var{n}$BHVL\$N%S%C%H$b(B1$B$K$J$k!#(B
$B0z?t$r;XDj$7$J$$$H(B0$B$rJV$9$,!"$3$l$O$3$N1i;;$N91Ey85$G$"$k!#(B
@code{logxor}$B$K0z?t$r(B1$B$D$@$1;XDj$9$k$H$=$N0z?t$rJV$9!#(B

@smallexample
@group
@c                    ; @r{              28-bit binary values}
                   ; @r{              28$B%S%C%H(B2$B?JCM(B}

(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}
@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}
@end group
@end smallexample
@end defun

@defun lognot integer
@c @cindex logical not
@c @cindex bitwise not
@cindex $BO@M}H]Dj(B
@cindex $B%S%C%H$4$H$NH]Dj(B
@c This function returns the logical complement of its argument: the @var{n}th
@c bit is one in the result if, and only if, the @var{n}th bit is zero in
@c @var{integer}, and vice-versa.
$B$3$N4X?t$O0z?t$NO@M}E*$JJd?t$rJV$9!#(B
$B$D$^$j!"(B@var{integer}$B$N(B@var{n}$BHVL\$N%S%C%H$,(B0$B$G$"$k>l9g$K8B$j!"(B
$B7k2L$N(B@var{n}$BHVL\$N%S%C%H$O(B1$B$K$J$k!#(B

@example
(lognot 5)             
     @result{} -6
;;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
;; @r{becomes}
;; -6  =  @r{1111  1111 1111  1111 1111  1111 1010}
@end example
@end defun

@node Math Functions
@c @section Standard Mathematical Functions
@section $BI8=`?t3X4X?t(B
@c @cindex transcendental functions
@c @cindex mathematical functions
@cindex $B;03Q4X?t(B
@cindex $B?t3X4X?t(B

@c   These mathematical functions allow integers as well as floating point
@c numbers as arguments.
$B$3$l$i$N?t3X4X?t$OIbF0>.?tE@?t$K2C$($F@0?t$b0z?t$H$7$F<u$1IU$1$^$9!#(B

@defun sin arg
@defunx cos arg
@defunx tan arg
@c These are the ordinary trigonometric functions, with argument measured
@c in radians.
$B$3$l$i$OIaDL$N;03Q4X?t$G$"$j!"0z?t$O8LEYK!$GI=$9!#(B
@end defun

@defun asin arg
@c The value of @code{(asin @var{arg})} is a number between @minus{}pi/2
@c and pi/2 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
@c is out of range (outside [-1, 1]), then the result is a NaN.
@code{(asin @var{arg})}$B$NCM$O(B@minus{}pi/2$B$+$i(Bpi/2$B$^$G$N?t$G$"$j!"(B
$B$=$N@589!J(Bsin$B!K$O(B@var{arg}$B$KEy$7$$!#(B
$B$7$+$7!"(B@var{arg}$B$,!J(B[-1, 1]$B$N!KHO0O$r1[$($F$$$k$H7k2L$O(BNaN$B!#(B
@end defun

@defun acos arg
@c The value of @code{(acos @var{arg})} is a number between 0 and pi
@c (inclusive) whose cosine is @var{arg}; if, however, @var{arg}
@c is out of range (outside [-1, 1]), then the result is a NaN.
@code{(acos @var{arg})}$B$NCM$O(B0$B$+$i(Bpi$B$^$G$N?t$G$"$j!"(B
$B$=$NM>89!J(Bcos$B!K$O(B@var{arg}$B$KEy$7$$!#(B
$B$7$+$7!"(B@var{arg}$B$,!J(B[-1, 1]$B$N!KHO0O$r1[$($F$$$k$H7k2L$O(BNaN$B!#(B
@end defun

@defun atan arg
@c The value of @code{(atan @var{arg})} is a number between @minus{}pi/2
@c and pi/2 (exclusive) whose tangent is @var{arg}.
@code{(atan @var{arg})}$B$NCM$O(B@minus{}pi/2$B$+$i(Bpi/2$B$^$G$N?t$G$"$j!"(B
$B$=$N@5@\!J(Btan$B!K$O(B@var{arg}$B$KEy$7$$!#(B
@end defun

@defun exp arg
@c This is the exponential function; it returns
$B$3$l$O;X?t4X?t$G$"$j!"(B
@tex
$e$
@end tex
@ifinfo
@i{e}
@end ifinfo
@c to the power @var{arg}.
$B$N(B@var{arg}$B>h$rJV$9!#(B
@tex
$e$
@end tex
@ifinfo
@i{e}
@end ifinfo
@c is a fundamental mathematical constant also called the base of natural
@c logarithms.
$B$O?t3X$N4pK\Dj?t$G$"$j!"<+A3BP?t$NDl$H$b8F$V!#(B
@end defun

@defun log arg &optional base
@c This function returns the logarithm of @var{arg}, with base @var{base}.
@c If you don't specify @var{base}, the base
$B$3$N4X?t$O(B@var{arg}$B$N(B@var{base}$B$rDl$H$9$kBP?t$rJV$9!#(B
@var{base}$B$r;XDj$7$J$1$l$P!"Dl$H$7$F(B
@tex
$e$
@end tex
@ifinfo
@i{e}
@end ifinfo
@c is used.  If @var{arg}
@c is negative, the result is a NaN.
$B$r;H$&!#(B
@var{arg}$B$,Ii$G$"$k$H7k2L$O(BNaN$B!#(B
@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
@c This function returns the logarithm of @var{arg}, with base 10.  If
@c @var{arg} is negative, the result is a NaN.  @code{(log10 @var{x})}
@c @equiv{} @code{(log @var{x} 10)}, at least approximately.
$B$3$N4X?t$O(B@var{arg}$B$N(B10$B$rDl$H$9$kBP?t$rJV$9!#(B
@var{arg}$B$,Ii$G$"$k$H7k2L$O(BNaN$B!#(B
$B>/$J$/$H$b8m:9$r9MN8$9$l$P!"(B
@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}$B!#(B
@end defun

@defun expt x y
@c This function returns @var{x} raised to power @var{y}.  If both
@c arguments are integers and @var{y} is positive, the result is an
@c integer; in this case, it is truncated to fit the range of possible
@c integer values.
$B$3$N4X?t$O(B@var{x}$B$N(B@var{y}$B>h$rJV$9!#(B
$B$I$A$i$N0z?t$b@0?t$G$"$j(B@var{y}$B$,@5$J$i$P!"7k2L$O@0?t!#(B
$B$3$N>l9g!"7k2L$O@0?tCM$N2DG=$JHO0O$K@Z$j5M$a$i$l$k!#(B
@end defun

@defun sqrt arg
@c This returns the square root of @var{arg}.  If @var{arg} is negative,
@c the value is a NaN.
$B$3$N4X?t$O(B@var{arg}$B$NJ?J}:,$rJV$9!#(B
@var{arg}$B$,Ii$G$"$k$HCM$O(BNaN$B!#(B
@end defun

@node Random Numbers
@c @section Random Numbers
@section $BMp?t(B
@c @cindex random numbers
@cindex $BMp?t(B

@c A deterministic computer program cannot generate true random numbers.
@c For most purposes, @dfn{pseudo-random numbers} suffice.  A series of
@c pseudo-random numbers is generated in a deterministic fashion.  The
@c numbers are not truly random, but they have certain properties that
@c mimic a random series.  For example, all possible values occur equally
@c often in a pseudo-random series.
$B7hDjO@E*$J7W;;5!%W%m%0%i%`$O??$NMp?t$rH/@8$G$-$^$;$s!#(B
$B$7$+$7!"$[$H$s$I$NL\E*$K$O(B@dfn{$B5?;wMp?t(B}$B!J(Bpseudo-random numbers$B!K$G==J,$G$9!#(B
$B0lO"$N5?;wMp?t$r7hDjO@E*$JJ}K!$G@8@.$7$^$9!#(B
$B$=$l$i$N?t$O??$NMp?t$G$O$"$j$^$;$s$,!"(B
$BMp?tNs$N$"$k<o$N@-<A$K;w$?@-<A$,$"$j$^$9!#(B
$B$?$H$($P!"5?;wMp?tNs$G$b$9$Y$F$N2DG=$J?t$,$7$P$7$PEy$7$/@85/$7$^$9!#(B

@c In Emacs, pseudo-random numbers are generated from a ``seed'' number.
@c Starting from any given seed, the @code{random} function always
@c generates the same sequence of numbers.  Emacs always starts with the
@c same seed value, so the sequence of values of @code{random} is actually
@c the same in each Emacs run!  For example, in one operating system, the
@c first call to @code{(random)} after you start Emacs always returns
@c -1457731, and the second one always returns -7692030.  This
@c repeatability is helpful for debugging.
Emacs$B$G$O!"5?;wMp?t$O!X<o!Y$H$J$k?t$+$i@8@.$7$^$9!#(B
$B;XDj$7$?G$0U$N<o$+$i;O$a$F$b!"4X?t(B@code{random}$B$OF1$8?t$NNs$r@8@.$7$^$9!#(B
Emacs$B$O$D$M$KF1$8<o$NCM$G7W;;$7;O$a$k$?$a!"(B
$B$=$l$>$l$N(BEmacs$B$N<B9T$G$b(B@code{random}$B$O<B:]$K$OF1$8?t$NNs$r@8@.$7$^$9!#(B
$B$?$H$($P!"$"$k%*%Z%l!<%F%#%s%0%7%9%F%`$G!"(B
Emacs$B3+;OD>8e$K(B@code{random}$B$r8F$V$H$D$M$K(B-1457731$B$rJV$7!"(B
$B$D$.$K8F$V$H$D$M$K(B-7692030$B$rJV$7$^$9!#(B
$B$3$N$h$&$J:F8=@-$O%G%P%C%0$K$OM-Mx$G$9!#(B

@c If you want truly unpredictable random numbers, execute @code{(random
@c t)}.  This chooses a new seed based on the current time of day and on
@c Emacs's process @sc{id} number.
$BM=B,IT2DG=$JMp?t$,I,MW$J$i$P(B@code{(random t)}$B$r<B9T$7$^$9!#(B
$B$3$l$O!"8=:_;~9o$H(BEmacs$B%W%m%;%9$N(B@sc{id}$BHV9f$K4p$E$$$F!"(B
$B?7$?$J<o$NCM$rA*$S$^$9!#(B

@defun random &optional limit
@c This function returns a pseudo-random integer.  Repeated calls return a
@c series of pseudo-random integers.
$B$3$N4X?t$O5?;wMp?t$N@0?t$rJV$9!#(B
$B7+$jJV$78F$S=P$9$H0lO"$N5?;wMp?t$N@0?t$rJV$9!#(B

@c If @var{limit} is a positive integer, the value is chosen to be
@c nonnegative and less than @var{limit}.
@var{limit}$B$,@5@0?t$J$i$P!"HsIi$G(B@var{limit}$BL$K~$K$J$k$h$&$KCM$rA*$V!#(B

@c If @var{limit} is @code{t}, it means to choose a new seed based on the
@c current time of day and on Emacs's process @sc{id} number.
@var{limit}$B$,(B@code{t}$B$J$i$P!"(B
$B8=:_;~9o$H(BEmacs$B%W%m%;%9$N(B@sc{id}$BHV9f$K4p$E$$$F!"(B
$B?7$?$J<o$NCM$rA*$V$3$H$r0UL#$9$k!#(B
@c "Emacs'" is incorrect usage!

@c On some machines, any integer representable in Lisp may be the result
@c of @code{random}.  On other machines, the result can never be larger
@c than a certain maximum or less than a certain (negative) minimum.
@code{random}$B$N7k2L$O!"(BLisp$B$K$*$$$FI=8=2DG=$JG$0U$N@0?t$K$J$k7W;;5!$b$"$k!#(B
$BB>$N7W;;5!$G$O!"7k2L$O$"$k:GBgCM$H!JIi?t!K:G>.CM$N$"$$$@$K$"$k!#(B
@end defun