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

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

Added 'mailbox' doc.

File size: 4.6 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<macro>(make-box-variable VARIABLE [#:immutable? #f]) => BOX</macro>
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<macro>(make-box-location TYPE INITIAL-VALUE [#:immutable? #f]) => BOX</macro>
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 [#:weak? #f]) => LOCATION</procedure>
96
97Returns a {{LOCATION}} object for a boxed variable, location or locatable box.
98Signals an exception otherwise.
99
100The locative is "strong" unless the {{weak?}} keyword argument is {{#t}}. The
101{{weak?}} keyword argument is ignored for boxed variables and locations.
102
103The location of a boxed value or boxed location is the box. The location of a boxed
104variable is the same as {{(location (box-ref BOX))}}; currently the location of a
105symbol may not be taken.
106
107See [[Locations]].
108
109=== box
110
111<procedure>(box OBJECT) => BOX</procedure>
112
113Returns a mutable {{BOX}} with initial value {{OBJECT}}.
114
115=== set-box!
116
117<procedure>(set-box! BOX OBJECT) => UNSPECIFIED</procedure>
118
119Changes the boxed value of {{BOX}} to {{OBJECT}}. Will signal an exception for an
120immutable {{BOX}.
121
122=== unbox
123
124<procedure>(unbox BOX) => OBJECT</procedure>
125
126Returns the boxed value of {{BOX}}.
127
128
129== Usage
130
131<enscript language=scheme>
132(require-extension box)
133(import box)
134</enscript>
135
136
137== Examples
138
139<enscript language=scheme>
140#;1> (define b (box 0))
141#;2> b
142#&0
143#;3> (define (inc-box! bx) (set! (box-ref bx) (add1 (unbox bx))))
144#;4> (inc-box! b)
145#;5> (unbox b)
1461
147</enscript>
148
149
150== Notes
151
152
153== Requirements
154
155[[Unit lolevel]]
156
157
158== Bugs and Limitations
159
160The location of a boxed variable is rather useless.
161
162
163== Author
164
165[[kon lovett]]
166
167
168== Version history
169
170; 2.0.0 : Port to hygienic Chicken. Reduced memory footprint for basic usage.
171
172
173== License
174
175Copyright (C) 2009 Kon Lovett.  All rights reserved.
176
177Permission is hereby granted, free of charge, to any person obtaining a
178copy of this software and associated documentation files (the Software),
179to deal in the Software without restriction, including without limitation
180the rights to use, copy, modify, merge, publish, distribute, sublicense,
181and/or sell copies of the Software, and to permit persons to whom the
182Software is furnished to do so, subject to the following conditions:
183
184The above copyright notice and this permission notice shall be included
185in all copies or substantial portions of the Software.
186
187THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
188IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
189FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
190THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
191OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
192ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
193OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.