From e48968561728d6c1d9e4e8753cd7eafa08e37ac7 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 8 Sep 2018 12:20:55 +0300 Subject: [PATCH] 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 7b272a204a1..e11a8366d58 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 c4cda400a06..70c5bb24b4e 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 191a9ab8f8a..f19c3f1dca9 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 5a98f148818..c9a6dd6de1e 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 50ec39a9a49..799d5db205c 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 454278a5a27..ebaaf33e57f 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 153cba9f755..9a9789d8af3 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 53e788523cc..a87784fb4b1 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 . ) 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. -- 2.39.2