11.17 srfi.69 - Basic hash tables

Module: srfi.69 ¶

This module has been superseded by R7RS scheme.hash-table (see scheme.hash-table - R7RS hash tables). New code should use it instead.

This is a thin adaptor on Gauche’s built-in hashtables (see Hashtables). This is provided for the compatibility to the portable libraries; the hashtable object created by this module’s make-hash-table is the same as the one created by Gauche’s built-in, and you can pass the table to both APIs.

Here’s a summary of difference between SRFI-69 and Gauche’s built-in hash table API:

• The constructor make-hash-table, as well as alist->hash-table, takes equality predicate and hash function, instead of a single comparator argument as Gauche does.
• The hash function passed to SRFI-69’s make-hash-table takes two arguments, an object to calculate a hash value, and a positive integer that limits the range of the hash value.
• SRFI-69’s primary hash table accessor is hash-table-ref, which takes a thunk to be called when the table doesn’t have an entry for the given key, while Gauche’s hash-table-get takes a fallback value for that. SRFI-69 also has hash-table-ref/default, which takes a fallback value like Gauche’s hash-table-get, but the default value can’t be omitted.
• SRFI-69’s hash-table-update! and hash-table-update!/default to Gauche’s hash-table-update! is the same as hash-table-ref, hash-table-ref/default and hash-table-get.
• The basic iterator of SRFI-69 is called hash-table-walk, which is Gauche’s hash-table-for-each. The srfi name is chosen to avoid conflict with existing Scheme implementations.

The following procedures are the same as Gauche’s built-in ones. See Hashtables, for the details.

hash-table?       hash-table-delete!   hash-table-exists?
hash-table-keys   hash-table-values    hash-table-fold
hash-table->alist hash-table-copy

Function: make-hash-table :optional eq-pred hash-proc :rest args ¶

[SRFI-69]{srfi.69} Creates a new hashtable and returns it. This is the same name as Gauche’s built-in procedure, but the arguments are different.

The eq-pred argument is an equality predicate; it takes two arguments and returns #t if two are the same, and #f if not. When omitted, equal? is used.

The hash-proc argument is a hash function. It takes two arguments: an object to hash, and a positive integer to limit the range of the hash value. (Note that Gauche’s native hash functions takes only one argument.) When omitted, Gauche tries to choose appropriate hash function if eq-pred is known one (eq?, eqv?, equal?, string=? or string-ci=?). Otherwise we use scheme.hash-table’s hash procedure (see scheme.hash-table - R7RS hash tables). But there’s no guarantee that the generic hash works appropriately; you should give suitable hash-proc if you pass custom eq-pred.

The returned hash table is an instance of Gauche’s native hash table. You can pass it to Gauche’s builtin procedures.

SRFI-69 allows implementation-specific arguments args to be passed to make-hash-table. At this moment, Gauche ignores them.

Function: alist->hash-table alist :optional eq-pred hash-fn :rest args ¶

[SRFI-69]{srfi.69} Like Gauche’s builtin alist->hash-table, but takes eq-pred and hash-fn separately, instead of a single comparator.

The alist argument is a list of pairs. The car of each pair is used for a key, and the cdr for its value.

See make-hash-table above for the description of eq-pred, hash-fn and args.

Function: hash-table-equivalence-function ht ¶

Function: hash-table-hash-function ht ¶

[SRFI-69]{srfi.69} Returns equivalence function and hash function of the hashtable ht.

Note that SRFI-69’s hash function takes an optional bound argument. Since our underlying hash tables don’t use bound argument, we actually wrap the internal hash function to allow the optional bound argument.

Function: hash-table-ref ht key :optional thunk ¶

[SRFI-69]{srfi.69} Looks up the value corresponding to key in a hash table ht. If there’s no entry for key, thunk is called without arguments, and its result is returned. The default of thunk is to signal an error.

This convention differs from Gauche’s built-in hash-table-get, which takes optonal default argument to be returned when the key doesn’t exist (see Hashtables). The following equivalence holds:

(hash-table-get ht key default) ≡ (hash-table-ref ht key (^[] default))

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

[SRFI-69]{srfi.69} Looks up the value corresponding to key in a hash table ht. If the key doesn’t exist, default is returned. This is like Gauche’s hash-table-get, but default can’t be omitted (see Hashtables).

Function: hash-table-set! ht key val ¶

[SRFI-69]{srfi.69} This is the same as Gauche’s hash-table-put! (see Hashtables).

Function: hash-table-update! ht key proc :optional thunk ¶

Function: hash-table-update!/default ht key proc default ¶

[SRFI-69]{srfi.69} Calls proc with the value associated to key in ht, and replace the value in ht with the result of proc. The following functional equivalences hold, though these procedures may be more efficient.

(hash-table-update! ht key proc thunk)
 ≡ (hash-table-set! ht key (proc (hash-table-ref ht key thunk)))

(hash-table-update!/default ht key proc default)
 ≡ (hash-table-set! ht key (proc (hash-table-ref/default ht key default)))

Note that Gauche’s built-in hash-table-update! is different, for it takes optional default argument instead of thunk (see Hashtables).

Function: hash-table-size ht ¶

[SRFI-69]{srfi.69} Returns the number of entries in a hash table ht. The same as Gauche’s hash-table-num-entries.

Function: hash-table-walk ht proc ¶

[SRFI-69]{srfi.69} For each entry in a hash table ht, calls proc with two arguments, a key and its value. It’s the same as Gauche’s hash-table-for-each.

Function: hash-table-merge! ht1 ht2 ¶

[SRFI-69]{srfi.69} Add all entries in a hash table ht2 into a hash table ht1, and returns ht1. Note that ht1 is destructively modified. If an entry with the same key exists in both ht1 and ht2, its value in ht1 is replaced with ht2’s.

Function: hash obj :optional bound ¶

[SRFI-69]{srfi.69} Like Gauche’s hash, except this one can take bound argument; if provided, it must be a positive integer, and the return value is limited between 0 and (- bound 1), inclusive.

Function: string-hash obj :optional bound ¶

Function: string-ci-hash obj :optional bound ¶

[SRFI-69]{srfi.69} These are like SRFI-13’s (see srfi.13 - String library), except these don’t take start and end argument.

Function: hash-by-identity obj :optional bound ¶

[SRFI-69]{srfi.69} This is Gauche’s eq-hash, except this one can take bound argument.