4.16 Records

8.12

4.16 Records🔗ℹ

A record is a collection of name-value mappings, each which is called a record field. The name of a field is a keyword. Records support constant-time lookup of field values by name.

Records are similar to hash tables, except keys must be keywords. Records are less dynamic than general-purpose hash tables, but their specialized nature can offer improved performance. In particular, constructing a record with record does not require sorting keywords at runtime, and calling a keyword-accepting function with a record imposes only constant-time overhead. Use records instead of hash tables when keys are expected to be literal names written in source code. As a rule of thumb, if you find yourself reaching for a hash table whose keys are symbols or strings, use records instead.

procedure
(record? v) → boolean?
v : any/c

A predicate for records.

procedure
(record #:<kw> v ...) → record?
v : any/c

Constructs a record containing each v, where #:<kw> stands for any keyword.

Example:

> (record #:name "Alyssa P. Hacker"
#:age 42
#:favorite-color 'turqoise)
(record #:age 42 #:favorite-color 'turqoise #:name "Alyssa P. Hacker")

procedure
(record-keywords rec) → keyset?
rec : record?

Returns a keyset of the keywords contained in rec.

Examples:

> (define rec
    (record #:name "Alyssa P. Hacker"
            #:age 42
            #:favorite-color 'turqoise))
> (record-keywords rec)
(keyset #:age #:favorite-color #:name)

procedure
(record-values rec) → immutable-vector?
rec : record?

Returns the values contained in rec, in the same order as the value’s corresponding keyword in (record-keywords rec).

Examples:

> (define rec
    (record #:name "Alyssa P. Hacker"
            #:age 42
            #:favorite-color 'turqoise))
> (record-values rec)
'#(42 turqoise "Alyssa P. Hacker")

value
empty-record : record?

The empty record, which contains no entries.

procedure
(record-size rec) → natural?
rec : record?

Returns the number of keyword-value entries in rec.

Examples:

> (define rec
    (record #:name "Alyssa P. Hacker"
            #:age 42
            #:favorite-color 'turqoise))
> (record-size rec)
3

procedure
(record-ref rec kw) → any/c
rec : record?
kw : keyword?

Returns the value in rec for kw, or #f if none exists.

Examples:

> (define rec
    (record #:name "Alyssa P. Hacker"
            #:age 42
            #:favorite-color 'turqoise))
> (record-ref rec '#:name)
"Alyssa P. Hacker"
> (record-ref rec '#:fur-color)
#f

)

procedure
(record-remove rec kw) → record?
rec : record?
kw : keyword?

Returns rec with the entry for kw removed.

Example:

> (record-remove (record #:x 42 #:y 7) '#:x)
(record #:y 7)

procedure
(build-record builder keys) → record?
builder : (-> keyword? any/c)
keys : keyset?

Constructs a record by calling builder with each keyword in keys in an unspecified order.

Example:

> (build-record keyword->string (keyset #:x #:y #:z))
(record #:x "x" #:y "y" #:z "z")

procedure
(record-merge2 rec1 rec2 [#:merge merge]) → record?
  rec1 : record?
  rec2 : record?
  merge : (-> any/c any/c any/c) = (λ (a b) b)

Combines rec1 and rec2 into a single record containing the entries of both. If a keyword is contained in both records the values for that key are combined with merge. The default merge function ignores the first value, causing entries in rec2 to overwrite entries in rec1.

Examples:

> (record-merge2 (record #:x 1 #:y 2)
                 (record #:name "Alyssa P. Hacker" #:age 42))
(record #:age 42 #:name "Alyssa P. Hacker" #:x 1 #:y 2)
> (record-merge2 (record #:x 1 #:y 2 #:z 3)
                 (record #:z 100))
(record #:x 1 #:y 2 #:z 100)
> (record-merge2 (record #:x 1 #:y 2 #:z 3)
                 (record #:x -1 #:y -2 #:z -3)
                 #:merge +)
(record #:x 0 #:y 0 #:z 0)

procedure
(record-map rec f) → record?
rec : record?
f : (-> any/c any/c)

Applies f to each value in rec and returns a new record containing the results with the same keys as rec.

Example:

> (record-map (record #:x 1 #:y 2 #:z 3)
(λ (x) (* x 100)))
(record #:x 100 #:y 200 #:z 300)

procedure
(record-contains-key? rec kw) → boolean?
rec : record?
kw : keyword?

Returns #t if rec contains a mapping for kw, returns #f otherwise.

Examples:

> (record-contains-key? (record #:x 0 #:y 0) '#:x)
#t
> (record-contains-key? (record #:x 0 #:y 0) '#:theta)
#f

4.16.1 Record Fields🔗ℹ

procedure
(record-field? v) → boolean?
v : any/c

A predicate for record fields.

procedure
(record-field #:<kw> v) → record-field?
v : any/c

Constructs a record field mapping whatever keyword is given for #:<kw> to v.

Examples:

> (record-field #:title "Fabulous Widget 2.0")
(record-field #:title "Fabulous Widget 2.0")
> (record-field #:color 'firetruck-red)
(record-field #:color 'firetruck-red)

procedure
(record-field-name field) → keyword?
field : record-field?
procedure
(record-field-value field) → any/c
field : record-field?

Accessors for the name and value of a record field.

Examples:

> (define field (record-field #:title "Fabulous Widget 2.0"))
> (record-field-name field)
'#:title
> (record-field-value field)
"Fabulous Widget 2.0"

1	Base Libraries
2	Data Types
3	Streaming Computations
4	Collections
5	Concurrency
6	Binary Data
7	Module Utilities
8	Other Libraries

4.1	Choosing Collections
4.2	Entries
4.3	Lists
4.4	Vectors
4.5	Vector Builders
4.6	Immutable Vectors
4.7	Sets
4.8	Hash Tables
4.9	Multisets
4.10	Multidicts
4.11	Association Lists
4.12	Sorted Sets
4.13	Sorted Maps
4.14	Range Sets
4.15	Keysets
4.16	Records
4.17	Tables