source: project/wiki/eggref/5/callable-sequences @ 38867

Last change on this file since 38867 was 38867, checked in by juergen, 2 months ago

callable-sequences 1.1 docu

File size: 6.7 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== Sequential- and random-access sequences as procedures
5
6This is a variant of Mario's callable-datastructures. But contrary to
7that egg, I don't consider hash-tables, but only ordered sequences.
8
9The most important procedure, make-callable, is a generic procedure with
10a local database supporting lists, pseudolists, vectors and strings. But
11this database can be enhanced, by giving make-callable two unary
12procedures as arguments, a type predicate and a maker, the latter being
13a spezialization of make-sas-callable or make-ras-callable, handling
14sequential-access or random-access sequences respectively.
15
16Giving make-callable one argument, a sequence, a procedure of zero, one
17or two arguments is returned. The first call returns the encapsulated data
18and its length, the second the data's value at its index argument and
19the third the slice between its two index arguments, in either
20direction, the first included, the second excluded. For convenience, the
21argument #f is allowed in slices, representing the length.
22
23So, for example, if vec is (make-callable #(0 1 2 3 4 5)), then
24(vec 1 4) or (vec 4 1) are callables comprising #(1 2 3) or #(4 3 2)
25respectively, and, using length, (vec 3 #f) or (vec #f 3) comprise
26#(3 4 5) or #(5 4) respectively.
27
28=== API
29
30==== callable-sequences
31
32<procedure>(callable-sequences)</procedure>
33<procedure>(callable-sequences sym)</procedure>
34
35documentation procedure: returns the list of exported symbols if called
36without argument, or the documentation of sym otherwise.
37
38==== make-callable
39
40<procedure>(make-callable)</procedure>
41<procedure>(make-callable seq)</procedure>
42<procedure>(make-callable seq? seq-maker?)</procedure>
43
44generic procedure.
45
46The first resets the local datbase to standard form, which can handle
47lists, vectors, strings and pseudolists.
48
49The second transforms the sequence into a procedure of zero, one or
50two arguments, meaning
51
52* zero: returns the original sequence and its length
53* one:  returns the reference of its integer argument
54* two:  returns the slice of its integer arguments respecting their order
55
56The third updates the local database inserting the new pair in next to
57last position. The seq-maker argument specializes one of the two
58constructors make-sas-callable and make-ras-callable respectively.
59
60==== make-callable*
61
62<procedure>(make-callable* seq)</procedure>
63
64recursive version of make-callable
65
66==== make-sas-callable
67
68<procedure>(make-sas-callable seq seq-cons seq-car seq-cdr seq-null?)</procedure>
69
70constructor for sequential-access sequences: transforms the sequence,
71seq, into a procedure of zero, one or two arguments as above.
72
73==== make-ras-callable
74
75<procedure>(make-ras-callable seq make-seq seq-ref seq-set! seq-length)</procedure>
76
77constructor for random-access sequences: transforms the sequence,
78seq, into a procedure of zero, one or two arguments as above.
79
80==== callable-sas?
81
82<procedure>(callable-sas? xpr)</procedure>
83
84type predicate for callable sequential-access sequences
85
86==== callable-ras?
87
88<procedure>(callable-ras? xpr)</procedure>
89
90type predicate for callable random-access sequences
91
92==== callable?
93
94<procedure>(callable? xpr)</procedure>
95
96type predicate for arbitrary sequences
97
98==== callable-null?
99
100<procedure>(callable-null? xpr)</procedure>
101
102is xpr a callable-sequence with empty data?
103
104==== callable-length
105
106<procedure>(callable-length cs)</procedure>
107
108returns the length of the callable sequence cs
109
110==== callable-data
111
112<procedure>(callable-data cs)</procedure>
113
114returns the encapsulated data of the callable sequence cs
115
116==== callable-reverse
117
118<procedure>(callable-reverse cs)</procedure>
119
120returns a callable sequence, which is the reverse of the original one
121
122=== Requirements
123
124None
125
126=== Examples
127
128<enscript highlight=scheme>
129
130(import callable-sequences)
131
132(define vec (make-callable #(0 1 2 3 4 5)))
133
134(define lst (make-callable '(0 1 2 3 4 5)))
135
136(define pair (make-callable '(0 1 2 3 4 5 . 6)))
137
138(define str (make-callable "012345"))
139
140(lst 2)
141; -> 2
142
143(vec 5)
144; -> 5
145
146(str 1)
147; -> #\1
148
149(callable-length pair)
150; -> 6
151
152(callable-length str)
153; -> 6
154
155(callable-sas? lst)
156; -> #t
157
158(callable-ras? lst)
159; -> #f
160
161(callable? lst)
162; -> #t
163
164(callable? (pair 2 4))
165; -> #t
166
167(callable-data (callable-reverse pair))
168; ->  '(5 4 3 2 1 0 . 6))
169
170(callable-data vec)
171; -> #(0 1 2 3 4 5)
172
173(callable-date (vec 2 4))
174; -> #(2 3)
175
176(callable-data (lst 2 4))
177; -> '(2 3)
178
179(callable-data (lst 2 #f))
180; -> '(2 3 4 5)
181
182(callable-data (vec #f 2)
183; -> #(5 4 3)
184
185(callable-data (pair 4 2))
186; -> '(4 3 . 6)
187
188(callable-data (pair 2 2))
189; -> 6
190
191(callable-null? (pair 2 2))
192; -> #t
193
194(callable-data (str 2 5))
195; -> "234"
196
197(callable-data (str 2 2))
198; -> ""
199
200(callable-data (str 5 2))
201; -> "543"
202
203(callable-data (callable-reverse str))
204; -> "543210"
205
206;; recursive examples
207(define vp* (make-callable* (vector 'a '(b . c))))
208((vp* 1) 0)
209; -> 'b
210(((vp* 1) 1 #f))
211; -> 'c
212
213(define vs* (make-callable* (vector 'a "bc")))
214((vs* 1) 0)
215; -> #\b
216((vs* 1) 1)
217; -> #\c
218(((vs* 1) 2 #f))
219; -> ""
220
221(define lv** (make-callable* '(a (b #(c d) e) f)))
222(lv** 0)
223; -> 'a
224((lv** 1) 0)
225; -> 'b
226(((lv** 1) 1) 0)
227; -> 'c
228(((lv** 1) 1) 1)
229; -> 'd
230(lv** 2)
231; -> 'f
232((lv** 1) 2)
233; -> 'e
234
235</enscript>
236
237== Last update
238
239Aug 21, 2020
240
241== Author
242
243[[/users/juergen-lorenz|Juergen Lorenz]]
244
245== License
246
247 Copyright (c) 2020, Juergen Lorenz
248 All rights reserved.
249
250 Redistribution and use in source and binary forms, with or without
251 modification, are permitted provided that the following conditions are
252 met:
253 
254 Redistributions of source code must retain the above copyright
255 notice, this list of conditions and the following disclaimer.
256 
257 Redistributions in binary form must reproduce the above copyright
258 notice, this list of conditions and the following disclaimer in the
259 documentation and/or other materials provided with the distribution.
260 Neither the name of the author nor the names of its contributors may be
261 used to endorse or promote products derived from this software without
262 specific prior written permission.
263   
264 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
265 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
266 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
267 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
268 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
269 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
270 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
271 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
272 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
273 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
274 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
275
276== Version History
277; 1.1 : make-callable* added, a recursive version of (make-callable seq)
278; 1.0.0 : initial version
Note: See TracBrowser for help on using the repository browser.