6.6.18.2 Structure Basics

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

Scheme Procedure: make-struct/no-tail vtable init …

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

The optional init… arguments are initial values for the fields of the structure. 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 unboxed field (type u).

The name is a bit strange, we admit. The reason for it is that Guile used to have a make-struct that took an additional argument; while we deprecate that old interface, make-struct/no-tail is the new name for this functionality.

For example,

(define v (make-vtable "pwpwpw"))
(define s (make-struct/no-tail v 123 "abc" 456))
(struct-ref s 0) ⇒ 123
(struct-ref s 1) ⇒ "abc"

C Function: SCM scm_make_struct (SCM vtable, SCM tail_size, SCM init_list)

C Function: SCM scm_c_make_struct (SCM vtable, SCM tail_size, SCM init, ...)

C Function: SCM scm_c_make_structv (SCM vtable, SCM tail_size, size_t n_inits, scm_t_bits init[])

There are a few ways to make structures from C. scm_make_struct takes a list, scm_c_make_struct takes variable arguments terminated with SCM_UNDEFINED, and scm_c_make_structv takes a packed array.

For all of these, tail_size should be zero (as a SCM value).

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.

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.

Unboxed fields (those with type u) need to be accessed with special procedures.

Scheme Procedure: struct-ref/unboxed struct n

Scheme Procedure: struct-set!/unboxed struct n value

C Function: scm_struct_ref_unboxed (struct, n)

C Function: scm_struct_set_x_unboxed (struct, n, value)

Like struct-ref and struct-set!, except that these may only be used on unboxed fields. struct-ref/unboxed will always return a positive integer. Likewise, struct-set!/unboxed takes an unsigned integer as the value argument, and will signal an error otherwise.

Scheme Procedure: struct-vtable struct

C Function: scm_struct_vtable (struct)

Return the vtable that describes struct.

The vtable is effectively the type of the structure. See Vtable Contents, for more on vtables.