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

Last change on this file since 38996 was 38996, checked in by juergen, 8 weeks ago

callable-sequences 1.2 docu

File size: 12.4 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== Rationale
5
6
7This is a variant of Mario's callable-datastructures. But contrary to
8that egg, I don't consider hash-tables, but only ordered sequences. So
9it makes sense, to define slices. Moreover, I'll consider nested
10sequences as well.
11
12Central to this module is a generic procedure, sequence-constructors, which
13stores a local database initially supporting lists, pseudolists, vectors
14and strings. But this database can be enhanced, by adding generic
15constructors, make-sas-callable or make-ras-callable for sequential or
16random access sequences respectively, the former following the list
17pattern, the latter the vector pattern.
18
19Based on this, the most important procedure is make-callable, which
20transforms an ordinary into a callable-sequence, i.e. a procedure of
21zero, one or two arguments. With no argument, this returns i.a. the
22encapsulated sequence, with one, an index, the value of that sequence at
23the index and with two a slice between its two index arguments, in
24either direction, the first included, the second excluded. For
25convenience, the argument #f is allowed in slices, representing the
26length.
27
28So, for example, if vec is (make-callable #(0 1 2 3 4 5)), then
29(vec 1 4) or (vec 4 1) are callable-sequences encapsulating #(1 2 3)
30or #(4 3 2) respectively, and (vec 3 #f) or (vec #f 3) encapsulate
31#(3 4 5) or #(5 4) respectively.
32
33
34=== API
35
36==== make-sas-callable
37 
38<procedure>(make-sas-callable seq seq-cons seq-car seq-cdr seq-null?)</procedure>
39
40sequential access constructor with arguments similar to lists
41
42==== callable-sas?
43 
44<procedure>(callable-sas? xpr)</procedure>
45
46evaluates xpr to a sequential access callable-sequence?
47
48==== make-ras-callable
49 
50<procedure>(make-ras-callable seq make-seq seq-ref seq-set! seq-length)</procedure>
51
52random access constructor with arguments similar to vectors
53
54==== callable-ras?
55 
56<procedure>(callable-ras? xpr)</procedure>
57
58evaluates xpr to a random access callable-sequence?
59
60==== sequence?
61 
62<procedure>(sequence? xpr)</procedure>
63
64evaluates xpr to a sequence type, initially a list, pseudolist, vector
65or string.
66To be updated, if new sequence types are added.
67
68==== sequence-constructors
69 
70<procedure>(sequence-constructors)</procedure>
71
72<procedure>(sequence-constructors seq)</procedure>
73
74<procedure>(sequence-constructors sym)</procedure>
75
76the first resets the internal database and the sequence? predicate,
77the second selects and returns the constructor corresponding to the sequence
78argument,
79and the third adds a new sequential-access or random-access constructor,
80according to the symbol 'sas or 'ras. sequence? is updated as well.
81
82==== make-callable
83 
84<procedure>(make-callable seq)</procedure>
85
86makes the sequence seq callable
87
88==== callable?
89 
90<procedure>(callable? xpr)</procedure>
91
92evaluates xpr to a callable sequence
93
94==== callable-null?
95 
96<procedure>(callable-null? clb)</procedure>
97
98is the callable-sequence clb empty?
99
100==== callable-flat?
101 
102<procedure>(callable-flat? clb)</procedure>
103
104is the callable sequence clb flat?
105
106==== callable-length
107 
108<procedure>(callable-length clb)</procedure>
109
110returns the length of the callable sequence clb
111
112==== callable-nil
113 
114<procedure>(callable-nil clb)</procedure>
115
116returns an empty callable sequence of the same type as clb
117
118==== callable-data
119 
120<procedure>(callable-data clb)</procedure>
121
122returns the encapsulated sequence of the flat callable-sequence clb
123
124==== callable-indices
125 
126<procedure>(callable-indices ok? clb)</procedure>
127
128returns the list of indices, k, for which (clb k) passes the ok? test
129
130==== callable-copy
131 
132<procedure>(callable-copy clb)</procedure>
133
134returns a callable sequence which is a copy of the initial one
135
136==== callable-map
137 
138<procedure>(callable-map fn clb)</procedure>
139
140maps the callable-sequence, clb, via procedure fn
141
142==== callable-for-each
143 
144<procedure>(callable-for-each fn clb)</procedure>
145
146executes fn for each item of clb
147
148==== callable-filter
149 
150<procedure>(callable-filter ok? clb)</procedure>
151
152returnstwo callable sequences filtering items of clb
153via ok? or not-ok? respectively
154
155==== callable-reverse
156 
157<procedure>(callable-reverse clb)</procedure>
158
159<procedure>(callable-reverse clb clb1)</procedure>
160
161returns a callable sequence which is the reverse of the first argument
162appended to the second one which defaults to callable-nil, if not given
163
164==== callable-append
165 
166<procedure>(callable-append clb . clbs)</procedure>
167
168returns the callable sequence appending encapsulated sequences
169of same type
170
171==== callable-data*
172 
173<procedure>(callable-data* clb)</procedure>
174
175nested version of callable-data
176
177==== callable-map*
178 
179<procedure>(callable-map* fn clb)</procedure>
180
181nested version of callable-map, i.e. maps a nested callable-sequence
182
183==== make-callable*
184 
185<procedure>(make-callable* seq)</procedure>
186
187nested version of make-callable, i.e. creates a nested callable-sequence
188from a nested ordinary sequence
189
190==== callable-sequences
191 
192<procedure>(callable-sequences)</procedure>
193
194<procedure>(callable-sequences sym)</procedure>
195
196with sym: documentation of exported symbol
197without sym: list of exported symbols
198
199=== Examples
200
201<enscript highlight=scheme>
202
203(import callable-sequences)
204
205(callable-length pls)
206;-> 6
207
208(callable-length lst)
209;-> 6
210
211(callable-length str)
212;-> 6
213
214(callable-length vec)
215;-> 6
216
217(callable-null? str)
218;-> #f
219
220(callable-flat? vec)
221;-> #t
222
223(lst 0)
224;-> 0
225
226(lst 3)
227;-> 3
228
229(vec 3)
230;-> 3
231
232(str 3)
233;-> 3
234
235(lst 5)
236;-> 5
237
238(condition-case (lst (callable-length lst)) ((exn) #f))
239;-> #f
240
241(condition-case (vec (callable-length vec)) ((exn) #f))
242;-> #f
243
244(condition-case (str (callable-length str)) ((exn) #f))
245;-> #f
246
247(callable-data (lst 2 4))
248;-> (quote (2 3))
249
250(callable-data (lst 0 3))
251;-> (quote (0 1 2))
252
253(callable-length (lst 0 3))
254;-> 3
255
256(callable-data (pls 0 3))
257;-> (quote (0 1 2 . 6))
258
259((pls 0 0))
260;-> 6
261
262(callable-data (pls 0 0))
263;-> 6
264
265(callable-null? (pls 3 3))
266;-> #t
267
268(callable-null? (vec 1 2))
269;-> #f
270
271(callable-data (pls 3 0))
272;-> (quote (3 2 1 . 6))
273
274(callable-data (vec 0 3))
275;-> #(0 1 2)
276
277(callable-data (str 0 3))
278;-> 012
279
280(callable-data (lst 3 0))
281;-> (quote (3 2 1))
282
283(callable-data (vec 3 0))
284;-> #(3 2 1)
285
286(callable-data (str 3 0))
287;-> 321
288
289(callable-data (pls 0 #f))
290;-> (quote (0 1 2 3 4 5 . 6))
291
292(callable-data (pls 0 (callable-length pls)))
293;-> (quote (0 1 2 3 4 5 . 6))
294
295(callable-data (lst 0 6))
296;-> (quote (0 1 2 3 4 5))
297
298(callable-data (vec 0 #f))
299;-> #(0 1 2 3 4 5)
300
301(callable-data (str 0 #f))
302;-> 012345
303
304(condition-case (lst 0 7) ((exn) #f))
305;-> #f
306
307(condition-case (vec 0 7) ((exn) #f))
308;-> #f
309
310(condition-case (str 0 7) ((exn) #f))
311;-> #f
312
313(callable-data (lst 0 #f))
314;-> (quote (0 1 2 3 4 5))
315
316(callable-data (vec 0 #f))
317;-> #(0 1 2 3 4 5)
318
319(callable-data (str 0 #f))
320;-> 012345
321
322(callable-data (lst #f -1))
323;-> (quote (5 4 3 2 1 0))
324
325(callable-data (lst (- (callable-length lst) 1) -1))
326;-> (quote (5 4 3 2 1 0))
327
328(callable-data (callable-reverse lst))
329;-> (quote (5 4 3 2 1 0))
330
331(callable-data (vec #f -1))
332;-> #(5 4 3 2 1 0)
333
334(callable-data (vec (- (callable-length vec) 1) -1))
335;-> #(5 4 3 2 1 0)
336
337(callable-data (vec #f -1))
338;-> #(5 4 3 2 1 0)
339
340(callable-data (str #f -1))
341;-> 543210
342
343(callable-data (str (- (callable-length str) 1) -1))
344;-> 543210
345
346(callable-data (lst 3 1))
347;-> (quote (3 2))
348
349(callable-data (vec 3 1))
350;-> #(3 2)
351
352(callable-data (str 3 1))
353;-> 32
354
355(callable? str)
356;-> #t
357
358(callable-sas? lst)
359;-> #t
360
361(callable-ras? lst)
362;-> #f
363
364(callable? lst)
365;-> #t
366
367(callable? vec)
368;-> #t
369
370(callable? (lst 1 4))
371;-> #t
372
373(callable? (vec 1 4))
374;-> #t
375
376(callable-ras? (str 1 4))
377;-> #t
378
379(callable-sas? (str 1 4))
380;-> #f
381
382(callable? (str 1 4))
383;-> #t
384
385(callable? car)
386;-> #f
387
388(callable? '(0 1 2 3))
389;-> #f
390
391(callable? #(0 1 2 3))
392;-> #f
393
394(sequence? #(0 1 2 3))
395;-> #t
396
397(callable? "0123")
398;-> #f
399
400(sequence? "0123")
401;-> #t
402
403(sequence? #f)
404;-> #f
405
406(callable? pls)
407;-> #t
408
409(callable? '())
410;-> #f
411
412(callable-null? vec)
413;-> #f
414
415(callable-null? (callable-nil vec))
416;-> #t
417
418(callable-flat? vec)
419;-> #t
420
421(callable-data (callable-nil vec))
422;-> #()
423
424(callable-nil pls)
425;-> 6
426
427(callable-data (callable-reverse lst lst))
428;-> (quote (5 4 3 2 1 0 0 1 2 3 4 5))
429
430(callable-data (callable-reverse str str))
431;-> 543210012345
432
433(callable-data (callable-reverse str))
434;-> 543210
435
436(callable-indices even? vec)
437;-> (quote (0 2 4))
438
439(callable-indices odd? pls)
440;-> (quote (1 3 5))
441
442(callable-data (callable-copy lst))
443;-> (quote (0 1 2 3 4 5))
444
445(callable-data (callable-copy vec))
446;-> #(0 1 2 3 4 5)
447
448(callable-data (callable-map add1 vec))
449;-> #(1 2 3 4 5 6)
450
451(callable-data (callable-map add1 pls))
452;-> (quote (1 2 3 4 5 6 . 6))
453
454(callable-for-each print vec)
455;-> (if #f #f)
456
457(callable-data (callable-filter odd? vec))
458;-> #(1 3 5)
459
460(receive (yes no) (callable-filter odd? vec) (list (yes) (no)))
461;-> (quote (#(1 3 5) #(0 2 4)))
462
463(callable-data (callable-append str str str))
464;-> 012345012345012345
465
466(callable-data (callable-append str str str str))
467;-> 012345012345012345012345
468
469(callable-data* pl*)
470;-> (quote (a (b . c)))
471
472(callable-data* lv**)
473;-> (quote (a (b #(c d) e) f))
474
475(callable-data* ns**)
476;-> (quote (0 (1 #(2) 3) 4))
477
478(callable-data* (callable-map* add1 ns**))
479;-> (quote (1 (2 #(3) 4) 5))
480
481(ls* 0)
482;-> (quote a)
483
484((ls* 1) 1)
485;-> (quote c)
486
487(callable-data ((ls* 1) 2 #f))
488;-> (quote ())
489
490(callable? ((ls* 1) 1 2))
491;-> #t
492
493(callable-data ((ls* 1) 1 2))
494;-> (quote (c))
495
496(callable? pl*)
497;-> #t
498
499(callable-data (pl* 1))
500;-> (quote (b . c))
501
502(callable? (pl* 1))
503;-> #t
504
505((pl* 1) 0)
506;-> (quote b)
507
508(callable? ((pl* 1) 1 #f))
509;-> #t
510
511(((pl* 1) 1 #f))
512;-> (quote c)
513
514(callable-data ((pl* 1) 1 #f))
515;-> (quote c)
516
517((lv* 1) 1)
518;-> (quote c)
519
520(callable-data ((lv* 1) 1 2))
521;-> #(c)
522
523((vp* 1) 0)
524;-> (quote b)
525
526(callable? (vp* 1))
527;-> #t
528
529(callable? ((vp* 1) 1 #f))
530;-> #t
531
532(((vp* 1) 1 #f))
533;-> (quote c)
534
535(callable-data ((vp* 1) 1 #f))
536;-> (quote c)
537
538((vs* 1) 0)
539;-> b
540
541((vs* 1) 1)
542;-> c
543
544(callable-data ((vs* 1) 2 #f))
545;->
546
547(lv** 0)
548;-> (quote a)
549
550((lv** 1) 0)
551;-> (quote b)
552
553(((lv** 1) 1) 0)
554;-> (quote c)
555
556(((lv** 1) 1) 1)
557;-> (quote d)
558
559(lv** 2)
560;-> (quote f)
561
562((lv** 1) 2)
563;-> (quote e)
564
565;; add a new sequence type, arrays
566(import arrays)
567
568((sequence-constructors 'ras)
569 array?
570 (lambda (k)
571   (apply array
572          (let loop ((i 0) (result '()))
573            (if (= i k) result (loop (+ i 1) (cons #f result))))))
574 (lambda (arr k) (array-at k arr))
575 (lambda (arr k new) (array-update! k new arr))
576 array-length)
577;-> (if #f #f)
578
579(sequence? (make-array))
580;-> #t
581
582(set! arr (make-callable (array 0 1 2 3)))
583;-> (if #f #f)
584
585(arr 2)
586;-> 2
587
588(array-equal? (callable-data (arr 1 3)) (array 1 2))
589;-> #t
590
591(array-equal? (callable-data (arr 3 #f)) (array 3))
592;-> #t
593
594(array-equal? (callable-data (arr 3 1)) (array 3 2))
595;-> #t
596
597(set! va* (make-callable* (vector 0 (array 1 2 3))))
598;-> (if #f #f)
599
600(set! mva* (callable-map* add1 va*))
601;-> (if #f #f)
602
603(mva* 0)
604;-> 1
605
606((mva* 1) 0)
607;-> 2
608
609(array-equal? (callable-data (mva* 1)) (array 2 3 4))
610;-> #t
611
612(sequence-constructors)
613;-> (if #f #f)
614
615(sequence? (make-array))
616;-> #f
617
618</enscript>
619
620
621== Requirements
622
623None
624
625== Last update
626
627Sep 3, 2020
628
629== Author
630
631Juergen Lorenz
632
633== License
634
635Copyright (c) 2020 , Juergen Lorenz, ju (at) jugilo (dot) de
636All rights reserved.
637
638Redistribution and use in source and binary forms, with or without
639modification, are permitted provided that the following conditions are
640met:
641
642Redistributions of source code must retain the above copyright
643notice, this list of conditions and the following disclaimer.
644
645Redistributions in binary form must reproduce the above copyright
646notice, this list of conditions and the following disclaimer in the
647documentation and/or other materials provided with the distribution.
648Neither the name of the author nor the names of its contributors may be
649used to endorse or promote products derived from this software without
650specific prior written permission.
651 
652THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
653IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
654TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
655PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
656HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
657SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
658TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
659PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
660LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
661NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
662SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
663
664== Version history
665
666; 1.2 : some sequenece operations added
667; 1.1 : make-callable* added, a recursive version of make-callable
668; 1.0.0 : initial version
Note: See TracBrowser for help on using the repository browser.