Sagittarius Users' Reference

Hashtables

The (rnrs hashtables (6))library provides a set of operations on hashtables. A hashtable is a data structure that associates keys with values. Any object can be used as a key, provided a hash function and a suitable equivalence function is available. A hash function is a procedure that maps keys to exact integer objects. It is the programmer's responsibility to ensure that the hash function is compatible with the equivalence function, which is a procedure that accepts two keys and returns true if they are equivalent and #f otherwise. Standard hashtables for arbitrary objects based on the eq? and eqv? predicates are provided. Also, hash functions for arbitrary objects, strings, and symbols are provided.

This section uses the hashtable parameter name for arguments that must be hashtables, and the key parameter name for arguments that must be hashtable keys.

Library (rnrs hashtable (6))

[R6RS] This library exports a set of operations on hashtables.

Constructors

Function make-eq-hashtable :optional k weakness

Function make-eqv-hashtable :optional k weakness

[R6RS+] Returns a newly allocated mutable hashtable that accepts arbitrary objects as keys, and compares those keys with eq?(make-eq-hashtable) or eqv? (make-eqv-hashtable).

If optional argument k is given, it must be exact non-negative integer or #f. If it's #f, then the procedure picks up default initial capacity, otherwise the initial capacity of the hashtable is set to approximately k elements.

If optional argument weakness is given, then it must be one of the symbols key, value or both, or #f. If the value is one of the symbols, then the procedure creates weak hashtable of given symbol's weakness. If the symbol is key, then entries whose keys are refered only from this hashtable might be removed when garbage collection is occurred. value is for entry values. both is for both.

Function make-hashtable hash-function equiv :optional k weakness

[R6RS] Hash-function and equiv must be procedures.

Hash-function should accept a key as an argument and should return a non-negative exact integer object. Equiv should accept two keys as arguments and return a single value.

The make-hashtable procedure returns a newly allocated mutable hashtable using hash-function as the hash function and equiv as the equivalence function used to compare keys.

If optional argument k and weakness are the same as make-eq-hashtable and make-eqv-hashtable.

Procedures

Function hashtable? obj

[R6RS] Returns #t if obj is a hashtable, #f otherwise.

Function hashtable-size hashtable

[R6RS] Returns the number of keys contained in hashtable as an exact integer object.

Function hashtable-ref hashtable key :optional (default #f)

[R6RS+] Returns the value in hashtable associated with key. If hashtable does not contain an association for key, default is returned.

Since Sagittarius version 0.3.4, this procedure's default argument is optional to implement SRFI-17 efficiently.

Function hashtable-set! hashtable key obj

[R6RS] Changes hashtable to associate key with obj, adding a new association or replacing any existing association for key, and returns unspecified values.

Function hashtable-delete! hashtable key

[R6RS] Removes any association for key within hashtable and returns unspecified values.

Function hashtable-contains? hashtable key

[R6RS] Returns #t if hashtable contains an association for key, #f otherwise.

Note: On Sagittarius, hashtable-ref and hashtable-contains? do not make any difference fot the performance.

Function hashtable-update! hashtable key proc default

desc{[R6RS] Proc should accept one argument, should return a single value.

The hashtable-update! procedure applies proc to the value in hashtable associated with key, or to default if hashtable does not contain an association for key. The hashtable is then changed to associate key with the value returned by proc. }

Function hashtable-copy hashtable :optional mutable

[R6RS] Returns a copy of hashtable. If the mutable argument is provided and is true, the returned hashtable is mutable; otherwise it is immutable.

Function hashtable-clear hashtable :optional k

[R6RS] Removes all associations from hashtable and returns unspecified values.

If a second argument is given, the current capacity of the hashtable is reset to approximately k elements.

Function hashtable-keys hashtable

Function hashtable-entries hashtable

[R6RS] Returns a vector of all keys or entries in hashtable, respectively. The order of the vector is unspecified.

Inspection

Function hashtable-equivalence-function hashtable

Function hashtable-hash-function hashtable

[R6RS] Returns the equivalence or hash function used by _hashtable_respectively.

Function hashtable-mutable? hashtable

[R6RS] Returns #t if hashtable is mutable, otherwise #f.

Hash functions

Function equal-hash obj

Function symbol-hash symbol

[R6RS] Returns hash value of given argument. Each procedures return the hash values suitable for equal? and symbols.

Function string-hash string :optional bound start end

Function string-ci-hash string :optional bound start end

[R6RS+][SRFI-13] Returns hash value of given argument. Each procedures return the hash values suitable for string=? and string-ci=?.

If the optional argument start and end is given, then the given string will be substringed with start and end.

If the optional argument bound is given, it must be exact integer and hash function will also use the given value.