(guile.info.gz) Hash Table Reference

(guile.info.gz) Hash Table Examples
 
 22.7.3.2 Hash Table Reference
 .............................
 
 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.
 
  -- Scheme Procedure: make-hash-table size
      Create a new hash table of SIZE slots.  Note that the number of
      slots does not limit the size of the table, it just tells how large
      the underlying vector will be.  The SIZE should be similar to the
      expected number of elements which will be added to the table, but
      they need not match.  For good performance, it might be a good
      idea to use a prime number as the SIZE.
 
  -- Scheme Procedure: hashq-ref table key [dflt]
  -- C Function: scm_hashq_ref (table, key, 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.
 
  -- Scheme Procedure: hashv-ref table key [dflt]
  -- C Function: scm_hashv_ref (table, key, 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.
 
  -- Scheme Procedure: hash-ref table key [dflt]
  -- C Function: scm_hash_ref (table, key, 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.
 
  -- Scheme Procedure: hashq-set! table key val
  -- C Function: scm_hashq_set_x (table, key, val)
      Find the entry in TABLE associated with KEY, and store VALUE
      there. Uses `eq?' for equality testing.
 
  -- Scheme Procedure: hashv-set! table key val
  -- C Function: scm_hashv_set_x (table, key, val)
      Find the entry in TABLE associated with KEY, and store VALUE
      there. Uses `eqv?' for equality testing.
 
  -- Scheme Procedure: hash-set! table key val
  -- C Function: scm_hash_set_x (table, key, val)
      Find the entry in TABLE associated with KEY, and store VALUE
      there. Uses `equal?' for equality testing.
 
  -- Scheme Procedure: hashq-remove! table key
  -- C Function: scm_hashq_remove_x (table, key)
      Remove KEY (and any value associated with it) from TABLE.  Uses
      `eq?' for equality tests.
 
  -- Scheme Procedure: hashv-remove! table key
  -- C Function: scm_hashv_remove_x (table, key)
      Remove KEY (and any value associated with it) from TABLE.  Uses
      `eqv?' for equality tests.
 
  -- Scheme Procedure: hash-remove! table key
  -- C Function: scm_hash_remove_x (table, key)
      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.
 
  -- Scheme Procedure: hashq key size
  -- C Function: scm_hashq (key, size)
      Determine a hash value for KEY that is suitable for lookups in a
      hash table 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.
 
  -- Scheme Procedure: hashv key size
  -- C Function: scm_hashv (key, size)
      Determine a hash value for KEY that is suitable for lookups in a
      hash table 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.
 
  -- Scheme Procedure: hash key size
  -- C Function: scm_hash (key, size)
      Determine a hash value for KEY that is suitable for lookups in a
      hash table of size SIZE, where `equal?' is used as the equality
      predicate.  The function returns an integer in the range 0 to SIZE
      - 1.
 
  -- Scheme Procedure: hashx-ref hash assoc table key [dflt]
  -- C Function: scm_hashx_ref (hash, assoc, table, key, dflt)
      This behaves the same way as the corresponding `ref' function, but
      uses HASH as a hash function and ASSOC to compare keys.  `hash'
      must be a function that takes two arguments, a key to be hashed
      and a table size.  `assoc' mu