6 Dictionaries

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

Version: 5.0.1

This library is unstable; compatibility will not be maintained. See Unstable for more information.

This module provides tools for manipulating dictionary values.

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

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

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

(dict-ref! d k v) → any/c

d : (and/c dict? dict-mutable?)

k : any/c

v : (or/c (-> any/c) any/c)

Looks up key k in dictionary d. If d has no entry for k, updates d to map k to the result of (v) (if v is a procedure) or v (otherwise), and returns the new mapping.

Examples:
  (define d (make-hash))

  > (dict-set! d 1 'one)
  > (dict-set! d 2 'two)
  > d
  '#hash((1 . one) (2 . two))
  > (dict-ref! d 2 'dos)
  'two
  > d
  '#hash((1 . one) (2 . two))
  > (dict-ref! d 3 'tres)
  'tres
  > d
  '#hash((1 . one) (2 . two) (3 . tres))
  > (dict-ref! d 4 gensym)
  'g51036
  > d
  '#hash((1 . one) (2 . two) (3 . tres) (4 . g51036))

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

(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

(dict-has-key? d k) → boolean?

d : dict?

k : any/c

Reports whether d has an entry for k.

Examples:
  > (dict-has-key? '([1 . one] [2 . two] [3 . three]) 2)
  #t
  > (dict-has-key? '([1 . one] [2 . two] [3 . three]) 4)
  #f

(dict-domain d) → list?

d : dict?

Produces the domain of a dictionary as a list of keys.

Example:
> (dict-domain '([1 . one] [2 . two] [3 . three]))
'(1 2 3)

(dict-range d) → list?

d : dict?

Produces the range of a dictionary as a list of values.

Example:
> (dict-range '([1 . one] [2 . two] [3 . three]))
'(one two three)

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

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

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

(make-dict

#:mutable? mutable?

#:weak? weak?

#:compare compare])

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

top← prev up next →

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	Imperative Queues
18	Regular Expressions
19	Requiring Modules
20	Sandboxed Evaluation
21	Scribble Documentation
22	Sets
23	S-Expression Diff
24	Source Locations
25	Strings
26	Structs
27	Syntax
28	Planet Package Macros
29	Text Representations
30	Multiple Values
31	XML and CSS
32	Polymorphic Contracts
33	Finding Mutated Variables
34	Find
35	Interface-Oriented Programming for Classes
36	Sequences
37	Hash Tables
38	Match
39	Skip Lists
40	Interval Maps
41	Generics
42	Mark Parameters
43	Debugging
44	GUI libraries

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