⟦a405208ae⟧

TextFile

@setfilename ../info/numbers
@node Numbers, Strings and Characters, Types of Lisp Object, Top
@chapter Numbers

@cindex integers
Integers  are the one kind of number in version 18 Emacs Lisp.  These
are whole numbers such as @minus{}3, 0, 7, 13, and 511.

In version 19, there is a compile time option to support floating point
numbers, which are represented internally as the C type @code{double}.
A floating point number is a number with a fractional part, such as
@minus{}4.5, 0.0, or 2.71828.  A floating point number can be expressed in
an exponetial notation as well: thus, 1.5e2 equals 150; in this example,
`e2' stands for ten to the second power, and is multiplied by 1.5.


@menu
* Number Basics::	
* Predicates on Numbers::	
* Comparison of Numbers::	
* Arithmetic Operations::	
* Bitwise Operations on Integers::	
* Random Numbers::	
@end menu

@node Number Basics, Predicates on Numbers, Numbers, Numbers
@comment  node-name,  next,  previous,  up
@section Number Basics

The range of values for a small integer depends on the machine.  The
range is @minus{}8388608 to 8388607 (24 bits; i.e.,
@ifinfo 
-2**24 
@end ifinfo
@tex 
$-2^{24}$ 
@end tex
to 
@ifinfo 
2**24 - 1
@end ifinfo
@tex 
$2^{24}-1$
@end tex
) on most
machines, but on others it is @minus{}16777216 to 16777215
(25 bits), or @minus{}33554432 to 33554431 (26 bits).  All
of the examples shown below assume an integer has 24 bits.@refill
@cindex overflow

The Lisp reader reads numbers as a sequence of digits with an optional
sign.

@example
1                ; @r{The integer 1.}
+1               ; @r{Also the integer 1.}
-1               ; @r{The integer -1.}
16777217         ; @r{Also the integer 1, due to overflow.}
0                ; @r{The number 0.}
-0               ; @r{The number 0.}
1.               ; @r{Invalid syntax.}
@end example

  To understand how various functions work on integers, especially the
bitwise operators (@pxref{Bitwise Operations on Integers}), it is often
helpful to view the numbers in their binary form.

  In 24 bit binary, the decimal integer 5 looks like this:

@example
0000 0000  0000 0000  0000 0101
@end example

@noindent
(In the example, a space is put every 4 bits, and two spaces every 8
bits, to make the binary integer easier to read.)

  The negative integer, @minus{}1, looks like this:

@example
1111 1111  1111 1111  1111 1111
@end example

@noindent
@minus{}1 is represented as 24 ones.  (In jargon, this is called
`@dfn{two's complement} notation.)

  The negative integer, @minus{}5, is creating by subtracting 4 from
@minus{}1.  In binary, the decimal integer 4 is 100.  Consequently,
@minus{}5 looks like this:

@example
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, this number looks like this:

@example
0111 1111  1111 1111  1111 1111
@end example

@noindent
This binary number consists of all 1's, except for the left-most digit, which
is zero.  

  As we said before, the arithmetic functions do not check whether
integers go outside their range; hence, when you add 1 to 8,388,607, the
negative integer @minus{}8,388,608 is returned:

@example
(+ 1 8388607)
     @result{} -8388608
     @result{} 1000 0000  0000 0000  0000 0000
@end example

@cindex markers
  Many of the following functions accept markers for arguments as well
as integers.  (@xref{Markers}.)  More accurately, the actual parameters
to such functions may be integers or markers; and @var{marker-or-int}
specifies the formal parameter.  When the actual parameter is a marker,
the position value of the marker is used and the buffer of the marker is
ignored.

  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.

@node Predicates on Numbers, Comparison of Numbers, Number Basics, Numbers
@section Type Predicates for Numbers

  The @code{integerp} and @code{floatp} predicates test whether the
argument is an integer or floating point number, respectively.  Note
that these functions and the @code{natnump} predicate can take any type
of Lisp object as argument (the predicates would not be of much use
otherwise); but the @code{zerop} predicate requires an integer as
its argument.

@defun floatp object

This predicate tests to see whether its argument is a floating point
number and returns @code{t} if so, @code{nil} otherwise.

@code{floatp} is part of version 19 Emacs, not version 18.

@end defun

@defun integerp object

This predicate tests to see whether its argument is an integer (a whole number)
and returns @code{t} if so, @code{nil} otherwise.

@end defun

@defun natnump 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 (i.e., natural) 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}.

@end defun

@defun zerop integer

This predicate tests to see whether its argument is zero, and returns @code{t}
if so, @code{nil} otherwise.  These two forms are equivalent: @code{(zerop x)
@equiv{} (= x 0)}.

@end defun

@node Comparison of Numbers, Arithmetic Operations, Predicates on Numbers, Numbers
@section Comparison of Numbers

@cindex number equality
  The integer type is implemented by storing the value in the ``pointer
part'' of a Lisp object pointer (which, in the canonical case, has 24
bits of pointer, 7 bits of type and 1 bit for the garbage collector).
Because of this, the function @code{eq} will return @code{t} for
two integers with the same value.  @xref{Equality Predicates}.

@quotation
@cindex Common Lisp numbers
@b{Common Lisp Note:} Because of the way numbers are implemented in
Common Lisp, you generally need to use @samp{@code{=}} to test for
equality between numbers.  However, GNU Emacs Lisp does not need very
large integers; as a consequence, it is possible to restrict them to the
size of a single word, allowing @code{eq} to be used.
@end quotation

@defun = marker-or-int1 marker-or-int2
This function tests to see whether its arguments are the same number, and
returns @code{t} if so, @code{nil} otherwise.
@end defun

@defun /= marker-or-int1 marker-or-int2
This function tests to see whether its arguments are not the same number, and
returns @code{t} if so, @code{nil} otherwise.
@end defun

@defun <  marker-or-int1 marker-or-int2
  This function tests to see whether its first argument is strictly less than
its second argument.  It returns @code{t} if so, @code{nil} otherwise.
@end defun

@defun <=  marker-or-int1 marker-or-int2
  This function tests to see whether its first argument is less than or equal
to its second argument.  It returns @code{t} if so, @code{nil}
otherwise.
@end defun

@defun >  marker-or-int1 marker-or-int2
  This function tests to see whether its first argument is strictly greater
than its second argument.  It returns @code{t} if so, @code{nil}
otherwise.
@end defun

@defun >=  marker-or-int1 marker-or-int2
  This function tests to see whether its first argument is greater than or
equal to its second argument.  It returns @code{t} if so, @code{nil}
otherwise.
@end defun

@defun max marker-or-int &rest marker-or-ints
This function returns the largest of its arguments.

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

@defun min marker-or-int &rest marker-or-ints
This function returns the smallest of its arguments.
@end defun

@node Arithmetic Operations, Bitwise Operations on Integers, Comparison of Numbers, Numbers
@section Arithmetic Operations

  Emacs Lisp provides the traditional four arithmetic operations:
addition, subtraction, multiplication, and division.  A remainder
function supplements the (integer) division function.  In addition, as
a convenience, incrementing and decrementing functions are provided.

  It is important to note that in GNU Emacs Lisp, arithmetic functions
do not check for overflow.  Thus (1+ 8388607) may equal
@minus{}8388608, depending on your hardware.

@defun 1+ marker-or-int
This function adds one to @var{marker-or-int}.
@end defun

@defun 1- marker-or-int
  This function subtracts one from @var{marker-or-int}.
@end defun

@defun + &rest integers
  This function adds its arguments together.  When given no arguments,
@code{+} returns 0.  It does not check for overflow.

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

@defun - &optional integer &rest other-integers
The @code{@minus{}} function serves two purposes: negation and
subtraction.

When @code{@minus{}} has a single argument, the value is the
negative of the argument.

When there are multiple arguments, each of the @var{other-integers} is
subtracted from @var{integer}, cumulatively.
If there are no arguments, the result is @code{0}.

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

@defun * &rest integers
  This function multiplies its arguments together, and returns the
product.  When given no arguments, @code{*} returns @code{1}.  It does
not check for overflow.

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

@defun / dividend divisor &rest other-integers
  This function divides @var{dividend} by @var{divisor}, and returns the
quotient.  If there are more arguments, then they are each used to
divide the previous result.  The result is always rounded down after
each division.@refill

@cindex arith-error in division
If you divide a numerator by @code{0}, an @code{arith-error} results.
(@xref{Errors}.)

@example
(/ 6 2)
     @result{} 3
(/ 5 2)
     @result{} 2
(/ 25 3 2)
     @result{} 4
(/ -17 6)
     @result{} -2          ; @r{(Could be -3 on some machines.)}
@end example
@end defun

@defun % dividend divisor

@cindex modulus
This function returns the value of @var{dividend} modulo @var{divisor},
or in other words, the integer remainder after division of @var{dividend} by
@var{divisor}.  The sign of the result is the sign of @var{dividend}.
The sign of @var{divisor} is ignored.

An @code{arith-error} results if @var{divisor} = @code{0}.

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

@node Bitwise Operations on Integers, Random Numbers, Arithmetic Operations, Numbers
@section Bitwise Operations on Integers
@cindex bitwise operations

  In a computer, an integer is a binary number, a pattern of zeros and ones.
A bitwise operation transforms such a pattern.  For example, a shift
moves the whole pattern left or right one or more places, reproducing
the same pattern `moved over'.  

  The following bitwise operations apply only to integers.

@defun lsh integer1 integer2
@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
bits in @var{integer1} to the left @var{integer2} places, or to the
right if @var{integer2} is negative.  If both arguments are negative,
@code{lsh} shifts in zeros.  See @code{ash} below.

Thus, the decimal number 5 is the binary number @samp{00000101}.  Shifted
once to the left, with a zero put in the one's place, the number becomes
@samp{00001010}, decimal 10.

Here are two examples of shifting the pattern of bits one place to the
left.  Since the contents of the right-most place has been moved one
place to the left, a value has to be inserted into the right-most
place.  With @code{lsh}, a zero is placed into the right-most place.
(In these examples, the binary pattern is only eight bits long.  See
@code{ash} for examples illustrating the full twenty-four bits of an
Emacs Lisp integer.)

@group
@example
(lsh 5 1)
     @result{} 10

00000101 @result 00001010     ; @r{Decimal 5 becomes decimal 10.}

(lsh 7 1)
     @result{} 14

00000111 @result{} 00001110     ; @r{Decimal 7 becomes decimal 14.}
@end example
@end group

@noindent
As the examples illustrate, shifting the pattern of bits one place to
the left produces a number that is twice the value of the previous
number.

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:

@example
(lsh 8388607 1)         ; @r{left shift}
     @result{} -2
@end example

In binary, in the 24 bit implementation, 

@example
0111 1111  1111 1111  1111 1111         ; @r{decimal 8,388,607}

@r{becomes}

1111 1111  1111 1111  1111 1110         ; @r{decimal @minus{}2}
@end example

Shifting the pattern of bits two places to the left produces results
like this (with 8-bit binary numbers):

@group
@example
(lsh 3 2)
     @result{} 12

00000011 @result{} 00001100       ; @r{Decimal 3 becomes decimal 12.}
@end example
@end group

On the other hand, shifting the pattern of bits one place to the right
looks like this:

@group
@example
(lsh 6 -1)
     @result{} 3

00000110 @result{} 00000011       ; @r{Decimal 6 becomes decimal 3.}

(lsh 5 -1)
     @result{} 2

00000101 @result{} 00000010       ; @r{Decimal 5 becomes decimal 2.}
@end example
@end group

@noindent
As the example illustrates, shifting the pattern of bits one place to
the right divides the value of the binary number in half (or less then
half if the orignal right-most digit is a 1 that is lost).

@end defun

@defun ash integer1 integer2
@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
to the left @var{integer2} places, or to the right if @var{integer2}
is negative.

  @code{ash} gives the same results as @code{lsh} except when
@var{integer1} and @var{integer2} are both negative.  In that case,
@code{ash} puts a one in the left-most position, while @code{lsh} puts
a zero in the left-most position.

Thus, with @code{ash}, shifting the pattern of bits one place to the right
looks like this:

@group
@example
(ash -6 -1)
     @result{} -3                    ; @r{Decimal -6 becomes decimal -3.}

1111 1111  1111 1111  1111 1010
     @result{} 
1111 1111  1111 1111  1111 1101
@end example
@end group

In contrast, shifting the pattern of bits one place to the right with
@code{lsh} looks like this:

@group
@example
(lsh -6 -1)
     @result{} 8388605        ; @r{Decimal -6 becomes decimal 8,288,605.}

1111 1111  1111 1111  1111 1010
     @result{} 
0111 1111  1111 1111  1111 1101
@end example
@end group

@noindent
In this case, the 1 in the left-most position is shifted one place to the
right, and a zero is shifted into the left-most position.

Here are other examples:

@example
                       ;              24-bit binary values

(lsh 5 2)              ; @r{ 5  =  0000 0000  0000 0000  0000 0101}
     @result{} 20            ; @r{20  =  0000 0000  0000 0000  0001 0100}
(ash 5 2)
     @result{} 20
(lsh -5 2)             ; @r{-5  =  1111 1111  1111 1111  1111 1011}
     @result{} -20           ; @r{-20  =  1111 1111  1111 1111  1110 1100}
(ash -5 2)
     @result{} -20

(lsh 5 -2)             ; @r{ 5  =  0000 0000  0000 0000  0000 0101}
     @result{} 1             ; @r{ 1  =  0000 0000  0000 0000  0000 0001}
(ash 5 -2)
     @result{} 1
(lsh -5 -2     )       ; @r{-5  =  1111 1111  1111 1111  1111 1011}
     @result{} 4194302       ; @r{   0011 1111  1111 1111  1111 1110}
(ash -5 -2)            ; @r{-5  =  1111 1111  1111 1111  1111 1011}
     @result{} -2            ; @r{-2  =  1111 1111  1111 1111  1111 1110}
@end example
@end defun

@defun logand &rest marker-or-ints
@cindex logical and
@cindex bitwise and
  This function returns the ``logical and'' of the arguments: the
@var{n}'th bit is set in the result if, and only if, the @var{n}'th bit
is set in all the arguments.  ``Set'' means that the value of the bit is
1 rather than 0.

For example, using 4-bit binary numbers, the ``logical and'' of 13 and
12 is 12:

@group
@example
1101
1100
     @result{} 1100
@end example
@end group

@noindent
In both the binary numbers, the two left-most bits are set (i.e., they
are 1's), so the two left-most bits of the returned value are set.  But
both of the two right-most bits are not set, so the two right-most bits of
the returned value are 0's.

@noindent
Restating that example in decimal numbers,

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

  If @code{logand} is not passed any argument, it returns a value of
@code{-1}, the number which consists entirely of ones.  

  For @code{logand}, @code{logior}, and @code{logxor}, if there is only
one argument, that argument is the result.

@example
                       ;                24-bit binary values

(logand 14 13)         ; @r{14  =  0000 0000  0000 0000  0000 1110}
                       ; @r{13  =  0000 0000  0000 0000  0000 1101}
     @result{} 12            ; @r{12  =  0000 0000  0000 0000  0000 1100}

(logand 14 13 4)       ; @r{14  =  0000 0000  0000 0000  0000 1110}
                       ; @r{13  =  0000 0000  0000 0000  0000 1101}
     @result{} 4             ; @r{ 4  =  0000 0000  0000 0000  0000 0100}

(logand)
-1                     ; @r{-1  =  1111 1111  1111 1111  1111 1111}
@end example
@end defun

@defun logior &rest marker-or-ints
@cindex logical inclusive or
@cindex bitwise or
  This function returns the ``inclusive or'' of it arguments: the n'th
bit is set in the result if, and only if, the n'th bit is set in at
least one of the arguments.  If there are no arguments, the result is
@code{0}.

@example
                       ;               24-bit binary values

(logior 12 5)          ; @r{12  =  0000 0000  0000 0000  0000 1100}
                       ; @r{ 5  =  0000 0000  0000 0000  0000 0101}
     @result{} 13            ; @r{13  =  0000 0000  0000 0000  0000 1101}

(logior 12 5 7)        ; @r{12  =  0000 0000  0000 0000  0000 1100}
                       ; @r{ 5  =  0000 0000  0000 0000  0000 0101}
                       ; @r{ 7  =  0000 0000  0000 0000  0000 0111}
     @result{} 15            ; @r{15  =  0000 0000  0000 0000  0000 1111}
@end example
@end defun

@defun logxor &rest marker-or-ints
@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.

@example
                       ;               24-bit binary values

(logxor 12 5)          ; @r{12  =  0000 0000  0000 0000  0000 1100}
                       ; @r{ 5  =  0000 0000  0000 0000  0000 0101}
     @result{} 9             ; @r{ 9  =  0000 0000  0000 0000  0000 1001}

(logxor 12 5 7)        ; @r{12  =  0000 0000  0000 0000  0000 1100}
                       ; @r{ 5  =  0000 0000  0000 0000  0000 0101}
                       ; @r{ 7  =  0000 0000  0000 0000  0000 0111}
     @result{} 14            ; @r{14  =  0000 0000  0000 0000  0000 1110}
@end example
@end defun

@defun lognot integer
@cindex logical not
@cindex bitwise not
  This function returns the logical complement of its argument: the @var{n}'th
bit is one in the result if, and only if, the @var{n}'th bit is zero in
@var{integer}, and vice-versa.

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

@node Random Numbers,  , Bitwise Operations on Integers, Numbers
@section Random Numbers

@cindex random numbers

@defun random &optional flag

  This function returns a pseudo-random number of type integer.  When
called more than once, this function returns a series of
pseudo-random numbers.

  In a computer, such a series of a pseudo-random numbers is generated in
a deterministic fashion.  As its name indicates, a pseudo-random number
is not a random number.  However, a pseudo-random series of numbers has
properties that mimic a truly random series in many ways.  For example,
in a pseudo-random series, no number is supposed to appear more
frequently that it would in a truly random series.

  A series of pseudo-random numbers is generated from a `seed' number
that is derived from some changing value such as the time of day.  If
the @code{random} function starts with the same seed, it generates the
same sequence of numbers.

  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.

  When a pseudo-random series of numbers is generated, any of the possible
values has the same probability of being returned as any other possible
value.

  If you want random numbers that are different each time you run Emacs,
use @code{(random t)} in your code at least once.  This reinitializes the
pseudo-random number seed based on the current time of day and on Emacs'
process ID number.

Put another way, the sequence of numbers returned by @code{random} is
the same in each Emacs run, unless you use @code{(random t)}.  For
example, in one operating system, the first call to @code{(random)}
after you start Emacs always returns @code{-1457731}, and the second one
always returns @code{-7692030}.  Therefore, programs that use
@code{random} are repeatable, unless you evaluate @code{(random t)}.
This is helpful when you are debugging.
@end defun
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦a405208ae⟧ TextFile

Derivation

TextFile
