On this page:
37.1 Hash Table Lookup
hash-ref/ check
hash-ref/ identity
hash-ref/ default
hash-ref/ failure
37.2 Hash Table Accessors
hash-equal?
hash-has-key?
hash-domain
hash-range
37.3 Hash Table Combinations
hash-union
hash-union!
Version: 5.0.1

37 Hash Tables

Carl Eastlund <cce@racket-lang.org>

 (require unstable/hash)

This library is unstable; compatibility will not be maintained. See Unstable for more information.

This module provides tools for manipulating hash tables.

37.1 Hash Table Lookup

(hash-ref/check h k)  any/c
  h : hash?
  k : (lambda (k) (hash-has-key? h k))
Looks up key k in hash table h. Raises a contract error if h has no entry for k. Equivalent to (hash-ref h k), except for the specific exception value raised.

Example:

  > (hash-ref/check (make-immutable-hash '([1 . one] [2 . two] [3 . three])) 2)

  'two

(hash-ref/identity h k)  any/c
  h : hash?
  k : any/c
Looks up key k in hash table h. Returns k if h has no entry for k. Equivalent to (hash-ref h k (lambda () k)).

Examples:

  > (hash-ref/identity (make-immutable-hash '([1 . one] [2 . two] [3 . three])) 2)

  'two

  > (hash-ref/identity (make-immutable-hash '([1 . one] [2 . two] [3 . three])) 4)

  4

(hash-ref/default h k v)  any/c
  h : hash?
  k : any/c
  v : any/c
Looks up key k in hash table h. Returns v if h has no entry for k. Equivalent to (hash-ref h k (lambda () v)).

Examples:

  > (hash-ref/default (make-immutable-hash '([1 . one] [2 . two] [3 . three])) 2 'other)

  'two

  > (hash-ref/default (make-immutable-hash '([1 . one] [2 . two] [3 . three])) 4 'other)

  'other

(hash-ref/failure h k f)  any/c
  h : hash?
  k : any/c
  f : (-> any/c)
Looks up key k in hash table h. Returns the result of applying f (in tail position) if h has no entry for k. Equivalent to (hash-ref h k f).

Examples:

  > (hash-ref/failure (make-immutable-hash '([1 . one] [2 . two] [3 . three])) 2 gensym)

  'two

  > (hash-ref/failure (make-immutable-hash '([1 . one] [2 . two] [3 . three])) 4 gensym)

  'g49541

37.2 Hash Table Accessors

(hash-equal? h)  boolean?
  h : hash?
Reports whether h maps keys according to equal?.

Examples:

  > (hash-equal? #hash())

  #t

  > (hash-equal? #hasheq())

  #f

  > (hash-equal? #hasheqv())

  #f

(hash-has-key? h k)  boolean?
  h : hash?
  k : any/c
Reports whether h has an entry for k. This function is re-exported from scheme/base. In versions of Racket before hash-has-key? was implemented, this module provides its own definition.

Examples:

  > (hash-has-key? (make-immutable-hash '([1 . one] [2 . two] [3 . three])) 2)

  #t

  > (hash-has-key? (make-immutable-hash '([1 . one] [2 . two] [3 . three])) 4)

  #f

(hash-domain h)  list?
  h : hash?
Produces the domain of a hash table as a list of keys.

Example:

  > (hash-domain (make-immutable-hash '([1 . one] [2 . two] [3 . three])))

  '(1 2 3)

(hash-range h)  list?
  h : hash?
Produces the range of a hash table as a list of values.

Example:

  > (hash-range (make-immutable-hash '([1 . one] [2 . two] [3 . three])))

  '(one two three)

37.3 Hash Table Combinations

(hash-union h0 
  h ... 
  [#:combine combine 
  #:combine/key combine/key]) 
  (and/c hash? hash-can-functional-set?)
  h0 : (and/c hash? hash-can-functional-set?)
  h : hash?
  combine : (-> any/c any/c any/c)
   = (lambda _ (error 'hash-union ...))
  combine/key : (-> any/c any/c any/c any/c)
   = (lambda (k a b) (combine a b))
Computes the union of h0 with each hash table h by functional update, adding each element of each h to h0 in turn. For each key k and value v, if a mapping from k to some value v0 already exists, it is replaced with a mapping from k to (combine/key k v0 v).

Examples:

  > (hash-union (make-immutable-hash '([1 . one])) (make-immutable-hash '([2 . two])) (make-immutable-hash '([3 . three])))

  '#hash((1 . one) (2 . two) (3 . three))

  > (hash-union (make-immutable-hash '([1    one uno]  [2    two dos]))
                (make-immutable-hash '([1    ein une]  [2    zwei deux]))
                #:combine/key (lambda (k v1 v2) (append v1 v2)))

  '#hash((1 . (one uno ein une)) (2 . (two dos zwei deux)))

(hash-union! h0    
  h ...    
  [#:combine combine    
  #:combine/key combine/key])  void?
  h0 : (and/c hash? hash-mutable?)
  h : hash?
  combine : (-> any/c any/c any/c)
   = (lambda _ (error 'hash-union ...))
  combine/key : (-> any/c any/c any/c any/c)
   = (lambda (k a b) (combine a b))
Computes the union of h0 with each hash table h by mutable update, adding each element of each h to h0 in turn. For each key k and value v, if a mapping from k to some value v0 already exists, it is replaced with a mapping from k to (combine/key k v0 v).

Examples:

  (define h (make-hash))
  > h

  '#hash()

  > (hash-union! h (make-immutable-hash '([1    one uno]  [2    two dos])))
  > h

  '#hash((1 . (one uno)) (2 . (two dos)))

  > (hash-union! h
                 (make-immutable-hash '([1    ein une]  [2    zwei deux]))
                 #:combine/key (lambda (k v1 v2) (append v1 v2)))
  > h

  '#hash((1 . (one uno ein une)) (2 . (two dos zwei deux)))