GNU Info

(elisp)Creating Hash

---

Next: Hash Access Up: Hash Tables

---

Enter node , (file) or (file)node

Creating Hash Tables
====================

   The principal function for creating a hash table is
`make-hash-table'.

 - Function: make-hash-table &rest keyword-args
     This function creates a new hash table according to the specified
     arguments.  The arguments should consist of alternating keywords
     (particular symbols recognized specially) and values corresponding
     to them.

     Several keywords make sense in `make-hash-table', but the only two
     that you really need to know about are `:test' and `:weakness'.

    `:test TEST'
          This specifies the method of key lookup for this hash table.
          The default is `eql'; `eq' and `equal' are other alternatives:

         `eql'
               Keys which are numbers are "the same" if they are equal
               in value; otherwise, two distinct objects are never "the
               same".

         `eq'
               Any two distinct Lisp objects are "different" as keys.

         `equal'
               Two Lisp objects are "the same", as keys, if they are
               equal according to `equal'.

          You can use `define-hash-table-test' (Note: Defining Hash)
          to define additional possibilities for TEST.

    `:weakness WEAK'
          The weakness of a hash table specifies whether the presence
          of a key or value in the hash table preserves it from garbage
          collection.

          The value, WEAK, must be one of `nil', `key', `value',
          `key-or-value', `key-and-value', or `t' which is an alias for
          `key-and-value'.  If WEAK is `key' then the hash table does
          not prevent its keys from being collected as garbage (if they
          are not referenced anywhere else); if a particular key does
          get collected, the corresponding association is removed from
          the hash table.

          If WEAK is `value', then the hash table does not prevent
          values from being collected as garbage (if they are not
          referenced anywhere else); if a particular value does get
          collected, the corresponding association is removed from the
          hash table.

          If WEAK is `key-or-value' or `t', the hash table does not
          protect either keys or values from garbage collection; if
          either one is collected as garbage, the association is
          removed.

          If WEAK is `key-and-value', associations are removed from the
          hash table when both their key and value would be collected as
          garbage, again not considering references to the key and
          value from weak hash tables.

          The default for WEAK is `nil', so that all keys and values
          referenced in the hash table are preserved from garbage
          collection.  If WEAK is `t', neither keys nor values are
          protected (that is, both are weak).

    `:size SIZE'
          This specifies a hint for how many associations you plan to
          store in the hash table.  If you know the approximate number,
          you can make things a little more efficient by specifying it
          this way.  If you specify too small a size, the hash table
          will grow automatically when necessary, but doing that takes
          some extra time.

          The default size is 65.

    `:rehash-size REHASH-SIZE'
          When you add an association to a hash table and the table is
          "full," it grows automatically.  This value specifies how to
          make the hash table larger, at that time.

          If REHASH-SIZE is an integer, it should be positive, and the
          hash table grows by adding that much to the nominal size.  If
          REHASH-SIZE is a floating point number, it had better be
          greater than 1, and the hash table grows by multiplying the
          old size by that number.

          The default value is 1.5.

    `:rehash-threshold THRESHOLD'
          This specifies the criterion for when the hash table is
          "full."  The value, THRESHOLD, should be a positive floating
          point number, no greater than 1.  The hash table is "full"
          whenever the actual number of entries exceeds this fraction
          of the nominal size.  The default for THRESHOLD is 0.8.

 - Function: makehash &optional test
     This is equivalent to `make-hash-table', but with a different style
     argument list.  The argument TEST specifies the method of key
     lookup.

     If you want to specify other parameters, you should use
     `make-hash-table'.