`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.

DRAFT