3.15 Dictionaries
A dictionary is an instance of a datatype that maps keys to
values. The following datatypes are all dictionaries:
A dictionary can be used as a two-valued sequence (see
Sequences). The associations of the dictionary serve as elements
of the sequence. See also in-dict, in-dict-keys, and in-dict-values.
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 |
|
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).
Maps each
key to each
v in
dict, overwriting any
existing mapping for each
key. The update can fail with a
exn:fail:contract exception if
dict is not mutable
or if any
key is not an allowed key for the dictionary (e.g., not
an exact integer in the appropriate range when
dict is a
vector). The update takes place from the left, so later mappings overwrite
earlier mappings.
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((b . "banana") (a . "apple")) | | > (dict-set '() 'a "apple") | '((a . "apple")) | | > (dict-set '((a . "apple") (b . "beer")) 'b "banana") | '((a . "apple") (b . "banana")) |
|
Functionally extends
dict by mapping each
key to
each
v, overwriting any existing mapping for each
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 any
key is not an allowed key for the
dictionary. The update takes place from the left, so later mappings overwrite
earlier mappings.
Examples: |
| > (dict-set* #hash() 'a "apple" 'b "beer") | '#hash((b . "beer") (a . "apple")) | | > (dict-set* #hash((a . "apple") (b . "beer")) 'b "banana" 'a "anchor") | '#hash((b . "banana") (a . "anchor")) | | > (dict-set* '() 'a "apple" 'b "beer") | '((a . "apple") (b . "beer")) | | > (dict-set* '((a . "apple") (b . "beer")) 'b "banana" 'a "anchor") | '((a . "anchor") (b . "banana")) | | > (dict-set* '((a . "apple") (b . "beer")) 'b "banana" 'b "balistic") | '((a . "apple") (b . "balistic")) |
|
Returns #t if dict contains a value for the given
key, #f otherwise.
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) | contract violation: expected <exact-nonnegative-integer?>, | given: -3 | contract on dict-ref from | (file | /var/tmp/racket/collects/racket/dict.rkt) | blaming top-level | contract: | (->i | ((d dict?) (k (d) ...)) | ((default any/c)) | any) | at: <collects>/racket/dict.rkt:147.2 |
|
Returns the value for
key in
dict. If no value
is found for
key, then
to-set determines the
result as in
dict-ref (i.e., it is either a thunk that computes a value
or a plain value), and this result is stored in
dict for the
key. (Note that if
to-set is a thunk, it is not
invoked in tail position.)
Composes
dict-ref and
dict-set! to update an
existing mapping in
dict, where the optional
failure-result
argument is used as in
dict-ref when no mapping exists for
key already.
Composes
dict-ref and
dict-set to functionally
update an existing mapping in
dict, where the optional
failure-result
argument is used as in
dict-ref when no mapping exists for
key already.
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).
Functionally removes any existing mapping for key in
dict, returning the fresh dictionary. The update can fail
if dict does not support functional update or does not
support removing keys.
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.
Example: |
| > (dict-map #hash((a . "apple") (b . "banana")) vector) | '(#(b "banana") #(a "apple")) |
|
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.
Returns the number of keys mapped by dict, usually in
constant time.
Returns #f if dict contains no elements, otherwise
it returns a non-#f value that is an 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.
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.
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.
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.
Returns a
sequence
whose each element is two values: a key and corresponding value from
dict.
Examples: |
| > (define h #hash((a . "apple") (b . "banana"))) | | '("b = \"banana\"" "a = \"apple\"") |
|
Returns a sequence whose elements are the keys of dict.
Examples: |
| > (define h #hash((a . "apple") (b . "banana"))) | | '(b a) |
|
Returns a sequence whose elements are the values of dict.
Examples: |
| > (define h #hash((a . "apple") (b . "banana"))) | | '("banana" "apple") |
|
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"))) | | '((b . "banana") (a . "apple")) |
|
Returns a list of the keys from
dict in an unspecified order.
Returns a list of the values from
dict in an unspecified order.
Returns a list of the associations from
dict in an unspecified order.
Examples: |
| > (define h #hash((a . "apple") (b . "banana"))) | | > (dict->list h) | '((b . "banana") (a . "apple")) |
|
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
A structure type property for defining dictionaries with
contracts. The value associated with
prop:dict/contract must
be a list of two immutable vectors:
| (list dict-vector |
| (vector type-key-contract |
| type-value-contract |
| type-iter-contract |
| instance-key-contract |
| instance-value-contract |
| instance-iter-contract)) |
The first vector must be suitable as a value for prop:dict
(in addition, it must be an immutable vector). The second vector must
contain six elements; each of the first three is a contract for the
dictionary type’s keys, values, and positions, respectively. Each of
the second three is either #f or a procedure used to extract
the contract from a dictionary instance.
Returns the contract that
d imposes on its keys, values, or
iterators, respectively, if
d implements the
prop:dict/contract interface.
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?.