master 6803b70c197 6/7: Update NEWS and manual after obarray changes

[Mattias Engdegård]

branch: master
commit 6803b70c1972bc82f7dc1f1d6bbb2a60b6f40367
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    Update NEWS and manual after obarray changes
    
    * doc/lispref/abbrevs.texi (Abbrev Tables):
    * doc/lispref/symbols.texi (Creating Symbols):
    * doc/lispref/objects.texi (Type Predicates): Update text for obarray
    now being an opaque type.
    * etc/NEWS: Announce.
---
 doc/lispref/abbrevs.texi |  2 +-
 doc/lispref/objects.texi |  5 +++-
 doc/lispref/symbols.texi | 65 +++++++++++++++++-------------------------------
 etc/NEWS                 | 20 +++++++++++++++
 4 files changed, 48 insertions(+), 44 deletions(-)

diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi
index 9b719145584..d89cec4bc2b 100644
--- a/doc/lispref/abbrevs.texi
+++ b/doc/lispref/abbrevs.texi
@@ -65,7 +65,7 @@ expanded in the buffer.  For the user-level commands for 
abbrevs, see
 
 @defun make-abbrev-table &optional props
 This function creates and returns a new, empty abbrev table---an
-obarray containing no symbols.  It is a vector filled with zeros.
+obarray containing no symbols.
 @var{props} is a property list that is applied to the new table
 (@pxref{Abbrev Table Properties}).
 @end defun
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index b8fd5ed4345..e6def69454e 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -2121,6 +2121,9 @@ with references to further information.
 @item numberp
 @xref{Predicates on Numbers, numberp}.
 
+@item obarrayp
+@xref{Creating Symbols, obarrayp}.
+
 @item overlayp
 @xref{Overlays, overlayp}.
 
@@ -2181,7 +2184,7 @@ This function returns a symbol naming the primitive type 
of
 @code{condition-variable}, @code{cons}, @code{finalizer},
 @code{float}, @code{font-entity}, @code{font-object},
 @code{font-spec}, @code{frame}, @code{hash-table}, @code{integer},
-@code{marker}, @code{mutex}, @code{overlay}, @code{process},
+@code{marker}, @code{mutex}, @code{obarray}, @code{overlay}, @code{process},
 @code{string}, @code{subr}, @code{symbol}, @code{thread},
 @code{vector}, @code{window}, or @code{window-configuration}.
 However, if @var{object} is a record, the type specified by its first
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index e95e53d972d..5207ea4ea7b 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -177,34 +177,16 @@ know how Lisp reads them.  Lisp must ensure that it finds 
the same
 symbol every time it reads the same sequence of characters in the same
 context.  Failure to do so would cause complete confusion.
 
-@cindex symbol name hashing
-@cindex hashing
 @cindex obarray
-@cindex bucket (in obarray)
   When the Lisp reader encounters a name that references a symbol in
-the source code, it reads all the characters of that name.  Then it
-looks up that name in a table called an @dfn{obarray} to find the
-symbol that the programmer meant.  The technique used in this lookup
-is called ``hashing'', an efficient method of looking something up by
-converting a sequence of characters to a number, known as a ``hash
-code''.  For example, instead of searching a telephone book cover to
-cover when looking up Jan Jones, you start with the J's and go from
-there.  That is a simple version of hashing.  Each element of the
-obarray is a @dfn{bucket} which holds all the symbols with a given
-hash code; to look for a given name, it is sufficient to look through
-all the symbols in the bucket for that name's hash code.  (The same
-idea is used for general Emacs hash tables, but they are a different
-data type; see @ref{Hash Tables}.)
-
-When looking up names, the Lisp reader also considers ``shorthands''.
+the source code, it looks up that name in a table called an @dfn{obarray}
+to find the symbol that the programmer meant.  An obarray is an unordered
+container of symbols, indexed by name.
+
+The Lisp reader also considers ``shorthands''.
 If the programmer supplied them, this allows the reader to find a
 symbol even if its name isn't present in its full form in the source
-code.  Of course, the reader needs to be aware of some pre-established
-context about such shorthands, much as one needs context to be to able
-to refer uniquely to Jan Jones by just the name ``Jan'': it's probably
-fine when amongst the Joneses, or when Jan has been mentioned
-recently, but very ambiguous in any other situation.
-@xref{Shorthands}.
+code.  @xref{Shorthands}.
 
 @cindex interning
   If a symbol with the desired name is found, the reader uses that
@@ -236,23 +218,6 @@ to gain access to it is by finding it in some other object 
or as the
 value of a variable.  Uninterned symbols are sometimes useful in
 generating Lisp code, see below.
 
-  In Emacs Lisp, an obarray is actually a vector.  Each element of the
-vector is a bucket; its value is either an interned symbol whose name
-hashes to that bucket, or 0 if the bucket is empty.  Each interned
-symbol has an internal link (invisible to the user) to the next symbol
-in the bucket.  Because these links are invisible, there is no way to
-find all the symbols in an obarray except using @code{mapatoms} (below).
-The order of symbols in a bucket is not significant.
-
-  In an empty obarray, every element is 0, so you can create an obarray
-with @code{(make-vector @var{length} 0)}.  @strong{This is the only
-valid way to create an obarray.}  Prime numbers as lengths tend
-to result in good hashing; lengths one less than a power of two are also
-good.
-
-  @strong{Do not try to put symbols in an obarray yourself.}  This does
-not work---only @code{intern} can enter a symbol in an obarray properly.
-
 @cindex CL note---symbol in obarrays
 @quotation
 @b{Common Lisp note:} Unlike Common Lisp, Emacs Lisp does not provide
@@ -262,9 +227,21 @@ Emacs Lisp provides a different namespacing system called
 ``shorthands'' (@pxref{Shorthands}).
 @end quotation
 
+@defun obarray-make &optional size
+This function creates and returns a new obarray.
+The optional @var{size} may be used to specify the number of symbols
+that it is expected to hold, but since obarrays grow automatically
+as needed, this rarely provide any benefit.
+@end defun
+
+@defun obarrayp object
+This function returns @code{t} if @var{object} is an obarray,
+@code{nil} otherwise.
+@end defun
+
   Most of the functions below take a name and sometimes an obarray as
 arguments.  A @code{wrong-type-argument} error is signaled if the name
-is not a string, or if the obarray is not a vector.
+is not a string, or if the obarray is not an obarray object.
 
 @defun symbol-name symbol
 This function returns the string that is @var{symbol}'s name.  For example:
@@ -416,6 +393,10 @@ If @code{unintern} does delete a symbol, it returns 
@code{t}.  Otherwise
 it returns @code{nil}.
 @end defun
 
+@defun obarray-clear obarray
+This function removes all symbols from @var{obarray}.
+@end defun
+
 @node Symbol Properties
 @section Symbol Properties
 @cindex symbol property
diff --git a/etc/NEWS b/etc/NEWS
index 13b41feccbc..1a5ddf0f7e3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1993,6 +1993,26 @@ The 'test' parameter is omitted if it is 'eql' (the 
default), as is
 'data' if empty.  'rehash-size', 'rehash-threshold' and 'size' are
 always omitted, and ignored if present when the object is read back in.
 
+** Obarrays
+
++++
+*** New obarray type.
+Obarrays are now represented by an opaque type instead of using vectors.
+They are created by 'obarray-make' and manage their internal storage
+automatically, which means that the size parameter to 'obarray-make' can
+safely be omitted.  That is, they do not become slower as they fill up.
+
+The old vector representation is still accepted by functions operating
+on obarrays, but 'obarrayp' only returns 't' for obarray objects.
+'type-of' now returns 'obarray' for obarray objects.
+
++++
+*** New function 'obarray-clear' removes all symbols from an obarray.
+
+---
+*** 'obarray-size' and 'obarray-default-size' are now obsolete.
+They pertained to the internal storage size which is now irrelevant.
+
 +++
 ** 'treesit-install-language-grammar' can handle local directory instead of 
URL.
 It is now possible to pass a directory of a local repository as URL