6.7.9.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 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 section 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.

This document was generated on February 3, 2012 using texi2html 5.0.