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

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

Added rel4 box

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