Version: 5.0.2

### 6Dictionaries

 (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.1Dictionary 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.2Dictionary Lookup

 (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) 'g4954

#### 6.3Dictionary 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

#### 6.4Dictionary 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.5Dictionary 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.6Contracted Dictionaries

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