From a1a31ecb4027a831eb81728bf66fbd44a28d2840 Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Sun, 7 Feb 2021 14:47:09 +0100 Subject: [PATCH] Clarify that #s(hash-table ...) doesn't always create a new hash table * doc/lispref/hash.texi (Creating Hash): Note that the printed representation doesn't necessarily create a new table (bug#23417). * doc/lispref/lists.texi (Rearrangement): Link to Self-Evaluating Forms to further expand upon immutability. --- doc/lispref/hash.texi | 9 +++++++-- doc/lispref/lists.texi | 15 ++++++++------- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index 8781fad30cd..12c6a659079 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -150,11 +150,11 @@ multiplied by an approximation to this value. The default for @end table @end defun -You can also create a new hash table using the printed representation +You can also create a hash table using the printed representation for hash tables. The Lisp reader can read this printed representation, provided each element in the specified hash table has a valid read syntax (@pxref{Printed Representation}). For instance, -the following specifies a new hash table containing the keys +the following specifies a hash table containing the keys @code{key1} and @code{key2} (both symbols) associated with @code{val1} (a symbol) and @code{300} (a number) respectively. @@ -162,6 +162,11 @@ the following specifies a new hash table containing the keys #s(hash-table size 30 data (key1 val1 key2 300)) @end example +Note, however, that when using this in Emacs Lisp code, it's +undefined whether this creates a new hash table or not. If you want +to create a new hash table, you should always use +@code{make-hash-table} (@pxref{Self-Evaluating Forms}). + @noindent The printed representation for a hash table consists of @samp{#s} followed by a list beginning with @samp{hash-table}. The rest of the diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index c54496f6168..2805b1f5fdc 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1168,13 +1168,14 @@ x @end group @end example -However, the other arguments (all but the last) should be mutable lists. - -A common pitfall is to use a constant list as a non-last -argument to @code{nconc}. If you do this, the resulting behavior -is undefined. It is possible that your program will change -each time you run it! Here is what might happen (though this -is not guaranteed to happen): +However, the other arguments (all but the last) should be mutable +lists. + +A common pitfall is to use a constant list as a non-last argument to +@code{nconc}. If you do this, the resulting behavior is undefined +(@pxref{Self-Evaluating Forms}). It is possible that your program +will change each time you run it! Here is what might happen (though +this is not guaranteed to happen): @smallexample @group -- 2.39.2