.RKT File Format – Structs

The struct form

(struct id maybe-super (field …) struct-option …)

• maybe-super is nothing or the name of another structure type; the new type then adds fields to the supertype's.
• each field is field-id or [field-id field-option …]; the field options are #:mutable and #:auto (the field is not a constructor argument and takes the value of #:auto-value, default #f).

With n fields it defines up to 4 + 2n names:

The options

#lang racket
(struct posn (x y) #:transparent)
(struct posn3 posn (z))                 ; a subtype with one more field
(define p (posn 1 2))
(posn-x p)                              ; 1
(posn? (posn3 1 2 3))                   ; #t: a subtype is a posn
(equal? (posn 1 2) (posn 1 2))          ; #t, because it is transparent

(struct counter ([n #:mutable]))
(define c (counter 0))
(set-counter-n! c (add1 (counter-n c)))

(struct celsius (degrees)
  #:guard (λ (d name)
            (unless (real? d) (error name "not a number: ~e" d))
            d))

(struct point (x y) #:prefab)
(point 1 2)                             ; prints as #s(point 1 2)
(struct-copy posn p [x 10])             ; a copy with x changed

Copying and reflection

• (struct-copy id struct-expr [field-id expr] …) makes a new instance with some fields changed; [field-id #:parent parent-id expr] reaches a field of a parent type.
• (struct->vector s) turns a transparent structure into a vector headed by struct:name. struct-info, struct-type-info, make-struct-type, make-struct-field-accessor and make-struct-field-mutator are the procedures behind struct: make-struct-type makes a type from a name, a supertype, field counts, an auto value, properties, an inspector and a guard.
• An opaque structure (no #:transparent) prints as #<name> and is equal? only to itself; struct->vector shows only '#(struct:name ...).
• define-struct is the older form: (define-struct name (field …) option …) names the constructor make-name. struct is preferred.

Prefab structures

A prefab type is defined by its name, number of fields, mutability and supertype alone, so two modules that use the same description share the type, and a value can be written to a file and read back. It is written #s(name field …). When the type has a supertype, automatic fields or mutable fields, the first datum is a list instead of a name, the prefab key; the shapes that make-prefab-struct accepts are not listed here. A prefab structure cannot have a guard or properties, and the read-syntax reader accepts only immutable ones. prefab-struct-key, make-prefab-struct and prefab-key->struct-type work on them.

Properties and generic interfaces

A structure type property adds behaviour. The built-in ones whose documentation I read include:

A generic interface (racket/generic) is a set of methods that a structure can implement with #:methods. (define-generics shape (area shape) (name shape)) defines the interface gen:shape and generic functions area and name; (struct circle (r) #:methods gen:shape [(define (area c) (* 3.14 (circle-r c) (circle-r c)))]) implements it. The library defines several: gen:equal+hash, gen:custom-write, gen:dict, gen:set, gen:stream, gen:ordered-dict.

Not described

Known, not yet covered

• Reference: inspectors (make-inspector, current-inspector, struct-info access rules), the full set of prefab key shapes, make-struct-type's arguments in detail, the structure-info protocol for macros (racket/struct-info), struct/derived, struct/contract (a struct with contracts on its fields) and #:name and #:extra-name's exact rules were not described. The list of properties is a sample, not the complete list in racket/base.
• Reference: gen:dict, gen:set, gen:ordered-dict and gen:custom-write are named from the library without having been read.

See also

• Pattern matching – taking a structure apart with match
• Classes and objects – the other way to define a type with behaviour
• Typed Racket – struct with typed fields
• Scheme: records – define-record-type, the Scheme equivalent