source: project/wiki/Unit extras @ 8312

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

Added left & right section. Simple but useful.

File size: 24.7 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-update!
311
312 [procedure] (hash-table-update! HASH-TABLE KEY [FUNCTION [THUNK]])
313
314The SRFI-69 procedure is extended to allow a default procedure for
315{{FUNCTION}}, the default is {{identity}}.
316
317==== hash-table-remove!
318
319 [procedure] (hash-table-remove! HASH-TABLE PROC)
320
321Calls {{PROC}} for all entries in {{HASH-TABLE}} with the key and value of each
322entry. If {{PROC}} returns true, then that entry is removed.
323
324==== hash-table-merge
325
326 [procedure] (hash-table-merge HASH-TABLE-1 HASH-TABLE-2)
327
328Returns a new {{hash-table}}, the merged result of {{HASH-TABLE-1}} &
329{{HASH-TABLE-2}}.
330
331==== hash-table-fold
332
333 [procedure] (hash-table-fold HASH-TABLE PROC INIT)
334
335Applies the {{PROC}} to every {{KEY}}/{{VALUE}} pair in the {{HASH-TABLE}}.
336
337{{PROC}} is a procedure of 3 arguments, {{(object object object -> object)}};
338the first argument is the {{KEY}}, the second argument is the {{VALUE}}, and
339the third argument is the current accumulated value. The return value becomes
340the new accumulated value.
341
342Returns the final accumulated value.
343
344==== hash-table-map
345
346 [procedure] (hash-table-map HASH-TABLE PROC)
347
348Applies the {{PROC}} to every {{KEY}}/{{VALUE}} pair in the {{HASH-TABLE}}.
349
350{{PROC}} is a procedure of 2 arguments, {{(object object -> object)}}; the
351first argument is the {{KEY}}, and the second argument is the {{VALUE}}. The
352return value is collected in a list.
353
354Returns the list collection.
355
356==== hash-table-for-each
357
358 [procedure] (hash-table-for-each HASH-TABLE PROC)
359
360Applies the {{PROC}} to every {{KEY}}/{{VALUE}} pair in the {{HASH-TABLE}}.
361
362{{PROC}} is a procedure of 2 arguments, {{(object object -> void)}}; the first
363argument is the {{KEY}}, and the second argument is the {{VALUE}}.
364
365No return value.
366
367
368=== Queues
369
370
371==== list->queue
372
373 [procedure] (list->queue LIST)
374
375Returns {{LIST}} converted into a queue, where the first element
376of the list is the same as the first element of the queue. The resulting
377queue may share memory with the list and the list should not be modified
378after this operation.
379
380
381==== make-queue
382
383 [procedure] (make-queue)
384
385Returns a newly created queue.
386
387
388==== queue?
389
390 [procedure] (queue? X)
391
392Returns {{#t}} if {{X}} is a queue, or {{#f}} otherwise.
393
394
395==== queue->list
396
397 [procedure] (queue->list QUEUE)
398
399Returns {{QUEUE}} converted into a list, where the first element
400of the list is the same as the first element of the queue. The resulting
401list may share memory with the queue object and should not be modified.
402
403
404==== queue-add!
405
406 [procedure] (queue-add! QUEUE X)
407
408Adds {{X}} to the rear of {{QUEUE}}.
409
410
411==== queue-empty?
412
413 [procedure] (queue-empty? QUEUE)
414
415Returns {{#t}} if {{QUEUE}} is empty, or {{#f}} otherwise.
416
417
418==== queue-first
419
420 [procedure] (queue-first QUEUE)
421
422Returns the first element of {{QUEUE}}. If {{QUEUE}} is empty
423an error is signaled
424
425
426==== queue-last
427
428 [procedure] (queue-last QUEUE)
429
430Returns the last element of {{QUEUE}}. If {{QUEUE}} is empty
431an error is signaled
432
433
434==== queue-remove!
435
436 [procedure] (queue-remove! QUEUE)
437
438Removes and returns the first element of {{QUEUE}}. If {{QUEUE}}
439is empty an error is signaled
440
441
442==== queue-push-back!
443
444 [procedure] (queue-push-back! QUEUE ITEM)
445
446Pushes an item into the first position of a queue, i.e. the next
447{{queue-remove!}} will return {{ITEM}}.
448
449
450==== queue-push-back-list!
451
452 [procedure] (queue-push-back-list! QUEUE LIST)
453
454Pushes the items in item-list back onto the queue,
455so that {{(car LIST)}} becomes the next removable item.
456
457
458
459=== Sorting
460
461
462==== merge
463
464 [procedure] (merge LIST1 LIST2 LESS?)
465 [procedure] (merge! LIST1 LIST2 LESS?)
466
467Joins two lists in sorted order. {{merge!}} is the destructive
468version of merge. {{LESS?  }} should be a procedure of two arguments,
469that returns true if the first argument is to be ordered before the
470second argument.
471
472
473==== sort
474
475 [procedure] (sort SEQUENCE LESS?)
476 [procedure] (sort! SEQUENCE LESS?)
477
478Sort {{SEQUENCE}}, which should be a list or a vector. {{sort!}}
479is the destructive version of sort.
480
481
482==== sorted?
483
484 [procedure] (sorted? SEQUENCE LESS?)
485
486Returns true if the list or vector {{SEQUENCE}} is already sorted.
487
488
489
490=== Random numbers
491
492
493==== random
494
495 [procedure] (random N)
496
497Returns an exact random integer from 0 to {{N}}-1.
498
499
500==== randomize
501
502 [procedure] (randomize [X])
503
504Set random-number seed. If {{X}} is not supplied, the current time is used.
505On startup (when the {{extras}} unit is initialized), the random number generator
506is initialized with the current time.
507
508
509
510=== Input/Output extensions
511
512
513==== make-input-port
514
515 [procedure] (make-input-port READ READY? CLOSE [PEEK])
516
517Returns a custom input port. Common operations on this
518port are handled by the given parameters, which should be
519procedures of no arguments. {{READ}} is called when the
520next character is to be read and should return a character or
521{{#!eof}}. {{READY?}} is called
522when {{char-ready?}} is called on this port and should return
523{{#t}} or {{#f}}.  {{CLOSE}} is called when the port is
524closed. {{PEEK}} is called when {{peek-char}} is called on this
525port and should return a character or {{#!eof}}.
526if the argument {{PEEK}} is not given, then {{READ}} is used
527instead and the created port object handles peeking automatically (by
528calling {{READ}} and buffering the character).
529
530
531==== make-output-port
532
533 [procedure] (make-output-port WRITE CLOSE [FLUSH])
534
535Returns a custom output port. Common operations on this port are handled
536by the given parameters, which should be procedures.  {{WRITE}} is
537called when output is sent to the port and receives a single argument,
538a string.  {{CLOSE}} is called when the port is closed and should
539be a procedure of no arguments. {{FLUSH}} (if provided) is called
540for flushing the output port.
541
542
543==== pretty-print
544
545 [procedure] (pretty-print EXP [PORT])
546 [procedure] (pp EXP [PORT])
547
548Print expression nicely formatted. {{PORT}} defaults to the value
549of {{(current-output-port)}}.
550
551
552==== pretty-print-width
553(Parameter) Specifies the maximal line-width for pretty printing, after which line
554wrap will occur.
555
556==== read-byte
557==== write-byte
558
559 [procedure] (read-byte [PORT])
560 [procedure] (write-byte BYTE [PORT])
561
562Read/write a byte to the port given in {{PORT}}, which default to the values
563of {{(current-input-port)}} and {{(current-output-port)}}, respectively.
564
565==== read-file
566
567 [procedure] (read-file [FILE-OR-PORT [READER [MAXCOUNT]]])
568
569Returns a list containing all toplevel expressions
570read from the file or port {{FILE-OR-PORT}}. If no argument is given,
571input is read from the port that is the current value of {{(current-input-port)}}.
572After all expressions are read, and if the argument is a port, then the port will
573not be closed. The {{READER}} argument specifies the procedure used to read
574expressions from the given file or port and defaults to {{read}}. The reader
575procedure will be called with a single argument (an input port).
576If {{MAXCOUNT}} is given then only up to {{MAXCOUNT}} expressions will be read in.
577
578
579==== read-line
580==== write-line
581
582 [procedure] (read-line [PORT [LIMIT]])
583 [procedure] (write-line STRING [PORT])
584
585Line-input and -output. {{PORT}} defaults to the value of
586{{(current-input-port)}} and {{(current-output-port)}},
587respectively. If the optional argument {{LIMIT}} is given and
588not {{#f}}, then {{read-line}} reads at most {{LIMIT}}
589characters per line. {{read-line}} returns a string without the terminating newline and {{write-line}} adds a terminating newline  before outputting.
590
591
592==== read-lines
593
594 [procedure] (read-lines [PORT [MAX]])
595
596Read {{MAX}} or fewer lines from {{PORT}}. {{PORT}}
597defaults to the value of {{(current-input-port)}}. {{PORT}} may optionally be
598a string naming a file. Returns a list of strings, each string representing a line read, not including any line separation character(s).
599
600
601==== read-string
602==== read-string!
603==== write-string
604
605 [procedure] (read-string [NUM [PORT]])
606 [procedure] (read-string! NUM STRING [PORT [START]])
607 [procedure] (write-string STRING [NUM [PORT]]
608
609Read or write {{NUM}} characters from/to {{PORT}}, which defaults to the
610value of {{(current-input-port)}} or {{(current-output-port)}}, respectively.
611If {{NUM}} is {{#f}} or not given, then all data
612up to the end-of-file is read, or, in the case of {{write-string}} the whole
613string is written. If no more input is available, {{read-string}} returns the
614empty string. {{read-string!}} reads destructively into the given {{STRING}} argument,
615but never more characters that would fit into {{STRING}}. If {{START}} is given, then
616the read characters are stored starting at that position.
617{{read-string!}} returns the actual number of characters read.
618
619
620==== read-token
621
622 [procedure] (read-token PREDICATE [PORT])
623
624Reads characters from {{PORT}} (which defaults to the value of {{(current-input-port)}})
625and calls the procedure {{PREDICATE}} with each character until {{PREDICATE}} returns
626false. Returns a string with the accumulated characters.
627
628
629==== with-error-output-to-port
630
631 [procedure] (with-error-output-to-port PORT THUNK)
632
633Call procedure {{THUNK}} with the current error output-port
634temporarily bound to {{PORT}}.
635
636
637==== with-input-from-port
638
639 [procedure] (with-input-from-port PORT THUNK)
640
641Call procedure {{THUNK}} with the current input-port temporarily
642bound to {{PORT}}.
643
644
645==== with-output-to-port
646
647 [procedure] (with-output-to-port PORT THUNK)
648
649Call procedure {{THUNK}} with the current output-port temporarily
650bound to {{PORT}}.
651
652
653
654=== Strings
655
656
657==== conc
658
659 [procedure] (conc X ...)
660
661Returns a string with the string-represenation of all arguments concatenated
662together. {{conc}} could be implemented as
663
664<enscript highlight=scheme>
665(define (conc . args)
666  (apply string-append (map ->string args)) )
667</enscript>
668
669
670
671==== ->string
672
673 [procedure] (->string X)
674
675Returns a string-representation of {{X}}.
676
677
678==== string-chop
679
680 [procedure] (string-chop STRING LENGTH)
681
682Returns a list of substrings taken by ''chopping'' {{STRING}} every {{LENGTH}}
683characters:
684
685<enscript highlight=scheme>
686(string-chop "one two three" 4)  ==>  ("one " "two " "thre" "e")
687</enscript>
688
689
690
691==== string-chomp
692
693 [procedure] (string-chomp STRING [SUFFIX])
694
695If {{STRING}} ends with {{SUFFIX}}, then this procedure returns a copy of its first argument with the suffix
696removed, otherwise returns {{STRING}} unchanged. {{SUFFIX}} defaults to {{"\n"}}.
697
698
699==== string-compare3
700
701 [procedure] (string-compare3 STRING1 STRING2)
702 [procedure] (string-compare3-ci STRING1 STRING2)
703
704Perform a three-way comparison between the {{STRING1}} and {{STRING2}},
705returning either {{-1}} if {{STRING1}} is lexicographically less
706than {{STRING2}}, {{0}} if it is equal, or {{1}} if it s greater.
707{{string-compare3-ci}} performs a case-insensitive comparison.
708
709
710==== string-intersperse
711
712 [procedure] (string-intersperse LIST [STRING])
713
714Returns a string that contains all strings in {{LIST}} concatenated
715together.  {{STRING}} is placed between each concatenated string and
716defaults to {{" "}}.
717
718<enscript highlight=scheme>
719(string-intersperse '("one" "two") "three")
720</enscript>
721
722is equivalent to
723
724<enscript highlight=scheme>
725(apply string-append (intersperse '("one" "two") "three"))
726</enscript>
727
728
729==== string-split
730
731 [procedure] (string-split STRING [DELIMITER-STRING [KEEPEMPTY]])
732
733Split string into substrings separated by the given delimiters. If
734no delimiters are specified, a string comprising the tab, newline and space characters
735is assumed. If the
736parameter {{KEEPEMPTY}} is given and not {{#f}}, then empty
737substrings are retained:
738
739<enscript highlight=scheme>
740(string-split "one  two  three") ==> ("one" "two" "three")
741(string-split "foo:bar::baz:" ":" #t) ==> ("foo" "bar" "" "baz" "")
742</enscript>
743
744
745==== string-translate
746
747 [procedure] (string-translate STRING FROM [TO])
748
749Returns a fresh copy of {{STRING}} with characters matching
750{{FROM}} translated to {{TO}}.  If {{TO}} is omitted, then
751matching characters are removed. {{FROM}} and {{TO}} may be
752a character, a string or a list. If both {{FROM}} and {{TO}}
753are strings, then the character at the same position in {{TO}}
754as the matching character in {{FROM}} is substituted.
755
756
757==== string-translate*
758
759 [procedure] (string-translate* STRING SMAP)
760
761Substitutes elements of {{STRING}} according to {{SMAP}}.
762{{SMAP}} should be an association-list where each element of the list
763is a pair of the form {{(MATCH \. REPLACEMENT)}}. Every occurrence of
764the string {{MATCH}} in {{STRING}} will be replaced by the string
765{{REPLACEMENT}}:
766
767<enscript highlight=scheme>
768(string-translate*
769  "<h1>this is a \"string\"</h1>"
770  '(("<" . "&lt;") (">" . "&gt;") ("\"" . "&quot;")) )
771=>  "&lt;h1&gt;this is a &quot;string&quot;&lt;/ht&gt;"
772</enscript>
773
774
775==== substring=?
776
777 [procedure] (substring=? STRING1 STRING2 [START1 [START2 [LENGTH]]])
778 [procedure] (substring-ci=? STRING1 STRING2 [START1 [START2 [LENGTH]]])
779
780Returns {{#t}} if the strings {{STRING1}} and {{STRING2}} are equal, or
781{{#f}} otherwise.
782The comparison starts at the positions {{START1}} and {{START2}} (which default
783to 0), comparing {{LENGTH}} characters (which defaults to the minimum of the remaining
784length of both strings).
785
786
787==== substring-index
788
789 [procedure] (substring-index WHICH WHERE [START])
790 [procedure] (substring-index-ci WHICH WHERE [START])
791
792Searches for first index in string {{WHERE}} where string
793{{WHICH}} occurs.  If the optional argument {{START}} is given,
794then the search starts at that index.  {{substring-index-ci}}
795is a case-insensitive version of {{substring-index}}.
796
797
798
799=== Combinators
800
801
802==== any?
803
804 [procedure] (any? X)
805
806Ignores its argument and always returns {{#t}}. This is actually useful sometimes.
807
808
809==== constantly
810
811 [procedure] (constantly X ...)
812
813Returns a procedure that always returns the values {{X ...}} regardless of the number and value of its arguments.
814
815<enscript highlight=scheme>
816(constantly X) <=> (lambda args X)
817</enscript>
818
819
820==== complement
821
822 [procedure] (complement PROC)
823
824Returns a procedure that returns the boolean inverse of {{PROC}}.
825
826<enscript highlight=scheme>
827(complement PROC) <=> (lambda (x) (not (PROC x)))
828</enscript>
829
830
831==== compose
832
833 [procedure] (compose PROC1 PROC2 ...)
834
835Returns a procedure that represents the composition of the
836argument-procedures {{PROC1 PROC2 ...}}.
837
838<enscript highlight=scheme>
839(compose F G) <=> (lambda args
840                      (call-with-values
841                         (lambda () (apply G args))
842                         F))
843</enscript>
844
845{{(compose)}} is equivalent to {{values}}.
846
847
848==== conjoin
849
850 [procedure] (conjoin PRED ...)
851
852Returns a procedure that returns {{#t}} if its argument satisfies the
853predicates {{PRED ...}}.
854<enscript highlight=scheme>
855((conjoin odd? positive?) 33)   ==>  #t
856((conjoin odd? positive?) -33)  ==>  #f
857</enscript>
858
859
860==== disjoin
861
862 [procedure] (disjoin PRED ...)
863
864Returns a procedure that returns {{#t}} if its argument satisfies any
865predicate {{PRED ...}}.
866<enscript highlight=scheme>
867((disjoin odd? positive?) 32)    ==>  #t
868((disjoin odd? positive?) -32)   ==>  #f
869</enscript>
870
871
872==== each
873
874 [procedure] (each PROC ...)
875
876Returns a procedure that applies {{PROC ...}} to its arguments, and returns the result(s)
877of the last procedure application. For example
878
879<enscript highlight=scheme>
880(each pp eval)
881</enscript>
882
883is equivalent to
884
885<enscript highlight=scheme>
886(lambda args
887  (apply pp args)
888  (apply eval args) )
889</enscript>
890
891{{(each PROC)}} is equivalent to {{PROC}} and {{(each)}} is equivalent to
892{{noop}}.
893
894
895==== flip
896
897 [procedure] (flip PROC)
898
899Returns a two-argument procedure that calls {{PROC}} with its
900arguments swapped:
901<enscript highlight=scheme>
902(flip PROC) <=> (lambda (x y) (PROC y x))
903</enscript>
904
905
906==== identity
907
908 [procedure] (identity X)
909
910Returns its sole argument {{X}}.
911
912
913==== project
914
915 [procedure] (project N)
916
917Returns a procedure that returns its {{N}}th argument (starting from 0).
918
919
920==== list-of
921
922 [procedure] (list-of PRED)
923
924Returns a procedure of one argument that returns {{#t}} when
925applied to a list of elements that all satisfy the predicate procedure
926{{PRED}}, or {{#f}} otherwise.
927
928<enscript highlight=scheme>
929((list-of even?) '(1 2 3))   ==> #f
930((list-of number?) '(1 2 3)) ==> #t
931</enscript>
932
933
934==== noop
935
936 [procedure] (noop X ...)
937
938Ignores it's arguments, does nothing and returns an unspecified value.
939
940
941==== o
942
943 [procedure] (o PROC ...)
944
945A single value version of {{compose}} (slightly faster). {{(o)}} is equivalent
946to {{identity}}.
947
948
949==== left-section
950
951 [procedure] (left-section PROC ARG ...)
952
953A left section partially applies arguments starting from the left.
954
955Returns a procedure of varying arity in which some prefix of its arguments,
956{{ARG ...}}, are partially applied to {{PROC}}.
957
958
959==== right-section
960
961 [procedure] (right-section PROC ARG ...)
962
963A right section partially applies arguments starting from the right.
964
965Returns a procedure of varying arity in which some reversed suffix of its
966arguments, {{ARG ...}}, are partially applied to {{PROC}}.
967
968
969=== Binary searching
970
971
972==== binary-search
973
974 [procedure] (binary-search SEQUENCE PROC)
975
976Performs a binary search in {{SEQUENCE}}, which should be a sorted
977list or vector.  {{PROC}} is called to compare items in the sequence,
978should accept a single argument and return an exact integer: zero if the
979searched value is equal to the current item, negative if the searched
980value is ''less'' than the current item, and positive otherwise.
981Returns the index of the found value or {{#f}} otherwise.
982
983Previous: [[Unit eval]]
984
985Next: [[Unit srfi-1]]
Note: See TracBrowser for help on using the repository browser.