From: Paul Eggert Date: Fri, 3 Jun 2011 18:49:33 +0000 (-0700) Subject: Document wide integers better. X-Git-Tag: emacs-pretest-24.0.90~104^2~618^2~8^2~7 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=be14b9ab109c8deb5745dc47cbc471e97be06486;p=emacs.git Document wide integers better. * files.texi (File Attributes): Document ino_t values better. * numbers.texi (Integer Basics, Integer Basics, Arithmetic Operations): (Bitwise Operations): * objects.texi (Integer Type): Integers are typically 62 bits now. * os.texi (Time Conversion): Document time_t values better. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 83cee10f899..16d175c338b 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,12 @@ +2011-06-03 Paul Eggert + + Document wide integers better. + * files.texi (File Attributes): Document ino_t values better. + * numbers.texi (Integer Basics, Integer Basics, Arithmetic Operations): + (Bitwise Operations): + * objects.texi (Integer Type): Integers are typically 62 bits now. + * os.texi (Time Conversion): Document time_t values better. + 2011-05-31 Lars Magne Ingebrigtsen * processes.texi (Process Information): Document diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 72f39f681ae..ed282349573 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1236,12 +1236,13 @@ deleted and recreated; @code{nil} otherwise. @item The file's inode number. If possible, this is an integer. If the -inode number is too large to be represented as an integer in Emacs -Lisp, but still fits into a 32-bit integer, then the value has the -form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 -bits. If the inode is wider than 32 bits, the value is of the form +inode number @math{N} is too large to be represented as an integer in +Emacs Lisp, but @math{N / 2^16} is representable, then the value has +the form @code{(@var{high} . @var{low})}, where @var{high} holds the +high bits (i.e., excluding the low-order bits) and @var{low} the low +16 bits. If the inode number is even larger, the value is of the form @code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds -the high 24 bits, @var{middle} the next 24 bits, and @var{low} the low +the high bits, @var{middle} the next 24 bits, and @var{low} the low 16 bits. @item diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index 2c73a03a26c..ff057c22254 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -36,22 +36,24 @@ 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{}536870912 to 536870911 (30 bits; i.e., +typical range is @minus{}2305843009213693952 to 2305843009213693951 +(62 bits; i.e., @ifnottex --2**29 +-2**61 @end ifnottex @tex -@math{-2^{29}} +@math{-2^{61}} @end tex to @ifnottex -2**29 - 1), +2**61 - 1) @end ifnottex @tex -@math{2^{29}-1}), +@math{2^{61}-1}) @end tex -but some machines may provide a wider range. Many examples in this -chapter assume an integer has 30 bits. +but some older machines provide only 30 bits. Many examples in this +chapter assume that an integer has 62 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 @@ -63,7 +65,8 @@ Emacs range is treated as a floating-point number. 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 1073741825 ; @r{The floating point number 1073741825.0.} + 4611686018427387904 + ; @r{The floating point number 4.611686018427388e+18.} 0 ; @r{The integer 0.} -0 ; @r{The integer 0.} @end example @@ -94,25 +97,21 @@ from 2 to 36. For example: bitwise operators (@pxref{Bitwise Operations}), it is often helpful to view the numbers in their binary form. - In 30-bit binary, the decimal integer 5 looks like this: + In 62-bit binary, the decimal integer 5 looks like this: @example -00 0000 0000 0000 0000 0000 0000 0101 +0000...000101 (62 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 integer @minus{}1 looks like this: @example -11 1111 1111 1111 1111 1111 1111 1111 +1111...111111 (62 bits total) @end example @noindent @cindex two's complement -@minus{}1 is represented as 30 ones. (This is called @dfn{two's +@minus{}1 is represented as 62 ones. (This is called @dfn{two's complement} notation.) The negative integer, @minus{}5, is creating by subtracting 4 from @@ -120,24 +119,24 @@ complement} notation.) @minus{}5 looks like this: @example -11 1111 1111 1111 1111 1111 1111 1011 +1111...111011 (62 bits total) @end example - In this implementation, the largest 30-bit binary integer value is -536,870,911 in decimal. In binary, it looks like this: + In this implementation, the largest 62-bit binary integer value is +2,305,843,009,213,693,951 in decimal. In binary, it looks like this: @example -01 1111 1111 1111 1111 1111 1111 1111 +0111...111111 (62 bits total) @end example Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 536,870,911, the value is the -negative integer @minus{}536,870,912: +outside their range, when you add 1 to 2,305,843,009,213,693,951, the value is the +negative integer @minus{}2,305,843,009,213,693,952: @example -(+ 1 536870911) - @result{} -536870912 - @result{} 10 0000 0000 0000 0000 0000 0000 0000 +(+ 1 2305843009213693951) + @result{} -2305843009213693952 + @result{} 1000...000000 (62 bits total) @end example Many of the functions described in this chapter accept markers for @@ -508,8 +507,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+ 2305843009213693951)} may +evaluate to @minus{}2305843009213693952, depending on your hardware. @defun 1+ number-or-marker This function returns @var{number-or-marker} plus 1. @@ -829,19 +828,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 -536,870,911 produces @minus{}2 on a 30-bit machine: +2,305,843,009,213,693,951 produces @minus{}2 on a typical machine: @example -(lsh 536870911 1) ; @r{left shift} +(lsh 2305843009213693951 1) ; @r{left shift} @result{} -2 @end example -In binary, in the 30-bit implementation, the argument looks like this: +In binary, in the 62-bit implementation, the argument looks like this: @example @group -;; @r{Decimal 536,870,911} -01 1111 1111 1111 1111 1111 1111 1111 +;; @r{Decimal 2,305,843,009,213,693,951} +0111...111111 (62 bits total) @end group @end example @@ -851,7 +850,7 @@ which becomes the following when left shifted: @example @group ;; @r{Decimal @minus{}2} -11 1111 1111 1111 1111 1111 1111 1110 +1111...111110 (62 bits total) @end group @end example @end defun @@ -874,9 +873,9 @@ looks like this: @group (ash -6 -1) @result{} -3 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -11 1111 1111 1111 1111 1111 1111 1010 +1111...111010 (62 bits total) @result{} -11 1111 1111 1111 1111 1111 1111 1101 +1111...111101 (62 bits total) @end group @end example @@ -885,11 +884,11 @@ In contrast, shifting the pattern of bits one place to the right with @example @group -(lsh -6 -1) @result{} 536870909 -;; @r{Decimal @minus{}6 becomes decimal 536,870,909.} -11 1111 1111 1111 1111 1111 1111 1010 +(lsh -6 -1) @result{} 2305843009213693949 +;; @r{Decimal @minus{}6 becomes decimal 2,305,843,009,213,693,949.} +1111...111010 (62 bits total) @result{} -01 1111 1111 1111 1111 1111 1111 1101 +0111...111101 (62 bits total) @end group @end example @@ -899,34 +898,35 @@ Here are other examples: @c with smallbook but not with regular book! --rjc 16mar92 @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ 62-bit binary values} -(lsh 5 2) ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101} - @result{} 20 ; = @r{00 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{11 1111 1111 1111 1111 1111 1111 1011} - @result{} -20 ; = @r{11 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{00 0000 0000 0000 0000 0000 0000 0101} - @result{} 1 ; = @r{00 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{11 1111 1111 1111 1111 1111 1111 1011} - @result{} 268435454 ; = @r{00 0111 1111 1111 1111 1111 1111 1110} +(lsh -5 -2) ; -5 = @r{1111...111011} + @result{} 1152921504606846974 + ; = @r{0011...111110} @end group @group -(ash -5 -2) ; -5 = @r{11 1111 1111 1111 1111 1111 1111 1011} - @result{} -2 ; = @r{11 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 @@ -961,23 +961,23 @@ because its binary representation consists entirely of ones. If @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ 62-bit binary values} -(logand 14 13) ; 14 = @r{00 0000 0000 0000 0000 0000 0000 1110} - ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101} - @result{} 12 ; 12 = @r{00 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{00 0000 0000 0000 0000 0000 0000 1110} - ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101} - ; 4 = @r{00 0000 0000 0000 0000 0000 0000 0100} - @result{} 4 ; 4 = @r{00 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{11 1111 1111 1111 1111 1111 1111 1111} + @result{} -1 ; -1 = @r{1111...111111} @end group @end smallexample @end defun @@ -991,18 +991,18 @@ passed just one argument, it returns that argument. @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ 62-bit binary values} -(logior 12 5) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101} - @result{} 13 ; 13 = @r{00 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{00 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101} - ; 7 = @r{00 0000 0000 0000 0000 0000 0000 0111} - @result{} 15 ; 15 = @r{00 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 @@ -1016,18 +1016,18 @@ result is 0, which is an identity element for this operation. If @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ 62-bit binary values} -(logxor 12 5) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101} - @result{} 9 ; 9 = @r{00 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{00 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101} - ; 7 = @r{00 0000 0000 0000 0000 0000 0000 0111} - @result{} 14 ; 14 = @r{00 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 @@ -1040,9 +1040,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{00 0000 0000 0000 0000 0000 0000 0101} +;; 5 = @r{0000...000101} (62 bits total) ;; @r{becomes} -;; -6 = @r{11 1111 1111 1111 1111 1111 1111 1010} +;; -6 = @r{1111...111010} (62 bits total) @end example @end defun diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index c58d54f13fc..d5aa51098e7 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -164,25 +164,25 @@ latter are unique to Emacs Lisp. @node Integer Type @subsection Integer Type - The range of values for integers in Emacs Lisp is @minus{}536870912 to -536870911 (30 bits; i.e., + The range of values for integers in Emacs Lisp is +@minus{}2305843009213693952 to 2305843009213693951 (62 bits; i.e., @ifnottex --2**29 +-2**61 @end ifnottex @tex -@math{-2^{29}} +@math{-2^{61}} @end tex to @ifnottex -2**29 - 1) +2**61 - 1) @end ifnottex @tex -@math{2^{29}-1}) +@math{2^{61}-1}) @end tex -on most machines. (Some machines may provide a wider range.) It is -important to note that the Emacs Lisp arithmetic functions do not check -for overflow. Thus @code{(1+ 536870911)} is @minus{}536870912 on most -machines. +on most machines. Some machines may provide a narrower or wider +range; all machines provide at least 30 bits. Emacs Lisp arithmetic +functions do not check for overflow. Thus @code{(1+ +2305843009213693951)} is @minus{}2305843009213693952 on most machines. The read syntax for integers is a sequence of (base ten) digits with an optional sign at the beginning and an optional period at the end. The @@ -195,7 +195,6 @@ leading @samp{+} or a final @samp{.}. 1 ; @r{The integer 1.} 1. ; @r{Also the integer 1.} +1 ; @r{Also the integer 1.} -1073741825 ; @r{Also the integer 1 on a 30-bit implementation.} @end group @end example @@ -203,8 +202,8 @@ leading @samp{+} or a final @samp{.}. As a special exception, if a sequence of digits specifies an integer too large or too small to be a valid integer object, the Lisp reader reads it as a floating-point number (@pxref{Floating Point Type}). -For instance, on most machines @code{536870912} is read as the -floating-point number @code{536870912.0}. +For instance, on most machines @code{2305843009213693952} is read as the +floating-point number @code{2.305843009213694e+18}. @xref{Numbers}, for more information. diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index b226d676462..5f422065c5b 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1193,11 +1193,11 @@ to calendrical information and vice versa. You can get time values from the functions @code{current-time} (@pxref{Time of Day}) and @code{file-attributes} (@pxref{Definition of file-attributes}). - Many operating systems are limited to time values that contain 32 bits + Many 32-bit operating systems are limited to time values that contain 32 bits of information; these systems typically handle only the times from -1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some -operating systems have larger time values, and can represent times far -in the past or future. +1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, 64-bit +and some 32-bit operating systems have larger time values, and can +represent times far in the past or future. Time conversion functions always use the Gregorian calendar, even for dates before the Gregorian calendar was introduced. Year numbers