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

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

tuples: single-state and single-state! renamed to single-ref and single-set!

File size: 7.1 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 tuples are implemented in the Design by Contract style, i.e. using the contracts module. A corollary of this is, that the documentation is included in the module. By convention, there is a routine with the module's name, tuples, which when called with no argument
13
14  (tuples)
15
16shows the exported contract-checked symbols, and called with one of its symbols, e.g.
17
18  (tuples 'tuple->list)
19
20shows the documentation of this symbol in all it's glory, i.e. together with call-structure, docstring, assumptions and propositions.
21
22Note that most contract-checked routines have brethren whith identical signature which are not contract-checked and are not exported. They are prefixed with an % sign and used internally, especially for contract-checking, thus avoiding double-checking.
23
24Another way to get the complete documentation is to use print-doclist from the contracts module. Issuing
25
26  (import tuples (only contracts print-doclist))
27  (with-output-to-file "tuples.docu" (lambda () (print-doclist)))
28
29you'll get a file tuples.docu with the following content
30
31        triple-right
32        ------------
33        (triple-right tup)
34        returns the right item of a triple
35
36        triple-middle
37        -------------
38        (triple-middle tup)
39        returns the middle item of a triple
40
41        triple-left
42        -----------
43        (triple-left tup)
44        returns the left item of a triple
45
46        triple
47        ------
48        (triple x y z)
49        constructor for a tuple storing two items
50
51        triple?
52        -------
53        (triple? x)
54        tests for a tuple storing two items
55
56        couple-right
57        ------------
58        (couple-right tup)
59        returns the right item of a couple
60
61        couple-left
62        -----------
63        (couple-left tup)
64        returns the left item of a couple
65
66        couple
67        ------
68        (couple x y)
69        constructor for a tuple storing two items
70
71        couple?
72        -------
73        (couple? x)
74        tests for a tuple storing two items
75
76        single-set!
77        -----------
78        (single-set! sg arg)
79        replaces state of sg with arg
80        (domain (%single? sg) (true? arg))
81        (effect (state (%tuple-state sg) arg))
82
83        single-ref
84        ----------
85        (single-ref sg)
86        returns the state of the single object sg
87        (domain (%single? sg))
88
89        single
90        ------
91        (single xpr)
92        package xpr into a box so that it can be modified
93        (domain (true? xpr))
94        (range (%single? result))
95
96        single?
97        -------
98        (single? xpr)
99        check, if xpr evaluates to a single
100
101        empty
102        -----
103        (empty)
104        constructor for an empty tuple
105
106        empty?
107        ------
108        (empty? x)
109        tests for an empty tuple
110
111        tuple-for-each
112        --------------
113        (tuple-for-each proc tup)
114        apply a one parameter procedure to each item of tup
115        (domain (%tuple? tup) (procedure? proc) a one parameter procedure)
116
117        tuple->list
118        -----------
119        (tuple->list tup)
120        transforms a tuple into a list
121        (domain (%tuple? tup))
122        (range (list? result))
123
124        tuple-find
125        ----------
126        (tuple-find tup item compare?)
127        checks by comparing with compare? if item is contained in tup
128        (domain (%tuple? tup) (procedure? compare?) a two parameter predicate)
129        (range (or (not result) (and (cardinal? result) (< result (%tuple-length tup)))))
130
131        tuple-right
132        -----------
133        (tuple-right tup)
134        returns the rightmost item of tup
135        (domain (%tuple? tup) (>= (%tuple-length tup) 2))
136
137        tuple-left
138        ----------
139        (tuple-left tup)
140        returns the leftmost item of tup
141        (domain (%tuple? tup) (positive? (%tuple-length tup)))
142
143        tuple-ref
144        ---------
145        (tuple-ref tup n)
146        returns the n'th item of tup, counting from zero
147        (domain (%tuple? tup) (cardinal? n) (< n (%tuple-length tup)))
148
149        tuple-length
150        ------------
151        (tuple-length tup)
152        returns the number of tuple items
153        (domain (%tuple? tup))
154        (range (cardinal? result))
155
156        tuple-copy
157        ----------
158        (tuple-copy tup . interval)
159        constructing a subtuple with tup data from interval
160        (domain (%tuple? tup)
161                                        (<= (length interval) 2)
162                                        ((list-of? cardinal?) interval)
163                                        (apply <= (append interval (list (%tuple-length tup)))))
164        (range (%tuple? result))
165
166        tuple-append
167        ------------
168        (tuple-append . tups)
169        constructs a new tuple by concatenating several others
170        (domain ((list-of? tuple?) tups))
171        (range (%tuple? result))
172
173        tuple-map
174        ---------
175        (tuple-map fn tup)
176        constructs a new tuple by mapping each item of tup with function fn
177        (domain (%tuple? tup) (procedure? fn) a one parameter function)
178        (range (%tuple? result))
179
180        list->tuple
181        -----------
182        (list->tuple lst)
183        transforms a list into a tuple
184        (domain (list? lst))
185        (range (%tuple? result))
186
187        tuple
188        -----
189        (tuple . args)
190        tuple constructor
191        (domain (true? args))
192        (range (%tuple? result))
193
194        tuple-of?
195        ---------
196        (tuple-of? ok?)
197        checks, if each tuple item satisfies predicate ok?
198        (domain (procedure? ok?) ok? is a one parameter predicate)
199        (range (procedure? result) result is a one parameter predicate)
200
201        tuple?
202        ------
203        (tuple? xpr)
204        checks if xpr evaluates to a tuple
205
206
207== Requirements
208
209[[contracts]]
210
211== Last update
212
213Mar 07, 2012
214
215== Author
216
217[[/users/juergen-lorenz|Juergen Lorenz]]
218
219== License
220
221 Copyright (c) 2012, Juergen Lorenz
222 All rights reserved.
223
224 Redistribution and use in source and binary forms, with or without
225 modification, are permitted provided that the following conditions are
226 met:
227 
228 Redistributions of source code must retain the above copyright
229 notice, this list of conditions and the following disclaimer.
230 
231 Redistributions in binary form must reproduce the above copyright
232 notice, this list of conditions and the following disclaimer in the
233 documentation and/or other materials provided with the distribution.
234 Neither the name of the author nor the names of its contributors may be
235 used to endorse or promote products derived from this software without
236 specific prior written permission.
237   
238 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
239 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
240 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
241 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
242 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
243 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
244 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
245 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
246 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
247 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
248 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
249
250== Version History
251
252; 0.7 : single-state and single-state! renamed to single-ref and single-set!
253; 0.6 : contracts rewritten
254; 0.5 : code maintenance
255; 0.4 : added copyright notice
256; 0.3 : updated for using contracts 1.0
257; 0.2 : added tuple-copy, tuple-left,  tuple-right
258; 0.1 : initial import
Note: See TracBrowser for help on using the repository browser.