On this page:
6.1 Dictionary Constructors
empty-dict
make-dict
custom-dict
6.2 Dictionary Lookup
dict-ref!
dict-ref/ check
dict-ref/ identity
dict-ref/ default
dict-ref/ failure
6.3 Dictionary Accessors
dict-empty?
dict-has-key?
dict-domain
dict-range
6.4 Dictionary Combinations
dict-union
dict-union!
6.5 Dictionary Structure Properties
wrapped-dict-property
6.6 Contracted Dictionaries
Version: 5.0.1

6 Dictionaries

Carl Eastlund <cce@racket-lang.org>

 (require unstable/dict)

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

This module provides tools for manipulating dictionary values.

6.1 Dictionary Constructors

(empty-dict [#:mutable? mutable?    
  #:weak? weak?    
  #:compare compare])  hash?
  mutable? : boolean? = weak?
  weak? : boolean? = #f
  compare : (or/c 'eq 'eqv 'equal) = equal
Constructs an empty hash table based on the behavior specified by mutable?, weak?, and compare.

Examples:

  > (empty-dict)

  '#hash()

  > (empty-dict #:mutable? #t)

  '#hash()

  > (empty-dict #:weak? #t)

  '#hash()

  > (empty-dict #:compare 'eqv)

  '#hasheqv()

(make-dict d    
  [#:mutable? mutable?    
  #:weak? weak?    
  #:compare compare])  hash?
  d : dict?
  mutable? : boolean? = weak?
  weak? : boolean? = #f
  compare : (or/c 'eq 'eqv 'equal) = equal
Converts a given dictionary d to a hash table based on the behavior specified by mutable?, weak?, and compare.

Examples:

  > (make-dict '([1 . one] [2 . two]))

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

  > (make-dict '([1 . one] [2 . two]) #:mutable? #t)

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

  > (make-dict '([1 . one] [2 . two]) #:weak? #t)

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

  > (make-dict '([1 . one] [2 . two]) #:compare 'eqv)

  '#hasheqv((1 . one) (2 . two))

(custom-dict equiv?    
  [hash-primary    
  hash-secondary    
  #:mutable? mutable?    
  #:weak? weak?])  dict?
  equiv? : (-> any/c any/c any/c)
  hash-primary : (-> any/c exact-integer?) = (lambda (x) 0)
  hash-secondary : (-> any/c exact-integer?) = (lambda (x) 0)
  mutable? : boolean? = weak?
  weak? : boolean? = #f
Constructs a dictionary based on custom comparison and optional hash functions. Given no hash functions, the dictionary defaults to a degenerate hash function and is thus essentially equivalent to a list-based dictionary.

Examples:

  (define table (custom-dict = add1 sub1 #:mutable? #t))
  > (dict-set! table 1 'one)
  > (dict-set! table 2 'two)
  > (for/list ([(key val) (in-dict table)])
      (cons key val))

  '((2 . two) (1 . one))

6.2 Dictionary Lookup

(dict-ref! d k v)  any/c
  d : (and/c dict? dict-mutable?)
  k : any/c
  v : (or/c (-> any/c) any/c)
Looks up key k in dictionary d. If d has no entry for k, updates d to map k to the result of (v) (if v is a procedure) or v (otherwise), and returns the new mapping.

Examples:

  (define d (make-hash))
  > (dict-set! d 1 'one)
  > (dict-set! d 2 'two)
  > d

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

  > (dict-ref! d 2 'dos)

  'two

  > d

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

  > (dict-ref! d 3 'tres)

  'tres

  > d

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

  > (dict-ref! d 4 gensym)

  'g51036

  > d

  '#hash((1 . one) (2 . two) (3 . tres) (4 . g51036))

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

Example:

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

  'two

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

Examples:

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

  'two

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

  4

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

Examples:

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

  'two

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

  'other

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

Examples:

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

  'two

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

  'g51126

6.3 Dictionary Accessors

(dict-empty? d)  boolean?
  d : dict?
Reports whether d is empty (has no keys).

Examples:

  > (dict-empty? '())

  #t

  > (dict-empty? '([1 . one] [2 . two]))

  #f

(dict-has-key? d k)  boolean?
  d : dict?
  k : any/c
Reports whether d has an entry for k.

Examples:

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

  #t

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

  #f

(dict-domain d)  list?
  d : dict?
Produces the domain of a dictionary as a list of keys.

Example:

  > (dict-domain '([1 . one] [2 . two] [3 . three]))

  '(1 2 3)

(dict-range d)  list?
  d : dict?
Produces the range of a dictionary as a list of values.

Example:

  > (dict-range '([1 . one] [2 . two] [3 . three]))

  '(one two three)

6.4 Dictionary Combinations

(dict-union d0 
  d ... 
  [#:combine combine 
  #:combine/key combine/key]) 
  (and/c dict? dict-can-functional-set?)
  d0 : (and/c dict? dict-can-functional-set?)
  d : dict?
  combine : (-> any/c any/c any/c)
   = (lambda _ (error 'dict-union ...))
  combine/key : (-> any/c any/c any/c any/c)
   = (lambda (k a b) (combine a b))
Computes the union of d0 with each dictionary d by functional update, adding each element of each d to d0 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:

  > (dict-union '([1 . one]) '([2 . two]) '([3 . three]))

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

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

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

(dict-union! d0    
  d ...    
  [#:combine combine    
  #:combine/key combine/key])  void?
  d0 : (and/c dict? dict-mutable?)
  d : dict?
  combine : (-> any/c any/c any/c)
   = (lambda _ (error 'dict-union! ...))
  combine/key : (-> any/c any/c any/c any/c)
   = (lambda (k a b) (combine a b))
Computes the union of d0 with each dictionary d by mutable update, adding each element of each d to d0 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 d (make-hash))
  > d

  '#hash()

  > (dict-union! d '([1    one uno]  [2    two dos]))
  > d

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

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

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

6.5 Dictionary Structure Properties

(wrapped-dict-property #:unwrap unwrap    
  [#:wrap wrap    
  #:predicate pred    
  #:mutable? mutable?    
  #:weak? mutable?    
  #:functional? functional?])  vector?
  unwrap : (-> (and/c dict? pred) dict?)
  wrap : (-> dict? (and/c dict? pred)) = (lambda (x) x)
  pred : (-> any/c boolean?) = (lambda (x) #t)
  mutable? : boolean? = weak?
  mutable? : boolean? = #f
  functional? : boolean? = #t
Produces a value appropriate for prop:dict for a derived dictionary type recognized by pred. Dictionaries constructed from this property will extract a nested dictionary using unwrap and will produce a wrapped dictionary during functional update using wrap.

Examples:

  (define-struct table [dict]
    #:transparent
    #:property prop:dict
    (wrapped-dict-property
     #:unwrap (lambda (d) (table-dict d))
     #:wrap (lambda (d) (make-table d))
     #:predicate (lambda (d) (table? d))))
  > (dict? (make-table '([1 . one] [2 . two])))

  #t

  > (dict-ref (make-table '([1 . one] [2 . two])) 1)

  'one

  > (dict-set (make-table '([1 . one] [2 . two])) 3 'three)

  (table ( (1 . one) (2 . two) (3 . three)))

6.6 Contracted Dictionaries

This library re-provides dict/c from unstable/contract.