source: project/wiki/eggref/4/tuples @ 27163

Last change on this file since 27163 was 27163, checked in by juergen, 8 years ago

version 0.8 of tuples

File size: 8.3 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== tuples
5
6Tuples are a datatype which has much in common with vectors. Namely they store a finite number of items with random access and make them available via (tuple-ref tup n). But contrary to vectors, the items can only by accessed but not assigned to. If you want to change a particular item, you must package it into a box or a single, which is a special tuple storing exactly one item, which can be changed via single-set! without changing the identity of the single object itself.
7
8singles are the only tuples, which can assign to their content. Other special tuples are empty, couple and triple. Note, that couples can be used instead of pairs to implement immutable lists.
9
10== Documentation
11
12In this implementation skiplists are implemented in the Design by
13Contract style, i.e. using the contracts module. A corollary of this is,
14that the documentation is included in one of the two modules in form of
15a procedure with the module's name. Apart from this documentation
16procedure the two modules, %tuples and tuples, have the same
17interface.  The first module contains the raw implementations of the
18procedures, the second imports the first with prefix % and wraps those
19prefixed routines with contracts.
20
21==== tuples
22
23<procedure>(tuples [sym])</procedure>
24
25returns all available routines of the module when called without an
26argument, but when called with one of these routines as a symbol,
27returns its contract and documentation string.
28
29Another way to get the complete documentation is to use print-doclist from the contracts module. Issuing
30
31<enscript highlight=scheme>
32  (import tuples (only contracts print-doclist))
33  (with-output-to-file "tuples.docu" (lambda () (print-doclist)))
34</enscript>
35
36you'll get a file tuples.docu which is the basis for the following
37documentation.
38
39==== triple-right
40
41<procedure>(triple-right tup)</procedure>
42
43returns the right item of a triple
44
45==== triple-middle
46
47<procedure>(triple-middle tup)</procedure>
48
49returns the middle item of a triple
50
51==== triple-left
52
53<procedure>(triple-left tup)</procedure>
54
55returns the left item of a triple
56
57==== triple
58
59<procedure>(triple x y z)</procedure>
60
61constructor for a tuple storing two items
62
63==== triple?
64
65<procedure>(triple? x)</procedure>
66
67tests for a tuple storing two items
68
69==== couple-right
70
71<procedure>(couple-right tup)</procedure>
72
73returns the right item of a couple
74
75==== couple-left
76
77<procedure>(couple-left tup)</procedure>
78
79returns the left item of a couple
80
81==== couple
82
83<procedure>(couple x y)</procedure>
84
85constructor for a tuple storing two items
86
87==== couple?
88
89<procedure>(couple? x)</procedure>
90
91tests for a tuple storing two items
92
93==== single-set!
94
95<procedure>(single-set! sg arg)</procedure>
96
97<enscript highlight=scheme>
98(domain (%single? sg) (true? arg))
99(effect (state (%tuple-state sg) arg))
100</enscript>
101
102replaces state of sg with arg
103
104==== single-ref
105
106<procedure>(single-ref sg)</procedure>
107
108<enscript highlight=scheme>
109(domain (%single? sg))
110</enscript>
111
112returns the state of the single object sg
113
114==== single
115
116<procedure>(single xpr)</procedure>
117
118<enscript highlight=scheme>
119(domain (true? xpr))
120(range (%single? result))
121</enscript>
122
123package xpr into a box so that it can be modified
124
125==== single?
126
127<procedure>(single? xpr)</procedure>
128
129check, if xpr evaluates to a single
130
131==== empty
132
133<procedure>(empty)</procedure>
134
135constructor for an empty tuple
136
137==== empty?
138
139<procedure>(empty? x)</procedure>
140
141tests for an empty tuple
142
143==== tuple-for-each
144
145<procedure>(tuple-for-each proc tup)</procedure>
146
147<enscript highlight=scheme>
148(domain (%tuple? tup) (procedure? proc) a one parameter procedure)
149</enscript>
150
151apply a one parameter procedure to each item of tup
152
153==== tuple->list
154
155<procedure>(tuple->list tup)</procedure>
156
157<enscript highlight=scheme>
158(domain (%tuple? tup))
159(range (list? result))
160</enscript>
161
162transforms a tuple into a list
163
164==== tuple-find
165
166<procedure>(tuple-find tup item compare?)</procedure>
167
168<enscript highlight=scheme>
169(domain (%tuple? tup) (procedure? compare?) a two parameter predicate)
170(range (or (not result) (and (cardinal? result) (< result (%tuple-length tup)))))
171</enscript>
172
173checks by comparing with compare? if item is contained in tup
174
175==== tuple-right
176
177<procedure>(tuple-right tup)</procedure>
178
179<enscript highlight=scheme>
180(domain (%tuple? tup) (>= (%tuple-length tup) 2))
181</enscript>
182
183returns the rightmost item of tup
184
185==== tuple-left
186
187<procedure>(tuple-left tup)</procedure>
188
189<enscript highlight=scheme>
190(domain (%tuple? tup) (positive? (%tuple-length tup)))
191</enscript>
192
193returns the leftmost item of tup
194
195==== tuple-ref
196
197<procedure>(tuple-ref tup n)</procedure>
198
199<enscript highlight=scheme>
200(domain (%tuple? tup) (cardinal? n) (< n (%tuple-length tup)))
201</enscript>
202
203returns the n'th item of tup, counting from zero
204
205==== tuple-length
206
207<procedure>(tuple-length tup)</procedure>
208
209<enscript highlight=scheme>
210(domain (%tuple? tup))
211(range (cardinal? result))
212</enscript>
213
214returns the number of tuple items
215
216==== tuple-copy
217
218<procedure>(tuple-copy tup . interval)</procedure>
219
220<enscript highlight=scheme>
221(domain (%tuple? tup)
222                                (<= (length interval) 2)
223                                ((list-of? cardinal?) interval)
224                                (apply <= (append interval (list (%tuple-length tup)))))
225(range (%tuple? result))
226</enscript>
227
228constructing a subtuple with tup data from interval
229
230==== tuple-append
231
232<procedure>(tuple-append . tups)</procedure>
233
234<enscript highlight=scheme>
235(domain ((list-of? tuple?) tups))
236(range (%tuple? result))
237</enscript>
238
239constructs a new tuple by concatenating several others
240
241==== tuple-map
242
243<procedure>(tuple-map fn tup)</procedure>
244
245<enscript highlight=scheme>
246(domain (%tuple? tup) (procedure? fn) a one parameter function)
247(range (%tuple? result))
248</enscript>
249
250constructs a new tuple by mapping each item of tup with function fn
251
252==== list->tuple
253
254<procedure>(list->tuple lst)</procedure>
255
256<enscript highlight=scheme>
257(domain (list? lst))
258(range (%tuple? result))
259</enscript>
260
261transforms a list into a tuple
262
263==== tuple
264
265<procedure>(tuple . args)</procedure>
266
267<enscript highlight=scheme>
268(domain (true? args))
269(range (%tuple? result))
270</enscript>
271
272tuple constructor
273
274==== tuple-of?
275
276<procedure>(tuple-of? ok?)</procedure>
277
278<enscript highlight=scheme>
279(domain (procedure? ok?) ok? is a one parameter predicate)
280(range (procedure? result) result is a one parameter predicate)
281</enscript>
282
283checks, if each tuple item satisfies predicate ok?
284
285==== tuple?
286
287<procedure>(tuple? xpr)</procedure>
288
289checks if xpr evaluates to a tuple
290
291
292== Requirements
293
294[[contracts]]
295
296== Last update
297
298Aug 02, 2012
299
300== Author
301
302[[/users/juergen-lorenz|Juergen Lorenz]]
303
304== License
305
306 Copyright (c) 2012, Juergen Lorenz
307 All rights reserved.
308
309 Redistribution and use in source and binary forms, with or without
310 modification, are permitted provided that the following conditions are
311 met:
312 
313 Redistributions of source code must retain the above copyright
314 notice, this list of conditions and the following disclaimer.
315 
316 Redistributions in binary form must reproduce the above copyright
317 notice, this list of conditions and the following disclaimer in the
318 documentation and/or other materials provided with the distribution.
319 Neither the name of the author nor the names of its contributors may be
320 used to endorse or promote products derived from this software without
321 specific prior written permission.
322   
323 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
324 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
325 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
326 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
327 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
328 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
329 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
330 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
331 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
332 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
333 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
334
335== Version History
336
337; 0.8 : code split into two modules
338; 0.7 : single-state and single-state! renamed to single-ref and single-set!
339; 0.6 : contracts rewritten
340; 0.5 : code maintenance
341; 0.4 : added copyright notice
342; 0.3 : updated for using contracts 1.0
343; 0.2 : added tuple-copy, tuple-left,  tuple-right
344; 0.1 : initial import
Note: See TracBrowser for help on using the repository browser.