[COMMIT] Correct, expand some docstrings, data.c, elhash.c, subr.el

APPROVE COMMIT NOTE: This patch has been committed # HG changeset patch # User Aidan Kehoe <kehoea(a)parhasard.net&gt; # Date 1506320760 -3600 # Mon Sep 25 07:26:00 2017 +0100 # Node ID 75f4aa8ac1314dcbbdfc21602ff4084b4a0253c0 # Parent 8ac369598a2ef9ce4785ffa64fc8945cce945ca5 Correct, expand some docstrings, data.c, elhash.c, subr.el src/ChangeLog addition: 2017-09-25 Aidan Kehoe <kehoea(a)parhasard.net&gt; * data.c (Fchar_to_int): Clarify the details of the integer to character mapping in the docstring, mentioning Unicode. * elhash.c (Fdefine_hash_table_test): Correct my understanding of the required range for hash values; since we get the modulus of the hash value base HT->SIZE, the most significant bits don't matter as much. * fns.c (Fstring_lessp): Fix a typo in a comment here. lisp/ChangeLog addition: 2017-09-25 Aidan Kehoe <kehoea(a)parhasard.net&gt; * subr.el (concat): This function hasn't accepted individual fixnums as arguments in twenty years, and GNU's version of the function doesn't either. Remove all mention of it. Clarify the types of the elements accepted in the argument sequences. * subr.el (bvconcat): Clarify the types of the elements accepted in the argument sequences. diff -r 8ac369598a2e -r 75f4aa8ac131 lisp/ChangeLog --- a/lisp/ChangeLog Sun Sep 24 16:04:49 2017 +0100 +++ b/lisp/ChangeLog Mon Sep 25 07:26:00 2017 +0100 ＠＠ -1,3 +1,13 ＠＠ +2017-09-25 Aidan Kehoe <kehoea(a)parhasard.net&gt; + + * subr.el (concat): + This function hasn't accepted individual fixnums as arguments in + twenty years, and GNU's version of the function doesn't + either. Remove all mention of it. + Clarify the types of the elements accepted in the argument sequences. + * subr.el (bvconcat): + Clarify the types of the elements accepted in the argument sequences. + 2017-09-07 Aidan Kehoe <kehoea(a)parhasard.net&gt; * rect.el (delete-extract-rectangle-line): diff -r 8ac369598a2e -r 75f4aa8ac131 lisp/subr.el --- a/lisp/subr.el Sun Sep 24 16:04:49 2017 +0100 +++ b/lisp/subr.el Mon Sep 25 07:26:00 2017 +0100 ＠＠ -206,12 +206,10 ＠＠ (defun concat (&rest args) "Concatenate all the arguments and make the result a string. The result is a string whose elements are the elements of all the arguments. -Each argument may be a string or a list or vector of characters. +Each argument may be a list, vector, bit-vector or string. -As of XEmacs 21.0, this function does NOT accept individual integers -as arguments. Old code that relies on, for example, (concat \"foo\" 50) -returning \"foo50\" will fail. To fix such code, either apply -`int-to-string' to the integer argument, or use `format'." +Argument elements must be characters, or integers that can be converted to +characters; see `char-int'." (apply #'concatenate 'string args)) (defun vconcat (&rest args) ＠＠ -223,7 +221,10 ＠＠ (defun bvconcat (&rest args) "Concatenate all the arguments and make the result a bit vector. The result is a bit vector whose elements are the elements of all the -arguments. Each argument may be a list, vector, bit vector, or string." +arguments. Each argument may be a list, vector, bit vector, or string. + +Argument elements must be the integers zero or one, or the characters ?\\x00, +?\\x01." (apply #'concatenate 'bit-vector args))  ;; XEmacs; move these non-basic predicates that can be easily implemented in diff -r 8ac369598a2e -r 75f4aa8ac131 src/ChangeLog --- a/src/ChangeLog Sun Sep 24 16:04:49 2017 +0100 +++ b/src/ChangeLog Mon Sep 25 07:26:00 2017 +0100 ＠＠ -1,3 +1,15 ＠＠ +2017-09-25 Aidan Kehoe <kehoea(a)parhasard.net&gt; + + * data.c (Fchar_to_int): + Clarify the details of the integer to character mapping in the + docstring, mentioning Unicode. + * elhash.c (Fdefine_hash_table_test): + Correct my understanding of the required range for hash values; + since we get the modulus of the hash value base HT->SIZE, the most + significant bits don't matter as much. + * fns.c (Fstring_lessp): + Fix a typo in a comment here. + 2017-09-24 Aidan Kehoe <kehoea(a)parhasard.net&gt; * chartab.c (chartab_data_validate): diff -r 8ac369598a2e -r 75f4aa8ac131 src/data.c --- a/src/data.c Sun Sep 24 16:04:49 2017 +0100 +++ b/src/data.c Mon Sep 25 07:26:00 2017 +0100 ＠＠ -394,10 +394,15 ＠＠ 128 - 159 Control set 1 160 - 255 Right half of ISO-8859-1 -If support for Mule does not exist, these are the only valid character -values. When Mule support exists, the values assigned to other characters -may vary depending on the particular version of XEmacs, the order in which -character sets were loaded, etc., and you should not depend on them. +If the `unicode-internal' feature is available, other integer values reflect +ISO-10646 values for character codes. Otherwise, if the `mule' feature is +available, the values assigned to other characters may vary depending on the +particular version of XEmacs, the order in which character sets were loaded, +and you should not depend on them. + +Some XEmacs builds have neither the `mule' nor the `unicode-internal' features +available, and in these builds no character has an integer value greater than +255. */ (character)) { diff -r 8ac369598a2e -r 75f4aa8ac131 src/elhash.c --- a/src/elhash.c Sun Sep 24 16:04:49 2017 +0100 +++ b/src/elhash.c Mon Sep 25 07:26:00 2017 +0100 ＠＠ -2557,14 +2557,15 ＠＠ if both arguments are the same. HASH-FUNCTION must be a function taking one argument and returning an integer that is the hash code of the argument. -Computation should use the whole value range of the underlying machine long -type. In XEmacs this will necessitate bignums for values above -`most-positive-fixnum' but below (1+ (* most-positive-fixnum 2)) and -analogous values below `most-negative-fixnum'. Relatively poor hashing -performance is guaranteed in a build without bignums. - -This function returns t if successful, and errors if NAME -cannot be defined as a hash table test. +Computation should ideally use the whole value range of the underlying machine +long type. In XEmacs this necessitates bignums for values above +`most-positive-fixnum' but below (1+ (* most-positive-fixnum 2)) and analogous +values below `most-negative-fixnum'. With this implementation, however, the +low-order bits are the most important, and so it is reasonable not to bother +producing bignums. + +This function returns t if successful, and errors if NAME cannot be defined as +a hash table test. */ (name, equal_function, hash_function)) { diff -r 8ac369598a2e -r 75f4aa8ac131 src/fns.c --- a/src/fns.c Sun Sep 24 16:04:49 2017 +0100 +++ b/src/fns.c Mon Sep 25 07:26:00 2017 +0100 ＠＠ -267,7 +267,7 ＠＠ /* Since we've assigned Control-1 and Latin-1 the two lowest leading bytes, the statement above about them and their ordering w.r.t. other charsets is guaranteed. Also, UTF-8 preserves Unicode character order - when comparing byte-by-byte. So need no to do an actual char-by-char + when comparing byte-by-byte. So no need to do an actual char-by-char comparison. */ if (qxememcmp4 (XSTRING_DATA (p1), XSTRING_LENGTH (p1), -- ‘As I sat looking up at the Guinness ad, I could never figure out / How your man stayed up on the surfboard after forty pints of stout’ (C. Moore)