3.15 Dictionaries
A dictionary is an instance of a datatype that maps keys to values. The following datatypes are all dictionaries:
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.
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? |
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? |
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? |
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 |
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 |
Examples: |
> (dict-set #hash() 'a "apple") |
'#hash((a . "apple")) |
> (dict-set #hash((a . "apple") (b . "beer")) 'b "banana") |
'#hash((b . "banana") (a . "apple")) |
> (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 | ||||||||||||
|
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 : (and/c dict? (not/c immutable?)) | ||||||||||||||||||||||||||||
key : any/c | ||||||||||||||||||||||||||||
updater : (any/c . -> . any/c) | ||||||||||||||||||||||||||||
|
Examples: |
> (define h (make-hash)) |
> (dict-update! h 'a add1) |
hash-ref: no value found for key: 'a |
> (dict-update! h 'a add1 0) |
> h |
'#hash((a . 1)) |
> (define v (vector #f #f #f)) |
> (dict-update! v 0 not) |
> v |
'#(#t #f #f) |
(dict-update dict key updater [failure-result]) | ||||||||||||
→ (and/c dict? immutable?) | ||||||||||||
dict : dict? | ||||||||||||
key : any/c | ||||||||||||
updater : (any/c . -> . any/c) | ||||||||||||
|
Examples: |
> (dict-update #hash() 'a add1) |
hash-ref: no value found for key: 'a |
> (dict-update #hash() 'a add1 0) |
'#hash((a . 1)) |
> (dict-update #hash((a . "apple") (b . "beer")) 'b string-length) |
'#hash((b . 4) (a . "apple")) |
(dict-remove! dict key) → void? |
dict : (and/c dict? (not/c immutable?)) |
key : any/c |
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 |
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")) |
Example: |
> (dict-map #hash((a . "apple") (b . "banana")) vector) |
'(#(b "banana") #(a "apple")) |
Example: | |||
| |||
|
(dict-count dict) → exact-nonnegative-integer? |
dict : dict? |
Examples: |
> (dict-count #hash((a . "apple") (b . "banana"))) |
2 |
> (dict-count #("apple" "banana")) |
2 |
(dict-iterate-first dict) → any/c |
dict : 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 |
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 |
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 |
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" |
Examples: | ||
> (define h #hash((a . "apple") (b . "banana"))) | ||
| ||
'("b = \"banana\"" "a = \"apple\"") |
(in-dict-keys dict) → sequence? |
dict : dict? |
Examples: | ||
> (define h #hash((a . "apple") (b . "banana"))) | ||
| ||
'(b a) |
(in-dict-values dict) → sequence? |
dict : dict? |
Examples: | ||
> (define h #hash((a . "apple") (b . "banana"))) | ||
| ||
'("banana" "apple") |
(in-dict-pairs dict) → sequence? |
dict : dict? |
Examples: | ||
> (define h #hash((a . "apple") (b . "banana"))) | ||
| ||
'((b . "banana") (a . "apple")) |
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
| |||||||||||||||||||||||||
| |||||||||||||||||||||||||
|
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: | ||||||
| ||||||
> (dict-set! h 1 'one) | ||||||
> (dict-ref h "1") | ||||||
'one |