6.17 Boxes

A box is a mutable container that can hold (possibly multiple) values. It can be used as a minimal data storage, or a sort of mutable indirect “pointer”.

Traditionally, a list or a vector has been used for this purpose. However, such datatypes imply sequences of objects, Using boxes emphasizes your intention is just for indirection, and not so much for sequencing.

It is originally introduced by SRFI-111, which was later adopted in R7RS-large as scheme.box. SRFI-195 enhances it to deal with multiple values.

The srfis leave some details to implementations. Here are our choices:

• We don’t support autoboxing; that is, it is an error to pass non-box value to the procedure expecting boxed value and vice versa.
• Comparing two boxes with equal? compares their contents when two are not eqv?. In the spec, when two boxes are eqv? then they must also be equal? to each other, but it’s up to the implementation when two are not eqv?.

When you’re writing portable code, be careful not to depend on the equal? behavior.

Function: box val … ¶

[R7RS box][SRFI-195] Returns a fresh box object that contains the value val ….

Function: box? obj ¶

[R7RS box] Returns #t iff obj is a box object.

Function: box-arity box ¶

[SRFI-195] Returns the number of values box holds.

Function: unbox box ¶

[R7RS box] Returns box’s content. If box has N values, it returns N values.

NB: If box is a single-valued box, unbox can be used with generalized setters. This is Gauche’s extension.

(define b (box 1))
(set! (unbox b) 2)
b ⇒ #<box 2>

(define b (box '()))
(push! (unbox b) 'x)
(push! (unbox b) 'y)
b ⇒ #<box (y x)>

Function: unbox-value box i ¶

[SRFI-195] Returns i-th value held in box.

NB: This can be used with generalized setters. This is Gauche’s extension.

(define mb (box 10 20 30))
(inc! (unbox-value mb 1)
mb ⇒ #<mv-box[3] 10 21 30>

Function: set-box! box val … ¶

[R7RS box][SRFI-195] Alters the content of box with val …. The numer of values must match the arity of the box. Returns unspecified value.

Function: set-box-value! box i val ¶

[SRFI-195] Alters i-th value of box with val. Returns unspecified value.