6 Dictionaries

▼ |  | Unstable

1 | Guidelines for developing unstable libraries
2 | Bytes
3 | Classes and Objects
4 | Contracts
5 | Definitions
6 | Dictionaries
7 | Directories
8 | Exceptions
9 | Filesystem
10 | Functions
11 | Lists
12 | Net
13 | Path
14 | PLane T Packages
15 | Ports
16 | Pretty-Printing
17 | Regular Expressions
18 | Requiring Modules
19 | Sandboxed Evaluation
20 | Scribble Documentation
21 | Sets
22 | S-Expression Diff
23 | Source Locations
24 | Strings
25 | Structs
26 | Syntax
27 | Planet Package Macros
28 | Text Representations
29 | Multiple Values
30 | XML and CSS
31 | Polymorphic Contracts
32 | Finding Mutated Variables
33 | Find
34 | Interface-Oriented Programming for Classes
35 | Sequences
36 | Hash Tables
37 | Match
38 | Generics
39 | Mark Parameters
40 | Debugging
41 | Contracts for macro subexpressions
42 | GUI libraries

► | 6 | Dictionaries

6.1 | Dictionary Constructors
6.2 | Dictionary Lookup
6.3 | Dictionary Accessors
6.4 | Dictionary Combinations
6.5 | Dictionary Structure Properties
6.6 | Contracted Dictionaries

On this page:

6.1`` Dictionary Constructors
empty-dict
make-dict
custom-dict
6.2`` Dictionary Lookup
dict-ref/ check
dict-ref/ identity
dict-ref/ default
dict-ref/ failure
6.3`` Dictionary Accessors
dict-empty?
6.4`` Dictionary Combinations
dict-union
dict-union!
6.5`` Dictionary Structure Properties
wrapped-dict-property
6.6`` Contracted Dictionaries

Version: 5.0.1.5
top← prev up next →

### 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/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)
'g3528

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

#### 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.

top← prev up next →