[Emacs-diffs] master e489685: Fix documentation for conversion to bignums

[Eli Zaretskii]

branch: master
commit e48968561728d6c1d9e4e8753cd7eafa08e37ac7
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Fix documentation for conversion to bignums
    
    * src/xselect.c (selection_data_to_lisp_data):
    * src/w32fns.c (Fw32_read_registry):
    * src/process.c (Fprocess_id):
    * src/font.c (Ffont_variation_glyphs, Finternal_char_font):
    * src/fns.c (Fsafe_length):
    * src/editfns.c (Fuser_uid, Fuser_real_uid, Fgroup_gid)
    (Fgroup_real_gid, Femacs_pid):
    * src/dired.c (Ffile_attributes):
    * src/charset.c (Fencode_char): Update commentary and doc
    strings for recent changes that produce bignums where
    previously cons cells of integers were produced.
---
 src/charset.c |  4 +++-
 src/dired.c   | 17 ++++++++---------
 src/editfns.c | 15 ++++++++++-----
 src/fns.c     |  3 ++-
 src/font.c    |  6 ++++--
 src/process.c |  1 +
 src/w32fns.c  | 17 +++++++----------
 src/xselect.c | 15 ++++-----------
 8 files changed, 39 insertions(+), 39 deletions(-)

diff --git a/src/charset.c b/src/charset.c
index 7b272a2..e11a836 100644
--- a/src/charset.c
+++ b/src/charset.c
@@ -1870,7 +1870,9 @@ although this usage is obsolescent.  */)
 
 DEFUN ("encode-char", Fencode_char, Sencode_char, 2, 2, 0,
        doc: /* Encode the character CH into a code-point of CHARSET.
-Return nil if CHARSET doesn't include CH.  */)
+Return the encoded code-point, a fixnum if its value is small enough,
+otherwise a bignum.
+Return nil if CHARSET doesn't support CH.  */)
   (Lisp_Object ch, Lisp_Object charset)
 {
   int c, id;
diff --git a/src/dired.c b/src/dired.c
index c4cda40..70c5bb2 100644
--- a/src/dired.c
+++ b/src/dired.c
@@ -867,7 +867,8 @@ Elements of the attribute list are:
  0. t for directory, string (name linked to) for symbolic link, or nil.
  1. Number of links to file.
  2. File uid as a string or a number.  If a string value cannot be
-  looked up, an integer value is returned.
+  looked up, an integer value is returned, which could be a fixnum,
+  if it's small enough, otherwise a bignum.
  3. File gid, likewise.
  4. Last access time, as a list of integers (HIGH LOW USEC PSEC) in the
   same style as (current-time).
@@ -876,16 +877,14 @@ Elements of the attribute list are:
   change to the file's contents.
  6. Last status change time, likewise.  This is the time of last change
   to the file's attributes: owner and group, access mode bits, etc.
- 7. Size in bytes.
+ 7. Size in bytes, which could be a fixnum, if it's small enough,
+  otherwise a bignum.
  8. File modes, as a string of ten letters or dashes as in ls -l.
  9. An unspecified value, present only for backward compatibility.
-10. inode number.  If it is larger than what an Emacs integer can hold,
-  this is of the form (HIGH . LOW): first the high bits, then the low 16 bits.
-  If even HIGH is too large for an Emacs integer, this is instead of the form
-  (HIGH MIDDLE . LOW): first the high bits, then the middle 24 bits,
-  and finally the low 16 bits.
-11. Filesystem device number.  If it is larger than what the Emacs
-  integer can hold, this is a cons cell, similar to the inode number.
+10. inode number, which could be a fixnum, if it's small enough,
+  otherwise a bignum.
+11. Filesystem device number.  If it is larger than what a fixnum
+  can hold, it is a bignum.
 
 On most filesystems, the combination of the inode and the device
 number uniquely identifies the file.
diff --git a/src/editfns.c b/src/editfns.c
index 191a9ab..f19c3f1 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -1377,7 +1377,8 @@ This ignores the environment variables LOGNAME and USER, 
so it differs from
 }
 
 DEFUN ("user-uid", Fuser_uid, Suser_uid, 0, 0, 0,
-       doc: /* Return the effective uid of Emacs.  */)
+       doc: /* Return the effective uid of Emacs.
+Value is a fixnum, if it's small enough, otherwise a bignum.  */)
   (void)
 {
   uid_t euid = geteuid ();
@@ -1385,7 +1386,8 @@ DEFUN ("user-uid", Fuser_uid, Suser_uid, 0, 0, 0,
 }
 
 DEFUN ("user-real-uid", Fuser_real_uid, Suser_real_uid, 0, 0, 0,
-       doc: /* Return the real uid of Emacs.  */)
+       doc: /* Return the real uid of Emacs.
+Value is a fixnum, if it's small enough, otherwise a bignum.  */)
   (void)
 {
   uid_t uid = getuid ();
@@ -1393,7 +1395,8 @@ DEFUN ("user-real-uid", Fuser_real_uid, Suser_real_uid, 
0, 0, 0,
 }
 
 DEFUN ("group-gid", Fgroup_gid, Sgroup_gid, 0, 0, 0,
-       doc: /* Return the effective gid of Emacs.  */)
+       doc: /* Return the effective gid of Emacs.
+Value is a fixnum, if it's small enough, otherwise a bignum.  */)
   (void)
 {
   gid_t egid = getegid ();
@@ -1401,7 +1404,8 @@ DEFUN ("group-gid", Fgroup_gid, Sgroup_gid, 0, 0, 0,
 }
 
 DEFUN ("group-real-gid", Fgroup_real_gid, Sgroup_real_gid, 0, 0, 0,
-       doc: /* Return the real gid of Emacs.  */)
+       doc: /* Return the real gid of Emacs.
+Value is a fixnum, if it's small enough, otherwise a bignum.  */)
   (void)
 {
   gid_t gid = getgid ();
@@ -1481,7 +1485,8 @@ DEFUN ("system-name", Fsystem_name, Ssystem_name, 0, 0, 0,
 }
 
 DEFUN ("emacs-pid", Femacs_pid, Semacs_pid, 0, 0, 0,
-       doc: /* Return the process ID of Emacs, as a number.  */)
+       doc: /* Return the process ID of Emacs, as a number.
+Value is a fixnum, if it's small enough, otherwise a bignum.  */)
   (void)
 {
   pid_t pid = getpid ();
diff --git a/src/fns.c b/src/fns.c
index 5a98f14..c9a6dd6 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -133,7 +133,8 @@ DEFUN ("safe-length", Fsafe_length, Ssafe_length, 1, 1, 0,
        doc: /* Return the length of a list, but avoid error or infinite loop.
 This function never gets an error.  If LIST is not really a list,
 it returns 0.  If LIST is circular, it returns an integer that is at
-least the number of distinct elements.  */)
+least the number of distinct elements.
+Value is a fixnum, if it's small enough, otherwise a bignum.  */)
   (Lisp_Object list)
 {
   intptr_t len = 0;
diff --git a/src/font.c b/src/font.c
index 50ec39a..799d5db 100644
--- a/src/font.c
+++ b/src/font.c
@@ -4485,7 +4485,8 @@ Each element of the value is a cons (VARIATION-SELECTOR . 
GLYPH-ID),
 where
   VARIATION-SELECTOR is a character code of variation selection
     (#xFE00..#xFE0F or #xE0100..#xE01EF)
-  GLYPH-ID is a glyph code of the corresponding variation glyph.  */)
+  GLYPH-ID is a glyph code of the corresponding variation glyph,
+a fixnum, if it's small enough, otherwise a bignum.  */)
   (Lisp_Object font_object, Lisp_Object character)
 {
   unsigned variations[256];
@@ -4522,7 +4523,8 @@ where
    that apply to POSITION.  POSITION may be nil, in which case,
    FONT-SPEC is the font for displaying the character CH with the
    default face.  GLYPH-CODE is the glyph code in the font to use for
-   the character.
+   the character, it is a fixnum, if it is small enough, otherwise a
+   bignum.
 
    For a text terminal, return a nonnegative integer glyph code for
    the character, or a negative integer if the character is not
diff --git a/src/process.c b/src/process.c
index 454278a..ebaaf33 100644
--- a/src/process.c
+++ b/src/process.c
@@ -1157,6 +1157,7 @@ If PROCESS has not yet exited or died, return 0.  */)
 DEFUN ("process-id", Fprocess_id, Sprocess_id, 1, 1, 0,
        doc: /* Return the process id of PROCESS.
 This is the pid of the external process which PROCESS uses or talks to.
+It is a fixnum if the value is small enough, otherwise a bignum.
 For a network, serial, and pipe connections, this value is nil.  */)
   (register Lisp_Object process)
 {
diff --git a/src/w32fns.c b/src/w32fns.c
index 153cba9..9a9789d 100644
--- a/src/w32fns.c
+++ b/src/w32fns.c
@@ -10100,19 +10100,16 @@ the return value depends on the type of the data 
stored in Registry:
 
   If the data type is REG_NONE, the function returns t.
   If the data type is REG_DWORD or REG_QWORD, the function returns
-    its integer value.  If the value is too large for a Lisp integer,
-    the function returns a cons (HIGH . LOW) of 2 integers, with LOW
-    the low 16 bits and HIGH the high bits.  If HIGH is too large for
-    a Lisp integer, the function returns (HIGH MIDDLE . LOW), first
-    the high bits, then the middle 24 bits, and finally the low 16 bits.
+    its integer value.  If the value is too large for a fixnum,
+    the function returns a bignum.
   If the data type is REG_BINARY, the function returns a vector whose
     elements are individual bytes of the value.
   If the data type is REG_SZ, the function returns a string.
-  If the data type REG_EXPAND_SZ, the function returns a string with
-    all the %..% references to environment variables replaced by the
-    values of those variables.  If the expansion fails, or some
-    variables are not defined in the environment, some or all of
-    the environment variables will remain unexpanded.
+  If the data type is REG_EXPAND_SZ, the function returns a string
+    with all the %..% references to environment variables replaced
+    by the values of those variables.  If the expansion fails, or
+    some variables are not defined in the environment, some or all
+    of the environment variables will remain unexpanded.
   If the data type is REG_MULTI_SZ, the function returns a list whose
     elements are the individual strings.
 
diff --git a/src/xselect.c b/src/xselect.c
index 53e7885..a87784f 100644
--- a/src/xselect.c
+++ b/src/xselect.c
@@ -1536,17 +1536,10 @@ x_get_window_property_as_lisp_data (struct 
x_display_info *dpyinfo,
        ATOM    32      > 1             Vector of Symbols
        *       16      1               Integer
        *       16      > 1             Vector of Integers
-       *       32      1               if <=16 bits: Integer
-                                       if > 16 bits: Cons of top16, bot16
+       *       32      1               if small enough: fixnum
+                                       otherwise: bignum
        *       32      > 1             Vector of the above
 
-   When converting a Lisp number to C, it is assumed to be of format 16 if
-   it is an integer, and of format 32 if it is a cons of two integers.
-
-   When converting a vector of numbers from Lisp to C, it is assumed to be
-   of format 16 if every element in the vector is an integer, and is assumed
-   to be of format 32 if any element is a cons of two integers.
-
    When converting an object to C, it may be of the form (SYMBOL . <data>)
    where SYMBOL is what we should claim that the type is.  Format and
    representation are as above.
@@ -1611,8 +1604,8 @@ selection_data_to_lisp_data (struct x_display_info 
*dpyinfo,
     }
 
   /* Convert a single 16-bit number or a small 32-bit number to a Lisp_Int.
-     If the number is 32 bits and won't fit in a Lisp_Int,
-     convert it to a cons of integers, 16 bits in each half.
+     If the number is 32 bits and won't fit in a Lisp_Int, convert it
+     to a bignum.
 
      INTEGER is a signed type, CARDINAL is unsigned.
      Assume any other types are unsigned as well.