3.15 Dictionaries

A dictionary is an instance of a datatype that maps keys to values. The following datatypes are all dictionaries:

• hash tables;

• vectors (using only exact integers as keys);

• lists of pairs (an association list using equal? to compare keys); and

• structures whose types have the prop:dict property.

(require scheme/dict)

The bindings documented in this section are provided by the scheme/dict and scheme libraries, but not scheme/base.

(dict? v) → boolean?

v : any/c

Returns #t if v is a dictionary, #f otherwise.

Beware that dict? is not a constant-time test on pairs, since checking that v is an association list may require traversing the list.

Examples:

> (dict? #hash((a . "apple")))

#t

> (dict? '#("apple" "banana"))

#t

> (dict? '("apple" "banana"))

#f

> (dict? '((a . "apple") (b . "banana")))

#t

(dict-mutable? d) → boolean?

d : dict?

Returns #t if d is mutable via dict-set! and maybe dict-remove!, #f otherwise.

Examples:

> (dict-mutable? #hash((a . "apple")))

#f

> (dict-mutable? (make-hash))

#t

> (dict-mutable? '#("apple" "banana"))

#f

> (dict-mutable? (vector "apple" "banana"))

#t

> (dict-mutable? '((a . "apple") (b . "banana")))

#f

(dict-can-remove-keys? d) → boolean?

d : dict?

Returns #t if d supports removing mappings via dict-remove! and/or dict-remove, #f otherwise.

Examples:

> (dict-can-remove-keys? #hash((a . "apple")))

#t

> (dict-can-remove-keys? '#("apple" "banana"))

#f

> (dict-can-remove-keys? '((a . "apple") (b . "banana")))

#t

(dict-can-functional-set? d) → boolean?

d : dict?

Returns #t if d supports functional update via dict-set and maybe dict-remove, #f otherwise.

Examples:

> (dict-can-functional-set? #hash((a . "apple")))

#t

> (dict-can-functional-set? (make-hash))

#f

> (dict-can-functional-set? '#("apple" "banana"))

#f

> (dict-can-functional-set? '((a . "apple") (b . "banana")))

#t

(dict-set! dict key v) → void?

dict : (and/c dict? (not/c immutable?))

key : any/c

v : any/c

Maps key to v in dict, overwriting any existing mapping for key. The update can fail with a exn:fail:contract exception if dict is not mutable or if key is not an allowed key for the dictionary (e.g., not an exact integer in the appropriate range when dict is a vector).

Examples:

> (define h (make-hash))

> (dict-set! h 'a "apple")

> h

#hash((a . "apple"))

> (define v (vector #f #f #f))

> (dict-set! v 0 "apple")

> v

#("apple" #f #f)

(dict-set dict key v) → (and/c dict? immutable?)

dict : (and/c dict? immutable?)

key : any/c

v : any/c

Functionally extends dict by mapping key to v, overwriting any existing mapping for key, and returning an extended dictionary. The update can fail with a exn:fail:contract exception if dict does not support functional extension or if key is not an allowed key for the dictionary.

Examples:

> (dict-set #hash() 'a "apple")

#hash((a . "apple"))

> (dict-set #hash((a . "apple") (b . "beer")) 'b "banana")

#hash((a . "apple") (b . "banana"))

> (dict-set '() 'a "apple")

((a . "apple"))

> (dict-set '((a . "apple") (b . "beer")) 'b "banana")

((a . "apple") (b . "banana"))

(dict-ref dict key [failure-result]) → any

dict : dict?

key : any/c

failure-result   :   any/c       =   (lambda () (raise (make-exn:fail ....)))

Returns the value for key in dict. If no value is found for key, then failure-result determines the result:

• If failure-result is a procedure, it is called (through a tail call) with no arguments to produce the result.

• Otherwise, failure-result is returned as the result.

Examples:

> (dict-ref #hash((a . "apple") (b . "beer")) 'a)

"apple"

> (dict-ref #hash((a . "apple") (b . "beer")) 'c)

hash-ref: no value found for key: c

> (dict-ref #hash((a . "apple") (b . "beer")) 'c #f)

#f

> (dict-ref '((a . "apple") (b . "banana")) 'b)

"banana"

> (dict-ref #("apple" "banana") 1)

"banana"

> (dict-ref #("apple" "banana") 3 #f)

#f

> (dict-ref #("apple" "banana") -3 #f)

#f

(dict-remove! dict key) → void?

dict : (and/c dict? (not/c immutable?))

key : any/c

Removes any existing mapping for key in dict. The update can fail if dict is not mutable or does not support removing keys (as is the case for vectors, for example).

Examples:

> (define h (make-hash))

> (dict-set! h 'a "apple")

> h

#hash((a . "apple"))

> (dict-remove! h 'a)

> h

#hash()

(dict-remove dict key) → (and/c dict? immutable?)

dict : (and/c dict? immutable?)

key : any/c

Functionally removes any existing mapping for key in dict, returning the updated dictionary. The update can fail if dict does not support functional update or does not support removing keys.

Examples:

> (define h #hash())

> (define h (dict-set h 'a "apple"))

> h

#hash((a . "apple"))

> (dict-remove h 'a)

#hash()

> h

#hash((a . "apple"))

> (dict-remove h 'z)

#hash((a . "apple"))

> (dict-remove '((a . "apple") (b . "banana")) 'a)

((b . "banana"))

(dict-map dict proc) → (listof any/c)

dict : dict?

proc : (any/c any/c . -> . any/c)

Applies the procedure proc to each element in dict in an unspecified order, accumulating the results into a list. The procedure proc is called each time with a key and its value.

Examples:

> (dict-map #hash((a . "apple") (b . "banana")) vector)

(#(a "apple") #(b "banana"))

(dict-for-each dict proc) → void?

dict : dict?

proc : (any/c any/c . -> . any)

Applies proc to each element in dict (for the side-effects of proc) in an unspecified order. The procedure proc is called each time with a key and its value.

Examples:

> (dict-for-each #hash((a . "apple") (b . "banana"))                    (lambda (k v)                      (printf "~a = ~s\n" k v)))

a = "apple"   b = "banana"

(dict-count dict) → nonnegative-exact-integer?

dict : dict?

Returns the number of keys mapped by dict, usually in constant time.

Examples:

> (dict-count #hash((a . "apple") (b . "banana")))

2

> (dict-count #("apple" "banana"))

2

(dict-iterate-first dict) → any/c

dict : dict?

Returns #f if dict contains no elements, otherwise it returns a non-#f value that is a index to the first element in the dict table; “first” refers to an unspecified ordering of the dictionary elements. For a mutable dict, this index is guaranteed to refer to the first item only as long as no mappings are added to or removed from dict.

Examples:

> (dict-iterate-first #hash((a . "apple") (b . "banana")))

0

> (dict-iterate-first #hash())

#f

> (dict-iterate-first #("apple" "banana"))

0

> (dict-iterate-first '((a . "apple") (b . "banana")))

#<assoc-iter>

(dict-iterate-next dict pos) → any/c

dict : dict?

pos : any/c

Returns either a non-#f that is an index to the element in dict after the element indexed by pos or #f if pos refers to the last element in dict. If pos is not a valid index, then the exn:fail:contract exception is raised. For a mutable dict, the result index is guaranteed to refer to its item only as long as no items are added to or removed from dict. The dict-iterate-next operation should take constant time.

Examples:

> (define h #hash((a . "apple") (b . "banana")))

> (define i (dict-iterate-first h))

> i

0

> (dict-iterate-next h i)

1

> (dict-iterate-next h (dict-iterate-next h i))

#f

(dict-iterate-key dict pos) → any

dict : dict?

pos : any/c

Returns the key for the element in dict at index pos. If pos is not a valid index for dict, the exn:fail:contract exception is raised. The dict-iterate-key operation should take constant time.

Examples:

> (define h '((a . "apple") (b . "banana")))

> (define i (dict-iterate-first h))

> (dict-iterate-key h i)

a

> (dict-iterate-key h (dict-iterate-next h i))

b

(dict-iterate-value dict pos) → any

dict : dict?

pos : any/c

Returns the value for the element in dict at index pos. If pos is not a valid index for dict, the exn:fail:contract exception is raised. The dict-iterate-key operation should take constant time.

Examples:

> (define h '((a . "apple") (b . "banana")))

> (define i (dict-iterate-first h))

> (dict-iterate-value h i)

"apple"

> (dict-iterate-value h (dict-iterate-next h i))

"banana"

(in-dict dict) → sequence?

dict : dict?

Returns a sequence whose each element is two values: a key and corresponding value from dict.

Examples:

> (define h #hash((a . "apple") (b . "banana")))

> (for/list ([(k v) (in-dict h)])       (format "~a = ~s" k v))

("a = \"apple\"" "b = \"banana\"")

(in-dict-keys dict) → sequence?

dict : dict?

Returns a sequence whose elements are the keys of dict.

Examples:

> (define h #hash((a . "apple") (b . "banana")))

> (for/list ([k (in-dict-keys h)])       k)

(a b)

(in-dict-values dict) → sequence?

dict : dict?

Returns a sequence whose elements are the values of dict.

Examples:

> (define h #hash((a . "apple") (b . "banana")))

> (for/list ([v (in-dict-values h)])       v)

("apple" "banana")

(in-dict-pairs dict) → sequence?

dict : dict?

Returns a sequence whose elements are pairs, each containing a key and its value from dict (as opposed to using in-dict, which gets the key and value as separate values for each element).

Examples:

> (define h #hash((a . "apple") (b . "banana")))

> (for/list ([p (in-dict-pairs h)])       p)

((a . "apple") (b . "banana"))

prop:dict : struct-type-property?

A structure type property (see Structure Type Properties) that supplies dictionary-operation implementations for a structure type. The property value must be a vector of ten procedures (some optional) that are applied only to instances of the structure type that has the property:

• ref : a procedure like dict-ref that accepts either two or three arguments

• set! : a procedure like dict-set! that accepts three arguments, or #f if mutation is not supported

• set : a procedure like dict-set that accepts three arguments and returns an updated dictionary, or #f if functional update is not supported

• remove! : a procedure like dict-remove! that accepts two arguments, or #f if mutation is not supported or if key removal is not supported

• remove : a procedure like dict-remove that accepts two arguments and returns an updated dictionary, or #f if functional update or key removal is not supported

• count : a procedure like dict-count that accepts one argument

• iterate-first : a procedure like dict-iterate-first that accepts one argument

• iterate-next : a procedure like dict-iterate-next that accepts two arguments; the procedure is responsible for checking that the second argument is a valid position for the first argument

• iterate-key : a procedure like dict-iterate-key that accepts two arguments; the procedure is responsible for checking that the second argument is a valid position for the first argument

• iterate-value : a procedure like dict-iterate-value that accepts two arguments; the procedure is responsible for checking that the second argument is a valid position for the first argument

(make-custom-hash eql? hash-proc hash2-proc) → dict?   eql? : (any/c any/c . -> . any/c)   hash-proc : (any/c . -> . exact-integer?)   hash2-proc : (any/c . -> . exact-integer?)

(make-immutable-custom-hash   eql?             hash-proc             hash2-proc)   →   dict?   eql? : (any/c any/c . -> . any/c)   hash-proc : (any/c . -> . exact-integer?)   hash2-proc : (any/c . -> . exact-integer?)

(make-weak-custom-hash   eql?             hash-proc             hash2-proc)   →   dict?   eql? : (any/c any/c . -> . any/c)   hash-proc : (any/c . -> . exact-integer?)   hash2-proc : (any/c . -> . exact-integer?)

Creates a dictionary that is implemented in terms of a hash table where keys are compared with eql? and hashed with hash-proc and hash2-proc. See prop:equal+hash for information on suitable equality and hashing functions.

The make-custom-hash and make-weak-custom-hash functions create a mutable dictionary that does not support functional update, while make-immutable-custom-hash creates an immutable dictionary that supports functional update. The dictionary created by make-weak-custom-hash retains its keys weakly, like the result of make-weak-hash.

Dictionaries created by make-custom-hash and company are equal? when they have the same mutability and key strength, the associated procedures are equal?, and the key–value mappings are the same when keys and values are compared with equal?.

Examples:

> (define h (make-custom-hash (lambda (a b)                                   (string=? (format "~a" a)                                             (format "~a" b)))                                 (lambda (a)                                   (equal-hash-code                                    (format "~a" a)))))

> (dict-set! h 1 'one)

> (dict-ref h "1")

one