source: project/wiki/eggref/4/box @ 13526

Last change on this file since 13526 was 13526, checked in by Kon Lovett, 11 years ago

Rmvd keyword arg style from 'box'. Save for 'stack'.

File size: 4.7 KB
Line 
1[[tags: egg]]
2
3== box
4
5[[toc:]]
6
7
8== Documentation
9
10Implements the "box" data type. A box is a cell containing a single, mutable or
11immutable, field. The boxed value maybe any Scheme type, including a variable or
12a location.
13
14Two APIs are provided, the original Chicken box API and a MzScheme/Gambit compatible API.
15
16=== Box syntax
17
18The lexical syntax of a box containing the object {{OBJECT}} is `#&OBJECT'.
19
20Only mutable boxes can be recovered. An immutable, variable, or location box
21will lose identity when printed.
22
23=== make-box
24
25<procedure>(make-box [INITIAL [IMMUTABLE? #f]]) => BOX</procedure>
26
27Returns a {{BOX}} with, optional, initial value {{INITIAL}}.
28
29The {{BOX}} is mutable unless the {{IMMUTABLE?}} argument is {{#t}}.
30
31An attempt to mutate an immutable box will signal an exception.
32
33=== make-box-variable
34
35<macro>(make-box-variable VARIABLE [IMMUTABLE? #f]) => BOX</macro>
36
37Returns a boxed reference to the {{VARIABLE}}, which must be in lexical-scope.
38
39The {{BOX}} is mutable unless the {{IMMUTABLE?}} argument is {{#t}}.
40
41An attempt to mutate an immutable box will signal an exception.
42
43=== make-box-location
44
45<macro>(make-box-location TYPE INITIAL-VALUE [IMMUTABLE? #f]) => BOX</macro>
46
47Returns a boxed reference to a location of {{TYPE}} and {{INITIAL-VALUE}}.
48
49The {{BOX}} is mutable unless the {{IMMUTABLE?}} argument is {{#t}}.
50
51An attempt to mutate an immutable box will signal an exception.
52
53Unavailable in EVALuated source.
54
55=== box?
56
57<procedure>(box? OBJECT) => BOOLEAN</procedure>
58
59Is {{OBJECT}} a {{BOX}}?
60
61=== box-mutable?
62
63<procedure>(box-mutable? OBJECT) => BOOLEAN</procedure>
64
65Is {{OBJECT}} a mutable {{BOX}}?
66
67=== box-immutable?
68
69<procedure>(box-immutable? OBJECT) => BOOLEAN</procedure>
70
71Is {{OBJECT}} an immutable {{BOX}}?
72
73=== box-variable?
74
75<procedure>(box-variable? OBJECT) => BOOLEAN</procedure>
76
77Is {{OBJECT}} a boxed variable?
78
79=== box-location?
80
81<procedure>(box-location? OBJECT) => BOOLEAN</procedure>
82
83Is {{OBJECT}} a boxed location?
84
85=== box-set!
86
87<procedure>(box-set! BOX OBJECT) => UNSPECIFIED</procedure>
88
89Changes the boxed value of {{BOX}} to {{OBJECT}}. Will signal an exception for an
90immutable {{BOX}.
91
92=== box-ref
93
94<procedure>(box-ref BOX) => OBJECT</procedure>
95
96Returns the boxed value of {{BOX}}.
97
98=== box-location
99
100<procedure>(box-location BOX [WEAK? #f]) => LOCATION</procedure>
101
102Returns a {{LOCATION}} object for a boxed variable, location or locatable box.
103Signals an exception otherwise.
104
105The locative is "strong" unless the {{WEAK?}} argument is {{#t}}. The
106{{WEAK?}} argument is ignored for boxed variables and locations.
107
108The location of a boxed value or boxed location is the box. The location of a boxed
109variable is the same as {{(location (box-ref BOX))}}; currently the location of a
110symbol may not be taken.
111
112See [[Locations]].
113
114=== box
115
116<procedure>(box OBJECT) => BOX</procedure>
117
118Returns a mutable {{BOX}} with initial value {{OBJECT}}.
119
120=== set-box!
121
122<procedure>(set-box! BOX OBJECT) => UNSPECIFIED</procedure>
123
124Changes the boxed value of {{BOX}} to {{OBJECT}}. Will signal an exception for an
125immutable {{BOX}.
126
127=== unbox
128
129<procedure>(unbox BOX) => OBJECT</procedure>
130
131Returns the boxed value of {{BOX}}.
132
133
134== Usage
135
136<enscript language=scheme>
137(require-extension box)
138(import box)
139</enscript>
140
141
142== Examples
143
144<enscript language=scheme>
145#;1> (define b (box 0))
146#;2> b
147#&0
148#;3> (define (inc-box! bx) (set! (box-ref bx) (add1 (unbox bx))))
149#;4> (inc-box! b)
150#;5> (unbox b)
1511
152</enscript>
153
154
155== Notes
156
157
158== Requirements
159
160[[Unit lolevel]]
161
162
163== Bugs and Limitations
164
165The location of a boxed variable is rather useless.
166
167
168== Author
169
170[[kon lovett]]
171
172
173== Version history
174
175; 2.0.0 : Port to hygienic Chicken. Reduced memory footprint for basic usage. Dropped keyword arguments.
176
177
178== License
179
180Copyright (C) 2009 Kon Lovett.  All rights reserved.
181
182Permission is hereby granted, free of charge, to any person obtaining a
183copy of this software and associated documentation files (the Software),
184to deal in the Software without restriction, including without limitation
185the rights to use, copy, modify, merge, publish, distribute, sublicense,
186and/or sell copies of the Software, and to permit persons to whom the
187Software is furnished to do so, subject to the following conditions:
188
189The above copyright notice and this permission notice shall be included
190in all copies or substantial portions of the Software.
191
192THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
193IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
194FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
195THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
196OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
197ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
198OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.