Next: , Previous: Vtables, Up: Structures Structure Basics

This section describes the basic procedures for working with structures. make-struct creates a structure, and struct-ref and struct-set! access write fields.

— Scheme Procedure: make-struct vtable tail-size [init...]
— C Function: scm_make_struct (vtable, tail_size, init_list)

Create a new structure, with layout per the given vtable (see Vtables).

tail-size is the size of the tail array if vtable specifies a tail array. tail-size should be 0 when vtable doesn't specify a tail array.

The optional init... arguments are initial values for the fields of the structure (and the tail array). This is the only way to put values in read-only fields. If there are fewer init arguments than fields then the defaults are #f for a Scheme field (type p) or 0 for an uninterpreted field (type u).

Type s self-reference fields, permission o opaque fields, and the count field of a tail array are all ignored for the init arguments, ie. an argument is not consumed by such a field. An s is always set to the structure itself, an o is always set to #f or 0 (with the intention that C code will do something to it later), and the tail count is always the given tail-size.

For example,

          (define v (make-vtable "prpwpw"))
          (define s (make-struct v 0 123 "abc" 456))
          (struct-ref s 0) ⇒ 123
          (struct-ref s 1) ⇒ "abc"
          (define v (make-vtable "prpW"))
          (define s (make-struct v 6 "fixed field" 'x 'y))
          (struct-ref s 0) ⇒ "fixed field"
          (struct-ref s 1) ⇒ 2    ;; tail size
          (struct-ref s 2) ⇒ x    ;; tail array ...
          (struct-ref s 3) ⇒ y
          (struct-ref s 4) ⇒ #f
— Scheme Procedure: struct? obj
— C Function: scm_struct_p (obj)

Return #t if obj is a structure, or #f if not.

— Scheme Procedure: struct-ref struct n
— C Function: scm_struct_ref (struct, n)

Return the contents of field number n in struct. The first field is number 0.

An error is thrown if n is out of range, or if the field cannot be read because it's o opaque.

— Scheme Procedure: struct-set! struct n value
— C Function: scm_struct_set_x (struct, n, value)

Set field number n in struct to value. The first field is number 0.

An error is thrown if n is out of range, or if the field cannot be written because it's r read-only or o opaque.

— Scheme Procedure: struct-vtable struct
— C Function: scm_struct_vtable (struct)

Return the vtable used by struct.

This can be used to examine the layout of an unknown structure, see Vtable Contents.