Copyright (C) 2000-2012 |
GNU Info (guile.info)Hash TablesHash Tables ----------- Like the association list functions, the hash table functions come in several varieties: `hashq', `hashv', and `hash'. The `hashq' functions use `eq?' to determine whether two keys match. The `hashv' functions use `eqv?', and the `hash' functions use `equal?'. In each of the functions that follow, the TABLE argument must be a vector. The KEY and VALUE arguments may be any Scheme object. - primitive: hashq-ref table obj [dflt] Look up KEY in the hash table TABLE, and return the value (if any) associated with it. If KEY is not found, return DEFAULT (or `#f' if no DEFAULT argument is supplied). Uses `eq?' for equality testing. - primitive: hashv-ref table obj [dflt] Look up KEY in the hash table TABLE, and return the value (if any) associated with it. If KEY is not found, return DEFAULT (or `#f' if no DEFAULT argument is supplied). Uses `eqv?' for equality testing. - primitive: hash-ref table obj [dflt] Look up KEY in the hash table TABLE, and return the value (if any) associated with it. If KEY is not found, return DEFAULT (or `#f' if no DEFAULT argument is supplied). Uses `equal?' for equality testing. - primitive: hashq-set! table obj val Find the entry in TABLE associated with KEY, and store VALUE there. Uses `eq?' for equality testing. - primitive: hashv-set! table obj val Find the entry in TABLE associated with KEY, and store VALUE there. Uses `eqv?' for equality testing. - primitive: hash-set! table obj val Find the entry in TABLE associated with KEY, and store VALUE there. Uses `equal?' for equality testing. - primitive: hashq-remove! table obj Remove KEY (and any value associated with it) from TABLE. Uses `eq?' for equality tests. - primitive: hashv-remove! table obj Remove KEY (and any value associated with it) from TABLE. Uses `eqv?' for equality tests. - primitive: hash-remove! table obj Remove KEY (and any value associated with it) from TABLE. Uses `equal?' for equality tests. The standard hash table functions may be too limited for some applications. For example, you may want a hash table to store strings in a case-insensitive manner, so that references to keys named "foobar", "FOOBAR" and "FooBaR" will all yield the same item. Guile provides you with "extended" hash tables that permit you to specify a hash function and associator function of your choosing. The functions described in the rest of this section can be used to implement such custom hash table structures. If you are unfamiliar with the inner workings of hash tables, then this facility will probably be a little too abstract for you to use comfortably. If you are interested in learning more, see an introductory textbook on data structures or algorithms for an explanation of how hash tables are implemented. - primitive: hashq key size Determine a hash value for KEY that is suitable for lookups in a hashtable of size SIZE, where eq? is used as the equality predicate. The function returns an integer in the range 0 to SIZE - 1. NOTE that `hashq' may use internal addresses. Thus two calls to hashq where the keys are eq? are not guaranteed to deliver the same value if the key object gets garbage collected in between. This can happen, for example with symbols: (hashq 'foo n) (gc) (hashq 'foo n) may produce two different values, since 'foo will be garbage collected. - primitive: hashv key size Determine a hash value for KEY that is suitable for lookups in a hashtable of size SIZE, where eqv? is used as the equality predicate. The function returns an integer in the range 0 to SIZE - 1. NOTE that (hashv key) may use internal addresses. Thus two calls to hashv where the keys are eqv? are not guaranteed to deliver the same value if the key object gets garbage collected in between. This can happen, for example with symbols: (hashv 'foo n) (gc) (hashv 'foo n) may produce two different values, since 'foo will be garbage collected. - primitive: hash key size Determine a hash value for KEY that is suitable for lookups in a hashtable of size SIZE, where equal? is used as the equality predicate. The function returns an integer in the range 0 to SIZE - 1. - primitive: hashx-ref hash assoc table obj [dflt] This behaves the same way as the corresponding `ref' function, but uses HASHER as a hash function and ASSOC to compare keys. `hasher' must be a function that takes two arguments, a key to be hashed and a table size. `assoc' must be an associator function, like `assoc', `assq' or `assv'. By way of illustration, `hashq-ref table key' is equivalent to `hashx-ref hashq assq table key'. - primitive: hashx-set! hash assoc table obj val This behaves the same way as the corresponding `set!' function, but uses HASHER as a hash function and ASSOC to compare keys. `hasher' must be a function that takes two arguments, a key to be hashed and a table size. `assoc' must be an associator function, like `assoc', `assq' or `assv'. By way of illustration, `hashq-set! table key' is equivalent to `hashx-set! hashq assq table key'. - primitive: hashq-get-handle table obj This procedure is similar to its `-ref' cousin, but returns a "handle" from the hash table rather than the value associated with KEY. By convention, a handle in a hash table is the pair which associates a key with a value. Where `hashq-ref table key' returns only a `value', `hashq-get-handle table key' returns the pair `(key . value)'. - primitive: hashv-get-handle table obj This procedure is similar to its `-ref' cousin, but returns a "handle" from the hash table rather than the value associated with KEY. By convention, a handle in a hash table is the pair which associates a key with a value. Where `hashv-ref table key' returns only a `value', `hashv-get-handle table key' returns the pair `(key . value)'. - primitive: hash-get-handle table obj This procedure is similar to its `-ref' cousin, but returns a "handle" from the hash table rather than the value associated with KEY. By convention, a handle in a hash table is the pair which associates a key with a value. Where `hash-ref table key' returns only a `value', `hash-get-handle table key' returns the pair `(key . value)'. - primitive: hashx-get-handle hash assoc table obj This behaves the same way as the corresponding `-get-handle' function, but uses HASHER as a hash function and ASSOC to compare keys. `hasher' must be a function that takes two arguments, a key to be hashed and a table size. `assoc' must be an associator function, like `assoc', `assq' or `assv'. - primitive: hashq-create-handle! table key init This function looks up KEY in TABLE and returns its handle. If KEY is not already present, a new handle is created which associates KEY with INIT. - primitive: hashv-create-handle! table key init This function looks up KEY in TABLE and returns its handle. If KEY is not already present, a new handle is created which associates KEY with INIT. - primitive: hash-create-handle! table key init This function looks up KEY in TABLE and returns its handle. If KEY is not already present, a new handle is created which associates KEY with INIT. - primitive: hashx-create-handle! hash assoc table obj init This behaves the same way as the corresponding `-create-handle' function, but uses HASHER as a hash function and ASSOC to compare keys. `hasher' must be a function that takes two arguments, a key to be hashed and a table size. `assoc' must be an associator function, like `assoc', `assq' or `assv'. - primitive: hash-fold proc init table An iterator over hash-table elements. Accumulates and returns a result by applying PROC successively. The arguments to PROC are "(key value prior-result)" where key and value are successive pairs from the hash table TABLE, and prior-result is either INIT (for the first application of PROC) or the return value of the previous application of PROC. For example, `(hash-fold acons () tab)' will convert a hash table into an a-list of key-value pairs. automatically generated by info2www version 1.2.2.9 |