From: Paul Eggert Date: Mon, 6 Jun 2011 19:43:39 +0000 (-0700) Subject: Merge: Document wide integers better. X-Git-Tag: emacs-pretest-24.0.90~104^2~618^2~8 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=001903b5498d4898455e1a69bff166a9cc699ec0;p=emacs.git Merge: Document wide integers better. --- 001903b5498d4898455e1a69bff166a9cc699ec0 diff --cc doc/emacs/ChangeLog index 89a78263e94,3b61ca6ccba..6e69a96a2a8 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@@ -1,3 -1,9 +1,10 @@@ + 2011-06-02 Paul Eggert + + Document wide integers better. + * buffers.texi (Buffers): - * files.texi (Visiting): Default buffer maximum is now 2 EiB typically. ++ * files.texi (Visiting): Document maxima for 64-bit machines, ++ and mention virtual memory limits. + 2011-05-28 Chong Yidong * custom.texi (Hooks): Reorganize. Mention Prog mode. diff --cc doc/emacs/buffers.texi index ae0d85f249b,ea48be48bf1..d4cc4f7bb6a --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@@ -43,8 -43,12 +43,11 @@@ can be different from the value in othe A buffer's size cannot be larger than some maximum, which is defined by the largest buffer position representable by the @dfn{Emacs integer} data type. This is because Emacs tracks buffer positions - using that data type. For 32-bit machines, the largest buffer size is - 512 megabytes. -using that data type. For 64-bit machines, the maximum buffer size ++using that data type. For typical 64-bit machines, the maximum buffer size + enforced by the data types is @math{2^61 - 2} bytes, or about 2 EiB. -For most 32-bit machines, the maximum is @math{2^31 - 1} bytes, or about 2 GiB. -For some older machines, the maximum is @math{2^29 - 2} bytes, or ++For typical 32-bit machines, the maximum is @math{2^29 - 2} bytes, or + about 512 MiB. Buffer sizes are also limited by the size of Emacs's + virtual memory. @menu * Select Buffer:: Creating a new buffer or reselecting an old one. diff --cc doc/lispref/ChangeLog index 83cee10f899,a22b86cf36b..54ad6abdb07 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@@ -1,3 -1,14 +1,15 @@@ + 2011-06-03 Paul Eggert + + Document wide integers better. + * files.texi (File Attributes): Document ino_t values better. + ino_t values no longer map to anything larger than a single cons. - + * numbers.texi (Integer Basics, Integer Basics, Arithmetic Operations): + (Bitwise Operations): - * objects.texi (Integer Type): Integers are typically 62 bits now. ++ * objects.texi (Integer Type): Use a binary notation that is a bit easier ++ to read, and that will port better if 62-bits becomes the default. ++ Fix or remove incorrect examples. + * os.texi (Time Conversion): Document time_t values better. + 2011-05-31 Lars Magne Ingebrigtsen * processes.texi (Process Information): Document diff --cc doc/lispref/files.texi index 72f39f681ae,51c27ecc42f..4d992bd2c51 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@@ -1236,13 -1236,10 +1236,14 @@@ deleted and recreated; @code{nil} other @item The file's inode number. If possible, this is an integer. If the -inode number @math{N} is too large to be represented as an integer in -Emacs Lisp, then the value has the form @code{(@var{high} -. @var{low})}, where @var{high} holds the high bits (i.e., all but the -low 16 bits) and @var{low} the low 16 bits. +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 ++Lisp but dividing it by @math{2^16} yields a representable 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 ++bits. If the inode number is too wide for even that, 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 middle 24 bits, and @var{low} the low +16 bits. @item The filesystem number of the device that the file is on. Depending on diff --cc doc/lispref/numbers.texi index 2c73a03a26c,ff057c22254..65921f444e0 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@@ -45,13 -46,14 +45,14 @@@ minimum range is @minus{}536870912 to 5 @end tex to @ifnottex -2**61 - 1) +2**29 - 1), @end ifnottex @tex -@math{2^{61}-1}) +@math{2^{29}-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 ++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 @@@ -94,20 -97,16 +95,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 62-bit binary, the decimal integer 5 looks like this: + In 30-bit binary, the decimal integer 5 looks like this: @example - 00 0000 0000 0000 0000 0000 0000 0101 -0000...000101 (62 bits total) ++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 - 11 1111 1111 1111 1111 1111 1111 1111 -1111...111111 (62 bits total) ++1111...111111 (30 bits total) @end example @noindent @@@ -120,24 -119,24 +122,24 @@@ complement} notation. @minus{}5 looks like this: @example - 11 1111 1111 1111 1111 1111 1111 1011 -1111...111011 (62 bits total) ++1111...111011 (30 bits total) @end example - 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: + In this implementation, the largest 30-bit binary integer value is +536,870,911 in decimal. In binary, it looks like this: @example - 01 1111 1111 1111 1111 1111 1111 1111 -0111...111111 (62 bits total) ++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 2,305,843,009,213,693,951, the value is the -negative integer @minus{}2,305,843,009,213,693,952: +outside their range, when you add 1 to 536,870,911, the value is the +negative integer @minus{}536,870,912: @example -(+ 1 2305843009213693951) - @result{} -2305843009213693952 - @result{} 1000...000000 (62 bits total) +(+ 1 536870911) + @result{} -536870912 - @result{} 10 0000 0000 0000 0000 0000 0000 0000 ++ @result{} 1000...000000 (30 bits total) @end example Many of the functions described in this chapter accept markers for @@@ -508,8 -507,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+ 2305843009213693951)} may -evaluate to @minus{}2305843009213693952, 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. @@@ -829,19 -828,19 +831,19 @@@ value of a positive integer by two, rou 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: ++536,870,911 produces @minus{}2 in the 30-bit implementation: @example -(lsh 2305843009213693951 1) ; @r{left shift} +(lsh 536870911 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: ++In binary, the argument looks like this: @example @group -;; @r{Decimal 2,305,843,009,213,693,951} -0111...111111 (62 bits total) +;; @r{Decimal 536,870,911} - 01 1111 1111 1111 1111 1111 1111 1111 ++0111...111111 (30 bits total) @end group @end example @@@ -851,7 -850,7 +853,7 @@@ which becomes the following when left s @example @group ;; @r{Decimal @minus{}2} - 11 1111 1111 1111 1111 1111 1111 1110 -1111...111110 (62 bits total) ++1111...111110 (30 bits total) @end group @end example @end defun @@@ -874,9 -873,9 +876,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) ++1111...111010 (30 bits total) @result{} - 11 1111 1111 1111 1111 1111 1111 1101 -1111...111101 (62 bits total) ++1111...111101 (30 bits total) @end group @end example @@@ -885,11 -884,11 +887,11 @@@ In contrast, shifting the pattern of bi @example @group -(lsh -6 -1) @result{} 2305843009213693949 -;; @r{Decimal @minus{}6 becomes decimal 2,305,843,009,213,693,949.} -1111...111010 (62 bits total) +(lsh -6 -1) @result{} 536870909 +;; @r{Decimal @minus{}6 becomes decimal 536,870,909.} - 11 1111 1111 1111 1111 1111 1111 1010 ++1111...111010 (30 bits total) @result{} - 01 1111 1111 1111 1111 1111 1111 1101 -0111...111101 (62 bits total) ++0111...111101 (30 bits total) @end group @end example @@@ -899,10 -898,10 +901,10 @@@ 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} ++ ; @r{ 30-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) @@@ -921,12 -920,13 +923,13 @@@ @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 ++ @result{} 268435454 + ; = @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,11 -961,11 +964,11 @@@ because its binary representation consi @smallexample @group - ; @r{ 30-bit binary values} - ; @r{ 62-bit binary values} ++ ; @r{ 30-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 @@@ -991,11 -991,11 +994,11 @@@ passed just one argument, it returns th @smallexample @group - ; @r{ 30-bit binary values} - ; @r{ 62-bit binary values} ++ ; @r{ 30-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 @@@ -1016,11 -1016,11 +1019,11 @@@ result is 0, which is an identity eleme @smallexample @group - ; @r{ 30-bit binary values} - ; @r{ 62-bit binary values} ++ ; @r{ 30-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 @@@ -1040,9 -1040,9 +1043,9 @@@ bit is one in the result if, and only i @example (lognot 5) @result{} -6 - ;; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101} -;; 5 = @r{0000...000101} (62 bits total) ++;; 5 = @r{0000...000101} (30 bits total) ;; @r{becomes} - ;; -6 = @r{11 1111 1111 1111 1111 1111 1111 1010} -;; -6 = @r{1111...111010} (62 bits total) ++;; -6 = @r{1111...111010} (30 bits total) @end example @end defun diff --cc doc/lispref/objects.texi index c58d54f13fc,d5aa51098e7..27d9ba10aef --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@@ -174,15 -174,15 +174,14 @@@ latter are unique to Emacs Lisp @end tex to @ifnottex -2**61 - 1) +2**29 - 1) @end ifnottex @tex -@math{2^{61}-1}) +@math{2^{29}-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. ++on typical 32-bit machines. (Some machines provide a wider range.) ++Emacs Lisp arithmetic functions do not check for overflow. Thus ++@code{(1+ 536870911)} is @minus{}536870912 if Emacs integers are 30 bits. 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 @@@ -203,8 -202,8 +201,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}. ++For instance, if Emacs integers are 30 bits, @code{536870912} is read ++as the floating-point number @code{536870912.0}. @xref{Numbers}, for more information.