5.1 Defining Structure Types: struct (original) (raw)

5.1 Defining Structure Types: struct 🔗ℹ

Programmer-Defined Datatypes in The Racket Guide introduces struct.

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

maybe-super = | super-id field = field-id [field-id field-option ...] struct-option = #:mutable #:super super-expr #:inspector inspector-expr #:auto-value auto-expr #:guard guard-expr #:property prop-expr val-expr #:transparent #:prefab #:sealed #:authentic #:name name-id #:extra-name name-id #:constructor-name constructor-id #:extra-constructor-name constructor-id #:reflection-name symbol-expr #:methods gen:name-id method-defs #:omit-define-syntaxes #:omit-define-values field-option = #:mutable #:auto method-defs = (definition ...)

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

maybe-super = \| super-id field = field-id	[field-id field-option ...] struct-option = #:mutable	#:super super-expr	#:inspector inspector-expr	#:auto-value auto-expr	#:guard guard-expr	#:property prop-expr val-expr	#:transparent	#:prefab	#:sealed	#:authentic	#:name name-id	#:extra-name name-id	#:constructor-name constructor-id	#:extra-constructor-name constructor-id	#:reflection-name symbol-expr	#:methods gen:name-id method-defs	#:omit-define-syntaxes	#:omit-define-values field-option = #:mutable	#:auto method-defs = (definition ...)

Creates a new structure type (or uses a pre-existing structure type if #:prefab is specified), and binds transformers and variables related to the structure type.

A struct form with n fields defines up to 4+2n names:

struct:id, a structure type descriptor value that represents the structure type.
constructor-id (which defaults to id), aconstructor procedure that takes m arguments and returns a new instance of the structure type, wherem is the number of fields that do not include an #:auto option.
name-id (which defaults to id), a transformer binding that encapsulates information about the structure type declaration. This binding is used to define subtypes, and it also works with theshared and match forms. For detailed information about the binding of name-id, seeStructure Type Transformer Binding.
The constructor-id and name-id can be the same, in which case name-id performs both roles. In that case, the expansion of name-id as an expression produces an otherwise inaccessible identifier that is bound to the constructor procedure; the expanded identifier has a'constructor-for property whose value is an identifier that is free-identifier=? to name-id as well as a syntax property accessible viasyntax-procedure-alias-property with an identifier that is free-identifier=? to name-id.
id?, a predicate procedure that returns #t for instances of the structure type (constructed by constructor-id or theconstructor for a subtype) and #f for any other value.
id-field-id, for eachfield; an accessor procedure that takes an instance of the structure type and extracts the value for the corresponding field.
set-id-field-id!, for each field that includes a#:mutable option, or when the#:mutable option is specified as astruct-option; a mutator procedure that takes an instance of the structure type and a new field value. The structure is destructively updated with the new value, and # is returned.

If super-id is provided, it must have a transformer binding of the same sort bound to name-id (see Structure Type Transformer Binding), and it specifies a supertype for the structure type. Alternately, the #:super option can be used to specify an expression that must produce a structure type descriptor. SeeStructures for more information on structure subtypes and supertypes. If both super-id and #:super are provided, a syntax error is reported.

Examples:

> (struct document (author title content))

> (struct book document (publisher))

> (struct paper (journal) #:super struct:document)

> (struct document (author title content))
> (struct book document (publisher))
> (struct paper (journal) #:super struct:document)

If the #:mutable option is specified for an individual field, then the field can be mutated in instances of the structure type, and a mutator procedure is bound. Supplying#:mutable as a struct-option is the same as supplying it for all fields. If #:mutable is specified as both a field-option and struct-option, a syntax error is reported.

Examples:

> (struct cell ([content #:mutable]) #:transparent)

> (define a-cell (cell 0))

> (set-cell-content! a-cell 1)

> (struct cell ([content #:mutable]) #:transparent)
> (define a-cell (cell 0))
> (set-cell-content! a-cell 1)

The #:inspector, #:auto-value, and #:guardoptions specify an inspector, value for automatic fields, and guard procedure, respectively. See make-struct-type for more information on these attributes of a structure type. The#:property option, which can be supplied multiple times, attaches a property value to the structure type; seeStructure Type Properties for more information on properties. The#:transparent option is a shorthand for #:inspector #f.

Examples:

> (struct point (x y) #:inspector #f)

> (point 3 5)

(point 3 5)

> (struct celsius (temp) #:guard (λ (temp name) (unless (and (real? temp) (>= temp -273.15)) (error "not a valid temperature")) temp))

> (celsius -275)

not a valid temperature

> (struct point (x y) #:inspector #f)
> (point 3 5)
(point 3 5)
> (struct celsius (temp) #:guard (λ (temp name) (unless (and (real? temp) (>= temp -273.15)) (error "not a valid temperature")) temp))
> (celsius -275)
not a valid temperature

Use the prop:procedure property to implement anapplicable structure, use prop:evt to create a structure type whose instances are synchronizable events, and so on. By convention, property names start with prop:.

The #:prefab option obtains a prefab (pre-defined, globally shared) structure type, as opposed to creating a new structure type. Such a structure type is inherently transparent and non-sealed, and it cannot have a guard or properties, so using #:prefab with#:transparent, #:inspector, #:guard,#:property, #:sealed, #:authentic, or #:methods is a syntax error. If a supertype is specified, it must also be a prefab structure type.

Examples:

> (struct prefab-point (x y) #:prefab)

> (prefab-point 1 2)

'#s(prefab-point 1 2)

> (prefab-point? #s(prefab-point 1 2))

#t

> (struct prefab-point (x y) #:prefab)
> (prefab-point 1 2)
'#s(prefab-point 1 2)
> (prefab-point? #s(prefab-point 1 2))
#t

The #:sealed option is a shorthand for #:property prop:sealed #t, which prevents the structure type from being used as the supertype of another structure type. Seeprop:sealed for more information.

The #:authentic option is a shorthand for #:property prop:authentic #t, which prevents instances of the structure type from being impersonated (see impersonate-struct), chaperoned (see chaperone-struct), or acquiring a non-flat contract (see struct/c). See prop:authentic for more information. If a supertype is specified, it must also have theprop:authentic property.

If name-id is supplied via #:extra-name and it is not id, then both name-id and id are bound to information about the structure type. Only one of#:extra-name and #:name can be provided within astruct form, and #:extra-name cannot be combined with #:omit-define-syntaxes.

Examples:

> (struct ghost (color name) #:prefab #:extra-name GHOST)

> (match (ghost 'red 'blinky) [(GHOST c n) c])

'red

> (struct ghost (color name) #:prefab #:extra-name GHOST)
> (match (ghost 'red 'blinky) [(GHOST c n) c])
'red

If constructor-id is supplied, then the transformerbinding of name-id records constructor-id as the constructor binding; as a result, for example, struct-outincludes constructor-id as an export. Ifconstructor-id is supplied via#:extra-constructor-name and it is not id, applyingobject-name on the constructor produces the symbolic form ofid rather than constructor-id. Ifconstructor-id is supplied via #:constructor-nameand it is not the same as name-id, then name-id does not serve as a constructor, and object-name on the constructor produces the symbolic form of constructor-id. Only one of#:extra-constructor-name and #:constructor-namecan be provided within a struct form.

Examples:

> (struct color (r g b) #:constructor-name -color)

> (struct rectangle (w h color) #:extra-constructor-name rect)

> (rectangle 13 50 (-color 192 157 235))

#

> (rect 50 37 (-color 35 183 252))

#

> (struct color (r g b) #:constructor-name -color)
> (struct rectangle (w h color) #:extra-constructor-name rect)
> (rectangle 13 50 (-color 192 157 235))
#
> (rect 50 37 (-color 35 183 252))
#

If #:reflection-name symbol-expr is provided, thensymbol-expr must produce a symbol that is used to identify the structure type in reflective operations such asstruct-type-info. It corresponds to the first argument ofmake-struct-type. Structure printing uses the reflective name, as do the various procedures that are bound by struct.

Examples:

> (struct circle (radius) #:reflection-name ')

> (circle 15)

#<>

> (circle-radius "bad")

-radius: contract violation

expected: ?

given: "bad"

> (struct circle (radius) #:reflection-name ')
> (circle 15)
#<>
> (circle-radius "bad")
-radius: contract violation
expected: ?
given: "bad"

If #:methods gen:name-id method-defs is provided (potentially multiple times), thengen:name-id must be a transformer binding for the static information about a generic interface produced by define-generics. The method-defs define the methods of the gen:name-idinterface. A define/generic form or auxiliary definitions and expressions may also appear in method-defs.

Examples:

> (stream-ref (constant-stream 'forever) 0)

'forever

> (stream-ref (constant-stream 'forever) 50)

'forever

> (stream-ref (constant-stream 'forever) 0)
'forever
> (stream-ref (constant-stream 'forever) 50)
'forever

If the #:omit-define-syntaxes option is supplied, thenname-id (and id, if #:extra-name is specified) is not bound as a transformer. If the#:omit-define-values option is supplied, then none of the usual variables are bound, but id is bound. If both are supplied, then the struct form is equivalent to(begin).

Examples:

> (struct square (side) #:omit-define-syntaxes)

> (match (square 5) ; fails to match because syntax is omitted [(struct square x) x])

eval:28:0: match: square does not refer to a structure

definition

at: square

in: (struct square x)

> (struct ellipse (width height) #:omit-define-values)

> ellipse-width

ellipse-width: undefined;

cannot reference an identifier before its definition

in module: top-level

> (struct square (side) #:omit-define-syntaxes)
> (match (square 5) ; fails to match because syntax is omitted [(struct square x) x])
eval:28:0: match: square does not refer to a structure
definition
at: square
in: (struct square x)
> (struct ellipse (width height) #:omit-define-values)
> ellipse-width
ellipse-width: undefined;
cannot reference an identifier before its definition
in module: top-level

Expressions supplied to #:auto-value are evaluated once and shared between every instance of the structure type. In particular, updates to a mutable #:auto-value affect all current and future instances.

If #:auto is supplied as a field-option, then theconstructor procedure for the structure type does not accept an argument corresponding to the field. Instead, the structure type’s automatic value is used for the field, as specified by the#:auto-value option, or as defaults to #f when#:auto-value is not supplied. The field is mutable (e.g., through reflective operations), but a mutator procedure is bound only if #:mutable is specified.

If a field includes the #:auto option, then all fields after it must also include #:auto, otherwise a syntax error is reported. If any field-option orstruct-option keyword is repeated, other than#:property, a syntax error is reported.

Examples:

(struct posn (x y [z #:auto #:mutable]) #:auto-value 0 #:transparent)

> (posn 1 2)

(posn 1 2 0)

> (posn? (posn 1 2))

#t

> (posn-y (posn 1 2))

2

> (posn-z (posn 1 2))

0

(struct color-posn posn (hue) #:mutable)(define cp (color-posn 1 2 "blue"))

> (color-posn-hue cp)

"blue"

> cp

(color-posn 1 2 0 ...)

> (set-posn-z! cp 3)

(struct posn (x y [z #:auto #:mutable]) #:auto-value 0 #:transparent)
> (posn 1 2)
(posn 1 2 0)
> (posn? (posn 1 2))
#t
> (posn-y (posn 1 2))
2
> (posn-z (posn 1 2))
0
(struct color-posn posn (hue) #:mutable)(define cp (color-posn 1 2 "blue"))
> (color-posn-hue cp)
"blue"
> cp
(color-posn 1 2 0 ...)
> (set-posn-z! cp 3)

For serialization, see define-serializable-struct.

Changed in version 6.9.0.4 of package base: Added #:authentic.
Changed in version 8.0.0.7: Added #:sealed.

(struct-field-index field-id)

This form can only appear as an expression within astruct form; normally, it is used with#:property, especially for a property likeprop:procedure. The result of a struct-field-indexexpression is an exact, non-negative integer that corresponds to the position within the structure declaration of the field named byfield-id.

Examples:

> (happy+ 2)

3

> (mood-procedure-rating happy+)

10

> (happy+ 2)
3
> (mood-procedure-rating happy+)
10

(define-struct id-maybe-super (field ...) struct-option ...)

id-maybe-super = id | (id super-id)

(define-struct id-maybe-super (field ...) struct-option ...)

id-maybe-super = id \| (id super-id)

Like struct, except that the syntax for supplying asuper-id is different, and a constructor-id that has a make- prefix on id is implicitly supplied via #:extra-constructor-name if neither#:extra-constructor-name nor #:constructor-name is provided.

This form is provided for backwards compatibility; struct is preferred.

Examples:

(define-struct posn (x y [z #:auto]) #:auto-value 0 #:transparent)

> (make-posn 1 2)

(posn 1 2 0)

> (posn? (make-posn 1 2))

#t

> (posn-y (make-posn 1 2))

2

(define-struct posn (x y [z #:auto]) #:auto-value 0 #:transparent)
> (make-posn 1 2)
(posn 1 2 0)
> (posn? (make-posn 1 2))
#t
> (posn-y (make-posn 1 2))
2

(struct/derived (id . rest-form)id (field ...) struct-option ...)

(struct/derived (id . rest-form)id super-id (field ...) struct-option ...)

(struct/derived (id . rest-form)id (field ...) struct-option ...)
(struct/derived (id . rest-form)id super-id (field ...) struct-option ...)

The same as struct, but with an extra (id . rest-form) sub-form that is treated as the overall form for syntax-error reporting and otherwise ignored. The only constraint on the sub-form for error reporting is that it starts with id. The struct/derived form is intended for use by macros that expand to struct.

Examples:

> (fruit-struct apple)

> (apple-seeds (apple 12 "red"))

12

> (fruit-struct apple #:mutable)

> (set-apple-seeds! (apple 12 "red") 8)

; this next line will cause an error due to a bad keyword

> (fruit-struct apple #:bad-option)

eval:54:0: fruit-struct: unrecognized struct-specification

keyword

at: #:bad-option

in: (fruit-struct apple #:bad-option)

> (fruit-struct apple)
> (apple-seeds (apple 12 "red"))
12
> (fruit-struct apple #:mutable)
> (set-apple-seeds! (apple 12 "red") 8)
; this next line will cause an error due to a bad keyword
> (fruit-struct apple #:bad-option)
eval:54:0: fruit-struct: unrecognized struct-specification
keyword
at: #:bad-option
in: (fruit-struct apple #:bad-option)

Added in version 7.5.0.16 of package base.

(define-struct/derived (id . rest-form)

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

(define-struct/derived (id . rest-form)
id-maybe-super (field ...) struct-option ...)

Like struct/derived, except that the syntax for supplying asuper-id is different, and a constructor-id that has a make- prefix on id is implicitly supplied via #:extra-constructor-name if neither#:extra-constructor-name nor #:constructor-name is provided. The define-struct/derived form is intended for use by macros that expand to define-struct.

Examples:

> (define-xy-struct posn)

> (posn-x (make-posn 1 2))

1

> (define-xy-struct posn #:mutable)

> (set-posn-x! (make-posn 1 2) 0)

; this next line will cause an error due to a bad keyword

> (define-xy-struct posn #:bad-option)

eval:60:0: define-xy-struct: unrecognized

struct-specification keyword

at: #:bad-option

in: (define-xy-struct posn #:bad-option)

> (define-xy-struct posn)
> (posn-x (make-posn 1 2))
1
> (define-xy-struct posn #:mutable)
> (set-posn-x! (make-posn 1 2) 0)
; this next line will cause an error due to a bad keyword
> (define-xy-struct posn #:bad-option)
eval:60:0: define-xy-struct: unrecognized
struct-specification keyword
at: #:bad-option
in: (define-xy-struct posn #:bad-option)

Changed in version 7.5.0.16 of package base: Moved main description to struct/derivedand replaced with differences.

5.1 Defining Structure Types: struct (original) (raw)

5.1 Defining Structure Types: struct🔗ℹ

5.1 Defining Structure Types: struct 🔗ℹ