@item numberp
@xref{Predicates on Numbers, numberp}.
+@item obarrayp
+@xref{Creating Symbols, obarrayp}.
+
@item overlayp
@xref{Overlays, overlayp}.
@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
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
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
``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:
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
'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
projects / emacs.git / commitdiff