source: project/wiki/eggref/5/box @ 36155

Last change on this file since 36155 was 36155, checked in by Kon Lovett, 15 months ago

rel 3.0.0

File size: 5.8 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)</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) -> *</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-swap!
115
116<procedure>(box-swap! BOX FUNC [OBJECT...])</procedure>
117
118Changes the boxed value of {{BOX}} to {{(FUNC <BOX-VALUE> OBJECT...)}}.
119Will signal an exception for an immutable {{BOX}. Returns the new value
120of {{BOX}}.
121
122=== make-box-variable-closure
123
124<procedure>(make-box-variable-closure IMMUTABLE? REF SET) -> box</procedure>
125
126; {{IMMUTABLE?}} : {{boolean}}
127; {{REF}} : {{(-> *)}}
128; {{SET}} : {{(* -> void)}}
129
130=== make-box-location-closure
131
132<procedure>(make-box-location-closure IMMUTABLE? REF SET REFLOC) -> box</procedure>
133
134; {{IMMUTABLE?}} : {{boolean}}
135; {{REF}} : {{(-> *)}}
136; {{SET}} : {{(* -> void)}}
137; {{REFLOC}} : {{(-> location)}}
138
139=== box
140
141<procedure>(box OBJECT) -> box</procedure>
142
143Returns a mutable {{BOX}} with initial value {{OBJECT}}.
144
145=== set-box!
146
147<procedure>(set-box! BOX OBJECT)</procedure>
148
149Changes the boxed value of {{BOX}} to {{OBJECT}}. Will signal an exception for an
150immutable {{BOX}.
151
152=== unbox
153
154<procedure>(unbox BOX) -> *</procedure>
155
156Returns the boxed value of {{BOX}}.
157
158
159== Usage
160
161<enscript language=scheme>
162(import box)
163</enscript>
164
165
166== Examples
167
168<enscript language=scheme>
169#;1> (define b (box 0))
170#;2> b
171#&0
172#;3> (define (inc-box! bx) (set! (box-ref bx) (add1 (unbox bx))))
173#;4> (inc-box! b)
174#;5> (unbox b)
1751
176#;6> (box-swap! b add1)
1772
178#;7> (box-swap! b * 3)
1796
180#;8> (box-ref b)
1816
182</enscript>
183
184
185== Notes
186
187* see https://srfi.schemers.org/srfi-111/srfi-111.html
188
189
190== Requirements
191
192[[check-errors]]
193
194
195== Bugs and Limitations
196
197The location of a boxed variable is rather useless.
198
199
200== Author
201
202[[/users/kon-lovett|Kon Lovett]]
203
204
205== Version history
206
207; 3.0.0 : CHICKEN 5 release.
208; 2.4.0 : Add {{make-box-variable-closure}} & {{make-box-location-closure}}.
209; 2.3.3 : Updated type information.
210; 2.3.2 : Added type information.
211; 2.3.1 :
212; 2.3.0 : Added {{box-swap!}}. Fix for print of mutable box.
213; 2.2.4 : Bug fix for Chicken 4.6.3
214; 2.2.3 :
215; 2.2.2 :
216; 2.2.1 :
217; 2.1.0 : Bug fix for {{box?}}. Added direct calls (only for use when the actual type is known.)
218; 2.0.0 : Port to hygienic Chicken. Reduced memory footprint for basic usage. Dropped keyword arguments.
219
220
221== License
222
223Copyright (C) 2009-2018 Kon Lovett.  All rights reserved.
224
225Permission is hereby granted, free of charge, to any person obtaining a
226copy of this software and associated documentation files (the Software),
227to deal in the Software without restriction, including without limitation
228the rights to use, copy, modify, merge, publish, distribute, sublicense,
229and/or sell copies of the Software, and to permit persons to whom the
230Software is furnished to do so, subject to the following conditions:
231
232The above copyright notice and this permission notice shall be included
233in all copies or substantial portions of the Software.
234
235THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
236IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
237FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
238THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
239OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
240ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
241OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.