For Gauche 0.9.5


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

6.15 Hashtables

Gauche’s native hashtable API is Gauche-specific. For portable programs, you can use srfi-69 (see Basic hash tables) for the time being.

There will be a revised hashtable API as a part of R7RS-large, we plan to adapt Gauche’s native API once it is published.

Builtin Class: <hash-table>

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

Function: make-hash-table :optional comparator

Creates a hash table. The optional comparator argument specifies key equality and hash function. It can be either a comparator (see Basic comparators), or 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.

If comparator is omitted, eq-comparator is assumed.

Function: hash-table? obj

Returns #t if obj is a hash table.

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

Returns the number of entries in the hash table ht.

Function: hash-table 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.

(hash-table '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-copy ht

Returns a new copy of a hash table ht.

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-exists? ht key

Returns #t if a hash table ht has a key key.

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.

Function: hash-table-clear! ht

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.

Function: hash-table-update! ht key proc :optional default

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)
  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))
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-keys ht
Function: hash-table-values ht

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

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

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.

Function: hash-table->alist hash-table
  (hash-table-map h cons)

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