For Gauche 0.9.6

Next: , Previous: , Up: Core library   [Contents][Index]

6.15 Hashtables

R7RS-large defines hashtable (scheme.hash-table module, see R7RS hash tables) but its API is not completely consistent with Gauche’s original hashtables and other native APIs.

Rather than mixing different flavor of APIs, we keep Gauche’s native API consistent, and provide R7RS procedures that are inconsitent with aliases—specifically, those procedures are suffixed with -r7 in gauche module. For portable programs, you can import scheme.hash-table to get R7RS names.

Builtin Class: <hash-table>

Hash table class. Inherits <collection> and <dictionary>.

Gauche doesn’t provide immutable hash tables for now. (If you need immutable maps, see Immutable map).

Hash table properties

Function: hash-table? obj

[R7RS hash-table] Returns #t iff obj is a hash table.

Function: hash-table-mutable? ht

[R7RS hash-table] Returns #t iff a hash table ht is mutable. Gauche doesn’t have immutable hash tables, so this procedure always returns #t for any hash tables.

Function: hash-table-comparator ht

Returns a comparator used in the hashtable ht.

Function: hash-table-type ht

This is an old API, superseded by hash-table-comparator.

Returns one of symbols eq?, eqv?, equal?, string=?, general, indicating the type of the hash table ht.

Function: hash-table-num-entries ht
Function: hash-table-size ht

[R7RS hash-table] Return the number of entries in the hash table ht. R7RS name is hash-table-size.

Hash table constructors and converters

Function: make-hash-table :optional comparator

[R7RS+ hash-table] Creates a hash table. The comparator argument specifies key equality and hash function using a comparator (see Basic comparators). If omitted, eq-comparator is used. Note that in R7RS, comparator argument can’t be omitted.

As Gauche’s extension, the comparator argument can also be one of the symbols eq?, eqv?, equal? or string=?. If it is one of those symbols, eq-comparator, eqv-comparator, equal-comparator and string-comparator will be used, respectively.

The comparator must have hash function, of course. See Hashing, for the built-in hash functions. In general, comparators derived from other comparators having hash functions also have appropriate hash functions.

Function: hash-table-from-pairs comparator key&value …

Constructs and returns a hash table from given list of arguments. The comparator argument is the same as of make-hash-table. Each key&value must be a pair, and its car is used as a key and its cdr is used as a value.

Note: This is called hash-table by 0.9.5. R7RS introduced a procedure with the same name, but different interface. We see R7RS version makes more sense, so we’ll eventually switch to it, but the transition will take long time. The R7RS interface is available as hash-table-r7, and we urge you to use it in the new code, and replace existing hash-table with hash-table-from-pairs.

(hash-table-from-pairs 'eq? '(a . 1) '(b . 2))
  (rlet1 h (make-hash-table 'eq?)
     (hash-table-put! h 'a 1)
     (hash-table-put! h 'b 2))
Function: hash-table comparator key&value …

An alias of hash-table-from-pairs above. R7RS introduced the same name procedure with different interface (see hash-table-r7 below), and we’d like to switch to it in future. For now, use either hash-table-from-pairs or hash-table-r7, or import scheme.hash-table and write in R7RS.

Function: hash-table-r7 comparator args …

Create and returns a hash table using comparator. The args … are the contents, alternating keys and values.

This is defined as hash-table in R7RS scheme.hash-table (see R7RS hash tables).

(hash-table-r7 'eq? 'a 1 'b 2)
  (rlet1 h (make-hash-table 'eq?)
     (hash-table-put! h 'a 1)
     (hash-table-put! h 'b 2))

Note: An R7RS compliant implementation of hash-table may return an immutable hash table. Since Gauche doesn’t have immutable hash tables (we have immutable maps instead; see Immutable map), we return mutable hash tables. However, the portable program should refrain from mutating the returned hash tables.

Function: hash-talbe-unfold p f g seed comparator :rest args

[R7RS hash-table] Constructs and returns a new hash table with those repetitive steps. Each iteration keeps the current seed value, whose initial value is seed.

  1. Apply a stop predicate p to the current seed value. If it returns a true value, stop.
  2. Apply a value producer f to the current seed value. It must return two values, which are used as a key and the corresponding value, of the hash table.
  3. Apply a next procedure g to the current seed value. The value it returns becomes the next seed value.
Function: hash-table-copy ht :optional mutable?

[R7RS hash-table] Returns a new copy of a hash table ht.

R7RS defines this procedure to return an immutable hash table if the implementation supports one, unless the optional mutable? argument is provided and not false. Gauche doesn’t have immutable hash tables so it ignores the optional argument and always returns a mutable hash table. But when you write a portable programs, keep it in mynd.

Function: hash-table-empty-copy ht

[R7RS hash-table] Returns a new mutable empty hash table that has the same properties as the given hash table ht.

Function: alist->hash-table alist :optional comparator

[R7RS+ hash-table] Creates and returns a hash table that has entries of each element in alist, using its car as the key and its cdr as the value. The comparator argument is the same as in make-hash-table. The default value of comparator is eq-comparator.

R7RS doesn’t allow to omit comparator.

Function: hash-table->alist hash-table

[R7RS hash-table]

  (hash-table-map h cons)

Hash table lookup and mutation

Function: hash-table-get ht key :optional default

Search key from a hash table ht, and returns its value if found. If the key is not found in the table and default is given, it is returned. Otherwise an error is signaled.

Function: hash-table-put! ht key value

Puts a key key with a value value to the hash table ht.

Method: ref (ht <hash-table>) key :optional default
Method: (setter ref) (ht <hash-table>) key value

Method versions of hash-table-get and hash-table-put!.

Function: hash-table-ref ht key :optional failure success

[R7RS hash-table] This is R7RS way to look up a hash table.

Look up a value associated to the key in the table ht, then pass it to a procedure success, and returns its value. If success is omitted, an identity function is used.

If there’s no association for key in ht, a thunk failure is called and its result is returned. The default value of failure throws an error.

It is more general than Gauche’s hash-table-get, but if you need to simply return a fallback value in case of failure, you need to wrap it with a clojure, which is annoying. In R7RS, you can use hash-table-ref/default below.

Function: hash-table-ref/default ht key default

[R7RS hash-table] Looks up key in a hash table ht and returns the associated value. If there’s no key in the table, returns default.

This is same as Gauche’s hash-table-get, except that default is not optional. We provide both, for hash-table-get is short and handy.

Function: hash-table-set! ht args …

[R7RS hash-table] This is R7RS version to put associations into a hash table. The args … is a list of alternating keys and values; so, unlike Gauche’s hash-table-put!, you can insert more than one associations at once. It is an error if args … have odd number of arguments.

(hash-table-set! ht 'a 1 'b 2)
  (begin (hash-table-put! ht 'a 1)
         (hash-table-put! ht 'b 2))
Function: hash-table-intern!-r7 ht key failure

This is defined in R7RS as hash-table-intern!. We add -r7 suffix to remind that it takes a failure thunk, which is consistent with R7RS hash-table interface but not Gauche’s way.

Lookup key in ht. If there’s already an entry, it just returns the value. Otherwise, it calls a thunk failure, and insert the association of key and the return value of failure into ht, and returns the value.

Function: hash-table-exists? ht key
Function: hash-table-contains? ht key

[R7RS hash-table] Returns #t if a hash table ht has a key key.

R7RS name is hash-table-contains?.

Function: hash-table-delete! ht key

Deletes an entry that has a key key from the hash table ht. Returns #t if the entry has exist, or #f if the entry hasn’t exist. The same function is called hash-table-remove! in STk (except that it returns an undefined value); I use ‘delete’ for consistency to SRFI-1, SRFI-13 and other parts of the libraries.

Note: This is different from R7RS hash-table-delete!, so we provide R7RS interface with an alias hash-table-delete!-r7.

Function: hash-table-delete!-r7 ht key …

Delets entries that have key … from the hash table ht. The key which isn’t in ht has no effect. Returns the number of entries actually deleted.

This is called hash-table-delete! in R7RS, and so as in scheme.hash-table. We provide this under different name, for Gauche’s hash-table-delete! returns a boolean value.

Function: hash-table-clear! ht

[R7RS hash-table] Removes all entries in the hash table ht.

Function: hash-table-push! ht key value

Conses value to the existing value for the key key in the hash table ht and makes it the new value for key. If there’s no entry for key, an entry is created with the value (list value).

Works the same as the following code, except that this function only looks up the key once, thus it’s more efficient.

(hash-table-put! ht key
    (cons value (hash-table-get ht key '())))
Function: hash-table-pop! ht key :optional default

Looks for the value for the key key in the hash table ht. If found and it is a pair, replaces the value for its cdr and returns car of the original value. If no entry for key is in the table, or the value is not a pair, the table is not modified and the procedure returns default if given, or signals an error otherwise.

During the operation the key is looked for only once, thus runs efficiently.

Note: R7RS has hash-table-pop! but its totally different. We provide R7RS version as an alias hash-table-pop!-r7

Function: hash-table-pop!-r7 ht

Removes one arbitrary entry from ht, and returns the removed entry’s key and value as two values. If ht is empty, an error is thrown.

This is called hash-table-pop! in R7RS, and so as in scheme.hash-table. A more general version of hash-table-push! etc. It works basically as the following code piece, except that the lookup of key is only done once.

(let ((tmp (proc (hash-table-get ht key default))))
  (hash-table-put! ht key tmp)

For example, when you use a hash table to count the occurrences of items, the following line is suffice to increment the counter of the item, regardless of whether item has already appeared or not.

(hash-table-update! ht item (cut + 1 <>) 0))

R7RS provides hash-table-update! with different interface, so we provide R7RS version as an alias hash-table-update!-r7.

Function: hash-table-update!-r7 ht key updater :optional failure success

This is R7RS version of hash-table-update!. With no optional arguments, it works like Gauche’s hash-table-update!. But in practice you often needs to specify the behavior when key hasn’t been in ht, in which case R7RS differs from Gauche.

The R7RS version works like this but potentially more efficiently:

(hash-table-put! ht key (updater (hash-table-ref-r7 ht key failure success)))
Function: hash-table-update!/default ht key updater default

[R7RS hash-table] This is the same as Gauche’s hash-table-default!, except that the default value can’t be omitted.

Hash table scanners

Function: hash-table-for-each ht proc
Function: hash-table-map ht proc

A procedure proc is called with two arguments, a key and its associated value, over all the entries in the hash table ht.

Function: hash-table-fold ht kons knil

For all entries in the hash table ht, a procedure kons is called with three arguments; a key, its associated value, and the previous return value of kons. The first call of kons receives knil as the third argument. The return value of the last call of kons is returned from hash-table-fold.

Function: hash-table-find ht pred :optional failure

Apply pred with each key and value in the hash table ht. Once pred returns a true value, that return value is immediately returned from hash-table-find. If no key-value satisfies pred, a thunk failure is invoked and its result is returned. If failure is omitted, (lambda () #f) is assumed.

Note: The convention starting from srfi-1 is that *-find returns an item in the collection that satisfy the predicate, while *-any returns a non-false value the predicate returns. SRFI-125 broke the convention. The justification given in SRFI-125 discussion was that the “any” semantics is strictly upper-compatible to the “find” semantics so we can combine two. So far, though, SRFI-125 is the only exception of this convention.

;; Find if hash tables ha and hb has a common key.
(hash-table-find ha (^[k v] (hash-table-exists? hb k)))
Function: hash-table-keys ht
Function: hash-table-values ht

Returns all the keys or values of hash table ht in a list, respectively.

Hash table as sets

Function: hash-table-compare-as-sets ht1 ht2 :optional value=? fallback

A hash table can be viewed as a set of pairs of key and value. This procedure compares two hash tables ht1 and ht2 as such sets.

The key comparators of two tables must match (in terms of equal? of the comparators). Otherwise, an error is signaled.

Two elements of the set are equal to each other iff their keys match with the equality predicate of the key comparator, and their values match with value=? procedure. If omitted, equal? is used for value=?

There can be four cases.

Function: hash-table=? value-cmpr ht1 ht2

[R7RS hash-table] This also compares two hash tables ht1 and ht2 as sets, and returns true iff two are the same. That is, every element in ht1 is also in ht2 and vice versa.

Two element are the same iff their keys are the same in terms of the equality predicate of the tables’ key comparator, and their values are the same in terms of the equality predicate of a comparator value-cmpr.

It is an error if ht1 and ht2 has different key comparators. See also hash-table-compare-as-sets above.

Function: hash-table-union! ht1 ht2
Function: hash-table-intersection! ht1 ht2
Function: hash-table-difference! ht1 ht2
Function: hash-table-xor! ht1 ht2

[R7RS hash-table] Perform set operations on two hashtables ht1 and ht2, and modify ht1 to store the result. Note that these procedures only look at the keys for operation; if the values of the same key differ between ht1 and ht2, the value in ht1 is taken.

Next: , Previous: , Up: Core library   [Contents][Index]