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

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

Merged with trunk up to r9887 (dev snapshot 3.0.10).

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