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

Last change on this file since 13467 was 13467, checked in by Kon Lovett, 12 years ago

Doc update for box-location

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<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 [#: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
161
162== Author
163
164[[kon lovett]]
165
166
167== License
168
169Copyright (C) 2008 Kon Lovett.  All rights reserved.
170
171Permission is hereby granted, free of charge, to any person obtaining a
172copy of this software and associated documentation files (the Software),
173to deal in the Software without restriction, including without limitation
174the rights to use, copy, modify, merge, publish, distribute, sublicense,
175and/or sell copies of the Software, and to permit persons to whom the
176Software is furnished to do so, subject to the following conditions:
177
178The above copyright notice and this permission notice shall be included
179in all copies or substantial portions of the Software.
180
181THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
182IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
183FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
184THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
185OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
186ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
187OTHER DEALINGS IN THE SOFTWARE.
188
189
190== Version history
191
192; 2.0 : Port to hygienic Chicken. Reduced memory footprint for basic usage.
Note: See TracBrowser for help on using the repository browser.