source: project/wiki/eggref/5/simple-sequences @ 39336

Last change on this file since 39336 was 39336, checked in by juergen, 6 months ago

simple-sequences docu

File size: 8.6 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== Rationale
5
6This module allows to acces some sequence types, in particular lists,
7pairs, vectors and strings with a common interface. The number of
8sequence types handled can be enhanced.
9The egg is not as complete and sophisticated as Felix' sequences egg,
10but quite usable. In particular, it is sufficient for use in Paul
11Graham's dbind implementation, cf. On Lisp, p. 232, which is the
12workhorse of my bindings egg.
13
14=== API
15
16==== sequence-db
17 
18<procedure>(sequence-db)</procedure>
19
20<procedure>(sequence-db seq)</procedure>
21
22<procedure>(sequence-db seq? seq-length seq-ref seq-tail seq-maker . pos?)</procedure>
23
24database processing:
25the first resets the database to the standard with
26lists, pairs, vectors and strings,
27the second returns the vector of handlers as well as the discriminator,
28the third adds a new database record either at the end or before the
29pos? discriminator.
30A record cosists of a discriminator, seq?, and a vector with items
31seq-lenth, seq-ref, seq-tail and seq-maker patterned after vectors.
32Note, that the last record can handle atoms, albeit it is not a
33sequence.
34
35==== sequence?
36 
37<procedure>(sequence? x)</procedure>
38
39type predicate.
40
41==== seq-length
42 
43<procedure>(seq-length seq)</procedure>
44
45returns the length of a sequences
46
47==== seq-ref
48 
49<procedure>(seq-ref seq k)</procedure>
50
51returns the item of seq at position k
52
53==== seq-tail
54 
55<procedure>(seq-tail seq k)</procedure>
56
57reuturns the subsequence of seq starting at position k.
58Note that k might be equal to (seq-length seq), returning
59the sentinel of empty sequence
60
61==== seq-maker
62 
63<procedure>(seq-maker seq)</procedure>
64
65returns the maker, like list or vector, to create new sequences
66of the same type as seq.
67
68==== seq-nil
69 
70<procedure>(seq-nil seq)</procedure>
71
72returns the sentinel of pairs or empty sequences
73
74==== seq-pseudo?
75 
76<procedure>(seq-pseudo? x)</procedure>
77
78checks, if the sequence is pseudo, i.e. a pair.
79This is needed to handle pairs like other sequences.
80
81==== sequence->list
82 
83<procedure>(sequence->list seq)</procedure>
84
85type transformer
86
87==== seq-reverse
88 
89<procedure>(seq-reverse seq)</procedure>
90
91returns a new sequence with items reversed
92
93==== subseq
94 
95<procedure>(subseq seq i)</procedure>
96
97<procedure>(subseq seq i j)</procedure>
98
99creates a new sequence of the same type as seq consisting
100of seq's items from i included and j excluded
101
102==== seq-filter
103 
104<procedure>(seq-filter ok? seq)</procedure>
105
106returns two subsequences of the same type as seq of items
107passed or not passed by the ok? test
108
109==== seq-memp
110 
111<procedure>(seq-memp ok? seq)</procedure>
112
113returns a new sequence of seq's type of items from seq
114starting at the first item which passes the ok? test,
115or #f
116
117==== seq-append
118 
119<procedure>(seq-append seq . seqs)</procedure>
120
121appends the items of all argument sequences, which must be of the same
122type as seq and in case of pairs, the same sentinel
123
124==== seq-map
125 
126<procedure>(seq-map fn seq . seqs)</procedure>
127
128maps the argument sequences up to the shortest length.
129All sequences must be of the same type, and in case of pairs,
130must have the same sentinels
131
132==== seq-for-each
133 
134<procedure>(seq-for-each proc seq . seqs)</procedure>
135
136applies proc to each item of seq and seqs
137up to the shortest length. The sequences might be
138of different type
139
140==== seq-ref*
141 
142<procedure>(seq-ref* seq ind)</procedure>
143
144references the value of a nested sequence at appropriate index list:
145with index '(0) it returns (seq-ref seq 0),
146with index '(1 0) it returns (seq-ref (seq-ref seq 1) 0)
147
148==== seq-flat?
149 
150<procedure>(seq-flat? seq)</procedure>
151
152is the sequence seq flat?
153
154==== seq-length*
155 
156<procedure>(seq-length* seq)</procedure>
157
158counts the number of items in a nested sequence seq
159
160==== seq-map*
161 
162<procedure>(seq-map* fn seq)</procedure>
163
164deep map: maps all items of a nested sequence seq with function fn
165
166==== simple-sequences
167 
168<procedure>(simple-sequences)</procedure>
169
170<procedure>(simple-sequences sym)</procedure>
171
172with sym: documentation of exported symbol
173without sym: list of exported symbols
174
175=== Examples
176
177<enscript highlight=scheme>
178
179(import simple-sequences)
180
181(sequence-db '())
182;-> (vector length list-ref list-tail list)
183
184(sequence-db #())
185;-> (vector vector-length vector-ref subvector vector)
186
187(sequence-db "")
188;-> (vector string-length string-ref substring string)
189
190(seq-length '())
191;-> 0
192
193(seq-length #())
194;-> 0
195
196(seq-length "")
197;-> 0
198
199(seq-length '(1 . 2))
200;-> 1
201
202(seq-length 1)
203;-> 0
204
205(seq-ref '(0 1 2 3) 1)
206;-> 1
207
208(seq-ref #(0 1 2 3) 1)
209;-> 1
210
211(seq-ref "0123" 1)
212;-> 1
213
214(seq-ref '(0 1 2 . 3) 1)
215;-> 1
216
217(seq-tail '(0 1 2 3 4) 1)
218;-> (quote (1 2 3 4))
219
220(seq-tail #(0 1 2 3 4) 1)
221;-> #(1 2 3 4)
222
223(seq-tail "01234" 1)
224;-> 1234
225
226(seq-tail '(0 1 2 3 . 4) 1)
227;-> (quote (1 2 3 . 4))
228
229(seq-tail '(0 1 2 3 . 4) 4)
230;-> 4
231
232(seq-tail 1 0)
233;-> 1
234
235(sequence? 1)
236;-> #f
237
238(length (sequence-db))
239;-> 5
240
241(list-ref
242  (sequence-db
243    number?
244    (lambda (x) 0)
245    (lambda (x i) (error))
246    (lambda (x i) x)
247    (lambda (x) x))
248  4)
249;-> number?
250
251(car (sequence-db
252       integer?
253       (lambda (x) 0)
254       (lambda (x i) (error))
255       (lambda (x i) x)
256       (lambda (x) x)
257       list?))
258;-> integer?
259
260(length (sequence-db))
261;-> 5
262
263(condition-case (seq-ref 1 0) ((exn) "out of range"))
264;-> out of range
265
266(seq-tail 1 0)
267;-> 1
268
269(condition-case (seq-tail 1 1) ((exn) "out of range"))
270;-> out of range
271
272(sequence->list '(0 1 2 . 3))
273;-> (quote (0 1 2))
274
275(seq-maker str)
276;-> string
277
278(subseq str 1)
279;-> 123
280
281(subseq str 1 3)
282;-> 12
283
284(subseq pls 1 3)
285;-> (quote (1 2 . 3))
286
287(seq-nil str)
288;->
289
290(seq-nil pls)
291;-> 3
292
293(seq-pseudo? pls)
294;-> #t
295
296(seq-pseudo? lst)
297;-> #f
298
299(seq-reverse "abc")
300;-> cba
301
302(seq-reverse '(1 2 3 . 0))
303;-> (quote (3 2 1 . 0))
304
305(receive (odd even) (seq-filter odd? vec) (list odd even))
306;-> (quote (#(1 3) #(0 2)))
307
308(receive (odd even) (seq-filter odd? pls) (list odd even))
309;-> (quote ((1 . 3) (0 2 . 3)))
310
311(seq-memp odd? vec)
312;-> #(1 2 3)
313
314(seq-memp odd? pls)
315;-> (quote (1 2 . 3))
316
317(seq-memp (lambda (s) (char=? s #\2)) str)
318;-> 23
319
320(seq-append #(1 2 3) #(10 20 30))
321;-> #(1 2 3 10 20 30)
322
323(seq-append '(1 2 3 . 0) '(10 20 30 . 0))
324;-> (quote (1 2 3 10 20 30 . 0))
325
326(seq-append "a" "b" "c" "d" "e")
327;-> abcde
328
329(seq-map add1 #(0 1 2))
330;-> #(1 2 3)
331
332(seq-map add1 '(0 1 2 . 0))
333;-> (quote (1 2 3 . 0))
334
335(seq-map + #(1 2 3) #(10 20 30 40))
336;-> #(11 22 33)
337
338(seq-map + '(1 2 . 0) '(10 20 . 0))
339;-> (quote (11 22 . 0))
340
341(condition-case (seq-map + '(1 2 . 3) '(10 20 . 30)) ((exn) "different nils"))
342;-> different nils
343
344(seq-ref* '(1 #(2 3)) '(1 0))
345;-> 2
346
347(seq-ref* '(0 #(1 "23")) '(1 1 1))
348;-> 3
349
350(seq-ref* '(0 #(1 "23")) '(1 0))
351;-> 1
352
353(seq-ref* '(0 #(1 "23")) '(1 1))
354;-> 23
355
356(seq-flat? #(1 2 3))
357;-> #t
358
359(seq-flat? '(1 #(2 3)))
360;-> #f
361
362(seq-length* '((2 (3 #(4) 5) 1) 0))
363;-> 6
364
365(seq-length* '(1 #(2 "3")))
366;-> 3
367
368(seq-length* '(((((0))))))
369;-> 1
370
371(seq-map* add1 '(((2) 1) 0))
372;-> (quote (((3) 2) 1))
373
374(seq-map* add1 '(0 #(1 2)))
375;-> (quote (1 #(2 3)))
376
377(seq-map* add1 '(0 (1 2 . 3)))
378;-> (quote (1 (2 3 . 3)))
379
380(seq-map* add1 '(0 (1 (2 . 3))))
381;-> (quote (1 (2 (3 . 3))))
382
383(seq-map* add1 '(0 (1 (2 . 3) . 0)))
384;-> (quote (1 (2 (3 . 3) . 0)))
385
386</enscript>
387
388
389== Requirements
390
391None
392
393== Last update
394
395Nov 22, 2020
396
397== Author
398
399Juergen Lorenz
400
401== License
402
403Copyright (c) 2020 , Juergen Lorenz, ju (at) jugilo (dot) de
404All rights reserved.
405
406Redistribution and use in source and binary forms, with or without
407modification, are permitted provided that the following conditions are
408met:
409
410Redistributions of source code must retain the above copyright
411notice, this list of conditions and the following disclaimer.
412
413Redistributions in binary form must reproduce the above copyright
414notice, this list of conditions and the following disclaimer in the
415documentation and/or other materials provided with the distribution.
416Neither the name of the author nor the names of its contributors may be
417used to endorse or promote products derived from this software without
418specific prior written permission.
419 
420THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
421IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
422TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
423PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
424HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
425SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
426TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
427PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
428LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
429NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
430SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
431
432== Version history
433; 0.1 : Initial check in
Note: See TracBrowser for help on using the repository browser.