source: project/wiki/Unit extras @ 8154

Last change on this file since 8154 was 8154, checked in by Kon Lovett, 12 years ago

Docu for SRFI-90-ish hash-table.

File size: 23.8 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit extras
5
6This unit contains a collection of useful utility definitions.
7This unit is used by default, unless the program
8is compiled with the {{-explicit-use}} option.
9
10
11=== Lists
12
13
14==== alist-ref
15
16 [procedure] (alist-ref KEY ALIST [TEST [DEFAULT]])
17
18Looks up {{KEY}} in {{ALIST}} using {{TEST}} as the comparison function (or {{eqv?}} if
19no test was given) and returns the cdr of the found pair, or {{DEFAULT}} (which defaults to {{#f}}).
20
21
22==== alist-update!
23
24 [procedure] (alist-update! KEY VALUE ALIST [TEST])
25
26If the list {{ALIST}} contains a pair of the form {{(KEY . X)}}, then this procedure
27replaces {{X}} with {{VALUE}} and returns {{ALIST}}. If {{ALIST}} contains no such item, then
28{{alist-update!}} returns {{((KEY . VALUE) . ALIST)}}. The optional argument
29{{TEST}} specifies the comparison procedure to search a matching pair in {{ALIST}}
30and defaults to {{eqv?}}.
31
32
33==== atom?
34
35 [procedure] (atom? X)
36
37Returns {{#t}} if {{X}} is not a pair. This is identical to {{not-pair?}} from [[Unit srfi-1]] but
38kept for historical reasons.
39
40
41==== rassoc
42
43 [procedure] (rassoc KEY LIST [TEST])
44
45Similar to {{assoc}}, but compares {{KEY}} with the {{cdr}} of each pair in {{LIST}} using
46{{TEST}} as the comparison procedures (which defaults to {{eqv?}}.
47
48
49==== butlast
50
51 [procedure] (butlast LIST)
52
53Returns a fresh list with all elements but the last of {{LIST}}.
54
55
56==== chop
57
58 [procedure] (chop LIST N)
59
60Returns a new list of sublists, where each sublist contains {{N}}
61elements of {{LIST}}. If {{LIST}} has a length that is not
62a multiple of {{N}}, then the last sublist contains the remaining
63elements.
64
65<enscript highlight=scheme>
66(chop '(1 2 3 4 5 6) 2) ==> ((1 2) (3 4) (5 6))
67(chop '(a b c d) 3)     ==> ((a b c) (d))
68</enscript>
69
70
71
72==== compress
73
74 [procedure] (compress BLIST LIST)
75
76Returns a new list with elements taken from {{LIST}} with
77corresponding true values in the list {{BLIST}}.
78
79<enscript highlight=scheme>
80(define nums '(99 100 110 401 1234))
81(compress (map odd? nums) nums)      ==> (99 401)
82</enscript>
83
84
85==== flatten
86
87 [procedure] (flatten LIST1 ...)
88
89Returns {{LIST1 ...}} concatenated together, with nested lists
90removed (flattened).
91
92
93==== intersperse
94
95 [procedure] (intersperse LIST X)
96
97Returns a new list with {{X}} placed between each element.
98
99
100==== join
101
102 [procedure] (join LISTOFLISTS [LIST])
103
104Concatenates the lists in {{LISTOFLISTS}} with {{LIST}} placed
105between each sublist. {{LIST}} defaults to the empty list.
106
107<enscript highlight=scheme>
108(join '((a b) (c d) (e)) '(x y)) ==> (a b x y c d x y e)
109(join '((p q) () (r (s) t)) '(-))  ==> (p q - - r (s) t)
110</enscript>
111
112{{join}} could be implemented as follows:
113
114<enscript highlight=scheme>
115(define (join lstoflsts #!optional (lst '()))
116  (apply append (intersperse lstoflists lst)) )
117</enscript>
118
119
120==== shuffle
121
122 [procedure] (shuffle LIST)
123
124Returns {{LIST}} with its elements sorted in a random order.
125
126
127==== tail?
128
129 [procedure] (tail? X LIST)
130
131Returns true if {{X}} is one of the tails (cdr's) of {{LIST}}.
132
133
134
135=== String-port extensions
136
137
138==== call-with-input-string
139
140 [procedure] (call-with-input-string STRING PROC)
141
142Calls the procedure {{PROC}} with a single argument that is a
143string-input-port with the contents of {{STRING}}.
144
145
146==== call-with-output-string
147
148 [procedure] (call-with-output-string PROC)
149
150Calls the procedure {{PROC}} with a single argument that is a
151string-output-port.  Returns the accumulated output-string.
152
153
154==== with-input-from-string
155
156 [procedure] (with-input-from-string STRING THUNK)
157
158Call procedure {{THUNK}} with the current input-port temporarily
159bound to an input-string-port with the contents of {{STRING}}.
160
161
162==== with-output-to-string
163
164 [procedure] (with-output-to-string THUNK)
165
166Call procedure {{THUNK}} with the current output-port temporarily
167bound to a string-output-port and return the accumulated output string.
168
169
170
171=== Formatted output
172
173
174==== printf
175==== fprintf
176==== sprintf
177
178 [procedure] (fprintf PORT FORMATSTRING ARG ...)
179 [procedure] (printf FORMATSTRING ARG ...)
180 [procedure] (sprintf FORMATSTRING ARG ...)
181
182Simple formatted output to a given port ({{fprintf}}), the
183value of {{(current-output-port)}} ({{printf}}), or a string
184({{sprintf}}).  The {{FORMATSTRING}} can contain any sequence
185of characters.  There must be at least as many {{ARG}} arguments given as there are format directives that require an argument in {{FORMATSTRING}}.  Extra {{ARG}} arguments are ignored.  The character `~' prefixes special formatting directives:
186
187<table>
188<tr><td> ~%
189write newline character
190</td></tr><tr><td> ~N
191the same as {{~%}}
192</td></tr><tr><td> ~S
193write the next argument
194</td></tr><tr><td> ~A
195display the next argument
196</td></tr><tr><td> ~\n
197skip all whitespace in the format-string until the next non-whitespace character
198</td></tr><tr><td> ~B
199write the next argument as a binary number
200</td></tr><tr><td> ~O
201write the next argument as an octal number
202</td></tr><tr><td> ~X
203write the next argument as a hexadecimal number
204</td></tr><tr><td> ~C
205write the next argument as a character
206</td></tr><tr><td> ~~
207display `~'
208</td></tr><tr><td> ~!
209flush all pending output
210</td></tr><tr><td> ~?
211invoke formatted output routine recursively with the next two arguments as format-string and list of parameters
212</td></tr></table>
213
214
215==== format
216
217 [procedure] (format [DESTINATION] FORMATSTRING ARG ...)
218
219The parameters  {{FORMATSTRING}} and {{ARG ...}} are as for
220({{printf}}/{{sprintf}}/{{fprintf}}).
221
222The optional {{DESTINATION}}, when supplied, performs
223a ({{sprintf}}) for a  {{#f}},
224a ({{printf}}) for a {{#t}},
225and a ({{fprintf}}) for an output-port.
226When missing a ({{sprintf}}) is performed.
227
228
229
230=== Hash tables
231
232CHICKEN implements SRFI-69. For more information,
233see [[http://srfi.schemers.org/srfi-69/srfi-69.html|SRFI-69]].
234
235A setter for {{hash-table-ref}} is defined, so
236
237<enscript highlight=scheme>
238(set! (hash-table-ref HT KEY) VAL)
239</enscript>
240
241is equivalent to
242
243<enscript highlight=scheme>
244(hash-table-set! HT KEY VAL)
245</enscript>
246
247As an extension to SRFI-69, {{hash-table-update!}} and {{hash-table-update!/default}} return
248the new value (after applying the update procedure).
249
250==== make-hash-table
251
252 [procedure] (make-hash-table [TEST [HASH [SIZE]]] [#:TEST #:HASH #:SIZE #:INITIAL #:MIN-LOAD #:MAX-LOAD #:WEAK-KEYS #:WEAK-VALUES])
253
254Returns a new {{HASH-TABLE}}, parameterized as follows:
255
256{{TEST}} is a procedure of one argument, {{(scheme-object -> boolean)}}; an equality predicate.
257
258{{HASH}} is a procedure of two arguments, {{(scheme-object (positive number) -> fixnum)}}; a bounded hash function.
259
260{{SIZE}} is a {{fixnum}}; the initial size of the hash-table.
261
262{{INITIAL}} is a {{scheme-object}}; the default initial value for any {{KEY}}.
263
264{{MIN-LOAD}} is an {{flonum}} in {{(0.0 1.0)}}; the lower bound for resizing the table.
265
266{{MAX-LOAD}} is an {{flonum}} in {{(0.0 1.0)}}; the upper bound for resizing the table.
267
268{{WEAK-KEYS}} is an {{boolean}}; always {{#f}} (until further notice).
269
270{{WEAK-VALUES}} is an {{boolean}}; always {{#f}} (until further notice).
271
272{{Note}} - Keyword arguments take precedence over optional arguments.
273
274==== hash-table-min-load
275
276 [procedure] (hash-table-min-load HASH-TABLE)
277
278Returns the {{MIN-LOAD}} property of the {{HASH-TABLE}}.
279
280==== hash-table-max-load
281
282 [procedure] (hash-table-max-load HASH-TABLE)
283
284Returns the {{MAX-LOAD}} property of the {{HASH-TABLE}}.
285
286==== hash-table-weak-keys
287
288 [procedure] (hash-table-weak-keys HASH-TABLE)
289
290Returns the {{WEAK-KEYS}} property of the {{HASH-TABLE}}.
291
292==== hash-table-weak-values
293
294 [procedure] (hash-table-weak-values HASH-TABLE)
295
296Returns the {{WEAK-VALUES}} property of the {{HASH-TABLE}}.
297
298==== hash-table-has-initial
299
300 [procedure] (hash-table-has-initial HASH-TABLE)
301
302Does the {{HASH-TABLE}} have an {{INITIAL}} property.
303
304==== hash-table-initial
305
306 [procedure] (hash-table-initial HASH-TABLE)
307
308Returns the {{INITIAL}} property of the {{HASH-TABLE}}.
309
310==== hash-table-remove!
311
312 [procedure] (hash-table-remove! HASH-TABLE PROC)
313
314Calls {{PROC}} for all entries in {{HASH-TABLE}} with the key and value of each
315entry. If {{PROC}} returns true, then that entry is removed.
316
317==== hash-table-fold
318
319 [procedure] (hash-table-fold HASH-TABLE PROC INIT)
320
321Applies the {{PROC}} to every {{KEY}}/{{VALUE}} pair in the {{HASH-TABLE}}.
322
323{{PROC}} is a procedure of 3 arguments, {{(object object object -> object)}};
324the first argument is the {{KEY}}, the second argument is the {{VALUE}}, and
325the third argument is the current accumulated value. The return value becomes
326the new accumulated value.
327
328Returns the final accumulated value.
329
330==== hash-table-map
331
332 [procedure] (hash-table-map HASH-TABLE PROC)
333
334Applies the {{PROC}} to every {{KEY}}/{{VALUE}} pair in the {{HASH-TABLE}}.
335
336{{PROC}} is a procedure of 2 arguments, {{(object object -> object)}}; the
337first argument is the {{KEY}}, and the second argument is the {{VALUE}}. The
338return value is collected in a list.
339
340Returns the list collection.
341
342==== hash-table-for-each
343
344 [procedure] (hash-table-for-each HASH-TABLE PROC)
345
346Applies the {{PROC}} to every {{KEY}}/{{VALUE}} pair in the {{HASH-TABLE}}.
347
348{{PROC}} is a procedure of 2 arguments, {{(object object -> void)}}; the first
349argument is the {{KEY}}, and the second argument is the {{VALUE}}.
350
351No return value.
352
353
354=== Queues
355
356
357==== list->queue
358
359 [procedure] (list->queue LIST)
360
361Returns {{LIST}} converted into a queue, where the first element
362of the list is the same as the first element of the queue. The resulting
363queue may share memory with the list and the list should not be modified
364after this operation.
365
366
367==== make-queue
368
369 [procedure] (make-queue)
370
371Returns a newly created queue.
372
373
374==== queue?
375
376 [procedure] (queue? X)
377
378Returns {{#t}} if {{X}} is a queue, or {{#f}} otherwise.
379
380
381==== queue->list
382
383 [procedure] (queue->list QUEUE)
384
385Returns {{QUEUE}} converted into a list, where the first element
386of the list is the same as the first element of the queue. The resulting
387list may share memory with the queue object and should not be modified.
388
389
390==== queue-add!
391
392 [procedure] (queue-add! QUEUE X)
393
394Adds {{X}} to the rear of {{QUEUE}}.
395
396
397==== queue-empty?
398
399 [procedure] (queue-empty? QUEUE)
400
401Returns {{#t}} if {{QUEUE}} is empty, or {{#f}} otherwise.
402
403
404==== queue-first
405
406 [procedure] (queue-first QUEUE)
407
408Returns the first element of {{QUEUE}}. If {{QUEUE}} is empty
409an error is signaled
410
411
412==== queue-last
413
414 [procedure] (queue-last QUEUE)
415
416Returns the last element of {{QUEUE}}. If {{QUEUE}} is empty
417an error is signaled
418
419
420==== queue-remove!
421
422 [procedure] (queue-remove! QUEUE)
423
424Removes and returns the first element of {{QUEUE}}. If {{QUEUE}}
425is empty an error is signaled
426
427
428==== queue-push-back!
429
430 [procedure] (queue-push-back! QUEUE ITEM)
431
432Pushes an item into the first position of a queue, i.e. the next
433{{queue-remove!}} will return {{ITEM}}.
434
435
436==== queue-push-back-list!
437
438 [procedure] (queue-push-back-list! QUEUE LIST)
439
440Pushes the items in item-list back onto the queue,
441so that {{(car LIST)}} becomes the next removable item.
442
443
444
445=== Sorting
446
447
448==== merge
449
450 [procedure] (merge LIST1 LIST2 LESS?)
451 [procedure] (merge! LIST1 LIST2 LESS?)
452
453Joins two lists in sorted order. {{merge!}} is the destructive
454version of merge. {{LESS?  }} should be a procedure of two arguments,
455that returns true if the first argument is to be ordered before the
456second argument.
457
458
459==== sort
460
461 [procedure] (sort SEQUENCE LESS?)
462 [procedure] (sort! SEQUENCE LESS?)
463
464Sort {{SEQUENCE}}, which should be a list or a vector. {{sort!}}
465is the destructive version of sort.
466
467
468==== sorted?
469
470 [procedure] (sorted? SEQUENCE LESS?)
471
472Returns true if the list or vector {{SEQUENCE}} is already sorted.
473
474
475
476=== Random numbers
477
478
479==== random
480
481 [procedure] (random N)
482
483Returns an exact random integer from 0 to {{N}}-1.
484
485
486==== randomize
487
488 [procedure] (randomize [X])
489
490Set random-number seed. If {{X}} is not supplied, the current time is used.
491On startup (when the {{extras}} unit is initialized), the random number generator
492is initialized with the current time.
493
494
495
496=== Input/Output extensions
497
498
499==== make-input-port
500
501 [procedure] (make-input-port READ READY? CLOSE [PEEK])
502
503Returns a custom input port. Common operations on this
504port are handled by the given parameters, which should be
505procedures of no arguments. {{READ}} is called when the
506next character is to be read and should return a character or
507{{#!eof}}. {{READY?}} is called
508when {{char-ready?}} is called on this port and should return
509{{#t}} or {{#f}}.  {{CLOSE}} is called when the port is
510closed. {{PEEK}} is called when {{peek-char}} is called on this
511port and should return a character or {{#!eof}}.
512if the argument {{PEEK}} is not given, then {{READ}} is used
513instead and the created port object handles peeking automatically (by
514calling {{READ}} and buffering the character).
515
516
517==== make-output-port
518
519 [procedure] (make-output-port WRITE CLOSE [FLUSH])
520
521Returns a custom output port. Common operations on this port are handled
522by the given parameters, which should be procedures.  {{WRITE}} is
523called when output is sent to the port and receives a single argument,
524a string.  {{CLOSE}} is called when the port is closed and should
525be a procedure of no arguments. {{FLUSH}} (if provided) is called
526for flushing the output port.
527
528
529==== pretty-print
530
531 [procedure] (pretty-print EXP [PORT])
532 [procedure] (pp EXP [PORT])
533
534Print expression nicely formatted. {{PORT}} defaults to the value
535of {{(current-output-port)}}.
536
537
538==== pretty-print-width
539(Parameter) Specifies the maximal line-width for pretty printing, after which line
540wrap will occur.
541
542==== read-byte
543==== write-byte
544
545 [procedure] (read-byte [PORT])
546 [procedure] (write-byte BYTE [PORT])
547
548Read/write a byte to the port given in {{PORT}}, which default to the values
549of {{(current-input-port)}} and {{(current-output-port)}}, respectively.
550
551==== read-file
552
553 [procedure] (read-file [FILE-OR-PORT [READER [MAXCOUNT]]])
554
555Returns a list containing all toplevel expressions
556read from the file or port {{FILE-OR-PORT}}. If no argument is given,
557input is read from the port that is the current value of {{(current-input-port)}}.
558After all expressions are read, and if the argument is a port, then the port will
559not be closed. The {{READER}} argument specifies the procedure used to read
560expressions from the given file or port and defaults to {{read}}. The reader
561procedure will be called with a single argument (an input port).
562If {{MAXCOUNT}} is given then only up to {{MAXCOUNT}} expressions will be read in.
563
564
565==== read-line
566==== write-line
567
568 [procedure] (read-line [PORT [LIMIT]])
569 [procedure] (write-line STRING [PORT])
570
571Line-input and -output. {{PORT}} defaults to the value of
572{{(current-input-port)}} and {{(current-output-port)}},
573respectively. If the optional argument {{LIMIT}} is given and
574not {{#f}}, then {{read-line}} reads at most {{LIMIT}}
575characters per line. {{read-line}} returns a string without the terminating newline and {{write-line}} adds a terminating newline  before outputting.
576
577
578==== read-lines
579
580 [procedure] (read-lines [PORT [MAX]])
581
582Read {{MAX}} or fewer lines from {{PORT}}. {{PORT}}
583defaults to the value of {{(current-input-port)}}. {{PORT}} may optionally be
584a string naming a file. Returns a list of strings, each string representing a line read, not including any line separation character(s).
585
586
587==== read-string
588==== read-string!
589==== write-string
590
591 [procedure] (read-string [NUM [PORT]])
592 [procedure] (read-string! NUM STRING [PORT [START]])
593 [procedure] (write-string STRING [NUM [PORT]]
594
595Read or write {{NUM}} characters from/to {{PORT}}, which defaults to the
596value of {{(current-input-port)}} or {{(current-output-port)}}, respectively.
597If {{NUM}} is {{#f}} or not given, then all data
598up to the end-of-file is read, or, in the case of {{write-string}} the whole
599string is written. If no more input is available, {{read-string}} returns the
600empty string. {{read-string!}} reads destructively into the given {{STRING}} argument,
601but never more characters that would fit into {{STRING}}. If {{START}} is given, then
602the read characters are stored starting at that position.
603{{read-string!}} returns the actual number of characters read.
604
605
606==== read-token
607
608 [procedure] (read-token PREDICATE [PORT])
609
610Reads characters from {{PORT}} (which defaults to the value of {{(current-input-port)}})
611and calls the procedure {{PREDICATE}} with each character until {{PREDICATE}} returns
612false. Returns a string with the accumulated characters.
613
614
615==== with-error-output-to-port
616
617 [procedure] (with-error-output-to-port PORT THUNK)
618
619Call procedure {{THUNK}} with the current error output-port
620temporarily bound to {{PORT}}.
621
622
623==== with-input-from-port
624
625 [procedure] (with-input-from-port PORT THUNK)
626
627Call procedure {{THUNK}} with the current input-port temporarily
628bound to {{PORT}}.
629
630
631==== with-output-to-port
632
633 [procedure] (with-output-to-port PORT THUNK)
634
635Call procedure {{THUNK}} with the current output-port temporarily
636bound to {{PORT}}.
637
638
639
640=== Strings
641
642
643==== conc
644
645 [procedure] (conc X ...)
646
647Returns a string with the string-represenation of all arguments concatenated
648together. {{conc}} could be implemented as
649
650<enscript highlight=scheme>
651(define (conc . args)
652  (apply string-append (map ->string args)) )
653</enscript>
654
655
656
657==== ->string
658
659 [procedure] (->string X)
660
661Returns a string-representation of {{X}}.
662
663
664==== string-chop
665
666 [procedure] (string-chop STRING LENGTH)
667
668Returns a list of substrings taken by ''chopping'' {{STRING}} every {{LENGTH}}
669characters:
670
671<enscript highlight=scheme>
672(string-chop "one two three" 4)  ==>  ("one " "two " "thre" "e")
673</enscript>
674
675
676
677==== string-chomp
678
679 [procedure] (string-chomp STRING [SUFFIX])
680
681If {{STRING}} ends with {{SUFFIX}}, then this procedure returns a copy of its first argument with the suffix
682removed, otherwise returns {{STRING}} unchanged. {{SUFFIX}} defaults to {{"\n"}}.
683
684
685==== string-compare3
686
687 [procedure] (string-compare3 STRING1 STRING2)
688 [procedure] (string-compare3-ci STRING1 STRING2)
689
690Perform a three-way comparison between the {{STRING1}} and {{STRING2}},
691returning either {{-1}} if {{STRING1}} is lexicographically less
692than {{STRING2}}, {{0}} if it is equal, or {{1}} if it s greater.
693{{string-compare3-ci}} performs a case-insensitive comparison.
694
695
696==== string-intersperse
697
698 [procedure] (string-intersperse LIST [STRING])
699
700Returns a string that contains all strings in {{LIST}} concatenated
701together.  {{STRING}} is placed between each concatenated string and
702defaults to {{" "}}.
703
704<enscript highlight=scheme>
705(string-intersperse '("one" "two") "three")
706</enscript>
707
708is equivalent to
709
710<enscript highlight=scheme>
711(apply string-append (intersperse '("one" "two") "three"))
712</enscript>
713
714
715==== string-split
716
717 [procedure] (string-split STRING [DELIMITER-STRING [KEEPEMPTY]])
718
719Split string into substrings separated by the given delimiters. If
720no delimiters are specified, a string comprising the tab, newline and space characters
721is assumed. If the
722parameter {{KEEPEMPTY}} is given and not {{#f}}, then empty
723substrings are retained:
724
725<enscript highlight=scheme>
726(string-split "one  two  three") ==> ("one" "two" "three")
727(string-split "foo:bar::baz:" ":" #t) ==> ("foo" "bar" "" "baz" "")
728</enscript>
729
730
731==== string-translate
732
733 [procedure] (string-translate STRING FROM [TO])
734
735Returns a fresh copy of {{STRING}} with characters matching
736{{FROM}} translated to {{TO}}.  If {{TO}} is omitted, then
737matching characters are removed. {{FROM}} and {{TO}} may be
738a character, a string or a list. If both {{FROM}} and {{TO}}
739are strings, then the character at the same position in {{TO}}
740as the matching character in {{FROM}} is substituted.
741
742
743==== string-translate*
744
745 [procedure] (string-translate* STRING SMAP)
746
747Substitutes elements of {{STRING}} according to {{SMAP}}.
748{{SMAP}} should be an association-list where each element of the list
749is a pair of the form {{(MATCH \. REPLACEMENT)}}. Every occurrence of
750the string {{MATCH}} in {{STRING}} will be replaced by the string
751{{REPLACEMENT}}:
752
753<enscript highlight=scheme>
754(string-translate*
755  "<h1>this is a \"string\"</h1>"
756  '(("<" . "&lt;") (">" . "&gt;") ("\"" . "&quot;")) )
757=>  "&lt;h1&gt;this is a &quot;string&quot;&lt;/ht&gt;"
758</enscript>
759
760
761==== substring=?
762
763 [procedure] (substring=? STRING1 STRING2 [START1 [START2 [LENGTH]]])
764 [procedure] (substring-ci=? STRING1 STRING2 [START1 [START2 [LENGTH]]])
765
766Returns {{#t}} if the strings {{STRING1}} and {{STRING2}} are equal, or
767{{#f}} otherwise.
768The comparison starts at the positions {{START1}} and {{START2}} (which default
769to 0), comparing {{LENGTH}} characters (which defaults to the minimum of the remaining
770length of both strings).
771
772
773==== substring-index
774
775 [procedure] (substring-index WHICH WHERE [START])
776 [procedure] (substring-index-ci WHICH WHERE [START])
777
778Searches for first index in string {{WHERE}} where string
779{{WHICH}} occurs.  If the optional argument {{START}} is given,
780then the search starts at that index.  {{substring-index-ci}}
781is a case-insensitive version of {{substring-index}}.
782
783
784
785=== Combinators
786
787
788==== any?
789
790 [procedure] (any? X)
791
792Ignores its argument and always returns {{#t}}. This is actually useful sometimes.
793
794
795==== constantly
796
797 [procedure] (constantly X ...)
798
799Returns a procedure that always returns the values {{X ...}} regardless of the number and value of its arguments.
800
801<enscript highlight=scheme>
802(constantly X) <=> (lambda args X)
803</enscript>
804
805
806==== complement
807
808 [procedure] (complement PROC)
809
810Returns a procedure that returns the boolean inverse of {{PROC}}.
811
812<enscript highlight=scheme>
813(complement PROC) <=> (lambda (x) (not (PROC x)))
814</enscript>
815
816
817==== compose
818
819 [procedure] (compose PROC1 PROC2 ...)
820
821Returns a procedure that represents the composition of the
822argument-procedures {{PROC1 PROC2 ...}}.
823
824<enscript highlight=scheme>
825(compose F G) <=> (lambda args
826                      (call-with-values
827                         (lambda () (apply G args))
828                         F))
829</enscript>
830
831{{(compose)}} is equivalent to {{values}}.
832
833
834==== conjoin
835
836 [procedure] (conjoin PRED ...)
837
838Returns a procedure that returns {{#t}} if its argument satisfies the
839predicates {{PRED ...}}.
840<enscript highlight=scheme>
841((conjoin odd? positive?) 33)   ==>  #t
842((conjoin odd? positive?) -33)  ==>  #f
843</enscript>
844
845
846==== disjoin
847
848 [procedure] (disjoin PRED ...)
849
850Returns a procedure that returns {{#t}} if its argument satisfies any
851predicate {{PRED ...}}.
852<enscript highlight=scheme>
853((disjoin odd? positive?) 32)    ==>  #t
854((disjoin odd? positive?) -32)   ==>  #f
855</enscript>
856
857
858
859==== each
860
861 [procedure] (each PROC ...)
862
863Returns a procedure that applies {{PROC ...}} to its arguments, and returns the result(s)
864of the last procedure application. For example
865
866<enscript highlight=scheme>
867(each pp eval)
868</enscript>
869
870is equivalent to
871
872<enscript highlight=scheme>
873(lambda args
874  (apply pp args)
875  (apply eval args) )
876</enscript>
877
878{{(each PROC)}} is equivalent to {{PROC}} and {{(each)}} is equivalent to
879{{noop}}.
880
881
882==== flip
883
884 [procedure] (flip PROC)
885
886Returns a two-argument procedure that calls {{PROC}} with its
887arguments swapped:
888<enscript highlight=scheme>
889(flip PROC) <=> (lambda (x y) (PROC y x))
890</enscript>
891
892
893==== identity
894
895 [procedure] (identity X)
896
897Returns its sole argument {{X}}.
898
899
900==== project
901
902 [procedure] (project N)
903
904Returns a procedure that returns its {{N}}th argument (starting from 0).
905
906
907==== list-of
908
909 [procedure] (list-of PRED)
910
911Returns a procedure of one argument that returns {{#t}} when
912applied to a list of elements that all satisfy the predicate procedure
913{{PRED}}, or {{#f}} otherwise.
914
915<enscript highlight=scheme>
916((list-of even?) '(1 2 3))   ==> #f
917((list-of number?) '(1 2 3)) ==> #t
918</enscript>
919
920
921==== noop
922
923 [procedure] (noop X ...)
924
925Ignores it's arguments, does nothing and returns an unspecified value.
926
927
928==== o
929
930 [procedure] (o PROC ...)
931
932A single value version of {{compose}} (slightly faster). {{(o)}} is equivalent
933to {{identity}}.
934
935=== Binary searching
936
937
938==== binary-search
939
940 [procedure] (binary-search SEQUENCE PROC)
941
942Performs a binary search in {{SEQUENCE}}, which should be a sorted
943list or vector.  {{PROC}} is called to compare items in the sequence,
944should accept a single argument and return an exact integer: zero if the
945searched value is equal to the current item, negative if the searched
946value is ''less'' than the current item, and positive otherwise.
947Returns the index of the found value or {{#f}} otherwise.
948
949Previous: [[Unit eval]]
950
951Next: [[Unit srfi-1]]
Note: See TracBrowser for help on using the repository browser.