1 Welcome to PLT Scheme
2 Scheme Essentials
3 Built-In Datatypes
4 Expressions and Definitions
5 Programmer-Defined Datatypes
6 Modules
7 Contracts
8 Input and Output
9 Regular Expressions
10 Exceptions and Control
11 Iterations and Comprehensions
12 Pattern Matching
13 Classes and Objects
14 Units (Components)
15 Reflection and Dynamic Evaluation
16 Macros
17 Performance
18 Running and Creating Executables
19 Compilation and Configuration
20 More Libraries
Bibliography
Index
On this page:
5.1 Simple Structure Types: define-struct
5.2 Copying and Update
5.3 Structure Subtypes
5.4 Opaque versus Transparent Stucture Types
5.5 Structure Type Generativity
5.6 Prefab Stucture Types
5.7 More Structure Type Options
Version: 4.0.2

 

5 Programmer-Defined Datatypes

Structures in Reference: PLT Scheme also documents structure types.

New datatypes are normally created with the define-struct form, which is the topic of this chapter. The class-based object system, which we defer to Classes and Objects, offers an alternate mechanism for creating new datatypes, but even classes and objects are implemented in terms of structure types.

5.1 Simple Structure Types: define-struct

Defining Structure Types: define-struct in Reference: PLT Scheme also documents define-struct.

To a first approximation, the syntax of define-struct is

(define-struct struct-id (field-id ...))

A define-struct declaration binds struct-id, but only to static information about the structure type that cannot be used directly:

  (define-struct posn (x y))

  > posn

  eval:2:0: posn: identifier for static struct-type

  information cannot be used as an expression in: posn

We show two uses of the struct-id binding below in Copying and Update and Structure Subtypes.

Meanwhile, in addition to defining struct-id, define-struct also defines a number of identifiers that are built from struct-id and the field-ids:

A define-struct form places no constraints on the kinds of values that can appear for fields in an instance of the structure type. For example, (make-posn "apple" #f) produces an instance of posn, even though "apple" and #f are not valid coordinates for the obvious uses of posn instances. Enforcing constraints on field values, such as requiring them to be numbers, is normally the job of a contract, as discussed later in Contracts.

5.2 Copying and Update

The struct-copy form clones a structure and optionally updates specified fields in the clone. This process is sometimes called a functional update, because the result is a structure with updated field values. but the original structure is not modified.

(struct-copy struct-id struct-expr [field-id expr] ...)

The struct-id that appears after struct-copy must be a structure type name bound by define-struct (i.e., the name that cannot be used directly as an expression). The struct-expr must produce an instance of the structure type. The result is a new instance of the structure tpe that is like the old one, except that the field indicated by each field-id gets the value of the corresponding expr.

Examples:

  > (define p1 (make-posn 1 2))

  > (define p2 (struct-copy posn p1 [x 3]))

  > (list (posn-x p2) (posn-y p2))

  (3 2)

  > (list (posn-x p1) (posn-x p2))

  (1 3)

5.3 Structure Subtypes

An extended form of define-struct can be used to define a structure subtype, which is a structure type that extends an existing structure type:

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

The super-id must be a structure type name bound by define-struct (i.e., the name that cannot be used directly as an expression).

Examples:

  (define-struct posn (x y))

  (define-struct (3d-posn posn) (z))

A structure subtype inherits the fields of its supertype, and the subtype constructor accepts the values for the subtype fields after values for the supertype fields. An instance of a structure subtype can be used with the predicate and accessors of the supertype.

Examples:

  > (define p (make-3d-posn 1 2 3))

  > p

  #<3d-posn>

  > (posn? p)

  #t

  > (posn-x p)

  1

  > (3d-posn-z p)

  3

5.4 Opaque versus Transparent Stucture Types

With a structure type definition like

  (define-struct posn (x y))

an instance of the structure type prints in a way that does not show any information about the fields values. That is, structure types by default are opaque. If the accessors and mutators of a structure type are kept private to a module, then no other module can rely on the representation of the type’s instances.

To make a structure type transparent, use the #:transparent keyword after the field-name sequence:

  (define-struct posn (x y)

                 #:transparent)

  > (make-posn 1 2)

  #(struct:posn 1 2)

An instance of a transparent structure type prints like a vector, and it shows the content of the structure’s fields. A transparent structure type also allows reflective operations, such as struct? and struct-info, to be used on its instances (see Reflection and Dynamic Evaluation).

Structure types are opaque by default, because opaque structure instances provide more encapsulation guarantees. That is, a library can use an opaque structure to encapsulate data, and clients of the library cannot manipulate the data in the structure except as allowed by the library.

5.5 Structure Type Generativity

Each time that a define-struct form is evaluated, it generates a structure type that is distinct from all existing structure types, even if some other structure type has the same name and fields.

This generativity is useful for enforcing abstractions and implementing programs such as interpreters, but beware of placing a define-struct form in positions that are evaluated multiple times.

Examples:

  (define (add-bigger-fish lst)

    (define-struct fish (size) #:transparent) ; new every time

    (cond

     [(null? lst) (list (make-fish 1))]

     [else (cons (make-fish (* 2 (fish-size (car lst))))

                 lst)]))

  > (add-bigger-fish null)

  (#(struct:fish 1))

  > (add-bigger-fish (add-bigger-fish null))

  fish-size: expects args of type <struct:fish>; given

  instance of a different <struct:fish>

  (define-struct fish (size) #:transparent)

  (define (add-bigger-fish lst)

    (cond

     [(null? lst) (list (make-fish 1))]

     [else (cons (make-fish (* 2 (fish-size (car lst))))

                 lst)]))

  > (add-bigger-fish (add-bigger-fish null))

  (#(struct:fish 2) #(struct:fish 1))

5.6 Prefab Stucture Types

Although a transparent structure type prints in a way that shows its content, the printed form of the structure cannot be used in an expression to get the structure back, unlike the printed form of a number, string, symbol, or list.

A prefab (“previously fabricated”) structure type is a built-in type that is known to the Scheme printer and expression reader. Infinitely many such types exist, and they are indexed by name, field count, supertype, and other such details. The printed form of a prefab structure is similar to a vector, but it starts #s instead of just #, and the first element in the printed form is the prefab structure type’s name.

The following examples show instances of the sprout prefab structure type that has one field. The first instance has a field value 'bean, and the second has field value 'alfalfa:

  > '#s(sprout bean)

  #s(sprout bean)

  > '#s(sprout alfalfa)

  #s(sprout alfalfa)

Like numbers and strings, prefab structures are “self-quoting,” so the quotes above are optional:

  > #s(sprout bean)

  #s(sprout bean)

When you use the #:prefab keyword with define-struct, instead of generating a new structure type, you obtain bindings that work with the existing prefab structure type:

  > (define lunch '#s(sprout bean))

  > (define-struct sprout (kind) #:prefab)

  > (sprout? lunch)

  #t

  > (sprout-kind lunch)

  bean

  > (make-sprout 'garlic)

  #s(sprout garlic)

The field name kind above does not matter for finding the prefab structure type; only the name sprout and the number of fields matters. At the same time, the prefab structure type sprout with three fields is a different structure type than the one with a single field:

  > (sprout? #s(sprout bean #f 17))

  #f

  > (define-struct sprout (kind yummy? count) #:prefab) ; redefine

  > (sprout? #s(sprout bean #f 17))

  #t

  > (sprout? lunch)

  #f

A prefab structure type can have another prefab structure type as its supertype, it can have mutable fields, and it can have auto fields. Variations in any of these dimensions correspond to different prefab structure types, and the printed form of the structure type’s name encodes all of the relevant details.

  > (define-struct building (rooms [location #:mutable]) #:prefab)

  > (define-struct (house building) ([occupied #:auto]) #:prefab

      #:auto-value 'no)

  > (make-house 5 'factory)

  #s((house (1 no) building 2 #(1)) 5 factory no)

Every prefab structure type is transparent – but even less abstract than a transparent type, because instances can be created without any access to a particular structure-type declaration or existing examples. Overall, the different options for structure types offer a spectrum of possibilities from more abstract to more convenient:

Since the expression reader can generate prefab instances, they are useful when convenient serialization is more important than abstraction. Opaque and transparent structures also can be serialized, however, if they are defined with define-serializable-struct as described in Datatypes and Serialization.

5.7 More Structure Type Options

The full syntax of define-struct supports many options, both at the structure-type level and at the level of individual fields:

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

               struct-option ...)

 

id-maybe-super

 

=

 

struct-id

 

 

|

 

(struct-id super-id)

 

 

 

 

 

field

 

=

 

field-id

 

 

|

 

[field-id field-option ...]

A struct-option always starts with a keyword:

#:mutable

Causes all fields of the structure to be mutable, and introduces for each field-id a mutator set-struct-id-field-id! that sets the value of the corresponding field in an instance of the structure type.

Examples:

  (define-struct dot (x y) #:mutable)

(define d (make-dot 1 2)) (dot-x d) (set-dot-x! d 10) (dot-x d)]

The #:mutable option can also be used as a field-option, in which case it makes an individual field mutable.

Examples:

  (define-struct person (name [age #:mutable]))

  (define friend (make-person "Barney" 5))

  > (set-person-age! friend 6)

  > (set-person-name! friend "Mary")

  reference to undefined identifier: set-person-name!

#:transparent

Controls reflective access to structure instances, as discussed in a previous section, Opaque versus Transparent Stucture Types.

#:inspector inspector-expr

Generalizes #:transparent to support more controlled access to reflective operations.

#:prefab

Accesses a built-in structure type, as discussed in a previous section, Prefab Stucture Types.

#:auto-value auto-expr

Specifies a value to be used for all automatic fields in the structure type, where an automatic field is indicated by the #:auto field option. The constructor procedure does not accept arguments for automatic fields, and they are implicitly mutable.

Examples:

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

                 #:transparent

                 #:auto-value 0)

  > (make-posn 1 2)

  #(struct:posn 1 2 0)

#:guard guard-expr

Specifies a constructor guard procedure to be called whenever an instance of the structure type is created. The guard takes as many arguments as non-automatic fields in the structure type, and it should return the same number of values. The guard can raise an exception if one of the given arguments is unacceptable, or it can convert an argument.

Examples:

  (define-struct thing (name)

                 #:transparent

                 #:guard (lambda (name type-name)

                           (cond

                             [(string? name) name]

                             [(number? name)

                              (number->string name)]

                             [else (error "bad name" name)])))

  > (make-thing "apple")

  #(struct:thing "apple")

  > (make-thing 1/2)

  #(struct:thing "1/2")

  > (make-thing #f)

  bad name #f

The guard is called even when subtype instances are created. In that case, only the fields accepted by the constructor are provided to the guard (but the subtype’s guard gets both the original fields and fields added by the subtype).

Examples:

  (define-struct (person thing) (age)

                 #:transparent

                 #:guard (lambda (name age type-name)

                           (if (negative? age)

                               (error "bad age" age)

                               (values name age))))

  > (make-person "John" 10)

  #(struct:person "John" 10)

  > (make-person "Mary" -1)

  bad age -1

  > (make-person #f 10)

  bad name #f

#:property prop-expr val-expr

Associates a property and value with the structure type. For example, the prop:procedure property allows a structure instance to be used as a function; the property value determines how a call is implemented when using the structure as a function.

Examples:

  (define-struct greeter (name)

                 #:property prop:procedure

                            (lambda (self other)

                              (string-append

                               "Hi " other

                               ", I'm " (greeter-name self))))

  (define joe-greet (make-greeter "Joe"))

  > (greeter-name joe-greet)

  "Joe"

  > (joe-greet "Mary")

  "Hi Mary, I'm Joe"

  > (joe-greet "John")

  "Hi John, I'm Joe"

#:super super-expr

An alternative to supplying a super-id next to struct-id. Instead of the name of a structure type (which is not an expression), super-expr should produce a structure type descriptor value. An advantage of #:super is that structure type descriptors are values, so they can be passed to procedures.

Examples:

  (define (make-raven-constructor super-type)

    (define-struct raven ()

                   #:super super-type

                   #:transparent

                   #:property prop:procedure (lambda (self)

                                               'nevermore))

    make-raven)

  > (let ([r ((make-raven-constructor struct:posn) 1 2)])

      (list r (r)))

  (#(struct:raven 1 2) nevermore)

  > (let ([r ((make-raven-constructor struct:thing) "apple")])

      (list r (r)))

  (#(struct:raven "apple") nevermore)

Structures in Reference: PLT Scheme provides more on structure types.