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 83cee10f8993d0ff6dd6ae5658a0faa84bb1c68c..16d175c338bcdfd98c7cccd4a5092554352c6873 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,12 @@
+2011-06-03  Paul Eggert  <eggert@cs.ucla.edu>
+
+       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  <larsi@gnus.org>
 
        * processes.texi (Process Information): Document

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 72f39f681ae713463637ee53435b0d47b70bf33f..ed2823495731a2fad78e3fdd123ada4d3a079370 100644 (file)
--- 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 2c73a03a26c5f90c6d201ef88762bf369900fb0a..ff057c22254e150957621031b9670d162803c984 100644 (file)
--- 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 c58d54f13fc8f74839dce7e4874de118a6bf9a37..d5aa51098e74e2bf532ad0fe9de35f8f24d5cbb2 100644 (file)
--- 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 b226d67646261d18aa4de588be166d7412a02a85..5f422065c5b59ec892aa4879d8fa09aa75b58276 100644 (file)
--- 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