GNU Info

(elisp)Creating Symbols

---

Next: Property Lists Prev: Definitions Up: Symbols

---

Enter node , (file) or (file)node

Creating and Interning Symbols
==============================

   To understand how symbols are created in GNU Emacs Lisp, you must
know how Lisp reads them.  Lisp must ensure that it finds the same
symbol every time it reads the same set of characters.  Failure to do
so would cause complete confusion.

   When the Lisp reader encounters a symbol, it reads all the characters
of the name.  Then it "hashes" those characters to find an index in a
table called an "obarray".  Hashing is an efficient method of looking
something up.  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 "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 Note: Hash Tables.)

   If a symbol with the desired name is found, the reader uses that
symbol.  If the obarray does not contain a symbol with that name, the
reader makes a new symbol and adds it to the obarray.  Finding or adding
a symbol with a certain name is called "interning" it, and the symbol
is then called an "interned symbol".

   Interning ensures that each obarray has just one symbol with any
particular name.  Other like-named symbols may exist, but not in the
same obarray.  Thus, the reader gets the same symbols for the same
names, as long as you keep reading with the same obarray.

   Interning usually happens automatically in the reader, but sometimes
other programs need to do it.  For example, after the `M-x' command
obtains the command name as a string using the minibuffer, it then
interns the string, to get the interned symbol with that name.

   No obarray contains all symbols; in fact, some symbols are not in any
obarray.  They are called "uninterned symbols".  An uninterned symbol
has the same four cells as other symbols; however, the only way to gain
access to it is by finding it in some other object or as the value of a
variable.

   Creating an uninterned symbol is useful in generating Lisp code,
because an uninterned symbol used as a variable in the code you generate
cannot clash with any variables used in other Lisp programs.

   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 `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 `(make-vector LENGTH 0)'.  *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.

   *Do not try to put symbols in an obarray yourself.*  This does not
work--only `intern' can enter a symbol in an obarray properly.

     Common Lisp note: In Common Lisp, a single symbol may be interned
     in several obarrays.

   Most of the functions below take a name and sometimes an obarray as
arguments.  A `wrong-type-argument' error is signaled if the name is
not a string, or if the obarray is not a vector.

 - Function: symbol-name symbol
     This function returns the string that is SYMBOL's name.  For
     example:

          (symbol-name 'foo)
               => "foo"

     *Warning:* Changing the string by substituting characters does
     change the name of the symbol, but fails to update the obarray, so
     don't do it!

 - Function: make-symbol name
     This function returns a newly-allocated, uninterned symbol whose
     name is NAME (which must be a string).  Its value and function
     definition are void, and its property list is `nil'.  In the
     example below, the value of `sym' is not `eq' to `foo' because it
     is a distinct uninterned symbol whose name is also `foo'.

          (setq sym (make-symbol "foo"))
               => foo
          (eq sym 'foo)
               => nil

 - Function: intern name &optional obarray
     This function returns the interned symbol whose name is NAME.  If
     there is no such symbol in the obarray OBARRAY, `intern' creates a
     new one, adds it to the obarray, and returns it.  If OBARRAY is
     omitted, the value of the global variable `obarray' is used.

          (setq sym (intern "foo"))
               => foo
          (eq sym 'foo)
               => t
          
          (setq sym1 (intern "foo" other-obarray))
               => foo
          (eq sym1 'foo)
               => nil

     Common Lisp note: In Common Lisp, you can intern an existing symbol
     in an obarray.  In Emacs Lisp, you cannot do this, because the
     argument to `intern' must be a string, not a symbol.

 - Function: intern-soft name &optional obarray
     This function returns the symbol in OBARRAY whose name is NAME, or
     `nil' if OBARRAY has no symbol with that name.  Therefore, you can
     use `intern-soft' to test whether a symbol with a given name is
     already interned.  If OBARRAY is omitted, the value of the global
     variable `obarray' is used.

     The argument NAME may also be a symbol; in that case, the function
     returns NAME if NAME is interned in the specified obarray, and
     otherwise `nil'.

          (intern-soft "frazzle")        ; No such symbol exists.
               => nil
          (make-symbol "frazzle")        ; Create an uninterned one.
               => frazzle
          (intern-soft "frazzle")        ; That one cannot be found.
               => nil
          (setq sym (intern "frazzle"))  ; Create an interned one.
               => frazzle
          (intern-soft "frazzle")        ; That one can be found!
               => frazzle
          (eq sym 'frazzle)              ; And it is the same one.
               => t

 - Variable: obarray
     This variable is the standard obarray for use by `intern' and
     `read'.

 - Function: mapatoms function &optional obarray
     This function calls FUNCTION once with each symbol in the obarray
     OBARRAY.  Then it returns `nil'.  If OBARRAY is omitted, it
     defaults to the value of `obarray', the standard obarray for
     ordinary symbols.

          (setq count 0)
               => 0
          (defun count-syms (s)
            (setq count (1+ count)))
               => count-syms
          (mapatoms 'count-syms)
               => nil
          count
               => 1871

     See `documentation' in Note: Accessing Documentation, for another
     example using `mapatoms'.

 - Function: unintern symbol &optional obarray
     This function deletes SYMBOL from the obarray OBARRAY.  If
     `symbol' is not actually in the obarray, `unintern' does nothing.
     If OBARRAY is `nil', the current obarray is used.

     If you provide a string instead of a symbol as SYMBOL, it stands
     for a symbol name.  Then `unintern' deletes the symbol (if any) in
     the obarray which has that name.  If there is no such symbol,
     `unintern' does nothing.

     If `unintern' does delete a symbol, it returns `t'.  Otherwise it
     returns `nil'.