Next: , Previous: , Up: Hash Tables   [Contents][Index]


11.4.1 Construction of Hash Tables

The next few procedures are hash-table constructors. All hash table constructors are procedures that accept one optional argument, initial-size, and return a newly allocated hash table. If initial-size is given, it must be an exact non-negative integer or #f. The meaning of initial-size is discussed below (see Resizing of Hash Tables).

Hash tables are normally characterized by two things: the equivalence predicate that is used to compare keys, and how the table allows its keys and data to be reclaimed by the garbage collector. If a table prevents its keys and data from being reclaimed by the garbage collector, it is said to hold its keys and data strongly; other arrangements are possible, where a table may hold keys or data weakly or ephemerally (see Weak References).

procedure: make-strong-eq-hash-table [initial-size]
obsolete procedure: make-symbol-hash-table [initial-size]

Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with eq?. The keys and data are held strongly. These are the fastest of the standard hash tables.

procedure: make-key-weak-eq-hash-table [initial-size]
obsolete procedure: make-weak-eq-hash-table [initial-size]
obsolete procedure: make-eq-hash-table [initial-size]

Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with eq?. The keys are held weakly and the data are held strongly. Note that if a datum holds a key strongly, the table will effectively hold that key strongly.

procedure: make-datum-weak-eq-hash-table [initial-size]

Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with eq?. The keys are held strongly and the data are held weakly. Note that if a key holds a datum strongly, the table will effectively hold that datum strongly.

procedure: make-key-ephemeral-eq-hash-table [initial-size]

Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with eq?. The keys are held weakly, even if some of the data should hold some of the keys strongly.

procedure: make-strong-eqv-hash-table [initial-size]

Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with eqv?. The keys and data are held strongly. These hash tables are a little slower than those made by make-strong-eq-hash-table.

procedure: make-key-weak-eqv-hash-table [initial-size]
obsolete procedure: make-weak-eqv-hash-table [initial-size]
obsolete procedure: make-eqv-hash-table [initial-size]
obsolete procedure: make-object-hash-table [initial-size]

Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with eqv?. The keys are held weakly, except that booleans, characters, numbers, and interned symbols are held strongly. The data are held strongly. Note that if a datum holds a key strongly, the table will effectively hold that key strongly.

procedure: make-datum-weak-eqv-hash-table [initial-size]

Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with eqv?. The keys are held strongly and the data are held weakly. Note that if a key holds a datum strongly, the table will effectively hold that datum strongly.

procedure: make-key-ephemeral-eqv-hash-table [initial-size]

Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with eqv?. The keys are held weakly, except that booleans, characters, numbers, and interned symbols are held strongly. The keys are effectively held weakly even if some of the data should hold some of the keys strongly.

procedure: make-equal-hash-table [initial-size]

Returns a newly allocated hash table that accepts arbitrary objects as keys, and compares those keys with equal?. The keys and data are held strongly. These hash tables are quite a bit slower than those made by make-strong-eq-hash-table.

procedure: make-string-hash-table [initial-size]

Returns a newly allocated hash table that accepts character strings as keys, and compares them with string=?. The keys and data are held strongly.

All of the above are highly optimized table implementations. Next are some general constructors that allow for more flexible table definitions.

procedure: make-hash-table comparator arg …
procedure: make-hash-table [key=? [hash-function arg …]]
procedure: alist->hash-table alist comparator arg …
procedure: alist->hash-table alist [key=? [hash-function arg …]]

These are the standard constructors for making hash tables. The behavior of each differs depending on its arguments: if the first argument is a comparator, then it behaves like a SRFI 125 procedure, otherwise it behaves like a SRFI 69 procedure.

For SRFI 125 behavior the comparator must be a comparator that satisfies comparator-hashable?. The remaining args are optional, and may include the following symbols:

weak-keys

Specifies that the table will have weak keys.

weak-values

Specifies that the table will have weak values.

ephemeral-keys

Specifies that the table will have ephemeral keys.

ephemeral-values

Specifies that the table will have ephemeral values.

The symbols weak-keys and weak-values can be specified together or separately, likewise for ephemeral-keys and ephemeral-values. But weak and ephemeral symbols can’t be mixed. If none of these symbols are present, then the keys and values are strongly held.

Additionally args may contain an exact non-negative integer, which specifies an initial size for the table; otherwise a default size is used.

For SRFI 69 behavior the key=? argument specifies how keys are compared and defaults to equal?. The hash-function argument specifies the hash function to use. If hash-function is not specified, it defaults to a standard value that depends on key=?; an error is signaled if there’s no standard value. The arg arguments are allowed but are implementation dependent; do not provide them.

The procedure alist->hash-table creates a new hash table, as with make-hash-table, and then fills it with the contents of alist.

The remaining constructors use hash-table types to encapsulate the hashing parameters.

obsolete procedure: make-hash-table* type [initial-size]

Constructs a new hash table using the hashing parameters in type.

procedure: hash-table-constructor comparator arg …
obsolete procedure: hash-table-constructor type

Returns a procedure that, when called, constructs a new hash table using the specified parameters. The returned procedure accepts an optional initial-size.

If its first argument is a comparator, it uses the comparator and args as in make-hash-table, except that any initial size specified in args can be overridden by the initial-size argument to the returned procedure.

If its first argument is a type, returns a procedure that, when called, constructs a new hash table using the hashing parameters in type. This is equivalent to

(lambda (#!optional initial-size)
  (make-hash-table* type initial-size))

The next two procedures are used to create hash-table types. The procedures are equivalent in power; they differ only in how the types are described.

obsolete procedure: make-hash-table-type hash-function key=? rehash-after-gc? entry-type

This procedure accepts four arguments and returns a hash-table type, which can be used to make hash tables of that type. The key=? argument is an equivalence predicate for the keys of the hash table. The hash-function argument is a procedure that computes a hash number. Specifically, hash-function accepts two arguments, a key and an exact positive integer (the modulus), and returns an exact non-negative integer that is less than the modulus.

The argument rehash-after-gc?, if true, says that the values returned by hash-function might change after a garbage collection. If so, the hash-table implementation arranges for the table to be rehashed when necessary. (See Address Hashing, for information about hash procedures that have this property.) Otherwise, it is assumed that hash-function always returns the same value for the same arguments.

The argument entry-type determines the strength with which the hash table will hold its keys and values. It must be one of the entry-type variables described below, which all start with hash-table-entry-type:.

obsolete procedure: make-hash-table-type* key=? hash-function rehash-after-gc? entry-type

This procedure’s arguments, except for key=?, are keyword arguments; that is, each argument is a symbol of the same name followed by its value. Aside from how they are passed, the arguments have the same meaning as those for make-hash-table-type. Note that all of the keyword arguments are optional, while key=? is required.

The argument entry-type specifies the name of an entry type. It must be a symbol corresponding to one of the entry-type variables described below. The name of an entry type is the symbol composed of the suffix of the corresponding variable; for example the type hash-table-entry-type:key-weak has the name key-weak.

The default values for the keyword arguments are as follows. The arguments hash-function and rehash-after-gc? default to standard values that depend on key=?; an error is signaled if key=? has no standard values. The argument entry-type defaults to strong.

obsolete variable: hash-table-entry-type:strong

The entry type for hash tables that hold both keys and data strongly.

obsolete variable: hash-table-entry-type:key-weak

An entry type for hash tables that hold keys weakly and data strongly. An entry of this type is a weak pair (see Weak Pairs) whose weak (car) slot holds the key of the entry and whose strong (cdr) slot holds the datum of the entry. If a key of such a hash table is garbage collected, the corresponding entry will be removed. Note that if some datum holds some key strongly, the table will effectively hold that key strongly.

obsolete variable: hash-table-entry-type:datum-weak

An entry type for hash tables that hold keys strongly and data weakly. An entry of this type is a weak pair (see Weak Pairs) whose weak (car) slot holds the datum of the entry and whose strong (cdr) slot holds the key of the entry. If a datum of such a hash table is garbage collected, all corresponding entries will be removed. Note that if some key holds some datum strongly, the table will effectively hold that datum strongly.

obsolete variable: hash-table-entry-type:key&datum-weak
obsolete variable: hash-table-entry-type:key/datum-weak

The entry type for hash tables that hold both keys and data weakly. An entry of this type is a weak list, holding both the key and the datum in the weak (car) slot of weak pairs (see Weak Pairs). If either a key or datum of such a hash table is garbage collected, all corresponding entries will be removed.

obsolete variable: hash-table-entry-type:key-ephemeral

An entry type for hash tables that hold data ephemerally, keyed by the keys. An entry of this type is an ephemeron (see Ephemerons) whose key is the key of the entry and whose datum is the datum of the entry. If a key of such a hash table is garbage collected, the corresponding entry will be removed. Note that the table holds all its keys weakly even if some data should hold some keys strongly.

obsolete variable: hash-table-entry-type:datum-ephemeral

An entry type for hash tables that hold keys ephemerally, keyed by the data. An entry of this type is an ephemeron (see Ephemerons) whose key is the datum of the entry and whose datum is the key of the entry. If a datum of such a hash table is garbage collected, all corresponding entries will be removed. Note that the table holds all its data weakly even if some keys should hold some data strongly.

obsolete variable: hash-table-entry-type:key&datum-ephemeral

The entry type for hash tables that hold both keys and data ephemerally keyed on each other. An entry of this type is a pair of ephemerons (see Ephemerons), one holding the datum keyed by the key and the other holding the key keyed by the datum. If both the key and the datum of any entry of such a hash table are garbage collected, the entry will be removed. The table holds all its keys and data weakly itself, but will prevent any key or datum from being garbage collected if there are strong references to its datum or key, respectively.

Some examples showing how some standard hash-table constructors could have been defined:

(define make-weak-eq-hash-table
  (hash-table-constructor
    (make-hash-table-type eq-hash eq? #t
      hash-table-entry-type:key-weak)))

(define make-equal-hash-table
  (hash-table-constructor
    (make-hash-table-type equal-hash equal? #t
      hash-table-entry-type:strong)))

(define make-string-hash-table
  (hash-table-constructor
    (make-hash-table-type string-hash string=? #f
      hash-table-entry-type:strong)))

The following procedures are provided only for backward compatibility. They should be considered deprecated and should not be used in new programs.

obsolete procedure: hash-table/constructor hash-function key=? rehash-after-gc? entry-type

This procedure is deprecated. Instead use the equivalent

(hash-table-constructor
  (make-hash-table-type hash-function key=? rehash-after-gc?
                        entry-type))
obsolete procedure: strong-hash-table/constructor hash-function key=? [rehash-after-gc?]

Like hash-table/constructor but always uses hash-table-entry-type:strong. If rehash-after-gc? is omitted, it defaults to #f.

obsolete procedure: weak-hash-table/constructor hash-function key=? [rehash-after-gc?]

Like hash-table/constructor but always uses hash-table-entry-type:key-weak. If rehash-after-gc? is omitted, it defaults to #f.


Next: , Previous: , Up: Hash Tables   [Contents][Index]