X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/1bad168e59601c1c843a38b2962e77b29f497f11..8875da1e9284e108386c4e58c638b483f4ced9b5:/doc/lispref/numbers.texi diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index d86e698cc2..65921f444e 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c 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 @@ -20,10 +20,10 @@ exact; they have a fixed, limited amount of precision. @menu * Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. +* 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. +* 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. @@ -36,33 +36,35 @@ exact; they have a fixed, limited amount of precision. @section Integer Basics The range of values for an integer depends on the machine. The -minimum range is @minus{}268435456 to 268435455 (29 bits; i.e., +minimum range is @minus{}536870912 to 536870911 (30 bits; i.e., @ifnottex --2**28 +-2**29 @end ifnottex @tex -@math{-2^{28}} +@math{-2^{29}} @end tex to @ifnottex -2**28 - 1), +2**29 - 1), @end ifnottex @tex -@math{2^{28}-1}), +@math{2^{29}-1}), @end tex -but some machines may provide a wider range. Many examples in this -chapter assume an integer has 29 bits. +but some machines provide a wider range. Many examples in this +chapter assume that an integer has 30 bits and that floating point +numbers are IEEE double precision. @cindex overflow The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. +initial sign and optional final period. An integer that is out of the +Emacs range is treated as a floating-point number. @example 1 ; @r{The integer 1.} 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 536870913 ; @r{Also the integer 1, due to overflow.} + 1073741825 ; @r{The floating point number 1073741825.0.} 0 ; @r{The integer 0.} -0 ; @r{The integer 0.} @end example @@ -93,25 +95,26 @@ from 2 to 36. For example: bitwise operators (@pxref{Bitwise Operations}), it is often helpful to view the numbers in their binary form. - In 29-bit binary, the decimal integer 5 looks like this: + In 30-bit binary, the decimal integer 5 looks like this: @example -0 0000 0000 0000 0000 0000 0000 0101 +0000...000101 (30 bits total) @end example @noindent -(We have inserted spaces between groups of 4 bits, and two spaces -between groups of 8 bits, to make the binary integer easier to read.) +(The @samp{...} stands for enough bits to fill out a 30-bit word; in +this case, @samp{...} stands for twenty 0 bits. Later examples also +use the @samp{...} notation to make binary integers easier to read.) The integer @minus{}1 looks like this: @example -1 1111 1111 1111 1111 1111 1111 1111 +1111...111111 (30 bits total) @end example @noindent @cindex two's complement -@minus{}1 is represented as 29 ones. (This is called @dfn{two's +@minus{}1 is represented as 30 ones. (This is called @dfn{two's complement} notation.) The negative integer, @minus{}5, is creating by subtracting 4 from @@ -119,24 +122,24 @@ complement} notation.) @minus{}5 looks like this: @example -1 1111 1111 1111 1111 1111 1111 1011 +1111...111011 (30 bits total) @end example - In this implementation, the largest 29-bit binary integer value is -268,435,455 in decimal. In binary, it looks like this: + In this implementation, the largest 30-bit binary integer value is +536,870,911 in decimal. In binary, it looks like this: @example -0 1111 1111 1111 1111 1111 1111 1111 +0111...111111 (30 bits total) @end example Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 268,435,455, the value is the -negative integer @minus{}268,435,456: +outside their range, when you add 1 to 536,870,911, the value is the +negative integer @minus{}536,870,912: @example -(+ 1 268435455) - @result{} -268435456 - @result{} 1 0000 0000 0000 0000 0000 0000 0000 +(+ 1 536870911) + @result{} -536870912 + @result{} 1000...000000 (30 bits total) @end example Many of the functions described in this chapter accept markers for @@ -155,6 +158,9 @@ The value of this variable is the smallest integer that Emacs Lisp can handle. It is negative. @end defvar + @xref{Character Codes, max-char}, for the maximum value of a valid +character codepoint. + @node Float Basics @section Floating Point Basics @@ -192,7 +198,7 @@ point values: @samp{1.0e+INF} @item negative infinity @samp{-1.0e+INF} -@item Not-a-number +@item Not-a-number @samp{0.0e+NaN} or @samp{-0.0e+NaN}. @end table @@ -220,6 +226,14 @@ down to an integer. @end example @end defun +@defvar float-e +The mathematical constant @math{e} (2.71828@dots{}). +@end defvar + +@defvar float-pi +The mathematical constant @math{pi} (3.14159@dots{}). +@end defvar + @node Predicates on Numbers @section Type Predicates for Numbers @cindex predicates for numbers @@ -496,8 +510,8 @@ commonly used. if any argument is floating. 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. +do not check for overflow. Thus @code{(1+ 536870911)} may evaluate to +@minus{}536870912, depending on your hardware. @defun 1+ number-or-marker This function returns @var{number-or-marker} plus 1. @@ -817,19 +831,19 @@ 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: +536,870,911 produces @minus{}2 in the 30-bit implementation: @example -(lsh 268435455 1) ; @r{left shift} +(lsh 536870911 1) ; @r{left shift} @result{} -2 @end example -In binary, in the 29-bit implementation, the argument looks like this: +In binary, the argument looks like this: @example @group -;; @r{Decimal 268,435,455} -0 1111 1111 1111 1111 1111 1111 1111 +;; @r{Decimal 536,870,911} +0111...111111 (30 bits total) @end group @end example @@ -839,7 +853,7 @@ which becomes the following when left shifted: @example @group ;; @r{Decimal @minus{}2} -1 1111 1111 1111 1111 1111 1111 1110 +1111...111110 (30 bits total) @end group @end example @end defun @@ -862,9 +876,9 @@ looks like this: @group (ash -6 -1) @result{} -3 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1 1111 1111 1111 1111 1111 1111 1010 +1111...111010 (30 bits total) @result{} -1 1111 1111 1111 1111 1111 1111 1101 +1111...111101 (30 bits total) @end group @end example @@ -873,11 +887,11 @@ In contrast, shifting the pattern of bits one place to the right with @example @group -(lsh -6 -1) @result{} 268435453 -;; @r{Decimal @minus{}6 becomes decimal 268,435,453.} -1 1111 1111 1111 1111 1111 1111 1010 +(lsh -6 -1) @result{} 536870909 +;; @r{Decimal @minus{}6 becomes decimal 536,870,909.} +1111...111010 (30 bits total) @result{} -0 1111 1111 1111 1111 1111 1111 1101 +0111...111101 (30 bits total) @end group @end example @@ -887,34 +901,35 @@ Here are other examples: @c with smallbook but not with regular book! --rjc 16mar92 @smallexample @group - ; @r{ 29-bit binary values} + ; @r{ 30-bit binary values} -(lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100} +(lsh 5 2) ; 5 = @r{0000...000101} + @result{} 20 ; = @r{0000...010100} @end group @group (ash 5 2) @result{} 20 -(lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} - @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100} +(lsh -5 2) ; -5 = @r{1111...111011} + @result{} -20 ; = @r{1111...101100} (ash -5 2) @result{} -20 @end group @group -(lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001} +(lsh 5 -2) ; 5 = @r{0000...000101} + @result{} 1 ; = @r{0000...000001} @end group @group (ash 5 -2) @result{} 1 @end group @group -(lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} - @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110} +(lsh -5 -2) ; -5 = @r{1111...111011} + @result{} 268435454 + ; = @r{0011...111110} @end group @group -(ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} - @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110} +(ash -5 -2) ; -5 = @r{1111...111011} + @result{} -2 ; = @r{1111...111110} @end group @end smallexample @end defun @@ -949,23 +964,23 @@ because its binary representation consists entirely of ones. If @smallexample @group - ; @r{ 29-bit binary values} + ; @r{ 30-bit binary values} -(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} +(logand 14 13) ; 14 = @r{0000...001110} + ; 13 = @r{0000...001101} + @result{} 12 ; 12 = @r{0000...001100} @end group @group -(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} +(logand 14 13 4) ; 14 = @r{0000...001110} + ; 13 = @r{0000...001101} + ; 4 = @r{0000...000100} + @result{} 4 ; 4 = @r{0000...000100} @end group @group (logand) - @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111} + @result{} -1 ; -1 = @r{1111...111111} @end group @end smallexample @end defun @@ -979,18 +994,18 @@ passed just one argument, it returns that argument. @smallexample @group - ; @r{ 29-bit binary values} + ; @r{ 30-bit binary values} -(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} +(logior 12 5) ; 12 = @r{0000...001100} + ; 5 = @r{0000...000101} + @result{} 13 ; 13 = @r{0000...001101} @end group @group -(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} +(logior 12 5 7) ; 12 = @r{0000...001100} + ; 5 = @r{0000...000101} + ; 7 = @r{0000...000111} + @result{} 15 ; 15 = @r{0000...001111} @end group @end smallexample @end defun @@ -1004,18 +1019,18 @@ result is 0, which is an identity element for this operation. If @smallexample @group - ; @r{ 29-bit binary values} + ; @r{ 30-bit binary values} -(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} +(logxor 12 5) ; 12 = @r{0000...001100} + ; 5 = @r{0000...000101} + @result{} 9 ; 9 = @r{0000...001001} @end group @group -(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} +(logxor 12 5 7) ; 12 = @r{0000...001100} + ; 5 = @r{0000...000101} + ; 7 = @r{0000...000111} + @result{} 14 ; 14 = @r{0000...001110} @end group @end smallexample @end defun @@ -1028,9 +1043,9 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in @example (lognot 5) @result{} -6 -;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} +;; 5 = @r{0000...000101} (30 bits total) ;; @r{becomes} -;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010} +;; -6 = @r{1111...111010} (30 bits total) @end example @end defun @@ -1205,7 +1220,3 @@ 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