6.7.10.2 Structure Basics

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

Scheme Procedure: make-struct vtable tail-size init …

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

Create a new structure, with layout per the given vtable (see section 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 uninterpreted field (type u).

Structures also have the ability to allocate a variable number of additional cells at the end, at their tails. However, this legacy tail array facilty is confusing and inefficient, and so we do not recommend it. See section Tail Arrays, for more on the legacy tail array interface.

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"

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.

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 that describes struct.

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

This document was generated on April 20, 2013 using texi2html 5.0.