"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/doc/lispref/hash.texi" (25 May 2018, 14300 Bytes) of package /linux/misc/emacs-26.1.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "hash.texi": 25.3_vs_26.1.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Hash Tables

A hash table is a very fast kind of lookup table, somewhat like an alist (@pxref{Association Lists}) in that it maps keys to corresponding values. It differs from an alist in these ways:

Emacs Lisp provides a general-purpose hash table data type, along with a series of functions for operating on them. Hash tables have a special printed representation, which consists of ‘#s’ followed by a list specifying the hash table properties and contents. See section Creating Hash Tables. (Hash notation, the initial ‘#’ character used in the printed representations of objects with no read representation, has nothing to do with hash tables. @xref{Printed Representation}.)

Obarrays are also a kind of hash table, but they are a different type of object and are used only for recording interned symbols (@pxref{Creating Symbols}).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 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, that is, if they are equal in value and either both are integers or both are floating point; 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 (see section Defining Hash Comparisons) 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-and-value or t, both the key and the value must be live in order to preserve the association. Thus, the hash table does not protect either keys or values from garbage collection; if either one is collected as garbage, that removes the association.

If weak is key-or-value, either the key or the value can preserve the association. Thus, associations are removed from the hash table when both their key and value would be collected as garbage (if not for references 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.

: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 approximately that much to the nominal size. If rehash-size is floating point, it had better be greater than 1, and the hash table grows by multiplying the old size by approximately that number.

The default value is 1.5.

:rehash-threshold threshold

This specifies the criterion for when the hash table is full (so it should be made larger). 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 the nominal size multiplied by an approximation to this value. The default for threshold is 0.8125.

You can also create a new 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 key1 and key2 (both symbols) associated with val1 (a symbol) and 300 (a number) respectively.

#s(hash-table size 30 data (key1 val1 key2 300))

The printed representation for a hash table consists of ‘#s’ followed by a list beginning with ‘hash-table’. The rest of the list should consist of zero or more property-value pairs specifying the hash table’s properties and initial contents. The properties and values are read literally. Valid property names are size, test, weakness, rehash-size, rehash-threshold, and data. The data property should be a list of key-value pairs for the initial contents; the other properties have the same meanings as the matching make-hash-table keywords (:size, :test, etc.), described above.

Note that you cannot specify a hash table whose initial contents include objects that have no read syntax, such as buffers and frames. Such objects may be added to the hash table after it is created.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Hash Table Access

This section describes the functions for accessing and storing associations in a hash table. In general, any Lisp object can be used as a hash key, unless the comparison method imposes limits. Any Lisp object can also be used as the value.

Function: gethash key table &optional default

This function looks up key in table, and returns its associated value—or default, if key has no association in table.

Function: puthash key value table

This function enters an association for key in table, with value value. If key already has an association in table, value replaces the old associated value.

Function: remhash key table

This function removes the association for key from table, if there is one. If key has no association, remhash does nothing.

Common Lisp note: In Common Lisp, remhash returns non-nil if it actually removed an association and nil otherwise. In Emacs Lisp, remhash always returns nil.

Function: clrhash table

This function removes all the associations from hash table table, so that it becomes empty. This is also called clearing the hash table.

Common Lisp note: In Common Lisp, clrhash returns the empty table. In Emacs Lisp, it returns nil.

Function: maphash function table

This function calls function once for each of the associations in table. The function function should accept two arguments—a key listed in table, and its associated value. maphash returns nil.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Defining Hash Comparisons

You can define new methods of key lookup by means of define-hash-table-test. In order to use this feature, you need to understand how hash tables work, and what a hash code means.

You can think of a hash table conceptually as a large array of many slots, each capable of holding one association. To look up a key, gethash first computes an integer, the hash code, from the key. It reduces this integer modulo the length of the array, to produce an index in the array. Then it looks in that slot, and if necessary in other nearby slots, to see if it has found the key being sought.

Thus, to define a new method of key lookup, you need to specify both a function to compute the hash code from a key, and a function to compare two keys directly.

Function: define-hash-table-test name test-fn hash-fn

This function defines a new hash table test, named name.

After defining name in this way, you can use it as the test argument in make-hash-table. When you do that, the hash table will use test-fn to compare key values, and hash-fn to compute a hash code from a key value.

The function test-fn should accept two arguments, two keys, and return non-nil if they are considered the same.

The function hash-fn should accept one argument, a key, and return an integer that is the hash code of that key. For good results, the function should use the whole range of integers for hash codes, including negative integers.

The specified functions are stored in the property list of name under the property hash-table-test; the property value’s form is (test-fn hash-fn).

Function: sxhash-equal obj

This function returns a hash code for Lisp object obj. This is an integer which reflects the contents of obj and the other Lisp objects it points to.

If two objects obj1 and obj2 are equal, then (sxhash-equal obj1) and (sxhash-equal obj2) are the same integer.

If the two objects are not equal, the values returned by sxhash-equal are usually different, but not always; once in a rare while, by luck, you will encounter two distinct-looking objects that give the same result from sxhash-equal.

Common Lisp note: In Common Lisp a similar function is called sxhash. Emacs provides this name as a compatibility alias for sxhash-equal.

Function: sxhash-eq obj

This function returns a hash code for Lisp object obj. Its result reflects identity of obj, but not its contents.

If two objects obj1 and obj2 are eq, then (sxhash-eq obj1) and (sxhash-eq obj2) are the same integer.

Function: sxhash-eql obj

This function returns a hash code for Lisp object obj suitable for eql comparison. I.e. it reflects identity of obj except for the case where the object is a float number, in which case hash code is generated for the value.

If two objects obj1 and obj2 are eql, then (sxhash-eql obj1) and (sxhash-eql obj2) are the same integer.

This example creates a hash table whose keys are strings that are compared case-insensitively.

(defun case-fold-string= (a b)
  (eq t (compare-strings a nil nil b nil nil t)))
(defun case-fold-string-hash (a)
  (sxhash-equal (upcase a)))

(define-hash-table-test 'case-fold
  'case-fold-string= 'case-fold-string-hash)

(make-hash-table :test 'case-fold)

Here is how you could define a hash table test equivalent to the predefined test value equal. The keys can be any Lisp object, and equal-looking objects are considered the same key.

(define-hash-table-test 'contents-hash 'equal 'sxhash-equal)

(make-hash-table :test 'contents-hash)

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Other Hash Table Functions

Here are some other functions for working with hash tables.

Function: hash-table-p table

This returns non-nil if table is a hash table object.

Function: copy-hash-table table

This function creates and returns a copy of table. Only the table itself is copied—the keys and values are shared.

Function: hash-table-count table

This function returns the actual number of entries in table.

Function: hash-table-test table

This returns the test value that was given when table was created, to specify how to hash and compare keys. See make-hash-table (see section Creating Hash Tables).

Function: hash-table-weakness table

This function returns the weak value that was specified for hash table table.

Function: hash-table-rehash-size table

This returns the rehash size of table.

Function: hash-table-rehash-threshold table

This returns the rehash threshold of table.

Function: hash-table-size table

This returns the current nominal size of table.


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on May 29, 2018 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on May 29, 2018 using texi2html.