source: project/chicken/branches/prerelease/manual/Unit extras @ 9381

Last change on this file since 9381 was 9381, checked in by Ivan Raikov, 12 years ago

Merged trunk into prerelease

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