2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000-2004, 2006, 2007-2014
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @section SRFI Support Modules
11 SRFI is an acronym for Scheme Request For Implementation. The SRFI
12 documents define a lot of syntactic and procedure extensions to standard
13 Scheme as defined in R5RS.
15 Guile has support for a number of SRFIs. This chapter gives an overview
16 over the available SRFIs and some usage hints. For complete
17 documentation, design rationales and further examples, we advise you to
18 get the relevant SRFI documents from the SRFI home page
19 @url{http://srfi.schemers.org/}.
22 * About SRFI Usage:: What to know about Guile's SRFI support.
23 * SRFI-0:: cond-expand
24 * SRFI-1:: List library.
26 * SRFI-4:: Homogeneous numeric vector datatypes.
27 * SRFI-6:: Basic String Ports.
29 * SRFI-9:: define-record-type.
30 * SRFI-10:: Hash-Comma Reader Extension.
31 * SRFI-11:: let-values and let*-values.
32 * SRFI-13:: String library.
33 * SRFI-14:: Character-set library.
34 * SRFI-16:: case-lambda
35 * SRFI-17:: Generalized set!
36 * SRFI-18:: Multithreading support
37 * SRFI-19:: Time/Date library.
38 * SRFI-23:: Error reporting
39 * SRFI-26:: Specializing parameters
40 * SRFI-27:: Sources of Random Bits
41 * SRFI-28:: Basic format strings.
42 * SRFI-30:: Nested multi-line block comments
43 * SRFI-31:: A special form `rec' for recursive evaluation
44 * SRFI-34:: Exception handling.
45 * SRFI-35:: Conditions.
46 * SRFI-37:: args-fold program argument processor
47 * SRFI-38:: External Representation for Data With Shared Structure
48 * SRFI-39:: Parameter objects
50 * SRFI-42:: Eager comprehensions
51 * SRFI-43:: Vector Library.
52 * SRFI-45:: Primitives for expressing iterative lazy algorithms
53 * SRFI-46:: Basic syntax-rules Extensions.
54 * SRFI-55:: Requiring Features.
55 * SRFI-60:: Integers as bits.
56 * SRFI-61:: A more general `cond' clause
57 * SRFI-62:: S-expression comments.
58 * SRFI-64:: A Scheme API for test suites.
59 * SRFI-67:: Compare procedures
60 * SRFI-69:: Basic hash tables.
61 * SRFI-87:: => in case clauses.
62 * SRFI-88:: Keyword objects.
63 * SRFI-98:: Accessing environment variables.
64 * SRFI-105:: Curly-infix expressions.
69 @node About SRFI Usage
70 @subsection About SRFI Usage
72 @c FIXME::martin: Review me!
74 SRFI support in Guile is currently implemented partly in the core
75 library, and partly as add-on modules. That means that some SRFIs are
76 automatically available when the interpreter is started, whereas the
77 other SRFIs require you to use the appropriate support module
80 There are several reasons for this inconsistency. First, the feature
81 checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
82 available immediately, because it must be there when the user wants to
83 check for the Scheme implementation, that is, before she can know that
84 it is safe to use @code{use-modules} to load SRFI support modules. The
85 second reason is that some features defined in SRFIs had been
86 implemented in Guile before the developers started to add SRFI
87 implementations as modules (for example SRFI-13 (@pxref{SRFI-13})). In
88 the future, it is possible that SRFIs in the core library might be
89 factored out into separate modules, requiring explicit module loading
90 when they are needed. So you should be prepared to have to use
91 @code{use-modules} someday in the future to access SRFI-13 bindings. If
92 you want, you can do that already. We have included the module
93 @code{(srfi srfi-13)} in the distribution, which currently does nothing,
94 but ensures that you can write future-safe code.
96 Generally, support for a specific SRFI is made available by using
97 modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
98 number of the SRFI needed. Another possibility is to use the command
99 line option @code{--use-srfi}, which will load the necessary modules
100 automatically (@pxref{Invoking Guile}).
104 @subsection SRFI-0 - cond-expand
107 This SRFI lets a portable Scheme program test for the presence of
108 certain features, and adapt itself by using different blocks of code,
109 or fail if the necessary features are not available. There's no
110 module to load, this is in the Guile core.
112 A program designed only for Guile will generally not need this
113 mechanism, such a program can of course directly use the various
114 documented parts of Guile.
116 @deffn syntax cond-expand (feature body@dots{}) @dots{}
117 Expand to the @var{body} of the first clause whose @var{feature}
118 specification is satisfied. It is an error if no @var{feature} is
121 Features are symbols such as @code{srfi-1}, and a feature
122 specification can use @code{and}, @code{or} and @code{not} forms to
123 test combinations. The last clause can be an @code{else}, to be used
126 For example, define a private version of @code{alist-cons} if SRFI-1
133 (define (alist-cons key val alist)
134 (cons (cons key val) alist))))
137 Or demand a certain set of SRFIs (list operations, string ports,
138 @code{receive} and string operations), failing if they're not
142 (cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13)
148 The Guile core has the following features,
152 guile-2 ;; starting from Guile 2.x
171 Other SRFI feature symbols are defined once their code has been loaded
172 with @code{use-modules}, since only then are their bindings available.
174 The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is
175 a good way to load SRFIs to satisfy @code{cond-expand} when running a
178 Testing the @code{guile} feature allows a program to adapt itself to
179 the Guile module system, but still run on other Scheme systems. For
180 example the following demands SRFI-8 (@code{receive}), but also knows
181 how to load it with the Guile mechanism.
187 (use-modules (srfi srfi-8))))
190 @cindex @code{guile-2} SRFI-0 feature
191 @cindex portability between 2.0 and older versions
192 Likewise, testing the @code{guile-2} feature allows code to be portable
193 between Guile 2.@var{x} and previous versions of Guile. For instance, it
194 makes it possible to write code that accounts for Guile 2.@var{x}'s compiler,
195 yet be correctly interpreted on 1.8 and earlier versions:
198 (cond-expand (guile-2 (eval-when (compile)
199 ;; This must be evaluated at compile time.
200 (fluid-set! current-reader my-reader)))
202 ;; Earlier versions of Guile do not have a
203 ;; separate compilation phase.
204 (fluid-set! current-reader my-reader)))
207 It should be noted that @code{cond-expand} is separate from the
208 @code{*features*} mechanism (@pxref{Feature Tracking}), feature
209 symbols in one are unrelated to those in the other.
213 @subsection SRFI-1 - List library
217 @c FIXME::martin: Review me!
219 The list library defined in SRFI-1 contains a lot of useful list
220 processing procedures for construction, examining, destructuring and
221 manipulating lists and pairs.
223 Since SRFI-1 also defines some procedures which are already contained
224 in R5RS and thus are supported by the Guile core library, some list
225 and pair procedures which appear in the SRFI-1 document may not appear
226 in this section. So when looking for a particular list/pair
227 processing procedure, you should also have a look at the sections
228 @ref{Lists} and @ref{Pairs}.
231 * SRFI-1 Constructors:: Constructing new lists.
232 * SRFI-1 Predicates:: Testing list for specific properties.
233 * SRFI-1 Selectors:: Selecting elements from lists.
234 * SRFI-1 Length Append etc:: Length calculation and list appending.
235 * SRFI-1 Fold and Map:: Higher-order list processing.
236 * SRFI-1 Filtering and Partitioning:: Filter lists based on predicates.
237 * SRFI-1 Searching:: Search for elements.
238 * SRFI-1 Deleting:: Delete elements from lists.
239 * SRFI-1 Association Lists:: Handle association lists.
240 * SRFI-1 Set Operations:: Use lists for representing sets.
243 @node SRFI-1 Constructors
244 @subsubsection Constructors
245 @cindex list constructor
247 @c FIXME::martin: Review me!
249 New lists can be constructed by calling one of the following
252 @deffn {Scheme Procedure} xcons d a
253 Like @code{cons}, but with interchanged arguments. Useful mostly when
254 passed to higher-order procedures.
257 @deffn {Scheme Procedure} list-tabulate n init-proc
258 Return an @var{n}-element list, where each list element is produced by
259 applying the procedure @var{init-proc} to the corresponding list
260 index. The order in which @var{init-proc} is applied to the indices
264 @deffn {Scheme Procedure} list-copy lst
265 Return a new list containing the elements of the list @var{lst}.
267 This function differs from the core @code{list-copy} (@pxref{List
268 Constructors}) in accepting improper lists too. And if @var{lst} is
269 not a pair at all then it's treated as the final tail of an improper
270 list and simply returned.
273 @deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
274 Return a circular list containing the given arguments @var{elt1}
278 @deffn {Scheme Procedure} iota count [start step]
279 Return a list containing @var{count} numbers, starting from
280 @var{start} and adding @var{step} each time. The default @var{start}
281 is 0, the default @var{step} is 1. For example,
284 (iota 6) @result{} (0 1 2 3 4 5)
285 (iota 4 2.5 -2) @result{} (2.5 0.5 -1.5 -3.5)
288 This function takes its name from the corresponding primitive in the
293 @node SRFI-1 Predicates
294 @subsubsection Predicates
295 @cindex list predicate
297 @c FIXME::martin: Review me!
299 The procedures in this section test specific properties of lists.
301 @deffn {Scheme Procedure} proper-list? obj
302 Return @code{#t} if @var{obj} is a proper list, or @code{#f}
303 otherwise. This is the same as the core @code{list?} (@pxref{List
306 A proper list is a list which ends with the empty list @code{()} in
307 the usual way. The empty list @code{()} itself is a proper list too.
310 (proper-list? '(1 2 3)) @result{} #t
311 (proper-list? '()) @result{} #t
315 @deffn {Scheme Procedure} circular-list? obj
316 Return @code{#t} if @var{obj} is a circular list, or @code{#f}
319 A circular list is a list where at some point the @code{cdr} refers
320 back to a previous pair in the list (either the start or some later
321 point), so that following the @code{cdr}s takes you around in a
325 (define x (list 1 2 3 4))
326 (set-cdr! (last-pair x) (cddr x))
327 x @result{} (1 2 3 4 3 4 3 4 ...)
328 (circular-list? x) @result{} #t
332 @deffn {Scheme Procedure} dotted-list? obj
333 Return @code{#t} if @var{obj} is a dotted list, or @code{#f}
336 A dotted list is a list where the @code{cdr} of the last pair is not
337 the empty list @code{()}. Any non-pair @var{obj} is also considered a
338 dotted list, with length zero.
341 (dotted-list? '(1 2 . 3)) @result{} #t
342 (dotted-list? 99) @result{} #t
346 It will be noted that any Scheme object passes exactly one of the
347 above three tests @code{proper-list?}, @code{circular-list?} and
348 @code{dotted-list?}. Non-lists are @code{dotted-list?}, finite lists
349 are either @code{proper-list?} or @code{dotted-list?}, and infinite
350 lists are @code{circular-list?}.
353 @deffn {Scheme Procedure} null-list? lst
354 Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
355 otherwise. If something else than a proper or circular list is passed
356 as @var{lst}, an error is signalled. This procedure is recommended
357 for checking for the end of a list in contexts where dotted lists are
361 @deffn {Scheme Procedure} not-pair? obj
362 Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
363 This is shorthand notation @code{(not (pair? @var{obj}))} and is
364 supposed to be used for end-of-list checking in contexts where dotted
368 @deffn {Scheme Procedure} list= elt= list1 @dots{}
369 Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
370 List equality is determined by testing whether all lists have the same
371 length and the corresponding elements are equal in the sense of the
372 equality predicate @var{elt=}. If no or only one list is given,
373 @code{#t} is returned.
377 @node SRFI-1 Selectors
378 @subsubsection Selectors
379 @cindex list selector
381 @c FIXME::martin: Review me!
383 @deffn {Scheme Procedure} first pair
384 @deffnx {Scheme Procedure} second pair
385 @deffnx {Scheme Procedure} third pair
386 @deffnx {Scheme Procedure} fourth pair
387 @deffnx {Scheme Procedure} fifth pair
388 @deffnx {Scheme Procedure} sixth pair
389 @deffnx {Scheme Procedure} seventh pair
390 @deffnx {Scheme Procedure} eighth pair
391 @deffnx {Scheme Procedure} ninth pair
392 @deffnx {Scheme Procedure} tenth pair
393 These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
396 @deffn {Scheme Procedure} car+cdr pair
397 Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
400 @deffn {Scheme Procedure} take lst i
401 @deffnx {Scheme Procedure} take! lst i
402 Return a list containing the first @var{i} elements of @var{lst}.
404 @code{take!} may modify the structure of the argument list @var{lst}
405 in order to produce the result.
408 @deffn {Scheme Procedure} drop lst i
409 Return a list containing all but the first @var{i} elements of
413 @deffn {Scheme Procedure} take-right lst i
414 Return a list containing the @var{i} last elements of @var{lst}.
415 The return shares a common tail with @var{lst}.
418 @deffn {Scheme Procedure} drop-right lst i
419 @deffnx {Scheme Procedure} drop-right! lst i
420 Return a list containing all but the @var{i} last elements of
423 @code{drop-right} always returns a new list, even when @var{i} is
424 zero. @code{drop-right!} may modify the structure of the argument
425 list @var{lst} in order to produce the result.
428 @deffn {Scheme Procedure} split-at lst i
429 @deffnx {Scheme Procedure} split-at! lst i
430 Return two values, a list containing the first @var{i} elements of the
431 list @var{lst} and a list containing the remaining elements.
433 @code{split-at!} may modify the structure of the argument list
434 @var{lst} in order to produce the result.
437 @deffn {Scheme Procedure} last lst
438 Return the last element of the non-empty, finite list @var{lst}.
442 @node SRFI-1 Length Append etc
443 @subsubsection Length, Append, Concatenate, etc.
445 @c FIXME::martin: Review me!
447 @deffn {Scheme Procedure} length+ lst
448 Return the length of the argument list @var{lst}. When @var{lst} is a
449 circular list, @code{#f} is returned.
452 @deffn {Scheme Procedure} concatenate list-of-lists
453 @deffnx {Scheme Procedure} concatenate! list-of-lists
454 Construct a list by appending all lists in @var{list-of-lists}.
456 @code{concatenate!} may modify the structure of the given lists in
457 order to produce the result.
459 @code{concatenate} is the same as @code{(apply append
460 @var{list-of-lists})}. It exists because some Scheme implementations
461 have a limit on the number of arguments a function takes, which the
462 @code{apply} might exceed. In Guile there is no such limit.
465 @deffn {Scheme Procedure} append-reverse rev-head tail
466 @deffnx {Scheme Procedure} append-reverse! rev-head tail
467 Reverse @var{rev-head}, append @var{tail} to it, and return the
468 result. This is equivalent to @code{(append (reverse @var{rev-head})
469 @var{tail})}, but its implementation is more efficient.
472 (append-reverse '(1 2 3) '(4 5 6)) @result{} (3 2 1 4 5 6)
475 @code{append-reverse!} may modify @var{rev-head} in order to produce
479 @deffn {Scheme Procedure} zip lst1 lst2 @dots{}
480 Return a list as long as the shortest of the argument lists, where
481 each element is a list. The first list contains the first elements of
482 the argument lists, the second list contains the second elements, and
486 @deffn {Scheme Procedure} unzip1 lst
487 @deffnx {Scheme Procedure} unzip2 lst
488 @deffnx {Scheme Procedure} unzip3 lst
489 @deffnx {Scheme Procedure} unzip4 lst
490 @deffnx {Scheme Procedure} unzip5 lst
491 @code{unzip1} takes a list of lists, and returns a list containing the
492 first elements of each list, @code{unzip2} returns two lists, the
493 first containing the first elements of each lists and the second
494 containing the second elements of each lists, and so on.
497 @deffn {Scheme Procedure} count pred lst1 lst2 @dots{}
498 Return a count of the number of times @var{pred} returns true when
499 called on elements from the given lists.
501 @var{pred} is called with @var{N} parameters @code{(@var{pred}
502 @var{elem1} @dots{} @var{elemN} )}, each element being from the
503 corresponding list. The first call is with the first element of each
504 list, the second with the second element from each, and so on.
506 Counting stops when the end of the shortest list is reached. At least
507 one list must be non-circular.
511 @node SRFI-1 Fold and Map
512 @subsubsection Fold, Unfold & Map
516 @c FIXME::martin: Review me!
518 @deffn {Scheme Procedure} fold proc init lst1 lst2 @dots{}
519 @deffnx {Scheme Procedure} fold-right proc init lst1 lst2 @dots{}
520 Apply @var{proc} to the elements of @var{lst1} @var{lst2} @dots{} to
521 build a result, and return that result.
523 Each @var{proc} call is @code{(@var{proc} @var{elem1} @var{elem2}
524 @dots{} @var{previous})}, where @var{elem1} is from @var{lst1},
525 @var{elem2} is from @var{lst2}, and so on. @var{previous} is the return
526 from the previous call to @var{proc}, or the given @var{init} for the
527 first call. If any list is empty, just @var{init} is returned.
529 @code{fold} works through the list elements from first to last. The
530 following shows a list reversal and the calls it makes,
533 (fold cons '() '(1 2 3))
541 @code{fold-right} works through the list elements from last to first,
542 ie.@: from the right. So for example the following finds the longest
543 string, and the last among equal longest,
546 (fold-right (lambda (str prev)
547 (if (> (string-length str) (string-length prev))
551 '("x" "abc" "xyz" "jk"))
555 If @var{lst1} @var{lst2} @dots{} have different lengths, @code{fold}
556 stops when the end of the shortest is reached; @code{fold-right}
557 commences at the last element of the shortest. Ie.@: elements past the
558 length of the shortest are ignored in the other @var{lst}s. At least
559 one @var{lst} must be non-circular.
561 @code{fold} should be preferred over @code{fold-right} if the order of
562 processing doesn't matter, or can be arranged either way, since
563 @code{fold} is a little more efficient.
565 The way @code{fold} builds a result from iterating is quite general,
566 it can do more than other iterations like say @code{map} or
567 @code{filter}. The following for example removes adjacent duplicate
568 elements from a list,
571 (define (delete-adjacent-duplicates lst)
572 (fold-right (lambda (elem ret)
573 (if (equal? elem (first ret))
578 (delete-adjacent-duplicates '(1 2 3 3 4 4 4 5))
579 @result{} (1 2 3 4 5)
582 Clearly the same sort of thing can be done with a @code{for-each} and
583 a variable in which to build the result, but a self-contained
584 @var{proc} can be re-used in multiple contexts, where a
585 @code{for-each} would have to be written out each time.
588 @deffn {Scheme Procedure} pair-fold proc init lst1 lst2 @dots{}
589 @deffnx {Scheme Procedure} pair-fold-right proc init lst1 lst2 @dots{}
590 The same as @code{fold} and @code{fold-right}, but apply @var{proc} to
591 the pairs of the lists instead of the list elements.
594 @deffn {Scheme Procedure} reduce proc default lst
595 @deffnx {Scheme Procedure} reduce-right proc default lst
596 @code{reduce} is a variant of @code{fold}, where the first call to
597 @var{proc} is on two elements from @var{lst}, rather than one element
598 and a given initial value.
600 If @var{lst} is empty, @code{reduce} returns @var{default} (this is
601 the only use for @var{default}). If @var{lst} has just one element
602 then that's the return value. Otherwise @var{proc} is called on the
603 elements of @var{lst}.
605 Each @var{proc} call is @code{(@var{proc} @var{elem} @var{previous})},
606 where @var{elem} is from @var{lst} (the second and subsequent elements
607 of @var{lst}), and @var{previous} is the return from the previous call
608 to @var{proc}. The first element of @var{lst} is the @var{previous}
609 for the first call to @var{proc}.
611 For example, the following adds a list of numbers, the calls made to
612 @code{+} are shown. (Of course @code{+} accepts multiple arguments
613 and can add a list directly, with @code{apply}.)
616 (reduce + 0 '(5 6 7)) @result{} 18
619 (+ 7 11) @result{} 18
622 @code{reduce} can be used instead of @code{fold} where the @var{init}
623 value is an ``identity'', meaning a value which under @var{proc}
624 doesn't change the result, in this case 0 is an identity since
625 @code{(+ 5 0)} is just 5. @code{reduce} avoids that unnecessary call.
627 @code{reduce-right} is a similar variation on @code{fold-right},
628 working from the end (ie.@: the right) of @var{lst}. The last element
629 of @var{lst} is the @var{previous} for the first call to @var{proc},
630 and the @var{elem} values go from the second last.
632 @code{reduce} should be preferred over @code{reduce-right} if the
633 order of processing doesn't matter, or can be arranged either way,
634 since @code{reduce} is a little more efficient.
637 @deffn {Scheme Procedure} unfold p f g seed [tail-gen]
638 @code{unfold} is defined as follows:
641 (unfold p f g seed) =
642 (if (p seed) (tail-gen seed)
644 (unfold p f g (g seed))))
649 Determines when to stop unfolding.
652 Maps each seed value to the corresponding list element.
655 Maps each seed value to next seed value.
658 The state value for the unfold.
661 Creates the tail of the list; defaults to @code{(lambda (x) '())}.
664 @var{g} produces a series of seed values, which are mapped to list
665 elements by @var{f}. These elements are put into a list in
666 left-to-right order, and @var{p} tells when to stop unfolding.
669 @deffn {Scheme Procedure} unfold-right p f g seed [tail]
670 Construct a list with the following loop.
673 (let lp ((seed seed) (lis tail))
676 (cons (f seed) lis))))
681 Determines when to stop unfolding.
684 Maps each seed value to the corresponding list element.
687 Maps each seed value to next seed value.
690 The state value for the unfold.
693 The tail of the list; defaults to @code{'()}.
698 @deffn {Scheme Procedure} map f lst1 lst2 @dots{}
699 Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
700 return a list containing the results of the procedure applications.
701 This procedure is extended with respect to R5RS, because the argument
702 lists may have different lengths. The result list will have the same
703 length as the shortest argument lists. The order in which @var{f}
704 will be applied to the list element(s) is not specified.
707 @deffn {Scheme Procedure} for-each f lst1 lst2 @dots{}
708 Apply the procedure @var{f} to each pair of corresponding elements of
709 the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not
710 specified. This procedure is extended with respect to R5RS, because
711 the argument lists may have different lengths. The shortest argument
712 list determines the number of times @var{f} is called. @var{f} will
713 be applied to the list elements in left-to-right order.
717 @deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
718 @deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
722 (apply append (map f clist1 clist2 ...))
728 (apply append! (map f clist1 clist2 ...))
731 Map @var{f} over the elements of the lists, just as in the @code{map}
732 function. However, the results of the applications are appended
733 together to make the final result. @code{append-map} uses
734 @code{append} to append the results together; @code{append-map!} uses
737 The dynamic order in which the various applications of @var{f} are
738 made is not specified.
741 @deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
742 Linear-update variant of @code{map} -- @code{map!} is allowed, but not
743 required, to alter the cons cells of @var{lst1} to construct the
746 The dynamic order in which the various applications of @var{f} are
747 made is not specified. In the n-ary case, @var{lst2}, @var{lst3},
748 @dots{} must have at least as many elements as @var{lst1}.
751 @deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{}
752 Like @code{for-each}, but applies the procedure @var{f} to the pairs
753 from which the argument lists are constructed, instead of the list
754 elements. The return value is not specified.
757 @deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
758 Like @code{map}, but only results from the applications of @var{f}
759 which are true are saved in the result list.
763 @node SRFI-1 Filtering and Partitioning
764 @subsubsection Filtering and Partitioning
766 @cindex list partition
768 @c FIXME::martin: Review me!
770 Filtering means to collect all elements from a list which satisfy a
771 specific condition. Partitioning a list means to make two groups of
772 list elements, one which contains the elements satisfying a condition,
773 and the other for the elements which don't.
775 The @code{filter} and @code{filter!} functions are implemented in the
776 Guile core, @xref{List Modification}.
778 @deffn {Scheme Procedure} partition pred lst
779 @deffnx {Scheme Procedure} partition! pred lst
780 Split @var{lst} into those elements which do and don't satisfy the
781 predicate @var{pred}.
783 The return is two values (@pxref{Multiple Values}), the first being a
784 list of all elements from @var{lst} which satisfy @var{pred}, the
785 second a list of those which do not.
787 The elements in the result lists are in the same order as in @var{lst}
788 but the order in which the calls @code{(@var{pred} elem)} are made on
789 the list elements is unspecified.
791 @code{partition} does not change @var{lst}, but one of the returned
792 lists may share a tail with it. @code{partition!} may modify
793 @var{lst} to construct its return.
796 @deffn {Scheme Procedure} remove pred lst
797 @deffnx {Scheme Procedure} remove! pred lst
798 Return a list containing all elements from @var{lst} which do not
799 satisfy the predicate @var{pred}. The elements in the result list
800 have the same order as in @var{lst}. The order in which @var{pred} is
801 applied to the list elements is not specified.
803 @code{remove!} is allowed, but not required to modify the structure of
808 @node SRFI-1 Searching
809 @subsubsection Searching
812 @c FIXME::martin: Review me!
814 The procedures for searching elements in lists either accept a
815 predicate or a comparison object for determining which elements are to
818 @deffn {Scheme Procedure} find pred lst
819 Return the first element of @var{lst} which satisfies the predicate
820 @var{pred} and @code{#f} if no such element is found.
823 @deffn {Scheme Procedure} find-tail pred lst
824 Return the first pair of @var{lst} whose @sc{car} satisfies the
825 predicate @var{pred} and @code{#f} if no such element is found.
828 @deffn {Scheme Procedure} take-while pred lst
829 @deffnx {Scheme Procedure} take-while! pred lst
830 Return the longest initial prefix of @var{lst} whose elements all
831 satisfy the predicate @var{pred}.
833 @code{take-while!} is allowed, but not required to modify the input
834 list while producing the result.
837 @deffn {Scheme Procedure} drop-while pred lst
838 Drop the longest initial prefix of @var{lst} whose elements all
839 satisfy the predicate @var{pred}.
842 @deffn {Scheme Procedure} span pred lst
843 @deffnx {Scheme Procedure} span! pred lst
844 @deffnx {Scheme Procedure} break pred lst
845 @deffnx {Scheme Procedure} break! pred lst
846 @code{span} splits the list @var{lst} into the longest initial prefix
847 whose elements all satisfy the predicate @var{pred}, and the remaining
848 tail. @code{break} inverts the sense of the predicate.
850 @code{span!} and @code{break!} are allowed, but not required to modify
851 the structure of the input list @var{lst} in order to produce the
854 Note that the name @code{break} conflicts with the @code{break}
855 binding established by @code{while} (@pxref{while do}). Applications
856 wanting to use @code{break} from within a @code{while} loop will need
857 to make a new define under a different name.
860 @deffn {Scheme Procedure} any pred lst1 lst2 @dots{}
861 Test whether any set of elements from @var{lst1} @var{lst2} @dots{}
862 satisfies @var{pred}. If so, the return value is the return value from
863 the successful @var{pred} call, or if not, the return value is
866 If there are n list arguments, then @var{pred} must be a predicate
867 taking n arguments. Each @var{pred} call is @code{(@var{pred}
868 @var{elem1} @var{elem2} @dots{} )} taking an element from each
869 @var{lst}. The calls are made successively for the first, second, etc.
870 elements of the lists, stopping when @var{pred} returns non-@code{#f},
871 or when the end of the shortest list is reached.
873 The @var{pred} call on the last set of elements (i.e., when the end of
874 the shortest list has been reached), if that point is reached, is a
878 @deffn {Scheme Procedure} every pred lst1 lst2 @dots{}
879 Test whether every set of elements from @var{lst1} @var{lst2} @dots{}
880 satisfies @var{pred}. If so, the return value is the return from the
881 final @var{pred} call, or if not, the return value is @code{#f}.
883 If there are n list arguments, then @var{pred} must be a predicate
884 taking n arguments. Each @var{pred} call is @code{(@var{pred}
885 @var{elem1} @var{elem2 @dots{}})} taking an element from each
886 @var{lst}. The calls are made successively for the first, second, etc.
887 elements of the lists, stopping if @var{pred} returns @code{#f}, or when
888 the end of any of the lists is reached.
890 The @var{pred} call on the last set of elements (i.e., when the end of
891 the shortest list has been reached) is a tail call.
893 If one of @var{lst1} @var{lst2} @dots{}is empty then no calls to
894 @var{pred} are made, and the return value is @code{#t}.
897 @deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{}
898 Return the index of the first set of elements, one from each of
899 @var{lst1} @var{lst2} @dots{}, which satisfies @var{pred}.
901 @var{pred} is called as @code{(@var{elem1} @var{elem2 @dots{}})}.
902 Searching stops when the end of the shortest @var{lst} is reached.
903 The return index starts from 0 for the first set of elements. If no
904 set of elements pass, then the return value is @code{#f}.
907 (list-index odd? '(2 4 6 9)) @result{} 3
908 (list-index = '(1 2 3) '(3 1 2)) @result{} #f
912 @deffn {Scheme Procedure} member x lst [=]
913 Return the first sublist of @var{lst} whose @sc{car} is equal to
914 @var{x}. If @var{x} does not appear in @var{lst}, return @code{#f}.
916 Equality is determined by @code{equal?}, or by the equality predicate
917 @var{=} if given. @var{=} is called @code{(= @var{x} elem)},
918 ie.@: with the given @var{x} first, so for example to find the first
919 element greater than 5,
922 (member 5 '(3 5 1 7 2 9) <) @result{} (7 2 9)
925 This version of @code{member} extends the core @code{member}
926 (@pxref{List Searching}) by accepting an equality predicate.
930 @node SRFI-1 Deleting
931 @subsubsection Deleting
934 @deffn {Scheme Procedure} delete x lst [=]
935 @deffnx {Scheme Procedure} delete! x lst [=]
936 Return a list containing the elements of @var{lst} but with those
937 equal to @var{x} deleted. The returned elements will be in the same
938 order as they were in @var{lst}.
940 Equality is determined by the @var{=} predicate, or @code{equal?} if
941 not given. An equality call is made just once for each element, but
942 the order in which the calls are made on the elements is unspecified.
944 The equality calls are always @code{(= x elem)}, ie.@: the given @var{x}
945 is first. This means for instance elements greater than 5 can be
946 deleted with @code{(delete 5 lst <)}.
948 @code{delete} does not modify @var{lst}, but the return might share a
949 common tail with @var{lst}. @code{delete!} may modify the structure
950 of @var{lst} to construct its return.
952 These functions extend the core @code{delete} and @code{delete!}
953 (@pxref{List Modification}) in accepting an equality predicate. See
954 also @code{lset-difference} (@pxref{SRFI-1 Set Operations}) for
955 deleting multiple elements from a list.
958 @deffn {Scheme Procedure} delete-duplicates lst [=]
959 @deffnx {Scheme Procedure} delete-duplicates! lst [=]
960 Return a list containing the elements of @var{lst} but without
963 When elements are equal, only the first in @var{lst} is retained.
964 Equal elements can be anywhere in @var{lst}, they don't have to be
965 adjacent. The returned list will have the retained elements in the
966 same order as they were in @var{lst}.
968 Equality is determined by the @var{=} predicate, or @code{equal?} if
969 not given. Calls @code{(= x y)} are made with element @var{x} being
970 before @var{y} in @var{lst}. A call is made at most once for each
971 combination, but the sequence of the calls across the elements is
974 @code{delete-duplicates} does not modify @var{lst}, but the return
975 might share a common tail with @var{lst}. @code{delete-duplicates!}
976 may modify the structure of @var{lst} to construct its return.
978 In the worst case, this is an @math{O(N^2)} algorithm because it must
979 check each element against all those preceding it. For long lists it
980 is more efficient to sort and then compare only adjacent elements.
984 @node SRFI-1 Association Lists
985 @subsubsection Association Lists
986 @cindex association list
989 @c FIXME::martin: Review me!
991 Association lists are described in detail in section @ref{Association
992 Lists}. The present section only documents the additional procedures
993 for dealing with association lists defined by SRFI-1.
995 @deffn {Scheme Procedure} assoc key alist [=]
996 Return the pair from @var{alist} which matches @var{key}. This
997 extends the core @code{assoc} (@pxref{Retrieving Alist Entries}) by
998 taking an optional @var{=} comparison procedure.
1000 The default comparison is @code{equal?}. If an @var{=} parameter is
1001 given it's called @code{(@var{=} @var{key} @var{alistcar})}, i.e.@: the
1002 given target @var{key} is the first argument, and a @code{car} from
1003 @var{alist} is second.
1005 For example a case-insensitive string lookup,
1008 (assoc "yy" '(("XX" . 1) ("YY" . 2)) string-ci=?)
1009 @result{} ("YY" . 2)
1013 @deffn {Scheme Procedure} alist-cons key datum alist
1014 Cons a new association @var{key} and @var{datum} onto @var{alist} and
1015 return the result. This is equivalent to
1018 (cons (cons @var{key} @var{datum}) @var{alist})
1021 @code{acons} (@pxref{Adding or Setting Alist Entries}) in the Guile
1022 core does the same thing.
1025 @deffn {Scheme Procedure} alist-copy alist
1026 Return a newly allocated copy of @var{alist}, that means that the
1027 spine of the list as well as the pairs are copied.
1030 @deffn {Scheme Procedure} alist-delete key alist [=]
1031 @deffnx {Scheme Procedure} alist-delete! key alist [=]
1032 Return a list containing the elements of @var{alist} but with those
1033 elements whose keys are equal to @var{key} deleted. The returned
1034 elements will be in the same order as they were in @var{alist}.
1036 Equality is determined by the @var{=} predicate, or @code{equal?} if
1037 not given. The order in which elements are tested is unspecified, but
1038 each equality call is made @code{(= key alistkey)}, i.e.@: the given
1039 @var{key} parameter is first and the key from @var{alist} second.
1040 This means for instance all associations with a key greater than 5 can
1041 be removed with @code{(alist-delete 5 alist <)}.
1043 @code{alist-delete} does not modify @var{alist}, but the return might
1044 share a common tail with @var{alist}. @code{alist-delete!} may modify
1045 the list structure of @var{alist} to construct its return.
1049 @node SRFI-1 Set Operations
1050 @subsubsection Set Operations on Lists
1051 @cindex list set operation
1053 Lists can be used to represent sets of objects. The procedures in
1054 this section operate on such lists as sets.
1056 Note that lists are not an efficient way to implement large sets. The
1057 procedures here typically take time @math{@var{m}@cross{}@var{n}} when
1058 operating on @var{m} and @var{n} element lists. Other data structures
1059 like trees, bitsets (@pxref{Bit Vectors}) or hash tables (@pxref{Hash
1060 Tables}) are faster.
1062 All these procedures take an equality predicate as the first argument.
1063 This predicate is used for testing the objects in the list sets for
1064 sameness. This predicate must be consistent with @code{eq?}
1065 (@pxref{Equality}) in the sense that if two list elements are
1066 @code{eq?} then they must also be equal under the predicate. This
1067 simply means a given object must be equal to itself.
1069 @deffn {Scheme Procedure} lset<= = list @dots{}
1070 Return @code{#t} if each list is a subset of the one following it.
1071 I.e., @var{list1} is a subset of @var{list2}, @var{list2} is a subset of
1072 @var{list3}, etc., for as many lists as given. If only one list or no
1073 lists are given, the return value is @code{#t}.
1075 A list @var{x} is a subset of @var{y} if each element of @var{x} is
1076 equal to some element in @var{y}. Elements are compared using the
1077 given @var{=} procedure, called as @code{(@var{=} xelem yelem)}.
1080 (lset<= eq?) @result{} #t
1081 (lset<= eqv? '(1 2 3) '(1)) @result{} #f
1082 (lset<= eqv? '(1 3 2) '(4 3 1 2)) @result{} #t
1086 @deffn {Scheme Procedure} lset= = list @dots{}
1087 Return @code{#t} if all argument lists are set-equal. @var{list1} is
1088 compared to @var{list2}, @var{list2} to @var{list3}, etc., for as many
1089 lists as given. If only one list or no lists are given, the return
1092 Two lists @var{x} and @var{y} are set-equal if each element of @var{x}
1093 is equal to some element of @var{y} and conversely each element of
1094 @var{y} is equal to some element of @var{x}. The order of the
1095 elements in the lists doesn't matter. Element equality is determined
1096 with the given @var{=} procedure, called as @code{(@var{=} xelem
1097 yelem)}, but exactly which calls are made is unspecified.
1100 (lset= eq?) @result{} #t
1101 (lset= eqv? '(1 2 3) '(3 2 1)) @result{} #t
1102 (lset= string-ci=? '("a" "A" "b") '("B" "b" "a")) @result{} #t
1106 @deffn {Scheme Procedure} lset-adjoin = list elem @dots{}
1107 Add to @var{list} any of the given @var{elem}s not already in the list.
1108 @var{elem}s are @code{cons}ed onto the start of @var{list} (so the
1109 return value shares a common tail with @var{list}), but the order that
1110 the @var{elem}s are added is unspecified.
1112 The given @var{=} procedure is used for comparing elements, called as
1113 @code{(@var{=} listelem elem)}, i.e., the second argument is one of
1114 the given @var{elem} parameters.
1117 (lset-adjoin eqv? '(1 2 3) 4 1 5) @result{} (5 4 1 2 3)
1121 @deffn {Scheme Procedure} lset-union = list @dots{}
1122 @deffnx {Scheme Procedure} lset-union! = list @dots{}
1123 Return the union of the argument list sets. The result is built by
1124 taking the union of @var{list1} and @var{list2}, then the union of
1125 that with @var{list3}, etc., for as many lists as given. For one list
1126 argument that list itself is the result, for no list arguments the
1127 result is the empty list.
1129 The union of two lists @var{x} and @var{y} is formed as follows. If
1130 @var{x} is empty then the result is @var{y}. Otherwise start with
1131 @var{x} as the result and consider each @var{y} element (from first to
1132 last). A @var{y} element not equal to something already in the result
1133 is @code{cons}ed onto the result.
1135 The given @var{=} procedure is used for comparing elements, called as
1136 @code{(@var{=} relem yelem)}. The first argument is from the result
1137 accumulated so far, and the second is from the list being union-ed in.
1138 But exactly which calls are made is otherwise unspecified.
1140 Notice that duplicate elements in @var{list1} (or the first non-empty
1141 list) are preserved, but that repeated elements in subsequent lists
1142 are only added once.
1145 (lset-union eqv?) @result{} ()
1146 (lset-union eqv? '(1 2 3)) @result{} (1 2 3)
1147 (lset-union eqv? '(1 2 1 3) '(2 4 5) '(5)) @result{} (5 4 1 2 1 3)
1150 @code{lset-union} doesn't change the given lists but the result may
1151 share a tail with the first non-empty list. @code{lset-union!} can
1152 modify all of the given lists to form the result.
1155 @deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{}
1156 @deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{}
1157 Return the intersection of @var{list1} with the other argument lists,
1158 meaning those elements of @var{list1} which are also in all of
1159 @var{list2} etc. For one list argument, just that list is returned.
1161 The test for an element of @var{list1} to be in the return is simply
1162 that it's equal to some element in each of @var{list2} etc. Notice
1163 this means an element appearing twice in @var{list1} but only once in
1164 each of @var{list2} etc will go into the return twice. The return has
1165 its elements in the same order as they were in @var{list1}.
1167 The given @var{=} procedure is used for comparing elements, called as
1168 @code{(@var{=} elem1 elemN)}. The first argument is from @var{list1}
1169 and the second is from one of the subsequent lists. But exactly which
1170 calls are made and in what order is unspecified.
1173 (lset-intersection eqv? '(x y)) @result{} (x y)
1174 (lset-intersection eqv? '(1 2 3) '(4 3 2)) @result{} (2 3)
1175 (lset-intersection eqv? '(1 1 2 2) '(1 2) '(2 1) '(2)) @result{} (2 2)
1178 The return from @code{lset-intersection} may share a tail with
1179 @var{list1}. @code{lset-intersection!} may modify @var{list1} to form
1183 @deffn {Scheme Procedure} lset-difference = list1 list2 @dots{}
1184 @deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{}
1185 Return @var{list1} with any elements in @var{list2}, @var{list3} etc
1186 removed (ie.@: subtracted). For one list argument, just that list is
1189 The given @var{=} procedure is used for comparing elements, called as
1190 @code{(@var{=} elem1 elemN)}. The first argument is from @var{list1}
1191 and the second from one of the subsequent lists. But exactly which
1192 calls are made and in what order is unspecified.
1195 (lset-difference eqv? '(x y)) @result{} (x y)
1196 (lset-difference eqv? '(1 2 3) '(3 1)) @result{} (2)
1197 (lset-difference eqv? '(1 2 3) '(3) '(2)) @result{} (1)
1200 The return from @code{lset-difference} may share a tail with
1201 @var{list1}. @code{lset-difference!} may modify @var{list1} to form
1205 @deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{}
1206 @deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{}
1207 Return two values (@pxref{Multiple Values}), the difference and
1208 intersection of the argument lists as per @code{lset-difference} and
1209 @code{lset-intersection} above.
1211 For two list arguments this partitions @var{list1} into those elements
1212 of @var{list1} which are in @var{list2} and not in @var{list2}. (But
1213 for more than two arguments there can be elements of @var{list1} which
1214 are neither part of the difference nor the intersection.)
1216 One of the return values from @code{lset-diff+intersection} may share
1217 a tail with @var{list1}. @code{lset-diff+intersection!} may modify
1218 @var{list1} to form its results.
1221 @deffn {Scheme Procedure} lset-xor = list @dots{}
1222 @deffnx {Scheme Procedure} lset-xor! = list @dots{}
1223 Return an XOR of the argument lists. For two lists this means those
1224 elements which are in exactly one of the lists. For more than two
1225 lists it means those elements which appear in an odd number of the
1228 To be precise, the XOR of two lists @var{x} and @var{y} is formed by
1229 taking those elements of @var{x} not equal to any element of @var{y},
1230 plus those elements of @var{y} not equal to any element of @var{x}.
1231 Equality is determined with the given @var{=} procedure, called as
1232 @code{(@var{=} e1 e2)}. One argument is from @var{x} and the other
1233 from @var{y}, but which way around is unspecified. Exactly which
1234 calls are made is also unspecified, as is the order of the elements in
1238 (lset-xor eqv? '(x y)) @result{} (x y)
1239 (lset-xor eqv? '(1 2 3) '(4 3 2)) @result{} (4 1)
1242 The return from @code{lset-xor} may share a tail with one of the list
1243 arguments. @code{lset-xor!} may modify @var{list1} to form its
1249 @subsection SRFI-2 - and-let*
1253 The following syntax can be obtained with
1256 (use-modules (srfi srfi-2))
1262 (use-modules (ice-9 and-let-star))
1265 @deffn {library syntax} and-let* (clause @dots{}) body @dots{}
1266 A combination of @code{and} and @code{let*}.
1268 Each @var{clause} is evaluated in turn, and if @code{#f} is obtained
1269 then evaluation stops and @code{#f} is returned. If all are
1270 non-@code{#f} then @var{body} is evaluated and the last form gives the
1271 return value, or if @var{body} is empty then the result is @code{#t}.
1272 Each @var{clause} should be one of the following,
1276 Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}.
1277 Like @code{let*}, that binding is available to subsequent clauses.
1279 Evaluate @var{expr} and check for @code{#f}.
1281 Get the value bound to @var{symbol} and check for @code{#f}.
1284 Notice that @code{(expr)} has an ``extra'' pair of parentheses, for
1285 instance @code{((eq? x y))}. One way to remember this is to imagine
1286 the @code{symbol} in @code{(symbol expr)} is omitted.
1288 @code{and-let*} is good for calculations where a @code{#f} value means
1289 termination, but where a non-@code{#f} value is going to be needed in
1290 subsequent expressions.
1292 The following illustrates this, it returns text between brackets
1293 @samp{[...]} in a string, or @code{#f} if there are no such brackets
1294 (ie.@: either @code{string-index} gives @code{#f}).
1297 (define (extract-brackets str)
1298 (and-let* ((start (string-index str #\[))
1299 (end (string-index str #\] start)))
1300 (substring str (1+ start) end)))
1303 The following shows plain variables and expressions tested too.
1304 @code{diagnostic-levels} is taken to be an alist associating a
1305 diagnostic type with a level. @code{str} is printed only if the type
1306 is known and its level is high enough.
1309 (define (show-diagnostic type str)
1310 (and-let* (want-diagnostics
1311 (level (assq-ref diagnostic-levels type))
1312 ((>= level current-diagnostic-level)))
1316 The advantage of @code{and-let*} is that an extended sequence of
1317 expressions and tests doesn't require lots of nesting as would arise
1318 from separate @code{and} and @code{let*}, or from @code{cond} with
1325 @subsection SRFI-4 - Homogeneous numeric vector datatypes
1328 SRFI-4 provides an interface to uniform numeric vectors: vectors whose elements
1329 are all of a single numeric type. Guile offers uniform numeric vectors for
1330 signed and unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
1331 floating point values, and, as an extension to SRFI-4, complex floating-point
1332 numbers of these two sizes.
1334 The standard SRFI-4 procedures and data types may be included via loading the
1338 (use-modules (srfi srfi-4))
1341 This module is currently a part of the default Guile environment, but it is a
1342 good practice to explicitly import the module. In the future, using SRFI-4
1343 procedures without importing the SRFI-4 module will cause a deprecation message
1344 to be printed. (Of course, one may call the C functions at any time. Would that
1348 * SRFI-4 Overview:: The warp and weft of uniform numeric vectors.
1349 * SRFI-4 API:: Uniform vectors, from Scheme and from C.
1350 * SRFI-4 and Bytevectors:: SRFI-4 vectors are backed by bytevectors.
1351 * SRFI-4 Extensions:: Guile-specific extensions to the standard.
1354 @node SRFI-4 Overview
1355 @subsubsection SRFI-4 - Overview
1357 Uniform numeric vectors can be useful since they consume less memory
1358 than the non-uniform, general vectors. Also, since the types they can
1359 store correspond directly to C types, it is easier to work with them
1360 efficiently on a low level. Consider image processing as an example,
1361 where you want to apply a filter to some image. While you could store
1362 the pixels of an image in a general vector and write a general
1363 convolution function, things are much more efficient with uniform
1364 vectors: the convolution function knows that all pixels are unsigned
1365 8-bit values (say), and can use a very tight inner loop.
1367 This is implemented in Scheme by having the compiler notice calls to the SRFI-4
1368 accessors, and inline them to appropriate compiled code. From C you have access
1369 to the raw array; functions for efficiently working with uniform numeric vectors
1370 from C are listed at the end of this section.
1372 Uniform numeric vectors are the special case of one dimensional uniform
1375 There are 12 standard kinds of uniform numeric vectors, and they all have their
1376 own complement of constructors, accessors, and so on. Procedures that operate on
1377 a specific kind of uniform numeric vector have a ``tag'' in their name,
1378 indicating the element type.
1382 unsigned 8-bit integers
1385 signed 8-bit integers
1388 unsigned 16-bit integers
1391 signed 16-bit integers
1394 unsigned 32-bit integers
1397 signed 32-bit integers
1400 unsigned 64-bit integers
1403 signed 64-bit integers
1406 the C type @code{float}
1409 the C type @code{double}
1413 In addition, Guile supports uniform arrays of complex numbers, with the
1419 complex numbers in rectangular form with the real and imaginary part
1420 being a @code{float}
1423 complex numbers in rectangular form with the real and imaginary part
1424 being a @code{double}
1428 The external representation (ie.@: read syntax) for these vectors is
1429 similar to normal Scheme vectors, but with an additional tag from the
1430 tables above indicating the vector's type. For example,
1437 Note that the read syntax for floating-point here conflicts with
1438 @code{#f} for false. In Standard Scheme one can write @code{(1 #f3)}
1439 for a three element list @code{(1 #f 3)}, but for Guile @code{(1 #f3)}
1440 is invalid. @code{(1 #f 3)} is almost certainly what one should write
1441 anyway to make the intention clear, so this is rarely a problem.
1445 @subsubsection SRFI-4 - API
1447 Note that the @nicode{c32} and @nicode{c64} functions are only available from
1448 @nicode{(srfi srfi-4 gnu)}.
1450 @deffn {Scheme Procedure} u8vector? obj
1451 @deffnx {Scheme Procedure} s8vector? obj
1452 @deffnx {Scheme Procedure} u16vector? obj
1453 @deffnx {Scheme Procedure} s16vector? obj
1454 @deffnx {Scheme Procedure} u32vector? obj
1455 @deffnx {Scheme Procedure} s32vector? obj
1456 @deffnx {Scheme Procedure} u64vector? obj
1457 @deffnx {Scheme Procedure} s64vector? obj
1458 @deffnx {Scheme Procedure} f32vector? obj
1459 @deffnx {Scheme Procedure} f64vector? obj
1460 @deffnx {Scheme Procedure} c32vector? obj
1461 @deffnx {Scheme Procedure} c64vector? obj
1462 @deffnx {C Function} scm_u8vector_p (obj)
1463 @deffnx {C Function} scm_s8vector_p (obj)
1464 @deffnx {C Function} scm_u16vector_p (obj)
1465 @deffnx {C Function} scm_s16vector_p (obj)
1466 @deffnx {C Function} scm_u32vector_p (obj)
1467 @deffnx {C Function} scm_s32vector_p (obj)
1468 @deffnx {C Function} scm_u64vector_p (obj)
1469 @deffnx {C Function} scm_s64vector_p (obj)
1470 @deffnx {C Function} scm_f32vector_p (obj)
1471 @deffnx {C Function} scm_f64vector_p (obj)
1472 @deffnx {C Function} scm_c32vector_p (obj)
1473 @deffnx {C Function} scm_c64vector_p (obj)
1474 Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1478 @deffn {Scheme Procedure} make-u8vector n [value]
1479 @deffnx {Scheme Procedure} make-s8vector n [value]
1480 @deffnx {Scheme Procedure} make-u16vector n [value]
1481 @deffnx {Scheme Procedure} make-s16vector n [value]
1482 @deffnx {Scheme Procedure} make-u32vector n [value]
1483 @deffnx {Scheme Procedure} make-s32vector n [value]
1484 @deffnx {Scheme Procedure} make-u64vector n [value]
1485 @deffnx {Scheme Procedure} make-s64vector n [value]
1486 @deffnx {Scheme Procedure} make-f32vector n [value]
1487 @deffnx {Scheme Procedure} make-f64vector n [value]
1488 @deffnx {Scheme Procedure} make-c32vector n [value]
1489 @deffnx {Scheme Procedure} make-c64vector n [value]
1490 @deffnx {C Function} scm_make_u8vector (n, value)
1491 @deffnx {C Function} scm_make_s8vector (n, value)
1492 @deffnx {C Function} scm_make_u16vector (n, value)
1493 @deffnx {C Function} scm_make_s16vector (n, value)
1494 @deffnx {C Function} scm_make_u32vector (n, value)
1495 @deffnx {C Function} scm_make_s32vector (n, value)
1496 @deffnx {C Function} scm_make_u64vector (n, value)
1497 @deffnx {C Function} scm_make_s64vector (n, value)
1498 @deffnx {C Function} scm_make_f32vector (n, value)
1499 @deffnx {C Function} scm_make_f64vector (n, value)
1500 @deffnx {C Function} scm_make_c32vector (n, value)
1501 @deffnx {C Function} scm_make_c64vector (n, value)
1502 Return a newly allocated homogeneous numeric vector holding @var{n}
1503 elements of the indicated type. If @var{value} is given, the vector
1504 is initialized with that value, otherwise the contents are
1508 @deffn {Scheme Procedure} u8vector value @dots{}
1509 @deffnx {Scheme Procedure} s8vector value @dots{}
1510 @deffnx {Scheme Procedure} u16vector value @dots{}
1511 @deffnx {Scheme Procedure} s16vector value @dots{}
1512 @deffnx {Scheme Procedure} u32vector value @dots{}
1513 @deffnx {Scheme Procedure} s32vector value @dots{}
1514 @deffnx {Scheme Procedure} u64vector value @dots{}
1515 @deffnx {Scheme Procedure} s64vector value @dots{}
1516 @deffnx {Scheme Procedure} f32vector value @dots{}
1517 @deffnx {Scheme Procedure} f64vector value @dots{}
1518 @deffnx {Scheme Procedure} c32vector value @dots{}
1519 @deffnx {Scheme Procedure} c64vector value @dots{}
1520 @deffnx {C Function} scm_u8vector (values)
1521 @deffnx {C Function} scm_s8vector (values)
1522 @deffnx {C Function} scm_u16vector (values)
1523 @deffnx {C Function} scm_s16vector (values)
1524 @deffnx {C Function} scm_u32vector (values)
1525 @deffnx {C Function} scm_s32vector (values)
1526 @deffnx {C Function} scm_u64vector (values)
1527 @deffnx {C Function} scm_s64vector (values)
1528 @deffnx {C Function} scm_f32vector (values)
1529 @deffnx {C Function} scm_f64vector (values)
1530 @deffnx {C Function} scm_c32vector (values)
1531 @deffnx {C Function} scm_c64vector (values)
1532 Return a newly allocated homogeneous numeric vector of the indicated
1533 type, holding the given parameter @var{value}s. The vector length is
1534 the number of parameters given.
1537 @deffn {Scheme Procedure} u8vector-length vec
1538 @deffnx {Scheme Procedure} s8vector-length vec
1539 @deffnx {Scheme Procedure} u16vector-length vec
1540 @deffnx {Scheme Procedure} s16vector-length vec
1541 @deffnx {Scheme Procedure} u32vector-length vec
1542 @deffnx {Scheme Procedure} s32vector-length vec
1543 @deffnx {Scheme Procedure} u64vector-length vec
1544 @deffnx {Scheme Procedure} s64vector-length vec
1545 @deffnx {Scheme Procedure} f32vector-length vec
1546 @deffnx {Scheme Procedure} f64vector-length vec
1547 @deffnx {Scheme Procedure} c32vector-length vec
1548 @deffnx {Scheme Procedure} c64vector-length vec
1549 @deffnx {C Function} scm_u8vector_length (vec)
1550 @deffnx {C Function} scm_s8vector_length (vec)
1551 @deffnx {C Function} scm_u16vector_length (vec)
1552 @deffnx {C Function} scm_s16vector_length (vec)
1553 @deffnx {C Function} scm_u32vector_length (vec)
1554 @deffnx {C Function} scm_s32vector_length (vec)
1555 @deffnx {C Function} scm_u64vector_length (vec)
1556 @deffnx {C Function} scm_s64vector_length (vec)
1557 @deffnx {C Function} scm_f32vector_length (vec)
1558 @deffnx {C Function} scm_f64vector_length (vec)
1559 @deffnx {C Function} scm_c32vector_length (vec)
1560 @deffnx {C Function} scm_c64vector_length (vec)
1561 Return the number of elements in @var{vec}.
1564 @deffn {Scheme Procedure} u8vector-ref vec i
1565 @deffnx {Scheme Procedure} s8vector-ref vec i
1566 @deffnx {Scheme Procedure} u16vector-ref vec i
1567 @deffnx {Scheme Procedure} s16vector-ref vec i
1568 @deffnx {Scheme Procedure} u32vector-ref vec i
1569 @deffnx {Scheme Procedure} s32vector-ref vec i
1570 @deffnx {Scheme Procedure} u64vector-ref vec i
1571 @deffnx {Scheme Procedure} s64vector-ref vec i
1572 @deffnx {Scheme Procedure} f32vector-ref vec i
1573 @deffnx {Scheme Procedure} f64vector-ref vec i
1574 @deffnx {Scheme Procedure} c32vector-ref vec i
1575 @deffnx {Scheme Procedure} c64vector-ref vec i
1576 @deffnx {C Function} scm_u8vector_ref (vec, i)
1577 @deffnx {C Function} scm_s8vector_ref (vec, i)
1578 @deffnx {C Function} scm_u16vector_ref (vec, i)
1579 @deffnx {C Function} scm_s16vector_ref (vec, i)
1580 @deffnx {C Function} scm_u32vector_ref (vec, i)
1581 @deffnx {C Function} scm_s32vector_ref (vec, i)
1582 @deffnx {C Function} scm_u64vector_ref (vec, i)
1583 @deffnx {C Function} scm_s64vector_ref (vec, i)
1584 @deffnx {C Function} scm_f32vector_ref (vec, i)
1585 @deffnx {C Function} scm_f64vector_ref (vec, i)
1586 @deffnx {C Function} scm_c32vector_ref (vec, i)
1587 @deffnx {C Function} scm_c64vector_ref (vec, i)
1588 Return the element at index @var{i} in @var{vec}. The first element
1589 in @var{vec} is index 0.
1592 @deffn {Scheme Procedure} u8vector-set! vec i value
1593 @deffnx {Scheme Procedure} s8vector-set! vec i value
1594 @deffnx {Scheme Procedure} u16vector-set! vec i value
1595 @deffnx {Scheme Procedure} s16vector-set! vec i value
1596 @deffnx {Scheme Procedure} u32vector-set! vec i value
1597 @deffnx {Scheme Procedure} s32vector-set! vec i value
1598 @deffnx {Scheme Procedure} u64vector-set! vec i value
1599 @deffnx {Scheme Procedure} s64vector-set! vec i value
1600 @deffnx {Scheme Procedure} f32vector-set! vec i value
1601 @deffnx {Scheme Procedure} f64vector-set! vec i value
1602 @deffnx {Scheme Procedure} c32vector-set! vec i value
1603 @deffnx {Scheme Procedure} c64vector-set! vec i value
1604 @deffnx {C Function} scm_u8vector_set_x (vec, i, value)
1605 @deffnx {C Function} scm_s8vector_set_x (vec, i, value)
1606 @deffnx {C Function} scm_u16vector_set_x (vec, i, value)
1607 @deffnx {C Function} scm_s16vector_set_x (vec, i, value)
1608 @deffnx {C Function} scm_u32vector_set_x (vec, i, value)
1609 @deffnx {C Function} scm_s32vector_set_x (vec, i, value)
1610 @deffnx {C Function} scm_u64vector_set_x (vec, i, value)
1611 @deffnx {C Function} scm_s64vector_set_x (vec, i, value)
1612 @deffnx {C Function} scm_f32vector_set_x (vec, i, value)
1613 @deffnx {C Function} scm_f64vector_set_x (vec, i, value)
1614 @deffnx {C Function} scm_c32vector_set_x (vec, i, value)
1615 @deffnx {C Function} scm_c64vector_set_x (vec, i, value)
1616 Set the element at index @var{i} in @var{vec} to @var{value}. The
1617 first element in @var{vec} is index 0. The return value is
1621 @deffn {Scheme Procedure} u8vector->list vec
1622 @deffnx {Scheme Procedure} s8vector->list vec
1623 @deffnx {Scheme Procedure} u16vector->list vec
1624 @deffnx {Scheme Procedure} s16vector->list vec
1625 @deffnx {Scheme Procedure} u32vector->list vec
1626 @deffnx {Scheme Procedure} s32vector->list vec
1627 @deffnx {Scheme Procedure} u64vector->list vec
1628 @deffnx {Scheme Procedure} s64vector->list vec
1629 @deffnx {Scheme Procedure} f32vector->list vec
1630 @deffnx {Scheme Procedure} f64vector->list vec
1631 @deffnx {Scheme Procedure} c32vector->list vec
1632 @deffnx {Scheme Procedure} c64vector->list vec
1633 @deffnx {C Function} scm_u8vector_to_list (vec)
1634 @deffnx {C Function} scm_s8vector_to_list (vec)
1635 @deffnx {C Function} scm_u16vector_to_list (vec)
1636 @deffnx {C Function} scm_s16vector_to_list (vec)
1637 @deffnx {C Function} scm_u32vector_to_list (vec)
1638 @deffnx {C Function} scm_s32vector_to_list (vec)
1639 @deffnx {C Function} scm_u64vector_to_list (vec)
1640 @deffnx {C Function} scm_s64vector_to_list (vec)
1641 @deffnx {C Function} scm_f32vector_to_list (vec)
1642 @deffnx {C Function} scm_f64vector_to_list (vec)
1643 @deffnx {C Function} scm_c32vector_to_list (vec)
1644 @deffnx {C Function} scm_c64vector_to_list (vec)
1645 Return a newly allocated list holding all elements of @var{vec}.
1648 @deffn {Scheme Procedure} list->u8vector lst
1649 @deffnx {Scheme Procedure} list->s8vector lst
1650 @deffnx {Scheme Procedure} list->u16vector lst
1651 @deffnx {Scheme Procedure} list->s16vector lst
1652 @deffnx {Scheme Procedure} list->u32vector lst
1653 @deffnx {Scheme Procedure} list->s32vector lst
1654 @deffnx {Scheme Procedure} list->u64vector lst
1655 @deffnx {Scheme Procedure} list->s64vector lst
1656 @deffnx {Scheme Procedure} list->f32vector lst
1657 @deffnx {Scheme Procedure} list->f64vector lst
1658 @deffnx {Scheme Procedure} list->c32vector lst
1659 @deffnx {Scheme Procedure} list->c64vector lst
1660 @deffnx {C Function} scm_list_to_u8vector (lst)
1661 @deffnx {C Function} scm_list_to_s8vector (lst)
1662 @deffnx {C Function} scm_list_to_u16vector (lst)
1663 @deffnx {C Function} scm_list_to_s16vector (lst)
1664 @deffnx {C Function} scm_list_to_u32vector (lst)
1665 @deffnx {C Function} scm_list_to_s32vector (lst)
1666 @deffnx {C Function} scm_list_to_u64vector (lst)
1667 @deffnx {C Function} scm_list_to_s64vector (lst)
1668 @deffnx {C Function} scm_list_to_f32vector (lst)
1669 @deffnx {C Function} scm_list_to_f64vector (lst)
1670 @deffnx {C Function} scm_list_to_c32vector (lst)
1671 @deffnx {C Function} scm_list_to_c64vector (lst)
1672 Return a newly allocated homogeneous numeric vector of the indicated type,
1673 initialized with the elements of the list @var{lst}.
1676 @deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len)
1677 @deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len)
1678 @deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len)
1679 @deftypefnx {C Function} SCM scm_take_s16vector (const scm_t_int16 *data, size_t len)
1680 @deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len)
1681 @deftypefnx {C Function} SCM scm_take_s32vector (const scm_t_int32 *data, size_t len)
1682 @deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len)
1683 @deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len)
1684 @deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len)
1685 @deftypefnx {C Function} SCM scm_take_f64vector (const double *data, size_t len)
1686 @deftypefnx {C Function} SCM scm_take_c32vector (const float *data, size_t len)
1687 @deftypefnx {C Function} SCM scm_take_c64vector (const double *data, size_t len)
1688 Return a new uniform numeric vector of the indicated type and length
1689 that uses the memory pointed to by @var{data} to store its elements.
1690 This memory will eventually be freed with @code{free}. The argument
1691 @var{len} specifies the number of elements in @var{data}, not its size
1694 The @code{c32} and @code{c64} variants take a pointer to a C array of
1695 @code{float}s or @code{double}s. The real parts of the complex numbers
1696 are at even indices in that array, the corresponding imaginary parts are
1697 at the following odd index.
1700 @deftypefn {C Function} {const scm_t_uint8 *} scm_u8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1701 @deftypefnx {C Function} {const scm_t_int8 *} scm_s8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1702 @deftypefnx {C Function} {const scm_t_uint16 *} scm_u16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1703 @deftypefnx {C Function} {const scm_t_int16 *} scm_s16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1704 @deftypefnx {C Function} {const scm_t_uint32 *} scm_u32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1705 @deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1706 @deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1707 @deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1708 @deftypefnx {C Function} {const float *} scm_f32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1709 @deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1710 @deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1711 @deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1712 Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
1713 returns a pointer to the elements of a uniform numeric vector of the
1717 @deftypefn {C Function} {scm_t_uint8 *} scm_u8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1718 @deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1719 @deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1720 @deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1721 @deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1722 @deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1723 @deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1724 @deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1725 @deftypefnx {C Function} {float *} scm_f32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1726 @deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1727 @deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1728 @deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1729 Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from
1730 C}), but returns a pointer to the elements of a uniform numeric vector
1731 of the indicated kind.
1734 @node SRFI-4 and Bytevectors
1735 @subsubsection SRFI-4 - Relation to bytevectors
1737 Guile implements SRFI-4 vectors using bytevectors (@pxref{Bytevectors}). Often
1738 when you have a numeric vector, you end up wanting to write its bytes somewhere,
1739 or have access to the underlying bytes, or read in bytes from somewhere else.
1740 Bytevectors are very good at this sort of thing. But the SRFI-4 APIs are nicer
1741 to use when doing number-crunching, because they are addressed by element and
1744 So as a compromise, Guile allows all bytevector functions to operate on numeric
1745 vectors. They address the underlying bytes in the native endianness, as one
1748 Following the same reasoning, that it's just bytes underneath, Guile also allows
1749 uniform vectors of a given type to be accessed as if they were of any type. One
1750 can fill a @nicode{u32vector}, and access its elements with
1751 @nicode{u8vector-ref}. One can use @nicode{f64vector-ref} on bytevectors. It's
1752 all the same to Guile.
1754 In this way, uniform numeric vectors may be written to and read from
1755 input/output ports using the procedures that operate on bytevectors.
1757 @xref{Bytevectors}, for more information.
1760 @node SRFI-4 Extensions
1761 @subsubsection SRFI-4 - Guile extensions
1763 Guile defines some useful extensions to SRFI-4, which are not available in the
1764 default Guile environment. They may be imported by loading the extensions
1768 (use-modules (srfi srfi-4 gnu))
1771 @deffn {Scheme Procedure} any->u8vector obj
1772 @deffnx {Scheme Procedure} any->s8vector obj
1773 @deffnx {Scheme Procedure} any->u16vector obj
1774 @deffnx {Scheme Procedure} any->s16vector obj
1775 @deffnx {Scheme Procedure} any->u32vector obj
1776 @deffnx {Scheme Procedure} any->s32vector obj
1777 @deffnx {Scheme Procedure} any->u64vector obj
1778 @deffnx {Scheme Procedure} any->s64vector obj
1779 @deffnx {Scheme Procedure} any->f32vector obj
1780 @deffnx {Scheme Procedure} any->f64vector obj
1781 @deffnx {Scheme Procedure} any->c32vector obj
1782 @deffnx {Scheme Procedure} any->c64vector obj
1783 @deffnx {C Function} scm_any_to_u8vector (obj)
1784 @deffnx {C Function} scm_any_to_s8vector (obj)
1785 @deffnx {C Function} scm_any_to_u16vector (obj)
1786 @deffnx {C Function} scm_any_to_s16vector (obj)
1787 @deffnx {C Function} scm_any_to_u32vector (obj)
1788 @deffnx {C Function} scm_any_to_s32vector (obj)
1789 @deffnx {C Function} scm_any_to_u64vector (obj)
1790 @deffnx {C Function} scm_any_to_s64vector (obj)
1791 @deffnx {C Function} scm_any_to_f32vector (obj)
1792 @deffnx {C Function} scm_any_to_f64vector (obj)
1793 @deffnx {C Function} scm_any_to_c32vector (obj)
1794 @deffnx {C Function} scm_any_to_c64vector (obj)
1795 Return a (maybe newly allocated) uniform numeric vector of the indicated
1796 type, initialized with the elements of @var{obj}, which must be a list,
1797 a vector, or a uniform vector. When @var{obj} is already a suitable
1798 uniform numeric vector, it is returned unchanged.
1803 @subsection SRFI-6 - Basic String Ports
1806 SRFI-6 defines the procedures @code{open-input-string},
1807 @code{open-output-string} and @code{get-output-string}. These
1808 procedures are included in the Guile core, so using this module does not
1809 make any difference at the moment. But it is possible that support for
1810 SRFI-6 will be factored out of the core library in the future, so using
1811 this module does not hurt, after all.
1814 @subsection SRFI-8 - receive
1817 @code{receive} is a syntax for making the handling of multiple-value
1818 procedures easier. It is documented in @xref{Multiple Values}.
1822 @subsection SRFI-9 - define-record-type
1824 This SRFI is a syntax for defining new record types and creating
1825 predicate, constructor, and field getter and setter functions. It is
1826 documented in the ``Compound Data Types'' section of the manual
1827 (@pxref{SRFI-9 Records}).
1831 @subsection SRFI-10 - Hash-Comma Reader Extension
1836 This SRFI implements a reader extension @code{#,()} called hash-comma.
1837 It allows the reader to give new kinds of objects, for use both in
1838 data and as constants or literals in source code. This feature is
1842 (use-modules (srfi srfi-10))
1846 The new read syntax is of the form
1849 #,(@var{tag} @var{arg}@dots{})
1853 where @var{tag} is a symbol and the @var{arg}s are objects taken as
1854 parameters. @var{tag}s are registered with the following procedure.
1856 @deffn {Scheme Procedure} define-reader-ctor tag proc
1857 Register @var{proc} as the constructor for a hash-comma read syntax
1858 starting with symbol @var{tag}, i.e.@: @nicode{#,(@var{tag} arg@dots{})}.
1859 @var{proc} is called with the given arguments @code{(@var{proc}
1860 arg@dots{})} and the object it returns is the result of the read.
1864 For example, a syntax giving a list of @var{N} copies of an object.
1867 (define-reader-ctor 'repeat
1869 (make-list reps obj)))
1871 (display '#,(repeat 99 3))
1875 Notice the quote @nicode{'} when the @nicode{#,( )} is used. The
1876 @code{repeat} handler returns a list and the program must quote to use
1877 it literally, the same as any other list. Ie.
1880 (display '#,(repeat 99 3))
1882 (display '(99 99 99))
1885 When a handler returns an object which is self-evaluating, like a
1886 number or a string, then there's no need for quoting, just as there's
1887 no need when giving those directly as literals. For example an
1891 (define-reader-ctor 'sum
1894 (display #,(sum 123 456)) @print{} 579
1897 A typical use for @nicode{#,()} is to get a read syntax for objects
1898 which don't otherwise have one. For example, the following allows a
1899 hash table to be given literally, with tags and values, ready for fast
1903 (define-reader-ctor 'hash
1905 (let ((table (make-hash-table)))
1906 (for-each (lambda (elem)
1907 (apply hash-set! table elem))
1911 (define (animal->family animal)
1912 (hash-ref '#,(hash ("tiger" "cat")
1917 (animal->family "lion") @result{} "cat"
1920 Or for example the following is a syntax for a compiled regular
1921 expression (@pxref{Regular Expressions}).
1924 (use-modules (ice-9 regex))
1926 (define-reader-ctor 'regexp make-regexp)
1928 (define (extract-angs str)
1929 (let ((match (regexp-exec '#,(regexp "<([A-Z0-9]+)>") str)))
1931 (match:substring match 1))))
1933 (extract-angs "foo <BAR> quux") @result{} "BAR"
1937 @nicode{#,()} is somewhat similar to @code{define-macro}
1938 (@pxref{Macros}) in that handler code is run to produce a result, but
1939 @nicode{#,()} operates at the read stage, so it can appear in data for
1940 @code{read} (@pxref{Scheme Read}), not just in code to be executed.
1942 Because @nicode{#,()} is handled at read-time it has no direct access
1943 to variables etc. A symbol in the arguments is just a symbol, not a
1944 variable reference. The arguments are essentially constants, though
1945 the handler procedure can use them in any complicated way it might
1948 Once @code{(srfi srfi-10)} has loaded, @nicode{#,()} is available
1949 globally, there's no need to use @code{(srfi srfi-10)} in later
1950 modules. Similarly the tags registered are global and can be used
1951 anywhere once registered.
1953 There's no attempt to record what previous @nicode{#,()} forms have
1954 been seen, if two identical forms occur then two calls are made to the
1955 handler procedure. The handler might like to maintain a cache or
1956 similar to avoid making copies of large objects, depending on expected
1959 In code the best uses of @nicode{#,()} are generally when there's a
1960 lot of objects of a particular kind as literals or constants. If
1961 there's just a few then some local variables and initializers are
1962 fine, but that becomes tedious and error prone when there's a lot, and
1963 the anonymous and compact syntax of @nicode{#,()} is much better.
1967 @subsection SRFI-11 - let-values
1972 This module implements the binding forms for multiple values
1973 @code{let-values} and @code{let*-values}. These forms are similar to
1974 @code{let} and @code{let*} (@pxref{Local Bindings}), but they support
1975 binding of the values returned by multiple-valued expressions.
1977 Write @code{(use-modules (srfi srfi-11))} to make the bindings
1981 (let-values (((x y) (values 1 2))
1982 ((z f) (values 3 4)))
1988 @code{let-values} performs all bindings simultaneously, which means that
1989 no expression in the binding clauses may refer to variables bound in the
1990 same clause list. @code{let*-values}, on the other hand, performs the
1991 bindings sequentially, just like @code{let*} does for single-valued
1996 @subsection SRFI-13 - String Library
1999 The SRFI-13 procedures are always available, @xref{Strings}.
2002 @subsection SRFI-14 - Character-set Library
2005 The SRFI-14 data type and procedures are always available,
2006 @xref{Character Sets}.
2009 @subsection SRFI-16 - case-lambda
2011 @cindex variable arity
2012 @cindex arity, variable
2014 SRFI-16 defines a variable-arity @code{lambda} form,
2015 @code{case-lambda}. This form is available in the default Guile
2016 environment. @xref{Case-lambda}, for more information.
2019 @subsection SRFI-17 - Generalized set!
2022 This SRFI implements a generalized @code{set!}, allowing some
2023 ``referencing'' functions to be used as the target location of a
2024 @code{set!}. This feature is available from
2027 (use-modules (srfi srfi-17))
2031 For example @code{vector-ref} is extended so that
2034 (set! (vector-ref vec idx) new-value)
2041 (vector-set! vec idx new-value)
2044 The idea is that a @code{vector-ref} expression identifies a location,
2045 which may be either fetched or stored. The same form is used for the
2046 location in both cases, encouraging visual clarity. This is similar
2047 to the idea of an ``lvalue'' in C.
2049 The mechanism for this kind of @code{set!} is in the Guile core
2050 (@pxref{Procedures with Setters}). This module adds definitions of
2051 the following functions as procedures with setters, allowing them to
2052 be targets of a @code{set!},
2055 @nicode{car}, @nicode{cdr}, @nicode{caar}, @nicode{cadr},
2056 @nicode{cdar}, @nicode{cddr}, @nicode{caaar}, @nicode{caadr},
2057 @nicode{cadar}, @nicode{caddr}, @nicode{cdaar}, @nicode{cdadr},
2058 @nicode{cddar}, @nicode{cdddr}, @nicode{caaaar}, @nicode{caaadr},
2059 @nicode{caadar}, @nicode{caaddr}, @nicode{cadaar}, @nicode{cadadr},
2060 @nicode{caddar}, @nicode{cadddr}, @nicode{cdaaar}, @nicode{cdaadr},
2061 @nicode{cdadar}, @nicode{cdaddr}, @nicode{cddaar}, @nicode{cddadr},
2062 @nicode{cdddar}, @nicode{cddddr}
2064 @nicode{string-ref}, @nicode{vector-ref}
2067 The SRFI specifies @code{setter} (@pxref{Procedures with Setters}) as
2068 a procedure with setter, allowing the setter for a procedure to be
2069 changed, eg.@: @code{(set! (setter foo) my-new-setter-handler)}.
2070 Currently Guile does not implement this, a setter can only be
2071 specified on creation (@code{getter-with-setter} below).
2073 @defun getter-with-setter
2074 The same as the Guile core @code{make-procedure-with-setter}
2075 (@pxref{Procedures with Setters}).
2080 @subsection SRFI-18 - Multithreading support
2083 This is an implementation of the SRFI-18 threading and synchronization
2084 library. The functions and variables described here are provided by
2087 (use-modules (srfi srfi-18))
2090 As a general rule, the data types and functions in this SRFI-18
2091 implementation are compatible with the types and functions in Guile's
2092 core threading code. For example, mutexes created with the SRFI-18
2093 @code{make-mutex} function can be passed to the built-in Guile
2094 function @code{lock-mutex} (@pxref{Mutexes and Condition Variables}),
2095 and mutexes created with the built-in Guile function @code{make-mutex}
2096 can be passed to the SRFI-18 function @code{mutex-lock!}. Cases in
2097 which this does not hold true are noted in the following sections.
2100 * SRFI-18 Threads:: Executing code
2101 * SRFI-18 Mutexes:: Mutual exclusion devices
2102 * SRFI-18 Condition variables:: Synchronizing of groups of threads
2103 * SRFI-18 Time:: Representation of times and durations
2104 * SRFI-18 Exceptions:: Signalling and handling errors
2107 @node SRFI-18 Threads
2108 @subsubsection SRFI-18 Threads
2110 Threads created by SRFI-18 differ in two ways from threads created by
2111 Guile's built-in thread functions. First, a thread created by SRFI-18
2112 @code{make-thread} begins in a blocked state and will not start
2113 execution until @code{thread-start!} is called on it. Second, SRFI-18
2114 threads are constructed with a top-level exception handler that
2115 captures any exceptions that are thrown on thread exit. In all other
2116 regards, SRFI-18 threads are identical to normal Guile threads.
2118 @defun current-thread
2119 Returns the thread that called this function. This is the same
2120 procedure as the same-named built-in procedure @code{current-thread}
2125 Returns @code{#t} if @var{obj} is a thread, @code{#f} otherwise. This
2126 is the same procedure as the same-named built-in procedure
2127 @code{thread?} (@pxref{Threads}).
2130 @defun make-thread thunk [name]
2131 Call @code{thunk} in a new thread and with a new dynamic state,
2132 returning the new thread and optionally assigning it the object name
2133 @var{name}, which may be any Scheme object.
2135 Note that the name @code{make-thread} conflicts with the
2136 @code{(ice-9 threads)} function @code{make-thread}. Applications
2137 wanting to use both of these functions will need to refer to them by
2141 @defun thread-name thread
2142 Returns the name assigned to @var{thread} at the time of its creation,
2143 or @code{#f} if it was not given a name.
2146 @defun thread-specific thread
2147 @defunx thread-specific-set! thread obj
2148 Get or set the ``object-specific'' property of @var{thread}. In
2149 Guile's implementation of SRFI-18, this value is stored as an object
2150 property, and will be @code{#f} if not set.
2153 @defun thread-start! thread
2154 Unblocks @var{thread} and allows it to begin execution if it has not
2158 @defun thread-yield!
2159 If one or more threads are waiting to execute, calling
2160 @code{thread-yield!} forces an immediate context switch to one of them.
2161 Otherwise, @code{thread-yield!} has no effect. @code{thread-yield!}
2162 behaves identically to the Guile built-in function @code{yield}.
2165 @defun thread-sleep! timeout
2166 The current thread waits until the point specified by the time object
2167 @var{timeout} is reached (@pxref{SRFI-18 Time}). This blocks the
2168 thread only if @var{timeout} represents a point in the future. it is
2169 an error for @var{timeout} to be @code{#f}.
2172 @defun thread-terminate! thread
2173 Causes an abnormal termination of @var{thread}. If @var{thread} is
2174 not already terminated, all mutexes owned by @var{thread} become
2175 unlocked/abandoned. If @var{thread} is the current thread,
2176 @code{thread-terminate!} does not return. Otherwise
2177 @code{thread-terminate!} returns an unspecified value; the termination
2178 of @var{thread} will occur before @code{thread-terminate!} returns.
2179 Subsequent attempts to join on @var{thread} will cause a ``terminated
2180 thread exception'' to be raised.
2182 @code{thread-terminate!} is compatible with the thread cancellation
2183 procedures in the core threads API (@pxref{Threads}) in that if a
2184 cleanup handler has been installed for the target thread, it will be
2185 called before the thread exits and its return value (or exception, if
2186 any) will be stored for later retrieval via a call to
2187 @code{thread-join!}.
2190 @defun thread-join! thread [timeout [timeout-val]]
2191 Wait for @var{thread} to terminate and return its exit value. When a
2192 time value @var{timeout} is given, it specifies a point in time where
2193 the waiting should be aborted. When the waiting is aborted,
2194 @var{timeout-val} is returned if it is specified; otherwise, a
2195 @code{join-timeout-exception} exception is raised
2196 (@pxref{SRFI-18 Exceptions}). Exceptions may also be raised if the
2197 thread was terminated by a call to @code{thread-terminate!}
2198 (@code{terminated-thread-exception} will be raised) or if the thread
2199 exited by raising an exception that was handled by the top-level
2200 exception handler (@code{uncaught-exception} will be raised; the
2201 original exception can be retrieved using
2202 @code{uncaught-exception-reason}).
2206 @node SRFI-18 Mutexes
2207 @subsubsection SRFI-18 Mutexes
2209 The behavior of Guile's built-in mutexes is parameterized via a set of
2210 flags passed to the @code{make-mutex} procedure in the core
2211 (@pxref{Mutexes and Condition Variables}). To satisfy the requirements
2212 for mutexes specified by SRFI-18, the @code{make-mutex} procedure
2213 described below sets the following flags:
2216 @code{recursive}: the mutex can be locked recursively
2218 @code{unchecked-unlock}: attempts to unlock a mutex that is already
2219 unlocked will not raise an exception
2221 @code{allow-external-unlock}: the mutex can be unlocked by any thread,
2222 not just the thread that locked it originally
2225 @defun make-mutex [name]
2226 Returns a new mutex, optionally assigning it the object name
2227 @var{name}, which may be any Scheme object. The returned mutex will be
2228 created with the configuration described above. Note that the name
2229 @code{make-mutex} conflicts with Guile core function @code{make-mutex}.
2230 Applications wanting to use both of these functions will need to refer
2231 to them by different names.
2234 @defun mutex-name mutex
2235 Returns the name assigned to @var{mutex} at the time of its creation,
2236 or @code{#f} if it was not given a name.
2239 @defun mutex-specific mutex
2240 @defunx mutex-specific-set! mutex obj
2241 Get or set the ``object-specific'' property of @var{mutex}. In Guile's
2242 implementation of SRFI-18, this value is stored as an object property,
2243 and will be @code{#f} if not set.
2246 @defun mutex-state mutex
2247 Returns information about the state of @var{mutex}. Possible values
2251 thread @code{T}: the mutex is in the locked/owned state and thread T
2252 is the owner of the mutex
2254 symbol @code{not-owned}: the mutex is in the locked/not-owned state
2256 symbol @code{abandoned}: the mutex is in the unlocked/abandoned state
2258 symbol @code{not-abandoned}: the mutex is in the
2259 unlocked/not-abandoned state
2263 @defun mutex-lock! mutex [timeout [thread]]
2264 Lock @var{mutex}, optionally specifying a time object @var{timeout}
2265 after which to abort the lock attempt and a thread @var{thread} giving
2266 a new owner for @var{mutex} different than the current thread. This
2267 procedure has the same behavior as the @code{lock-mutex} procedure in
2271 @defun mutex-unlock! mutex [condition-variable [timeout]]
2272 Unlock @var{mutex}, optionally specifying a condition variable
2273 @var{condition-variable} on which to wait, either indefinitely or,
2274 optionally, until the time object @var{timeout} has passed, to be
2275 signalled. This procedure has the same behavior as the
2276 @code{unlock-mutex} procedure in the core library.
2280 @node SRFI-18 Condition variables
2281 @subsubsection SRFI-18 Condition variables
2283 SRFI-18 does not specify a ``wait'' function for condition variables.
2284 Waiting on a condition variable can be simulated using the SRFI-18
2285 @code{mutex-unlock!} function described in the previous section, or
2286 Guile's built-in @code{wait-condition-variable} procedure can be used.
2288 @defun condition-variable? obj
2289 Returns @code{#t} if @var{obj} is a condition variable, @code{#f}
2290 otherwise. This is the same procedure as the same-named built-in
2292 (@pxref{Mutexes and Condition Variables, @code{condition-variable?}}).
2295 @defun make-condition-variable [name]
2296 Returns a new condition variable, optionally assigning it the object
2297 name @var{name}, which may be any Scheme object. This procedure
2298 replaces a procedure of the same name in the core library.
2301 @defun condition-variable-name condition-variable
2302 Returns the name assigned to @var{condition-variable} at the time of its
2303 creation, or @code{#f} if it was not given a name.
2306 @defun condition-variable-specific condition-variable
2307 @defunx condition-variable-specific-set! condition-variable obj
2308 Get or set the ``object-specific'' property of
2309 @var{condition-variable}. In Guile's implementation of SRFI-18, this
2310 value is stored as an object property, and will be @code{#f} if not
2314 @defun condition-variable-signal! condition-variable
2315 @defunx condition-variable-broadcast! condition-variable
2316 Wake up one thread that is waiting for @var{condition-variable}, in
2317 the case of @code{condition-variable-signal!}, or all threads waiting
2318 for it, in the case of @code{condition-variable-broadcast!}. The
2319 behavior of these procedures is equivalent to that of the procedures
2320 @code{signal-condition-variable} and
2321 @code{broadcast-condition-variable} in the core library.
2326 @subsubsection SRFI-18 Time
2328 The SRFI-18 time functions manipulate time in two formats: a
2329 ``time object'' type that represents an absolute point in time in some
2330 implementation-specific way; and the number of seconds since some
2331 unspecified ``epoch''. In Guile's implementation, the epoch is the
2332 Unix epoch, 00:00:00 UTC, January 1, 1970.
2335 Return the current time as a time object. This procedure replaces
2336 the procedure of the same name in the core library, which returns the
2337 current time in seconds since the epoch.
2341 Returns @code{#t} if @var{obj} is a time object, @code{#f} otherwise.
2344 @defun time->seconds time
2345 @defunx seconds->time seconds
2346 Convert between time objects and numerical values representing the
2347 number of seconds since the epoch. When converting from a time object
2348 to seconds, the return value is the number of seconds between
2349 @var{time} and the epoch. When converting from seconds to a time
2350 object, the return value is a time object that represents a time
2351 @var{seconds} seconds after the epoch.
2355 @node SRFI-18 Exceptions
2356 @subsubsection SRFI-18 Exceptions
2358 SRFI-18 exceptions are identical to the exceptions provided by
2359 Guile's implementation of SRFI-34. The behavior of exception
2360 handlers invoked to handle exceptions thrown from SRFI-18 functions,
2361 however, differs from the conventional behavior of SRFI-34 in that
2362 the continuation of the handler is the same as that of the call to
2363 the function. Handlers are called in a tail-recursive manner; the
2364 exceptions do not ``bubble up''.
2366 @defun current-exception-handler
2367 Returns the current exception handler.
2370 @defun with-exception-handler handler thunk
2371 Installs @var{handler} as the current exception handler and calls the
2372 procedure @var{thunk} with no arguments, returning its value as the
2373 value of the exception. @var{handler} must be a procedure that accepts
2374 a single argument. The current exception handler at the time this
2375 procedure is called will be restored after the call returns.
2379 Raise @var{obj} as an exception. This is the same procedure as the
2380 same-named procedure defined in SRFI 34.
2383 @defun join-timeout-exception? obj
2384 Returns @code{#t} if @var{obj} is an exception raised as the result of
2385 performing a timed join on a thread that does not exit within the
2386 specified timeout, @code{#f} otherwise.
2389 @defun abandoned-mutex-exception? obj
2390 Returns @code{#t} if @var{obj} is an exception raised as the result of
2391 attempting to lock a mutex that has been abandoned by its owner thread,
2392 @code{#f} otherwise.
2395 @defun terminated-thread-exception? obj
2396 Returns @code{#t} if @var{obj} is an exception raised as the result of
2397 joining on a thread that exited as the result of a call to
2398 @code{thread-terminate!}.
2401 @defun uncaught-exception? obj
2402 @defunx uncaught-exception-reason exc
2403 @code{uncaught-exception?} returns @code{#t} if @var{obj} is an
2404 exception thrown as the result of joining a thread that exited by
2405 raising an exception that was handled by the top-level exception
2406 handler installed by @code{make-thread}. When this occurs, the
2407 original exception is preserved as part of the exception thrown by
2408 @code{thread-join!} and can be accessed by calling
2409 @code{uncaught-exception-reason} on that exception. Note that
2410 because this exception-preservation mechanism is a side-effect of
2411 @code{make-thread}, joining on threads that exited as described above
2412 but were created by other means will not raise this
2413 @code{uncaught-exception} error.
2418 @subsection SRFI-19 - Time/Date Library
2423 This is an implementation of the SRFI-19 time/date library. The
2424 functions and variables described here are provided by
2427 (use-modules (srfi srfi-19))
2430 @strong{Caution}: The current code in this module incorrectly extends
2431 the Gregorian calendar leap year rule back prior to the introduction
2432 of those reforms in 1582 (or the appropriate year in various
2433 countries). The Julian calendar was used prior to 1582, and there
2434 were 10 days skipped for the reform, but the code doesn't implement
2437 This will be fixed some time. Until then calculations for 1583
2438 onwards are correct, but prior to that any day/month/year and day of
2439 the week calculations are wrong.
2442 * SRFI-19 Introduction::
2445 * SRFI-19 Time/Date conversions::
2446 * SRFI-19 Date to string::
2447 * SRFI-19 String to date::
2450 @node SRFI-19 Introduction
2451 @subsubsection SRFI-19 Introduction
2453 @cindex universal time
2457 This module implements time and date representations and calculations,
2458 in various time systems, including universal time (UTC) and atomic
2461 For those not familiar with these time systems, TAI is based on a
2462 fixed length second derived from oscillations of certain atoms. UTC
2463 differs from TAI by an integral number of seconds, which is increased
2464 or decreased at announced times to keep UTC aligned to a mean solar
2465 day (the orbit and rotation of the earth are not quite constant).
2468 So far, only increases in the TAI
2475 UTC difference have been needed. Such an increase is a ``leap
2476 second'', an extra second of TAI introduced at the end of a UTC day.
2477 When working entirely within UTC this is never seen, every day simply
2478 has 86400 seconds. But when converting from TAI to a UTC date, an
2479 extra 23:59:60 is present, where normally a day would end at 23:59:59.
2480 Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI
2483 @cindex system clock
2484 In the current implementation, the system clock is assumed to be UTC,
2485 and a table of leap seconds in the code converts to TAI. See comments
2486 in @file{srfi-19.scm} for how to update this table.
2489 @cindex modified julian day
2490 Also, for those not familiar with the terminology, a @dfn{Julian Day}
2491 is a real number which is a count of days and fraction of a day, in
2492 UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan
2493 4713 B.C. A @dfn{Modified Julian Day} is the same, but starting from
2494 1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC. That time
2495 is julian day 2400000.5.
2497 @c The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at
2498 @c noon, UTC), but this is incorrect. It looks like it might have
2499 @c arisen from the code incorrectly treating years a multiple of 100
2500 @c but not 400 prior to 1582 as non-leap years, where instead the Julian
2501 @c calendar should be used so all multiples of 4 before 1582 are leap
2506 @subsubsection SRFI-19 Time
2509 A @dfn{time} object has type, seconds and nanoseconds fields
2510 representing a point in time starting from some epoch. This is an
2511 arbitrary point in time, not just a time of day. Although times are
2512 represented in nanoseconds, the actual resolution may be lower.
2514 The following variables hold the possible time types. For instance
2515 @code{(current-time time-process)} would give the current CPU process
2519 Universal Coordinated Time (UTC).
2524 International Atomic Time (TAI).
2528 @defvar time-monotonic
2529 Monotonic time, meaning a monotonically increasing time starting from
2530 an unspecified epoch.
2532 Note that in the current implementation @code{time-monotonic} is the
2533 same as @code{time-tai}, and unfortunately is therefore affected by
2534 adjustments to the system clock. Perhaps this will change in the
2538 @defvar time-duration
2539 A duration, meaning simply a difference between two times.
2542 @defvar time-process
2543 CPU time spent in the current process, starting from when the process
2545 @cindex process time
2549 CPU time spent in the current thread. Not currently implemented.
2555 Return @code{#t} if @var{obj} is a time object, or @code{#f} if not.
2558 @defun make-time type nanoseconds seconds
2559 Create a time object with the given @var{type}, @var{seconds} and
2563 @defun time-type time
2564 @defunx time-nanosecond time
2565 @defunx time-second time
2566 @defunx set-time-type! time type
2567 @defunx set-time-nanosecond! time nsec
2568 @defunx set-time-second! time sec
2569 Get or set the type, seconds or nanoseconds fields of a time object.
2571 @code{set-time-type!} merely changes the field, it doesn't convert the
2572 time value. For conversions, see @ref{SRFI-19 Time/Date conversions}.
2575 @defun copy-time time
2576 Return a new time object, which is a copy of the given @var{time}.
2579 @defun current-time [type]
2580 Return the current time of the given @var{type}. The default
2581 @var{type} is @code{time-utc}.
2583 Note that the name @code{current-time} conflicts with the Guile core
2584 @code{current-time} function (@pxref{Time}) as well as the SRFI-18
2585 @code{current-time} function (@pxref{SRFI-18 Time}). Applications
2586 wanting to use more than one of these functions will need to refer to
2587 them by different names.
2590 @defun time-resolution [type]
2591 Return the resolution, in nanoseconds, of the given time @var{type}.
2592 The default @var{type} is @code{time-utc}.
2595 @defun time<=? t1 t2
2596 @defunx time<? t1 t2
2597 @defunx time=? t1 t2
2598 @defunx time>=? t1 t2
2599 @defunx time>? t1 t2
2600 Return @code{#t} or @code{#f} according to the respective relation
2601 between time objects @var{t1} and @var{t2}. @var{t1} and @var{t2}
2602 must be the same time type.
2605 @defun time-difference t1 t2
2606 @defunx time-difference! t1 t2
2607 Return a time object of type @code{time-duration} representing the
2608 period between @var{t1} and @var{t2}. @var{t1} and @var{t2} must be
2611 @code{time-difference} returns a new time object,
2612 @code{time-difference!} may modify @var{t1} to form its return.
2615 @defun add-duration time duration
2616 @defunx add-duration! time duration
2617 @defunx subtract-duration time duration
2618 @defunx subtract-duration! time duration
2619 Return a time object which is @var{time} with the given @var{duration}
2620 added or subtracted. @var{duration} must be a time object of type
2621 @code{time-duration}.
2623 @code{add-duration} and @code{subtract-duration} return a new time
2624 object. @code{add-duration!} and @code{subtract-duration!} may modify
2625 the given @var{time} to form their return.
2630 @subsubsection SRFI-19 Date
2633 A @dfn{date} object represents a date in the Gregorian calendar and a
2634 time of day on that date in some timezone.
2636 The fields are year, month, day, hour, minute, second, nanoseconds and
2637 timezone. A date object is immutable, its fields can be read but they
2638 cannot be modified once the object is created.
2641 Return @code{#t} if @var{obj} is a date object, or @code{#f} if not.
2644 @defun make-date nsecs seconds minutes hours date month year zone-offset
2645 Create a new date object.
2647 @c FIXME: What can we say about the ranges of the values. The
2648 @c current code looks it doesn't normalize, but expects then in their
2649 @c usual range already.
2653 @defun date-nanosecond date
2654 Nanoseconds, 0 to 999999999.
2657 @defun date-second date
2658 Seconds, 0 to 59, or 60 for a leap second. 60 is never seen when working
2659 entirely within UTC, it's only when converting to or from TAI.
2662 @defun date-minute date
2666 @defun date-hour date
2670 @defun date-day date
2671 Day of the month, 1 to 31 (or less, according to the month).
2674 @defun date-month date
2678 @defun date-year date
2679 Year, eg.@: 2003. Dates B.C.@: are negative, eg.@: @math{-46} is 46
2680 B.C. There is no year 0, year @math{-1} is followed by year 1.
2683 @defun date-zone-offset date
2684 Time zone, an integer number of seconds east of Greenwich.
2687 @defun date-year-day date
2688 Day of the year, starting from 1 for 1st January.
2691 @defun date-week-day date
2692 Day of the week, starting from 0 for Sunday.
2695 @defun date-week-number date dstartw
2696 Week of the year, ignoring a first partial week. @var{dstartw} is the
2697 day of the week which is taken to start a week, 0 for Sunday, 1 for
2700 @c FIXME: The spec doesn't say whether numbering starts at 0 or 1.
2701 @c The code looks like it's 0, if that's the correct intention.
2705 @c The SRFI text doesn't actually give the default for tz-offset, but
2706 @c the reference implementation has the local timezone and the
2707 @c conversions functions all specify that, so it should be ok to
2708 @c document it here.
2710 @defun current-date [tz-offset]
2711 Return a date object representing the current date/time, in UTC offset
2712 by @var{tz-offset}. @var{tz-offset} is seconds east of Greenwich and
2713 defaults to the local timezone.
2716 @defun current-julian-day
2718 Return the current Julian Day.
2721 @defun current-modified-julian-day
2722 @cindex modified julian day
2723 Return the current Modified Julian Day.
2727 @node SRFI-19 Time/Date conversions
2728 @subsubsection SRFI-19 Time/Date conversions
2729 @cindex time conversion
2730 @cindex date conversion
2732 @defun date->julian-day date
2733 @defunx date->modified-julian-day date
2734 @defunx date->time-monotonic date
2735 @defunx date->time-tai date
2736 @defunx date->time-utc date
2738 @defun julian-day->date jdn [tz-offset]
2739 @defunx julian-day->time-monotonic jdn
2740 @defunx julian-day->time-tai jdn
2741 @defunx julian-day->time-utc jdn
2743 @defun modified-julian-day->date jdn [tz-offset]
2744 @defunx modified-julian-day->time-monotonic jdn
2745 @defunx modified-julian-day->time-tai jdn
2746 @defunx modified-julian-day->time-utc jdn
2748 @defun time-monotonic->date time [tz-offset]
2749 @defunx time-monotonic->time-tai time
2750 @defunx time-monotonic->time-tai! time
2751 @defunx time-monotonic->time-utc time
2752 @defunx time-monotonic->time-utc! time
2754 @defun time-tai->date time [tz-offset]
2755 @defunx time-tai->julian-day time
2756 @defunx time-tai->modified-julian-day time
2757 @defunx time-tai->time-monotonic time
2758 @defunx time-tai->time-monotonic! time
2759 @defunx time-tai->time-utc time
2760 @defunx time-tai->time-utc! time
2762 @defun time-utc->date time [tz-offset]
2763 @defunx time-utc->julian-day time
2764 @defunx time-utc->modified-julian-day time
2765 @defunx time-utc->time-monotonic time
2766 @defunx time-utc->time-monotonic! time
2767 @defunx time-utc->time-tai time
2768 @defunx time-utc->time-tai! time
2770 Convert between dates, times and days of the respective types. For
2771 instance @code{time-tai->time-utc} accepts a @var{time} object of type
2772 @code{time-tai} and returns an object of type @code{time-utc}.
2774 The @code{!} variants may modify their @var{time} argument to form
2775 their return. The plain functions create a new object.
2777 For conversions to dates, @var{tz-offset} is seconds east of
2778 Greenwich. The default is the local timezone, at the given time, as
2779 provided by the system, using @code{localtime} (@pxref{Time}).
2781 On 32-bit systems, @code{localtime} is limited to a 32-bit
2782 @code{time_t}, so a default @var{tz-offset} is only available for
2783 times between Dec 1901 and Jan 2038. For prior dates an application
2784 might like to use the value in 1902, though some locations have zone
2785 changes prior to that. For future dates an application might like to
2786 assume today's rules extend indefinitely. But for correct daylight
2787 savings transitions it will be necessary to take an offset for the
2788 same day and time but a year in range and which has the same starting
2789 weekday and same leap/non-leap (to support rules like last Sunday in
2793 @node SRFI-19 Date to string
2794 @subsubsection SRFI-19 Date to string
2795 @cindex date to string
2796 @cindex string, from date
2798 @defun date->string date [format]
2799 Convert a date to a string under the control of a format.
2800 @var{format} should be a string containing @samp{~} escapes, which
2801 will be expanded as per the following conversion table. The default
2802 @var{format} is @samp{~c}, a locale-dependent date and time.
2804 Many of these conversion characters are the same as POSIX
2805 @code{strftime} (@pxref{Time}), but there are some extras and some
2808 @multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM}
2809 @item @nicode{~~} @tab literal ~
2810 @item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun}
2811 @item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday}
2812 @item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan}
2813 @item @nicode{~B} @tab locale full month, eg.@: @samp{January}
2814 @item @nicode{~c} @tab locale date and time, eg.@: @*
2815 @samp{Fri Jul 14 20:28:42-0400 2000}
2816 @item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31}
2818 @c Spec says d/m/y, reference implementation says m/d/y.
2819 @c Apparently the reference code was the intention, but would like to
2820 @c see an errata published for the spec before contradicting it here.
2822 @c @item @nicode{~D} @tab date @nicode{~d/~m/~y}
2824 @item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31}
2825 @item @nicode{~f} @tab seconds and fractional seconds,
2826 with locale decimal point, eg.@: @samp{5.2}
2827 @item @nicode{~h} @tab same as @nicode{~b}
2828 @item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23}
2829 @item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12}
2830 @item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366}
2831 @item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23}
2832 @item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12}
2833 @item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12}
2834 @item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59}
2835 @item @nicode{~n} @tab newline
2836 @item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999}
2837 @item @nicode{~p} @tab locale AM or PM
2838 @item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p}
2839 @item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC
2840 @item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @*
2841 (usual limit is 59, 60 is a leap second)
2842 @item @nicode{~t} @tab horizontal tab character
2843 @item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S}
2844 @item @nicode{~U} @tab week of year, Sunday first day of week,
2845 @samp{00} to @samp{52}
2846 @item @nicode{~V} @tab week of year, Monday first day of week,
2847 @samp{01} to @samp{53}
2848 @item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6}
2849 @item @nicode{~W} @tab week of year, Monday first day of week,
2850 @samp{00} to @samp{52}
2852 @c The spec has ~x as an apparent duplicate of ~W, and ~X as a locale
2853 @c date. The reference code has ~x as the locale date and ~X as a
2854 @c locale time. The rule is apparently that the code should be
2855 @c believed, but would like to see an errata for the spec before
2856 @c contradicting it here.
2858 @c @item @nicode{~x} @tab week of year, Monday as first day of week,
2859 @c @samp{00} to @samp{53}
2860 @c @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00}
2862 @item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99}
2863 @item @nicode{~Y} @tab year, full, eg.@: @samp{2003}
2864 @item @nicode{~z} @tab time zone, RFC-822 style
2865 @item @nicode{~Z} @tab time zone symbol (not currently implemented)
2866 @item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d}
2867 @item @nicode{~2} @tab ISO-8601 time+zone, @samp{~H:~M:~S~z}
2868 @item @nicode{~3} @tab ISO-8601 time, @samp{~H:~M:~S}
2869 @item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~H:~M:~S~z}
2870 @item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~H:~M:~S}
2874 Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently
2875 described here, since the specification and reference implementation
2878 Conversion is locale-dependent on systems that support it
2879 (@pxref{Accessing Locale Information}). @xref{Locales,
2880 @code{setlocale}}, for information on how to change the current
2884 @node SRFI-19 String to date
2885 @subsubsection SRFI-19 String to date
2886 @cindex string to date
2887 @cindex date, from string
2889 @c FIXME: Can we say what happens when an incomplete date is
2890 @c converted? I.e. fields left as 0, or what? The spec seems to be
2893 @defun string->date input template
2894 Convert an @var{input} string to a date under the control of a
2895 @var{template} string. Return a newly created date object.
2897 Literal characters in @var{template} must match characters in
2898 @var{input} and @samp{~} escapes must match the input forms described
2899 in the table below. ``Skip to'' means characters up to one of the
2900 given type are ignored, or ``no skip'' for no skipping. ``Read'' is
2901 what's then read, and ``Set'' is the field affected in the date
2904 For example @samp{~Y} skips input characters until a digit is reached,
2905 at which point it expects a year and stores that to the year field of
2908 @multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}}
2920 @tab @nicode{char-alphabetic?}
2921 @tab locale abbreviated weekday name
2925 @tab @nicode{char-alphabetic?}
2926 @tab locale full weekday name
2929 @c Note that the SRFI spec says that ~b and ~B don't set anything,
2930 @c but that looks like a mistake. The reference implementation sets
2931 @c the month field, which seems sensible and is what we describe
2935 @tab @nicode{char-alphabetic?}
2936 @tab locale abbreviated month name
2937 @tab @nicode{date-month}
2940 @tab @nicode{char-alphabetic?}
2941 @tab locale full month name
2942 @tab @nicode{date-month}
2945 @tab @nicode{char-numeric?}
2947 @tab @nicode{date-day}
2951 @tab day of month, blank padded
2952 @tab @nicode{date-day}
2955 @tab same as @samp{~b}
2958 @tab @nicode{char-numeric?}
2960 @tab @nicode{date-hour}
2964 @tab hour, blank padded
2965 @tab @nicode{date-hour}
2968 @tab @nicode{char-numeric?}
2970 @tab @nicode{date-month}
2973 @tab @nicode{char-numeric?}
2975 @tab @nicode{date-minute}
2978 @tab @nicode{char-numeric?}
2980 @tab @nicode{date-second}
2985 @tab @nicode{date-year} within 50 years
2988 @tab @nicode{char-numeric?}
2990 @tab @nicode{date-year}
2995 @tab date-zone-offset
2998 Notice that the weekday matching forms don't affect the date object
2999 returned, instead the weekday will be derived from the day, month and
3002 Conversion is locale-dependent on systems that support it
3003 (@pxref{Accessing Locale Information}). @xref{Locales,
3004 @code{setlocale}}, for information on how to change the current
3009 @subsection SRFI-23 - Error Reporting
3012 The SRFI-23 @code{error} procedure is always available.
3015 @subsection SRFI-26 - specializing parameters
3017 @cindex parameter specialize
3018 @cindex argument specialize
3019 @cindex specialize parameter
3021 This SRFI provides a syntax for conveniently specializing selected
3022 parameters of a function. It can be used with,
3025 (use-modules (srfi srfi-26))
3028 @deffn {library syntax} cut slot1 slot2 @dots{}
3029 @deffnx {library syntax} cute slot1 slot2 @dots{}
3030 Return a new procedure which will make a call (@var{slot1} @var{slot2}
3031 @dots{}) but with selected parameters specialized to given expressions.
3033 An example will illustrate the idea. The following is a
3034 specialization of @code{write}, sending output to
3035 @code{my-output-port},
3038 (cut write <> my-output-port)
3040 (lambda (obj) (write obj my-output-port))
3043 The special symbol @code{<>} indicates a slot to be filled by an
3044 argument to the new procedure. @code{my-output-port} on the other
3045 hand is an expression to be evaluated and passed, ie.@: it specializes
3046 the behaviour of @code{write}.
3050 A slot to be filled by an argument from the created procedure.
3051 Arguments are assigned to @code{<>} slots in the order they appear in
3052 the @code{cut} form, there's no way to re-arrange arguments.
3054 The first argument to @code{cut} is usually a procedure (or expression
3055 giving a procedure), but @code{<>} is allowed there too. For example,
3060 (lambda (proc) (proc 1 2 3))
3064 A slot to be filled by all remaining arguments from the new procedure.
3065 This can only occur at the end of a @code{cut} form.
3067 For example, a procedure taking a variable number of arguments like
3068 @code{max} but in addition enforcing a lower bound,
3071 (define my-lower-bound 123)
3073 (cut max my-lower-bound <...>)
3075 (lambda arglist (apply max my-lower-bound arglist))
3079 For @code{cut} the specializing expressions are evaluated each time
3080 the new procedure is called. For @code{cute} they're evaluated just
3081 once, when the new procedure is created. The name @code{cute} stands
3082 for ``@code{cut} with evaluated arguments''. In all cases the
3083 evaluations take place in an unspecified order.
3085 The following illustrates the difference between @code{cut} and
3089 (cut format <> "the time is ~s" (current-time))
3091 (lambda (port) (format port "the time is ~s" (current-time)))
3093 (cute format <> "the time is ~s" (current-time))
3095 (let ((val (current-time)))
3096 (lambda (port) (format port "the time is ~s" val))
3099 (There's no provision for a mixture of @code{cut} and @code{cute}
3100 where some expressions would be evaluated every time but others
3101 evaluated only once.)
3103 @code{cut} is really just a shorthand for the sort of @code{lambda}
3104 forms shown in the above examples. But notice @code{cut} avoids the
3105 need to name unspecialized parameters, and is more compact. Use in
3106 functional programming style or just with @code{map}, @code{for-each}
3107 or similar is typical.
3110 (map (cut * 2 <>) '(1 2 3 4))
3112 (for-each (cut write <> my-port) my-list)
3117 @subsection SRFI-27 - Sources of Random Bits
3120 This subsection is based on the
3121 @uref{http://srfi.schemers.org/srfi-27/srfi-27.html, specification of
3122 SRFI-27} written by Sebastian Egner.
3124 @c The copyright notice and license text of the SRFI-27 specification is
3125 @c reproduced below:
3127 @c Copyright (C) Sebastian Egner (2002). All Rights Reserved.
3129 @c Permission is hereby granted, free of charge, to any person obtaining a
3130 @c copy of this software and associated documentation files (the
3131 @c "Software"), to deal in the Software without restriction, including
3132 @c without limitation the rights to use, copy, modify, merge, publish,
3133 @c distribute, sublicense, and/or sell copies of the Software, and to
3134 @c permit persons to whom the Software is furnished to do so, subject to
3135 @c the following conditions:
3137 @c The above copyright notice and this permission notice shall be included
3138 @c in all copies or substantial portions of the Software.
3140 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3141 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3142 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3143 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3144 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3145 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3146 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3148 This SRFI provides access to a (pseudo) random number generator; for
3149 Guile's built-in random number facilities, which SRFI-27 is implemented
3150 upon, @xref{Random}. With SRFI-27, random numbers are obtained from a
3151 @emph{random source}, which encapsulates a random number generation
3152 algorithm and its state.
3155 * SRFI-27 Default Random Source:: Obtaining random numbers
3156 * SRFI-27 Random Sources:: Creating and manipulating random sources
3157 * SRFI-27 Random Number Generators:: Obtaining random number generators
3160 @node SRFI-27 Default Random Source
3161 @subsubsection The Default Random Source
3164 @defun random-integer n
3165 Return a random number between zero (inclusive) and @var{n} (exclusive),
3166 using the default random source. The numbers returned have a uniform
3171 Return a random number in (0,1), using the default random source. The
3172 numbers returned have a uniform distribution.
3175 @defun default-random-source
3176 A random source from which @code{random-integer} and @code{random-real}
3177 have been derived using @code{random-source-make-integers} and
3178 @code{random-source-make-reals} (@pxref{SRFI-27 Random Number Generators}
3179 for those procedures). Note that an assignment to
3180 @code{default-random-source} does not change @code{random-integer} or
3181 @code{random-real}; it is also strongly recommended not to assign a new
3185 @node SRFI-27 Random Sources
3186 @subsubsection Random Sources
3189 @defun make-random-source
3190 Create a new random source. The stream of random numbers obtained from
3191 each random source created by this procedure will be identical, unless
3192 its state is changed by one of the procedures below.
3195 @defun random-source? object
3196 Tests whether @var{object} is a random source. Random sources are a
3200 @defun random-source-randomize! source
3201 Attempt to set the state of the random source to a truly random value.
3202 The current implementation uses a seed based on the current system time.
3205 @defun random-source-pseudo-randomize! source i j
3206 Changes the state of the random source s into the initial state of the
3207 (@var{i}, @var{j})-th independent random source, where @var{i} and
3208 @var{j} are non-negative integers. This procedure provides a mechanism
3209 to obtain a large number of independent random sources (usually all
3210 derived from the same backbone generator), indexed by two integers. In
3211 contrast to @code{random-source-randomize!}, this procedure is entirely
3215 The state associated with a random state can be obtained an reinstated
3216 with the following procedures:
3218 @defun random-source-state-ref source
3219 @defunx random-source-state-set! source state
3220 Get and set the state of a random source. No assumptions should be made
3221 about the nature of the state object, besides it having an external
3222 representation (i.e.@: it can be passed to @code{write} and subsequently
3226 @node SRFI-27 Random Number Generators
3227 @subsubsection Obtaining random number generator procedures
3230 @defun random-source-make-integers source
3231 Obtains a procedure to generate random integers using the random source
3232 @var{source}. The returned procedure takes a single argument @var{n},
3233 which must be a positive integer, and returns the next uniformly
3234 distributed random integer from the interval @{0, ..., @var{n}-1@} by
3235 advancing the state of @var{source}.
3237 If an application obtains and uses several generators for the same
3238 random source @var{source}, a call to any of these generators advances
3239 the state of @var{source}. Hence, the generators do not produce the
3240 same sequence of random integers each but rather share a state. This
3241 also holds for all other types of generators derived from a fixed random
3244 While the SRFI text specifies that ``Implementations that support
3245 concurrency make sure that the state of a generator is properly
3246 advanced'', this is currently not the case in Guile's implementation of
3247 SRFI-27, as it would cause a severe performance penalty. So in
3248 multi-threaded programs, you either must perform locking on random
3249 sources shared between threads yourself, or use different random sources
3250 for multiple threads.
3253 @defun random-source-make-reals source
3254 @defunx random-source-make-reals source unit
3255 Obtains a procedure to generate random real numbers @math{0 < x < 1}
3256 using the random source @var{source}. The procedure rand is called
3259 The optional parameter @var{unit} determines the type of numbers being
3260 produced by the returned procedure and the quantization of the output.
3261 @var{unit} must be a number such that @math{0 < @var{unit} < 1}. The
3262 numbers created by the returned procedure are of the same numerical type
3263 as @var{unit} and the potential output values are spaced by at most
3264 @var{unit}. One can imagine rand to create numbers as @var{x} *
3265 @var{unit} where @var{x} is a random integer in @{1, ...,
3266 floor(1/unit)-1@}. Note, however, that this need not be the way the
3267 values are actually created and that the actual resolution of rand can
3268 be much higher than unit. In case @var{unit} is absent it defaults to a
3269 reasonably small value (related to the width of the mantissa of an
3270 efficient number format).
3274 @subsection SRFI-28 - Basic Format Strings
3277 SRFI-28 provides a basic @code{format} procedure that provides only
3278 the @code{~a}, @code{~s}, @code{~%}, and @code{~~} format specifiers.
3279 You can import this procedure by using:
3282 (use-modules (srfi srfi-28))
3285 @deffn {Scheme Procedure} format message arg @dots{}
3286 Returns a formatted message, using @var{message} as the format string,
3287 which can contain the following format specifiers:
3291 Insert the textual representation of the next @var{arg}, as if printed
3295 Insert the textual representation of the next @var{arg}, as if printed
3305 This procedure is the same as calling @code{simple-format} (@pxref{Writing})
3306 with @code{#f} as the destination.
3310 @subsection SRFI-30 - Nested Multi-line Comments
3313 Starting from version 2.0, Guile's @code{read} supports SRFI-30/R6RS
3314 nested multi-line comments by default, @ref{Block Comments}.
3317 @subsection SRFI-31 - A special form `rec' for recursive evaluation
3319 @cindex recursive expression
3322 SRFI-31 defines a special form that can be used to create
3323 self-referential expressions more conveniently. The syntax is as
3328 <rec expression> --> (rec <variable> <expression>)
3329 <rec expression> --> (rec (<variable>+) <body>)
3333 The first syntax can be used to create self-referential expressions,
3337 guile> (define tmp (rec ones (cons 1 (delay ones))))
3340 The second syntax can be used to create anonymous recursive functions:
3343 guile> (define tmp (rec (display-n item n)
3345 (begin (display n) (display-n (- n 1))))))
3353 @subsection SRFI-34 - Exception handling for programs
3356 Guile provides an implementation of
3357 @uref{http://srfi.schemers.org/srfi-34/srfi-34.html, SRFI-34's exception
3358 handling mechanisms} as an alternative to its own built-in mechanisms
3359 (@pxref{Exceptions}). It can be made available as follows:
3362 (use-modules (srfi srfi-34))
3365 @c FIXME: Document it.
3369 @subsection SRFI-35 - Conditions
3375 @uref{http://srfi.schemers.org/srfi-35/srfi-35.html, SRFI-35} implements
3376 @dfn{conditions}, a data structure akin to records designed to convey
3377 information about exceptional conditions between parts of a program. It
3378 is normally used in conjunction with SRFI-34's @code{raise}:
3381 (raise (condition (&message
3382 (message "An error occurred"))))
3385 Users can define @dfn{condition types} containing arbitrary information.
3386 Condition types may inherit from one another. This allows the part of
3387 the program that handles (or ``catches'') conditions to get accurate
3388 information about the exceptional condition that arose.
3390 SRFI-35 conditions are made available using:
3393 (use-modules (srfi srfi-35))
3396 The procedures available to manipulate condition types are the
3399 @deffn {Scheme Procedure} make-condition-type id parent field-names
3400 Return a new condition type named @var{id}, inheriting from
3401 @var{parent}, and with the fields whose names are listed in
3402 @var{field-names}. @var{field-names} must be a list of symbols and must
3403 not contain names already used by @var{parent} or one of its supertypes.
3406 @deffn {Scheme Procedure} condition-type? obj
3407 Return true if @var{obj} is a condition type.
3410 Conditions can be created and accessed with the following procedures:
3412 @deffn {Scheme Procedure} make-condition type . field+value
3413 Return a new condition of type @var{type} with fields initialized as
3414 specified by @var{field+value}, a sequence of field names (symbols) and
3415 values as in the following example:
3418 (let ((&ct (make-condition-type 'foo &condition '(a b c))))
3419 (make-condition &ct 'a 1 'b 2 'c 3))
3422 Note that all fields of @var{type} and its supertypes must be specified.
3425 @deffn {Scheme Procedure} make-compound-condition condition1 condition2 @dots{}
3426 Return a new compound condition composed of @var{condition1}
3427 @var{condition2} @enddots{}. The returned condition has the type of
3428 each condition of condition1 condition2 @dots{} (per
3429 @code{condition-has-type?}).
3432 @deffn {Scheme Procedure} condition-has-type? c type
3433 Return true if condition @var{c} has type @var{type}.
3436 @deffn {Scheme Procedure} condition-ref c field-name
3437 Return the value of the field named @var{field-name} from condition @var{c}.
3439 If @var{c} is a compound condition and several underlying condition
3440 types contain a field named @var{field-name}, then the value of the
3441 first such field is returned, using the order in which conditions were
3442 passed to @code{make-compound-condition}.
3445 @deffn {Scheme Procedure} extract-condition c type
3446 Return a condition of condition type @var{type} with the field values
3447 specified by @var{c}.
3449 If @var{c} is a compound condition, extract the field values from the
3450 subcondition belonging to @var{type} that appeared first in the call to
3451 @code{make-compound-condition} that created the condition.
3454 Convenience macros are also available to create condition types and
3457 @deffn {library syntax} define-condition-type type supertype predicate field-spec...
3458 Define a new condition type named @var{type} that inherits from
3459 @var{supertype}. In addition, bind @var{predicate} to a type predicate
3460 that returns true when passed a condition of type @var{type} or any of
3461 its subtypes. @var{field-spec} must have the form @code{(field
3462 accessor)} where @var{field} is the name of field of @var{type} and
3463 @var{accessor} is the name of a procedure to access field @var{field} in
3464 conditions of type @var{type}.
3466 The example below defines condition type @code{&foo}, inheriting from
3467 @code{&condition} with fields @code{a}, @code{b} and @code{c}:
3470 (define-condition-type &foo &condition
3478 @deffn {library syntax} condition type-field-binding1 type-field-binding2 @dots{}
3479 Return a new condition or compound condition, initialized according to
3480 @var{type-field-binding1} @var{type-field-binding2} @enddots{}. Each
3481 @var{type-field-binding} must have the form @code{(type
3482 field-specs...)}, where @var{type} is the name of a variable bound to a
3483 condition type; each @var{field-spec} must have the form
3484 @code{(field-name value)} where @var{field-name} is a symbol denoting
3485 the field being initialized to @var{value}. As for
3486 @code{make-condition}, all fields must be specified.
3488 The following example returns a simple condition:
3491 (condition (&message (message "An error occurred")))
3494 The one below returns a compound condition:
3497 (condition (&message (message "An error occurred"))
3502 Finally, SRFI-35 defines a several standard condition types.
3505 This condition type is the root of all condition types. It has no
3510 A condition type that carries a message describing the nature of the
3511 condition to humans.
3514 @deffn {Scheme Procedure} message-condition? c
3515 Return true if @var{c} is of type @code{&message} or one of its
3519 @deffn {Scheme Procedure} condition-message c
3520 Return the message associated with message condition @var{c}.
3524 This type describes conditions serious enough that they cannot safely be
3525 ignored. It has no fields.
3528 @deffn {Scheme Procedure} serious-condition? c
3529 Return true if @var{c} is of type @code{&serious} or one of its
3534 This condition describes errors, typically caused by something that has
3535 gone wrong in the interaction of the program with the external world or
3539 @deffn {Scheme Procedure} error? c
3540 Return true if @var{c} is of type @code{&error} or one of its subtypes.
3544 @subsection SRFI-37 - args-fold
3547 This is a processor for GNU @code{getopt_long}-style program
3548 arguments. It provides an alternative, less declarative interface
3549 than @code{getopt-long} in @code{(ice-9 getopt-long)}
3550 (@pxref{getopt-long,,The (ice-9 getopt-long) Module}). Unlike
3551 @code{getopt-long}, it supports repeated options and any number of
3552 short and long names per option. Access it with:
3555 (use-modules (srfi srfi-37))
3558 @acronym{SRFI}-37 principally provides an @code{option} type and the
3559 @code{args-fold} function. To use the library, create a set of
3560 options with @code{option} and use it as a specification for invoking
3563 Here is an example of a simple argument processor for the typical
3564 @samp{--version} and @samp{--help} options, which returns a backwards
3565 list of files given on the command line:
3568 (args-fold (cdr (program-arguments))
3569 (let ((display-and-exit-proc
3571 (lambda (opt name arg loads)
3572 (display msg) (quit)))))
3573 (list (option '(#\v "version") #f #f
3574 (display-and-exit-proc "Foo version 42.0\n"))
3575 (option '(#\h "help") #f #f
3576 (display-and-exit-proc
3577 "Usage: foo scheme-file ..."))))
3578 (lambda (opt name arg loads)
3579 (error "Unrecognized option `~A'" name))
3580 (lambda (op loads) (cons op loads))
3584 @deffn {Scheme Procedure} option names required-arg? optional-arg? processor
3585 Return an object that specifies a single kind of program option.
3587 @var{names} is a list of command-line option names, and should consist of
3588 characters for traditional @code{getopt} short options and strings for
3589 @code{getopt_long}-style long options.
3591 @var{required-arg?} and @var{optional-arg?} are mutually exclusive;
3592 one or both must be @code{#f}. If @var{required-arg?}, the option
3593 must be followed by an argument on the command line, such as
3594 @samp{--opt=value} for long options, or an error will be signalled.
3595 If @var{optional-arg?}, an argument will be taken if available.
3597 @var{processor} is a procedure that takes at least 3 arguments, called
3598 when @code{args-fold} encounters the option: the containing option
3599 object, the name used on the command line, and the argument given for
3600 the option (or @code{#f} if none). The rest of the arguments are
3601 @code{args-fold} ``seeds'', and the @var{processor} should return
3605 @deffn {Scheme Procedure} option-names opt
3606 @deffnx {Scheme Procedure} option-required-arg? opt
3607 @deffnx {Scheme Procedure} option-optional-arg? opt
3608 @deffnx {Scheme Procedure} option-processor opt
3609 Return the specified field of @var{opt}, an option object, as
3610 described above for @code{option}.
3613 @deffn {Scheme Procedure} args-fold args options unrecognized-option-proc operand-proc seed @dots{}
3614 Process @var{args}, a list of program arguments such as that returned by
3615 @code{(cdr (program-arguments))}, in order against @var{options}, a list
3616 of option objects as described above. All functions called take the
3617 ``seeds'', or the last multiple-values as multiple arguments, starting
3618 with @var{seed} @dots{}, and must return the new seeds. Return the
3621 Call @code{unrecognized-option-proc}, which is like an option object's
3622 processor, for any options not found in @var{options}.
3624 Call @code{operand-proc} with any items on the command line that are
3625 not named options. This includes arguments after @samp{--}. It is
3626 called with the argument in question, as well as the seeds.
3630 @subsection SRFI-38 - External Representation for Data With Shared Structure
3633 This subsection is based on
3634 @uref{http://srfi.schemers.org/srfi-38/srfi-38.html, the specification
3635 of SRFI-38} written by Ray Dillinger.
3637 @c Copyright (C) Ray Dillinger 2003. All Rights Reserved.
3639 @c Permission is hereby granted, free of charge, to any person obtaining a
3640 @c copy of this software and associated documentation files (the
3641 @c "Software"), to deal in the Software without restriction, including
3642 @c without limitation the rights to use, copy, modify, merge, publish,
3643 @c distribute, sublicense, and/or sell copies of the Software, and to
3644 @c permit persons to whom the Software is furnished to do so, subject to
3645 @c the following conditions:
3647 @c The above copyright notice and this permission notice shall be included
3648 @c in all copies or substantial portions of the Software.
3650 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3651 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3652 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3653 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3654 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3655 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3656 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3658 This SRFI creates an alternative external representation for data
3659 written and read using @code{write-with-shared-structure} and
3660 @code{read-with-shared-structure}. It is identical to the grammar for
3661 external representation for data written and read with @code{write} and
3662 @code{read} given in section 7 of R5RS, except that the single
3666 <datum> --> <simple datum> | <compound datum>
3669 is replaced by the following five productions:
3672 <datum> --> <defining datum> | <nondefining datum> | <defined datum>
3673 <defining datum> --> #<indexnum>=<nondefining datum>
3674 <defined datum> --> #<indexnum>#
3675 <nondefining datum> --> <simple datum> | <compound datum>
3676 <indexnum> --> <digit 10>+
3679 @deffn {Scheme procedure} write-with-shared-structure obj
3680 @deffnx {Scheme procedure} write-with-shared-structure obj port
3681 @deffnx {Scheme procedure} write-with-shared-structure obj port optarg
3683 Writes an external representation of @var{obj} to the given port.
3684 Strings that appear in the written representation are enclosed in
3685 doublequotes, and within those strings backslash and doublequote
3686 characters are escaped by backslashes. Character objects are written
3687 using the @code{#\} notation.
3689 Objects which denote locations rather than values (cons cells, vectors,
3690 and non-zero-length strings in R5RS scheme; also Guile's structs,
3691 bytevectors and ports and hash-tables), if they appear at more than one
3692 point in the data being written, are preceded by @samp{#@var{N}=} the
3693 first time they are written and replaced by @samp{#@var{N}#} all
3694 subsequent times they are written, where @var{N} is a natural number
3695 used to identify that particular object. If objects which denote
3696 locations occur only once in the structure, then
3697 @code{write-with-shared-structure} must produce the same external
3698 representation for those objects as @code{write}.
3700 @code{write-with-shared-structure} terminates in finite time and
3701 produces a finite representation when writing finite data.
3703 @code{write-with-shared-structure} returns an unspecified value. The
3704 @var{port} argument may be omitted, in which case it defaults to the
3705 value returned by @code{(current-output-port)}. The @var{optarg}
3706 argument may also be omitted. If present, its effects on the output and
3707 return value are unspecified but @code{write-with-shared-structure} must
3708 still write a representation that can be read by
3709 @code{read-with-shared-structure}. Some implementations may wish to use
3710 @var{optarg} to specify formatting conventions, numeric radixes, or
3711 return values. Guile's implementation ignores @var{optarg}.
3713 For example, the code
3716 (begin (define a (cons 'val1 'val2))
3718 (write-with-shared-structure a))
3721 should produce the output @code{#1=(val1 . #1#)}. This shows a cons
3722 cell whose @code{cdr} contains itself.
3726 @deffn {Scheme procedure} read-with-shared-structure
3727 @deffnx {Scheme procedure} read-with-shared-structure port
3729 @code{read-with-shared-structure} converts the external representations
3730 of Scheme objects produced by @code{write-with-shared-structure} into
3731 Scheme objects. That is, it is a parser for the nonterminal
3732 @samp{<datum>} in the augmented external representation grammar defined
3733 above. @code{read-with-shared-structure} returns the next object
3734 parsable from the given input port, updating @var{port} to point to the
3735 first character past the end of the external representation of the
3738 If an end-of-file is encountered in the input before any characters are
3739 found that can begin an object, then an end-of-file object is returned.
3740 The port remains open, and further attempts to read it (by
3741 @code{read-with-shared-structure} or @code{read} will also return an
3742 end-of-file object. If an end of file is encountered after the
3743 beginning of an object's external representation, but the external
3744 representation is incomplete and therefore not parsable, an error is
3747 The @var{port} argument may be omitted, in which case it defaults to the
3748 value returned by @code{(current-input-port)}. It is an error to read
3754 @subsection SRFI-39 - Parameters
3757 This SRFI adds support for dynamically-scoped parameters. SRFI 39 is
3758 implemented in the Guile core; there's no module needed to get SRFI-39
3759 itself. Parameters are documented in @ref{Parameters}.
3761 This module does export one extra function: @code{with-parameters*}.
3762 This is a Guile-specific addition to the SRFI, similar to the core
3763 @code{with-fluids*} (@pxref{Fluids and Dynamic States}).
3765 @defun with-parameters* param-list value-list thunk
3766 Establish a new dynamic scope, as per @code{parameterize} above,
3767 taking parameters from @var{param-list} and corresponding values from
3768 @var{value-list}. A call @code{(@var{thunk})} is made in the new
3769 scope and the result from that @var{thunk} is the return from
3770 @code{with-parameters*}.
3774 @subsection SRFI-41 - Streams
3777 This subsection is based on the
3778 @uref{http://srfi.schemers.org/srfi-41/srfi-41.html, specification of
3779 SRFI-41} by Philip L.@: Bewig.
3781 @c The copyright notice and license text of the SRFI-41 specification is
3782 @c reproduced below:
3784 @c Copyright (C) Philip L. Bewig (2007). All Rights Reserved.
3786 @c Permission is hereby granted, free of charge, to any person obtaining a
3787 @c copy of this software and associated documentation files (the
3788 @c "Software"), to deal in the Software without restriction, including
3789 @c without limitation the rights to use, copy, modify, merge, publish,
3790 @c distribute, sublicense, and/or sell copies of the Software, and to
3791 @c permit persons to whom the Software is furnished to do so, subject to
3792 @c the following conditions:
3794 @c The above copyright notice and this permission notice shall be included
3795 @c in all copies or substantial portions of the Software.
3797 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3798 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3799 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3800 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3801 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3802 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3803 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3806 This SRFI implements streams, sometimes called lazy lists, a sequential
3807 data structure containing elements computed only on demand. A stream is
3808 either null or is a pair with a stream in its cdr. Since elements of a
3809 stream are computed only when accessed, streams can be infinite. Once
3810 computed, the value of a stream element is cached in case it is needed
3811 again. SRFI-41 can be made available with:
3814 (use-modules (srfi srfi-41))
3818 * SRFI-41 Stream Fundamentals::
3819 * SRFI-41 Stream Primitives::
3820 * SRFI-41 Stream Library::
3823 @node SRFI-41 Stream Fundamentals
3824 @subsubsection SRFI-41 Stream Fundamentals
3826 SRFI-41 Streams are based on two mutually-recursive abstract data types:
3827 An object of the @code{stream} abstract data type is a promise that,
3828 when forced, is either @code{stream-null} or is an object of type
3829 @code{stream-pair}. An object of the @code{stream-pair} abstract data
3830 type contains a @code{stream-car} and a @code{stream-cdr}, which must be
3831 a @code{stream}. The essential feature of streams is the systematic
3832 suspensions of the recursive promises between the two data types.
3834 The object stored in the @code{stream-car} of a @code{stream-pair} is a
3835 promise that is forced the first time the @code{stream-car} is accessed;
3836 its value is cached in case it is needed again. The object may have any
3837 type, and different stream elements may have different types. If the
3838 @code{stream-car} is never accessed, the object stored there is never
3839 evaluated. Likewise, the @code{stream-cdr} is a promise to return a
3840 stream, and is only forced on demand.
3842 @node SRFI-41 Stream Primitives
3843 @subsubsection SRFI-41 Stream Primitives
3845 This library provides eight operators: constructors for
3846 @code{stream-null} and @code{stream-pair}s, type predicates for streams
3847 and the two kinds of streams, accessors for both fields of a
3848 @code{stream-pair}, and a lambda that creates procedures that return
3851 @defvr {Scheme Variable} stream-null
3852 A promise that, when forced, is a single object, distinguishable from
3853 all other objects, that represents the null stream. @code{stream-null}
3854 is immutable and unique.
3857 @deffn {Scheme Syntax} stream-cons object-expr stream-expr
3858 Creates a newly-allocated stream containing a promise that, when forced,
3859 is a @code{stream-pair} with @var{object-expr} in its @code{stream-car}
3860 and @var{stream-expr} in its @code{stream-cdr}. Neither
3861 @var{object-expr} nor @var{stream-expr} is evaluated when
3862 @code{stream-cons} is called.
3864 Once created, a @code{stream-pair} is immutable; there is no
3865 @code{stream-set-car!} or @code{stream-set-cdr!} that modifies an
3866 existing stream-pair. There is no dotted-pair or improper stream as
3870 @deffn {Scheme Procedure} stream? object
3871 Returns true if @var{object} is a stream, otherwise returns false. If
3872 @var{object} is a stream, its promise will not be forced. If
3873 @code{(stream? obj)} returns true, then one of @code{(stream-null? obj)}
3874 or @code{(stream-pair? obj)} will return true and the other will return
3878 @deffn {Scheme Procedure} stream-null? object
3879 Returns true if @var{object} is the distinguished null stream, otherwise
3880 returns false. If @var{object} is a stream, its promise will be forced.
3883 @deffn {Scheme Procedure} stream-pair? object
3884 Returns true if @var{object} is a @code{stream-pair} constructed by
3885 @code{stream-cons}, otherwise returns false. If @var{object} is a
3886 stream, its promise will be forced.
3889 @deffn {Scheme Procedure} stream-car stream
3890 Returns the object stored in the @code{stream-car} of @var{stream}. An
3891 error is signalled if the argument is not a @code{stream-pair}. This
3892 causes the @var{object-expr} passed to @code{stream-cons} to be
3893 evaluated if it had not yet been; the value is cached in case it is
3897 @deffn {Scheme Procedure} stream-cdr stream
3898 Returns the stream stored in the @code{stream-cdr} of @var{stream}. An
3899 error is signalled if the argument is not a @code{stream-pair}.
3902 @deffn {Scheme Syntax} stream-lambda formals body @dots{}
3903 Creates a procedure that returns a promise to evaluate the @var{body} of
3904 the procedure. The last @var{body} expression to be evaluated must
3905 yield a stream. As with normal @code{lambda}, @var{formals} may be a
3906 single variable name, in which case all the formal arguments are
3907 collected into a single list, or a list of variable names, which may be
3908 null if there are no arguments, proper if there are an exact number of
3909 arguments, or dotted if a fixed number of arguments is to be followed by
3910 zero or more arguments collected into a list. @var{Body} must contain
3911 at least one expression, and may contain internal definitions preceding
3912 any expressions to be evaluated.
3922 (stream-car strm123) @result{} 1
3923 (stream-car (stream-cdr strm123) @result{} 2
3927 (stream-cons (/ 1 0) stream-null))) @result{} #f
3929 (stream? (list 1 2 3)) @result{} #f
3932 (stream-lambda (f x)
3933 (stream-cons x (iter f (f x)))))
3935 (define nats (iter (lambda (x) (+ x 1)) 0))
3937 (stream-car (stream-cdr nats)) @result{} 1
3940 (stream-lambda (s1 s2)
3942 (+ (stream-car s1) (stream-car s2))
3943 (stream-add (stream-cdr s1)
3946 (define evens (stream-add nats nats))
3948 (stream-car evens) @result{} 0
3949 (stream-car (stream-cdr evens)) @result{} 2
3950 (stream-car (stream-cdr (stream-cdr evens))) @result{} 4
3953 @node SRFI-41 Stream Library
3954 @subsubsection SRFI-41 Stream Library
3956 @deffn {Scheme Syntax} define-stream (name args @dots{}) body @dots{}
3957 Creates a procedure that returns a stream, and may appear anywhere a
3958 normal @code{define} may appear, including as an internal definition.
3959 It may contain internal definitions of its own. The defined procedure
3960 takes arguments in the same way as @code{stream-lambda}.
3961 @code{define-stream} is syntactic sugar on @code{stream-lambda}; see
3962 also @code{stream-let}, which is also a sugaring of
3963 @code{stream-lambda}.
3965 A simple version of @code{stream-map} that takes only a single input
3966 stream calls itself recursively:
3969 (define-stream (stream-map proc strm)
3970 (if (stream-null? strm)
3973 (proc (stream-car strm))
3974 (stream-map proc (stream-cdr strm))))))
3978 @deffn {Scheme Procedure} list->stream list
3979 Returns a newly-allocated stream containing the elements from
3983 @deffn {Scheme Procedure} port->stream [port]
3984 Returns a newly-allocated stream containing in its elements the
3985 characters on the port. If @var{port} is not given it defaults to the
3986 current input port. The returned stream has finite length and is
3987 terminated by @code{stream-null}.
3989 It looks like one use of @code{port->stream} would be this:
3993 (with-input-from-file filename
3994 (lambda () (port->stream))))
3997 But that fails, because @code{with-input-from-file} is eager, and closes
3998 the input port prematurely, before the first character is read. To read
3999 a file into a stream, say:
4002 (define-stream (file->stream filename)
4003 (let ((p (open-input-file filename)))
4004 (stream-let loop ((c (read-char p)))
4006 (begin (close-input-port p)
4009 (loop (read-char p)))))))
4013 @deffn {Scheme Syntax} stream object-expr @dots{}
4014 Creates a newly-allocated stream containing in its elements the objects,
4015 in order. The @var{object-expr}s are evaluated when they are accessed,
4016 not when the stream is created. If no objects are given, as in
4017 (stream), the null stream is returned. See also @code{list->stream}.
4020 (define strm123 (stream 1 2 3))
4022 ; (/ 1 0) not evaluated when stream is created
4023 (define s (stream 1 (/ 1 0) -1))
4027 @deffn {Scheme Procedure} stream->list [n] stream
4028 Returns a newly-allocated list containing in its elements the first
4029 @var{n} items in @var{stream}. If @var{stream} has less than @var{n}
4030 items, all the items in the stream will be included in the returned
4031 list. If @var{n} is not given it defaults to infinity, which means that
4032 unless @var{stream} is finite @code{stream->list} will never return.
4036 (stream-map (lambda (x) (* x x))
4038 @result{} (0 1 4 9 16 25 36 49 64 81)
4042 @deffn {Scheme Procedure} stream-append stream @dots{}
4043 Returns a newly-allocated stream containing in its elements those
4044 elements contained in its input @var{stream}s, in order of input. If
4045 any of the input streams is infinite, no elements of any of the
4046 succeeding input streams will appear in the output stream. See also
4047 @code{stream-concat}.
4050 @deffn {Scheme Procedure} stream-concat stream
4051 Takes a @var{stream} consisting of one or more streams and returns a
4052 newly-allocated stream containing all the elements of the input streams.
4053 If any of the streams in the input @var{stream} is infinite, any
4054 remaining streams in the input stream will never appear in the output
4055 stream. See also @code{stream-append}.
4058 @deffn {Scheme Procedure} stream-constant object @dots{}
4059 Returns a newly-allocated stream containing in its elements the
4060 @var{object}s, repeating in succession forever.
4063 (stream-constant 1) @result{} 1 1 1 @dots{}
4064 (stream-constant #t #f) @result{} #t #f #t #f #t #f @dots{}
4068 @deffn {Scheme Procedure} stream-drop n stream
4069 Returns the suffix of the input @var{stream} that starts at the next
4070 element after the first @var{n} elements. The output stream shares
4071 structure with the input @var{stream}; thus, promises forced in one
4072 instance of the stream are also forced in the other instance of the
4073 stream. If the input @var{stream} has less than @var{n} elements,
4074 @code{stream-drop} returns the null stream. See also
4078 @deffn {Scheme Procedure} stream-drop-while pred stream
4079 Returns the suffix of the input @var{stream} that starts at the first
4080 element @var{x} for which @code{(pred x)} returns false. The output
4081 stream shares structure with the input @var{stream}. See also
4082 @code{stream-take-while}.
4085 @deffn {Scheme Procedure} stream-filter pred stream
4086 Returns a newly-allocated stream that contains only those elements
4087 @var{x} of the input @var{stream} which satisfy the predicate
4091 (stream-filter odd? (stream-from 0))
4092 @result{} 1 3 5 7 9 @dots{}
4096 @deffn {Scheme Procedure} stream-fold proc base stream
4097 Applies a binary procedure @var{proc} to @var{base} and the first
4098 element of @var{stream} to compute a new @var{base}, then applies the
4099 procedure to the new @var{base} and the next element of @var{stream} to
4100 compute a succeeding @var{base}, and so on, accumulating a value that is
4101 finally returned as the value of @code{stream-fold} when the end of the
4102 stream is reached. @var{stream} must be finite, or @code{stream-fold}
4103 will enter an infinite loop. See also @code{stream-scan}, which is
4104 similar to @code{stream-fold}, but useful for infinite streams. For
4105 readers familiar with other functional languages, this is a left-fold;
4106 there is no corresponding right-fold, since right-fold relies on finite
4107 streams that are fully-evaluated, in which case they may as well be
4108 converted to a list.
4111 @deffn {Scheme Procedure} stream-for-each proc stream @dots{}
4112 Applies @var{proc} element-wise to corresponding elements of the input
4113 @var{stream}s for side-effects; it returns nothing.
4114 @code{stream-for-each} stops as soon as any of its input streams is
4118 @deffn {Scheme Procedure} stream-from first [step]
4119 Creates a newly-allocated stream that contains @var{first} as its first
4120 element and increments each succeeding element by @var{step}. If
4121 @var{step} is not given it defaults to 1. @var{first} and @var{step}
4122 may be of any numeric type. @code{stream-from} is frequently useful as
4123 a generator in @code{stream-of} expressions. See also
4124 @code{stream-range} for a similar procedure that creates finite streams.
4127 @deffn {Scheme Procedure} stream-iterate proc base
4128 Creates a newly-allocated stream containing @var{base} in its first
4129 element and applies @var{proc} to each element in turn to determine the
4130 succeeding element. See also @code{stream-unfold} and
4131 @code{stream-unfolds}.
4134 @deffn {Scheme Procedure} stream-length stream
4135 Returns the number of elements in the @var{stream}; it does not evaluate
4136 its elements. @code{stream-length} may only be used on finite streams;
4137 it enters an infinite loop with infinite streams.
4140 @deffn {Scheme Syntax} stream-let tag ((var expr) @dots{}) body @dots{}
4141 Creates a local scope that binds each variable to the value of its
4142 corresponding expression. It additionally binds @var{tag} to a
4143 procedure which takes the bound variables as arguments and @var{body} as
4144 its defining expressions, binding the @var{tag} with
4145 @code{stream-lambda}. @var{tag} is in scope within body, and may be
4146 called recursively. When the expanded expression defined by the
4147 @code{stream-let} is evaluated, @code{stream-let} evaluates the
4148 expressions in its @var{body} in an environment containing the
4149 newly-bound variables, returning the value of the last expression
4150 evaluated, which must yield a stream.
4152 @code{stream-let} provides syntactic sugar on @code{stream-lambda}, in
4153 the same manner as normal @code{let} provides syntactic sugar on normal
4154 @code{lambda}. However, unlike normal @code{let}, the @var{tag} is
4155 required, not optional, because unnamed @code{stream-let} is
4158 For example, @code{stream-member} returns the first @code{stream-pair}
4159 of the input @var{strm} with a @code{stream-car} @var{x} that satisfies
4160 @code{(eql? obj x)}, or the null stream if @var{x} is not present in
4164 (define-stream (stream-member eql? obj strm)
4165 (stream-let loop ((strm strm))
4166 (cond ((stream-null? strm) strm)
4167 ((eql? obj (stream-car strm)) strm)
4168 (else (loop (stream-cdr strm))))))
4172 @deffn {Scheme Procedure} stream-map proc stream @dots{}
4173 Applies @var{proc} element-wise to corresponding elements of the input
4174 @var{stream}s, returning a newly-allocated stream containing elements
4175 that are the results of those procedure applications. The output stream
4176 has as many elements as the minimum-length input stream, and may be
4180 @deffn {Scheme Syntax} stream-match stream clause @dots{}
4181 Provides pattern-matching for streams. The input @var{stream} is an
4182 expression that evaluates to a stream. Clauses are of the form
4183 @code{(pattern [fender] expression)}, consisting of a @var{pattern} that
4184 matches a stream of a particular shape, an optional @var{fender} that
4185 must succeed if the pattern is to match, and an @var{expression} that is
4186 evaluated if the pattern matches. There are four types of patterns:
4190 () matches the null stream.
4193 (@var{pat0} @var{pat1} @dots{}) matches a finite stream with length
4194 exactly equal to the number of pattern elements.
4197 (@var{pat0} @var{pat1} @dots{} @code{.} @var{pat-rest}) matches an
4198 infinite stream, or a finite stream with length at least as great as the
4199 number of pattern elements before the literal dot.
4202 @var{pat} matches an entire stream. Should always appear last in the
4203 list of clauses; it's not an error to appear elsewhere, but subsequent
4204 clauses could never match.
4207 Each pattern element may be either:
4211 An identifier, which matches any stream element. Additionally, the
4212 value of the stream element is bound to the variable named by the
4213 identifier, which is in scope in the @var{fender} and @var{expression}
4214 of the corresponding @var{clause}. Each identifier in a single pattern
4218 A literal underscore (@code{_}), which matches any stream element but
4219 creates no bindings.
4222 The @var{pattern}s are tested in order, left-to-right, until a matching
4223 pattern is found; if @var{fender} is present, it must evaluate to a true
4224 value for the match to be successful. Pattern variables are bound in
4225 the corresponding @var{fender} and @var{expression}. Once the matching
4226 @var{pattern} is found, the corresponding @var{expression} is evaluated
4227 and returned as the result of the match. An error is signaled if no
4228 pattern matches the input @var{stream}.
4230 @code{stream-match} is often used to distinguish null streams from
4231 non-null streams, binding @var{head} and @var{tail}:
4237 ((head . tail) (+ 1 (len tail)))))
4240 Fenders can test the common case where two stream elements must be
4241 identical; the @code{else} pattern is an identifier bound to the entire
4242 stream, not a keyword as in @code{cond}.
4246 ((x y . _) (equal? x y) 'ok)
4250 A more complex example uses two nested matchers to match two different
4251 stream arguments; @code{(stream-merge lt? . strms)} stably merges two or
4252 more streams ordered by the @code{lt?} predicate:
4255 (define-stream (stream-merge lt? . strms)
4256 (define-stream (merge xx yy)
4257 (stream-match xx (() yy) ((x . xs)
4258 (stream-match yy (() xx) ((y . ys)
4260 (stream-cons y (merge xx ys))
4261 (stream-cons x (merge xs yy))))))))
4262 (stream-let loop ((strms strms))
4263 (cond ((null? strms) stream-null)
4264 ((null? (cdr strms)) (car strms))
4265 (else (merge (car strms)
4266 (apply stream-merge lt?
4271 @deffn {Scheme Syntax} stream-of expr clause @dots{}
4272 Provides the syntax of stream comprehensions, which generate streams by
4273 means of looping expressions. The result is a stream of objects of the
4274 type returned by @var{expr}. There are four types of clauses:
4278 (@var{var} @code{in} @var{stream-expr}) loops over the elements of
4279 @var{stream-expr}, in order from the start of the stream, binding each
4280 element of the stream in turn to @var{var}. @code{stream-from} and
4281 @code{stream-range} are frequently useful as generators for
4285 (@var{var} @code{is} @var{expr}) binds @var{var} to the value obtained
4286 by evaluating @var{expr}.
4289 (@var{pred} @var{expr}) includes in the output stream only those
4290 elements @var{x} which satisfy the predicate @var{pred}.
4293 The scope of variables bound in the stream comprehension is the clauses
4294 to the right of the binding clause (but not the binding clause itself)
4295 plus the result expression.
4297 When two or more generators are present, the loops are processed as if
4298 they are nested from left to right; that is, the rightmost generator
4299 varies fastest. A consequence of this is that only the first generator
4300 may be infinite and all subsequent generators must be finite. If no
4301 generators are present, the result of a stream comprehension is a stream
4302 containing the result expression; thus, @samp{(stream-of 1)} produces a
4303 finite stream containing only the element 1.
4307 (x in (stream-range 0 10))
4309 @result{} 0 4 16 36 64
4311 (stream-of (list a b)
4312 (a in (stream-range 1 4))
4313 (b in (stream-range 1 3)))
4314 @result{} (1 1) (1 2) (2 1) (2 2) (3 1) (3 2)
4316 (stream-of (list i j)
4317 (i in (stream-range 1 5))
4318 (j in (stream-range (+ i 1) 5)))
4319 @result{} (1 2) (1 3) (1 4) (2 3) (2 4) (3 4)
4323 @deffn {Scheme Procedure} stream-range first past [step]
4324 Creates a newly-allocated stream that contains @var{first} as its first
4325 element and increments each succeeding element by @var{step}. The
4326 stream is finite and ends before @var{past}, which is not an element of
4327 the stream. If @var{step} is not given it defaults to 1 if @var{first}
4328 is less than past and -1 otherwise. @var{first}, @var{past} and
4329 @var{step} may be of any real numeric type. @code{stream-range} is
4330 frequently useful as a generator in @code{stream-of} expressions. See
4331 also @code{stream-from} for a similar procedure that creates infinite
4335 (stream-range 0 10) @result{} 0 1 2 3 4 5 6 7 8 9
4336 (stream-range 0 10 2) @result{} 0 2 4 6 8
4339 Successive elements of the stream are calculated by adding @var{step} to
4340 @var{first}, so if any of @var{first}, @var{past} or @var{step} are
4341 inexact, the length of the output stream may differ from
4342 @code{(ceiling (- (/ (- past first) step) 1)}.
4345 @deffn {Scheme Procedure} stream-ref stream n
4346 Returns the @var{n}th element of stream, counting from zero. An error
4347 is signaled if @var{n} is greater than or equal to the length of stream.
4352 (stream-scan * 1 (stream-from 1))
4357 @deffn {Scheme Procedure} stream-reverse stream
4358 Returns a newly-allocated stream containing the elements of the input
4359 @var{stream} but in reverse order. @code{stream-reverse} may only be
4360 used with finite streams; it enters an infinite loop with infinite
4361 streams. @code{stream-reverse} does not force evaluation of the
4362 elements of the stream.
4365 @deffn {Scheme Procedure} stream-scan proc base stream
4366 Accumulates the partial folds of an input @var{stream} into a
4367 newly-allocated output stream. The output stream is the @var{base}
4368 followed by @code{(stream-fold proc base (stream-take i stream))} for
4369 each of the first @var{i} elements of @var{stream}.
4372 (stream-scan + 0 (stream-from 1))
4373 @result{} (stream 0 1 3 6 10 15 @dots{})
4375 (stream-scan * 1 (stream-from 1))
4376 @result{} (stream 1 1 2 6 24 120 @dots{})
4380 @deffn {Scheme Procedure} stream-take n stream
4381 Returns a newly-allocated stream containing the first @var{n} elements
4382 of the input @var{stream}. If the input @var{stream} has less than
4383 @var{n} elements, so does the output stream. See also
4387 @deffn {Scheme Procedure} stream-take-while pred stream
4388 Takes a predicate and a @code{stream} and returns a newly-allocated
4389 stream containing those elements @code{x} that form the maximal prefix
4390 of the input stream which satisfy @var{pred}. See also
4391 @code{stream-drop-while}.
4394 @deffn {Scheme Procedure} stream-unfold map pred gen base
4395 The fundamental recursive stream constructor. It constructs a stream by
4396 repeatedly applying @var{gen} to successive values of @var{base}, in the
4397 manner of @code{stream-iterate}, then applying @var{map} to each of the
4398 values so generated, appending each of the mapped values to the output
4399 stream as long as @code{(pred? base)} returns a true value. See also
4400 @code{stream-iterate} and @code{stream-unfolds}.
4402 The expression below creates the finite stream @samp{0 1 4 9 16 25 36 49
4403 64 81}. Initially the @var{base} is 0, which is less than 10, so
4404 @var{map} squares the @var{base} and the mapped value becomes the first
4405 element of the output stream. Then @var{gen} increments the @var{base}
4406 by 1, so it becomes 1; this is less than 10, so @var{map} squares the
4407 new @var{base} and 1 becomes the second element of the output stream.
4408 And so on, until the base becomes 10, when @var{pred} stops the
4409 recursion and stream-null ends the output stream.
4413 (lambda (x) (expt x 2)) ; map
4414 (lambda (x) (< x 10)) ; pred?
4415 (lambda (x) (+ x 1)) ; gen
4420 @deffn {Scheme Procedure} stream-unfolds proc seed
4421 Returns @var{n} newly-allocated streams containing those elements
4422 produced by successive calls to the generator @var{proc}, which takes
4423 the current @var{seed} as its argument and returns @var{n}+1 values
4425 (@var{proc} @var{seed}) @result{} @var{seed} @var{result_0} @dots{} @var{result_n-1}
4427 where the returned @var{seed} is the input @var{seed} to the next call
4428 to the generator and @var{result_i} indicates how to produce the next
4429 element of the @var{i}th result stream:
4433 (@var{value}): @var{value} is the next car of the result stream.
4436 @code{#f}: no value produced by this iteration of the generator
4437 @var{proc} for the result stream.
4440 (): the end of the result stream.
4443 It may require multiple calls of @var{proc} to produce the next element
4444 of any particular result stream. See also @code{stream-iterate} and
4445 @code{stream-unfold}.
4448 (define (stream-partition pred? strm)
4451 (if (stream-null? s)
4453 (let ((a (stream-car s))
4456 (values d (list a) #f)
4457 (values d #f (list a))))))
4462 (stream-partition odd?
4463 (stream-range 1 6)))
4464 (lambda (odds evens)
4465 (list (stream->list odds)
4466 (stream->list evens))))
4467 @result{} ((1 3 5) (2 4))
4471 @deffn {Scheme Procedure} stream-zip stream @dots{}
4472 Returns a newly-allocated stream in which each element is a list (not a
4473 stream) of the corresponding elements of the input @var{stream}s. The
4474 output stream is as long as the shortest input @var{stream}, if any of
4475 the input @var{stream}s is finite, or is infinite if all the input
4476 @var{stream}s are infinite.
4480 @subsection SRFI-42 - Eager Comprehensions
4483 See @uref{http://srfi.schemers.org/srfi-42/srfi-42.html, the
4484 specification of SRFI-42}.
4487 @subsection SRFI-43 - Vector Library
4490 This subsection is based on the
4491 @uref{http://srfi.schemers.org/srfi-43/srfi-43.html, specification of
4492 SRFI-43} by Taylor Campbell.
4494 @c The copyright notice and license text of the SRFI-43 specification is
4495 @c reproduced below:
4497 @c Copyright (C) Taylor Campbell (2003). All Rights Reserved.
4499 @c Permission is hereby granted, free of charge, to any person obtaining a
4500 @c copy of this software and associated documentation files (the
4501 @c "Software"), to deal in the Software without restriction, including
4502 @c without limitation the rights to use, copy, modify, merge, publish,
4503 @c distribute, sublicense, and/or sell copies of the Software, and to
4504 @c permit persons to whom the Software is furnished to do so, subject to
4505 @c the following conditions:
4507 @c The above copyright notice and this permission notice shall be included
4508 @c in all copies or substantial portions of the Software.
4510 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
4511 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
4512 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
4513 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
4514 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
4515 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
4516 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
4519 SRFI-43 implements a comprehensive library of vector operations. It can
4520 be made available with:
4523 (use-modules (srfi srfi-43))
4527 * SRFI-43 Constructors::
4528 * SRFI-43 Predicates::
4529 * SRFI-43 Selectors::
4530 * SRFI-43 Iteration::
4531 * SRFI-43 Searching::
4532 * SRFI-43 Mutators::
4533 * SRFI-43 Conversion::
4536 @node SRFI-43 Constructors
4537 @subsubsection SRFI-43 Constructors
4539 @deffn {Scheme Procedure} make-vector size [fill]
4540 Create and return a vector of size @var{size}, optionally filling it
4541 with @var{fill}. The default value of @var{fill} is unspecified.
4544 (make-vector 5 3) @result{} #(3 3 3 3 3)
4548 @deffn {Scheme Procedure} vector x @dots{}
4549 Create and return a vector whose elements are @var{x} @enddots{}.
4552 (vector 0 1 2 3 4) @result{} #(0 1 2 3 4)
4556 @deffn {Scheme Procedure} vector-unfold f length initial-seed @dots{}
4557 The fundamental vector constructor. Create a vector whose length
4558 is @var{length} and iterates across each index k from 0 up to
4559 @var{length} - 1, applying @var{f} at each iteration to the current
4560 index and current seeds, in that order, to receive n + 1 values: the
4561 element to put in the kth slot of the new vector, and n new seeds for
4562 the next iteration. It is an error for the number of seeds to vary
4566 (vector-unfold (lambda (i x) (values x (- x 1)))
4568 @result{} #(0 -1 -2 -3 -4 -5 -6 -7 -8 -9)
4570 (vector-unfold values 10)
4571 @result{} #(0 1 2 3 4 5 6 7 8 9)
4575 @deffn {Scheme Procedure} vector-unfold-right f length initial-seed @dots{}
4576 Like @code{vector-unfold}, but it uses @var{f} to generate elements from
4577 right-to-left, rather than left-to-right.
4580 (vector-unfold-right (lambda (i x) (values x (+ x 1)))
4582 @result{} #(9 8 7 6 5 4 3 2 1 0)
4586 @deffn {Scheme Procedure} vector-copy vec [start [end [fill]]]
4587 Allocate a new vector whose length is @var{end} - @var{start} and fills
4588 it with elements from @var{vec}, taking elements from @var{vec} starting
4589 at index @var{start} and stopping at index @var{end}. @var{start}
4590 defaults to 0 and @var{end} defaults to the value of
4591 @code{(vector-length vec)}. If @var{end} extends beyond the length of
4592 @var{vec}, the slots in the new vector that obviously cannot be filled
4593 by elements from @var{vec} are filled with @var{fill}, whose default
4594 value is unspecified.
4597 (vector-copy '#(a b c d e f g h i))
4598 @result{} #(a b c d e f g h i)
4600 (vector-copy '#(a b c d e f g h i) 6)
4603 (vector-copy '#(a b c d e f g h i) 3 6)
4606 (vector-copy '#(a b c d e f g h i) 6 12 'x)
4607 @result{} #(g h i x x x)
4611 @deffn {Scheme Procedure} vector-reverse-copy vec [start [end]]
4612 Like @code{vector-copy}, but it copies the elements in the reverse order
4616 (vector-reverse-copy '#(5 4 3 2 1 0) 1 5)
4617 @result{} #(1 2 3 4)
4621 @deffn {Scheme Procedure} vector-append vec @dots{}
4622 Return a newly allocated vector that contains all elements in order from
4623 the subsequent locations in @var{vec} @enddots{}.
4626 (vector-append '#(a) '#(b c d))
4627 @result{} #(a b c d)
4631 @deffn {Scheme Procedure} vector-concatenate list-of-vectors
4632 Append each vector in @var{list-of-vectors}. Equivalent to
4633 @code{(apply vector-append list-of-vectors)}.
4636 (vector-concatenate '(#(a b) #(c d)))
4637 @result{} #(a b c d)
4641 @node SRFI-43 Predicates
4642 @subsubsection SRFI-43 Predicates
4644 @deffn {Scheme Procedure} vector? obj
4645 Return true if @var{obj} is a vector, else return false.
4648 @deffn {Scheme Procedure} vector-empty? vec
4649 Return true if @var{vec} is empty, i.e. its length is 0, else return
4653 @deffn {Scheme Procedure} vector= elt=? vec @dots{}
4654 Return true if the vectors @var{vec} @dots{} have equal lengths and
4655 equal elements according to @var{elt=?}. @var{elt=?} is always applied
4656 to two arguments. Element comparison must be consistent with @code{eq?}
4657 in the following sense: if @code{(eq? a b)} returns true, then
4658 @code{(elt=? a b)} must also return true. The order in which
4659 comparisons are performed is unspecified.
4662 @node SRFI-43 Selectors
4663 @subsubsection SRFI-43 Selectors
4665 @deffn {Scheme Procedure} vector-ref vec i
4666 Return the element at index @var{i} in @var{vec}. Indexing is based on
4670 @deffn {Scheme Procedure} vector-length vec
4671 Return the length of @var{vec}.
4674 @node SRFI-43 Iteration
4675 @subsubsection SRFI-43 Iteration
4677 @deffn {Scheme Procedure} vector-fold kons knil vec1 vec2 @dots{}
4678 The fundamental vector iterator. @var{kons} is iterated over each index
4679 in all of the vectors, stopping at the end of the shortest; @var{kons}
4682 (kons i state (vector-ref vec1 i) (vector-ref vec2 i) ...)
4684 where @var{state} is the current state value, and @var{i} is the current
4685 index. The current state value begins with @var{knil}, and becomes
4686 whatever @var{kons} returned at the respective iteration. The iteration
4687 is strictly left-to-right.
4690 @deffn {Scheme Procedure} vector-fold-right kons knil vec1 vec2 @dots{}
4691 Similar to @code{vector-fold}, but it iterates right-to-left instead of
4695 @deffn {Scheme Procedure} vector-map f vec1 vec2 @dots{}
4696 Return a new vector of the shortest size of the vector arguments. Each
4697 element at index i of the new vector is mapped from the old vectors by
4699 (f i (vector-ref vec1 i) (vector-ref vec2 i) ...)
4701 The dynamic order of application of @var{f} is unspecified.
4704 @deffn {Scheme Procedure} vector-map! f vec1 vec2 @dots{}
4705 Similar to @code{vector-map}, but rather than mapping the new elements
4706 into a new vector, the new mapped elements are destructively inserted
4707 into @var{vec1}. The dynamic order of application of @var{f} is
4711 @deffn {Scheme Procedure} vector-for-each f vec1 vec2 @dots{}
4712 Call @code{(f i (vector-ref vec1 i) (vector-ref vec2 i) ...)} for each
4713 index i less than the length of the shortest vector passed. The
4714 iteration is strictly left-to-right.
4717 @deffn {Scheme Procedure} vector-count pred? vec1 vec2 @dots{}
4718 Count the number of parallel elements in the vectors that satisfy
4719 @var{pred?}, which is applied, for each index i less than the length of
4720 the smallest vector, to i and each parallel element in the vectors at
4721 that index, in order.
4724 (vector-count (lambda (i elt) (even? elt))
4725 '#(3 1 4 1 5 9 2 5 6))
4727 (vector-count (lambda (i x y) (< x y))
4728 '#(1 3 6 9) '#(2 4 6 8 10 12))
4733 @node SRFI-43 Searching
4734 @subsubsection SRFI-43 Searching
4736 @deffn {Scheme Procedure} vector-index pred? vec1 vec2 @dots{}
4737 Find and return the index of the first elements in @var{vec1} @var{vec2}
4738 @dots{} that satisfy @var{pred?}. If no matching element is found by
4739 the end of the shortest vector, return @code{#f}.
4742 (vector-index even? '#(3 1 4 1 5 9))
4744 (vector-index < '#(3 1 4 1 5 9 2 5 6) '#(2 7 1 8 2))
4746 (vector-index = '#(3 1 4 1 5 9 2 5 6) '#(2 7 1 8 2))
4751 @deffn {Scheme Procedure} vector-index-right pred? vec1 vec2 @dots{}
4752 Like @code{vector-index}, but it searches right-to-left, rather than
4753 left-to-right. Note that the SRFI 43 specification requires that all
4754 the vectors must have the same length, but both the SRFI 43 reference
4755 implementation and Guile's implementation allow vectors with unequal
4756 lengths, and start searching from the last index of the shortest vector.
4759 @deffn {Scheme Procedure} vector-skip pred? vec1 vec2 @dots{}
4760 Find and return the index of the first elements in @var{vec1} @var{vec2}
4761 @dots{} that do not satisfy @var{pred?}. If no matching element is
4762 found by the end of the shortest vector, return @code{#f}. Equivalent
4763 to @code{vector-index} but with the predicate inverted.
4766 (vector-skip number? '#(1 2 a b 3 4 c d)) @result{} 2
4770 @deffn {Scheme Procedure} vector-skip-right pred? vec1 vec2 @dots{}
4771 Like @code{vector-skip}, but it searches for a non-matching element
4772 right-to-left, rather than left-to-right. Note that the SRFI 43
4773 specification requires that all the vectors must have the same length,
4774 but both the SRFI 43 reference implementation and Guile's implementation
4775 allow vectors with unequal lengths, and start searching from the last
4776 index of the shortest vector.
4779 @deffn {Scheme Procedure} vector-binary-search vec value cmp [start [end]]
4780 Find and return an index of @var{vec} between @var{start} and @var{end}
4781 whose value is @var{value} using a binary search. If no matching
4782 element is found, return @code{#f}. The default @var{start} is 0 and
4783 the default @var{end} is the length of @var{vec}.
4785 @var{cmp} must be a procedure of two arguments such that @code{(cmp a
4786 b)} returns a negative integer if @math{a < b}, a positive integer if
4787 @math{a > b}, or zero if @math{a = b}. The elements of @var{vec} must
4788 be sorted in non-decreasing order according to @var{cmp}.
4790 Note that SRFI 43 does not document the @var{start} and @var{end}
4791 arguments, but both its reference implementation and Guile's
4792 implementation support them.
4795 (define (char-cmp c1 c2)
4796 (cond ((char<? c1 c2) -1)
4800 (vector-binary-search '#(#\a #\b #\c #\d #\e #\f #\g #\h)
4807 @deffn {Scheme Procedure} vector-any pred? vec1 vec2 @dots{}
4808 Find the first parallel set of elements from @var{vec1} @var{vec2}
4809 @dots{} for which @var{pred?} returns a true value. If such a parallel
4810 set of elements exists, @code{vector-any} returns the value that
4811 @var{pred?} returned for that set of elements. The iteration is
4812 strictly left-to-right.
4815 @deffn {Scheme Procedure} vector-every pred? vec1 vec2 @dots{}
4816 If, for every index i between 0 and the length of the shortest vector
4817 argument, the set of elements @code{(vector-ref vec1 i)}
4818 @code{(vector-ref vec2 i)} @dots{} satisfies @var{pred?},
4819 @code{vector-every} returns the value that @var{pred?} returned for the
4820 last set of elements, at the last index of the shortest vector.
4821 Otherwise it returns @code{#f}. The iteration is strictly
4825 @node SRFI-43 Mutators
4826 @subsubsection SRFI-43 Mutators
4828 @deffn {Scheme Procedure} vector-set! vec i value
4829 Assign the contents of the location at @var{i} in @var{vec} to
4833 @deffn {Scheme Procedure} vector-swap! vec i j
4834 Swap the values of the locations in @var{vec} at @var{i} and @var{j}.
4837 @deffn {Scheme Procedure} vector-fill! vec fill [start [end]]
4838 Assign the value of every location in @var{vec} between @var{start} and
4839 @var{end} to @var{fill}. @var{start} defaults to 0 and @var{end}
4840 defaults to the length of @var{vec}.
4843 @deffn {Scheme Procedure} vector-reverse! vec [start [end]]
4844 Destructively reverse the contents of @var{vec} between @var{start} and
4845 @var{end}. @var{start} defaults to 0 and @var{end} defaults to the
4846 length of @var{vec}.
4849 @deffn {Scheme Procedure} vector-copy! target tstart source [sstart [send]]
4850 Copy a block of elements from @var{source} to @var{target}, both of
4851 which must be vectors, starting in @var{target} at @var{tstart} and
4852 starting in @var{source} at @var{sstart}, ending when (@var{send} -
4853 @var{sstart}) elements have been copied. It is an error for
4854 @var{target} to have a length less than (@var{tstart} + @var{send} -
4855 @var{sstart}). @var{sstart} defaults to 0 and @var{send} defaults to
4856 the length of @var{source}.
4859 @deffn {Scheme Procedure} vector-reverse-copy! target tstart source [sstart [send]]
4860 Like @code{vector-copy!}, but this copies the elements in the reverse
4861 order. It is an error if @var{target} and @var{source} are identical
4862 vectors and the @var{target} and @var{source} ranges overlap; however,
4863 if @var{tstart} = @var{sstart}, @code{vector-reverse-copy!} behaves as
4864 @code{(vector-reverse! target tstart send)} would.
4867 @node SRFI-43 Conversion
4868 @subsubsection SRFI-43 Conversion
4870 @deffn {Scheme Procedure} vector->list vec [start [end]]
4871 Return a newly allocated list containing the elements in @var{vec}
4872 between @var{start} and @var{end}. @var{start} defaults to 0 and
4873 @var{end} defaults to the length of @var{vec}.
4876 @deffn {Scheme Procedure} reverse-vector->list vec [start [end]]
4877 Like @code{vector->list}, but the resulting list contains the specified
4878 range of elements of @var{vec} in reverse order.
4881 @deffn {Scheme Procedure} list->vector proper-list [start [end]]
4882 Return a newly allocated vector of the elements from @var{proper-list}
4883 with indices between @var{start} and @var{end}. @var{start} defaults to
4884 0 and @var{end} defaults to the length of @var{proper-list}. Note that
4885 SRFI 43 does not document the @var{start} and @var{end} arguments, but
4886 both its reference implementation and Guile's implementation support
4890 @deffn {Scheme Procedure} reverse-list->vector proper-list [start [end]]
4891 Like @code{list->vector}, but the resulting vector contains the specified
4892 range of elements of @var{proper-list} in reverse order. Note that SRFI
4893 43 does not document the @var{start} and @var{end} arguments, but both
4894 its reference implementation and Guile's implementation support them.
4898 @subsection SRFI-45 - Primitives for Expressing Iterative Lazy Algorithms
4901 This subsection is based on @uref{http://srfi.schemers.org/srfi-45/srfi-45.html, the
4902 specification of SRFI-45} written by Andr@'e van Tonder.
4904 @c Copyright (C) André van Tonder (2003). All Rights Reserved.
4906 @c Permission is hereby granted, free of charge, to any person obtaining a
4907 @c copy of this software and associated documentation files (the
4908 @c "Software"), to deal in the Software without restriction, including
4909 @c without limitation the rights to use, copy, modify, merge, publish,
4910 @c distribute, sublicense, and/or sell copies of the Software, and to
4911 @c permit persons to whom the Software is furnished to do so, subject to
4912 @c the following conditions:
4914 @c The above copyright notice and this permission notice shall be included
4915 @c in all copies or substantial portions of the Software.
4917 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
4918 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
4919 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
4920 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
4921 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
4922 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
4923 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
4925 Lazy evaluation is traditionally simulated in Scheme using @code{delay}
4926 and @code{force}. However, these primitives are not powerful enough to
4927 express a large class of lazy algorithms that are iterative. Indeed, it
4928 is folklore in the Scheme community that typical iterative lazy
4929 algorithms written using delay and force will often require unbounded
4932 This SRFI provides set of three operations: @{@code{lazy}, @code{delay},
4933 @code{force}@}, which allow the programmer to succinctly express lazy
4934 algorithms while retaining bounded space behavior in cases that are
4935 properly tail-recursive. A general recipe for using these primitives is
4936 provided. An additional procedure @code{eager} is provided for the
4937 construction of eager promises in cases where efficiency is a concern.
4939 Although this SRFI redefines @code{delay} and @code{force}, the
4940 extension is conservative in the sense that the semantics of the subset
4941 @{@code{delay}, @code{force}@} in isolation (i.e., as long as the
4942 program does not use @code{lazy}) agrees with that in R5RS. In other
4943 words, no program that uses the R5RS definitions of delay and force will
4944 break if those definition are replaced by the SRFI-45 definitions of
4947 Guile also adds @code{promise?} to the list of exports, which is not
4948 part of the official SRFI-45.
4950 @deffn {Scheme Procedure} promise? obj
4951 Return true if @var{obj} is an SRFI-45 promise, otherwise return false.
4954 @deffn {Scheme Syntax} delay expression
4955 Takes an expression of arbitrary type @var{a} and returns a promise of
4956 type @code{(Promise @var{a})} which at some point in the future may be
4957 asked (by the @code{force} procedure) to evaluate the expression and
4958 deliver the resulting value.
4961 @deffn {Scheme Syntax} lazy expression
4962 Takes an expression of type @code{(Promise @var{a})} and returns a
4963 promise of type @code{(Promise @var{a})} which at some point in the
4964 future may be asked (by the @code{force} procedure) to evaluate the
4965 expression and deliver the resulting promise.
4968 @deffn {Scheme Procedure} force expression
4969 Takes an argument of type @code{(Promise @var{a})} and returns a value
4970 of type @var{a} as follows: If a value of type @var{a} has been computed
4971 for the promise, this value is returned. Otherwise, the promise is
4972 first evaluated, then overwritten by the obtained promise or value, and
4973 then force is again applied (iteratively) to the promise.
4976 @deffn {Scheme Procedure} eager expression
4977 Takes an argument of type @var{a} and returns a value of type
4978 @code{(Promise @var{a})}. As opposed to @code{delay}, the argument is
4979 evaluated eagerly. Semantically, writing @code{(eager expression)} is
4980 equivalent to writing
4983 (let ((value expression)) (delay value)).
4986 However, the former is more efficient since it does not require
4987 unnecessary creation and evaluation of thunks. We also have the
4991 (delay expression) = (lazy (eager expression))
4995 The following reduction rules may be helpful for reasoning about these
4996 primitives. However, they do not express the memoization and memory
4997 usage semantics specified above:
5000 (force (delay expression)) -> expression
5001 (force (lazy expression)) -> (force expression)
5002 (force (eager value)) -> value
5005 @subsubheading Correct usage
5007 We now provide a general recipe for using the primitives @{@code{lazy},
5008 @code{delay}, @code{force}@} to express lazy algorithms in Scheme. The
5009 transformation is best described by way of an example: Consider the
5010 stream-filter algorithm, expressed in a hypothetical lazy language as
5013 (define (stream-filter p? s)
5018 (cons h (stream-filter p? t))
5019 (stream-filter p? t)))))
5022 This algorithm can be expressed as follows in Scheme:
5025 (define (stream-filter p? s)
5027 (if (null? (force s)) (delay '())
5028 (let ((h (car (force s)))
5029 (t (cdr (force s))))
5031 (delay (cons h (stream-filter p? t)))
5032 (stream-filter p? t))))))
5039 wrap all constructors (e.g., @code{'()}, @code{cons}) with @code{delay},
5041 apply @code{force} to arguments of deconstructors (e.g., @code{car},
5042 @code{cdr} and @code{null?}),
5044 wrap procedure bodies with @code{(lazy ...)}.
5048 @subsection SRFI-46 Basic syntax-rules Extensions
5051 Guile's core @code{syntax-rules} supports the extensions specified by
5052 SRFI-46/R7RS. Tail patterns have been supported since at least Guile
5053 2.0, and custom ellipsis identifiers have been supported since Guile
5054 2.0.10. @xref{Syntax Rules}.
5057 @subsection SRFI-55 - Requiring Features
5060 SRFI-55 provides @code{require-extension} which is a portable
5061 mechanism to load selected SRFI modules. This is implemented in the
5062 Guile core, there's no module needed to get SRFI-55 itself.
5064 @deffn {library syntax} require-extension clause1 clause2 @dots{}
5065 Require the features of @var{clause1} @var{clause2} @dots{} , throwing
5066 an error if any are unavailable.
5068 A @var{clause} is of the form @code{(@var{identifier} arg...)}. The
5069 only @var{identifier} currently supported is @code{srfi} and the
5070 arguments are SRFI numbers. For example to get SRFI-1 and SRFI-6,
5073 (require-extension (srfi 1 6))
5076 @code{require-extension} can only be used at the top-level.
5078 A Guile-specific program can simply @code{use-modules} to load SRFIs
5079 not already in the core, @code{require-extension} is for programs
5080 designed to be portable to other Scheme implementations.
5085 @subsection SRFI-60 - Integers as Bits
5087 @cindex integers as bits
5088 @cindex bitwise logical
5090 This SRFI provides various functions for treating integers as bits and
5091 for bitwise manipulations. These functions can be obtained with,
5094 (use-modules (srfi srfi-60))
5097 Integers are treated as infinite precision twos-complement, the same
5098 as in the core logical functions (@pxref{Bitwise Operations}). And
5099 likewise bit indexes start from 0 for the least significant bit. The
5100 following functions in this SRFI are already in the Guile core,
5109 @code{integer-length},
5115 @defun bitwise-and n1 ...
5116 @defunx bitwise-ior n1 ...
5117 @defunx bitwise-xor n1 ...
5118 @defunx bitwise-not n
5119 @defunx any-bits-set? j k
5120 @defunx bit-set? index n
5121 @defunx arithmetic-shift n count
5122 @defunx bit-field n start end
5124 Aliases for @code{logand}, @code{logior}, @code{logxor},
5125 @code{lognot}, @code{logtest}, @code{logbit?}, @code{ash},
5126 @code{bit-extract} and @code{logcount} respectively.
5128 Note that the name @code{bit-count} conflicts with @code{bit-count} in
5129 the core (@pxref{Bit Vectors}).
5132 @defun bitwise-if mask n1 n0
5133 @defunx bitwise-merge mask n1 n0
5134 Return an integer with bits selected from @var{n1} and @var{n0}
5135 according to @var{mask}. Those bits where @var{mask} has 1s are taken
5136 from @var{n1}, and those where @var{mask} has 0s are taken from
5140 (bitwise-if 3 #b0101 #b1010) @result{} 9
5144 @defun log2-binary-factors n
5145 @defunx first-set-bit n
5146 Return a count of how many factors of 2 are present in @var{n}. This
5147 is also the bit index of the lowest 1 bit in @var{n}. If @var{n} is
5148 0, the return is @math{-1}.
5151 (log2-binary-factors 6) @result{} 1
5152 (log2-binary-factors -8) @result{} 3
5156 @defun copy-bit index n newbit
5157 Return @var{n} with the bit at @var{index} set according to
5158 @var{newbit}. @var{newbit} should be @code{#t} to set the bit to 1,
5159 or @code{#f} to set it to 0. Bits other than at @var{index} are
5160 unchanged in the return.
5163 (copy-bit 1 #b0101 #t) @result{} 7
5167 @defun copy-bit-field n newbits start end
5168 Return @var{n} with the bits from @var{start} (inclusive) to @var{end}
5169 (exclusive) changed to the value @var{newbits}.
5171 The least significant bit in @var{newbits} goes to @var{start}, the
5172 next to @math{@var{start}+1}, etc. Anything in @var{newbits} past the
5173 @var{end} given is ignored.
5176 (copy-bit-field #b10000 #b11 1 3) @result{} #b10110
5180 @defun rotate-bit-field n count start end
5181 Return @var{n} with the bit field from @var{start} (inclusive) to
5182 @var{end} (exclusive) rotated upwards by @var{count} bits.
5184 @var{count} can be positive or negative, and it can be more than the
5185 field width (it'll be reduced modulo the width).
5188 (rotate-bit-field #b0110 2 1 4) @result{} #b1010
5192 @defun reverse-bit-field n start end
5193 Return @var{n} with the bits from @var{start} (inclusive) to @var{end}
5194 (exclusive) reversed.
5197 (reverse-bit-field #b101001 2 4) @result{} #b100101
5201 @defun integer->list n [len]
5202 Return bits from @var{n} in the form of a list of @code{#t} for 1 and
5203 @code{#f} for 0. The least significant @var{len} bits are returned,
5204 and the first list element is the most significant of those bits. If
5205 @var{len} is not given, the default is @code{(integer-length @var{n})}
5206 (@pxref{Bitwise Operations}).
5209 (integer->list 6) @result{} (#t #t #f)
5210 (integer->list 1 4) @result{} (#f #f #f #t)
5214 @defun list->integer lst
5215 @defunx booleans->integer bool@dots{}
5216 Return an integer formed bitwise from the given @var{lst} list of
5217 booleans, or for @code{booleans->integer} from the @var{bool}
5220 Each boolean is @code{#t} for a 1 and @code{#f} for a 0. The first
5221 element becomes the most significant bit in the return.
5224 (list->integer '(#t #f #t #f)) @result{} 10
5230 @subsection SRFI-61 - A more general @code{cond} clause
5232 This SRFI extends RnRS @code{cond} to support test expressions that
5233 return multiple values, as well as arbitrary definitions of test
5234 success. SRFI 61 is implemented in the Guile core; there's no module
5235 needed to get SRFI-61 itself. Extended @code{cond} is documented in
5236 @ref{Conditionals,, Simple Conditional Evaluation}.
5239 @subsection SRFI-62 - S-expression comments.
5242 Starting from version 2.0, Guile's @code{read} supports SRFI-62/R7RS
5243 S-expression comments by default.
5246 @subsection SRFI-64 - A Scheme API for test suites.
5249 See @uref{http://srfi.schemers.org/srfi-64/srfi-64.html, the
5250 specification of SRFI-64}.
5253 @subsection SRFI-67 - Compare procedures
5256 See @uref{http://srfi.schemers.org/srfi-67/srfi-67.html, the
5257 specification of SRFI-67}.
5260 @subsection SRFI-69 - Basic hash tables
5263 This is a portable wrapper around Guile's built-in hash table and weak
5264 table support. @xref{Hash Tables}, for information on that built-in
5265 support. Above that, this hash-table interface provides association
5266 of equality and hash functions with tables at creation time, so
5267 variants of each function are not required, as well as a procedure
5268 that takes care of most uses for Guile hash table handles, which this
5269 SRFI does not provide as such.
5274 (use-modules (srfi srfi-69))
5278 * SRFI-69 Creating hash tables::
5279 * SRFI-69 Accessing table items::
5280 * SRFI-69 Table properties::
5281 * SRFI-69 Hash table algorithms::
5284 @node SRFI-69 Creating hash tables
5285 @subsubsection Creating hash tables
5287 @deffn {Scheme Procedure} make-hash-table [equal-proc hash-proc #:weak weakness start-size]
5288 Create and answer a new hash table with @var{equal-proc} as the
5289 equality function and @var{hash-proc} as the hashing function.
5291 By default, @var{equal-proc} is @code{equal?}. It can be any
5292 two-argument procedure, and should answer whether two keys are the
5293 same for this table's purposes.
5295 My default @var{hash-proc} assumes that @code{equal-proc} is no
5296 coarser than @code{equal?} unless it is literally @code{string-ci=?}.
5297 If provided, @var{hash-proc} should be a two-argument procedure that
5298 takes a key and the current table size, and answers a reasonably good
5299 hash integer between 0 (inclusive) and the size (exclusive).
5301 @var{weakness} should be @code{#f} or a symbol indicating how ``weak''
5306 An ordinary non-weak hash table. This is the default.
5309 When the key has no more non-weak references at GC, remove that entry.
5312 When the value has no more non-weak references at GC, remove that
5316 When either has no more non-weak references at GC, remove the
5320 As a legacy of the time when Guile couldn't grow hash tables,
5321 @var{start-size} is an optional integer argument that specifies the
5322 approximate starting size for the hash table, which will be rounded to
5323 an algorithmically-sounder number.
5326 By @dfn{coarser} than @code{equal?}, we mean that for all @var{x} and
5327 @var{y} values where @code{(@var{equal-proc} @var{x} @var{y})},
5328 @code{(equal? @var{x} @var{y})} as well. If that does not hold for
5329 your @var{equal-proc}, you must provide a @var{hash-proc}.
5331 In the case of weak tables, remember that @dfn{references} above
5332 always refers to @code{eq?}-wise references. Just because you have a
5333 reference to some string @code{"foo"} doesn't mean that an association
5334 with key @code{"foo"} in a weak-key table @emph{won't} be collected;
5335 it only counts as a reference if the two @code{"foo"}s are @code{eq?},
5336 regardless of @var{equal-proc}. As such, it is usually only sensible
5337 to use @code{eq?} and @code{hashq} as the equivalence and hash
5338 functions for a weak table. @xref{Weak References}, for more
5339 information on Guile's built-in weak table support.
5341 @deffn {Scheme Procedure} alist->hash-table alist [equal-proc hash-proc #:weak weakness start-size]
5342 As with @code{make-hash-table}, but initialize it with the
5343 associations in @var{alist}. Where keys are repeated in @var{alist},
5344 the leftmost association takes precedence.
5347 @node SRFI-69 Accessing table items
5348 @subsubsection Accessing table items
5350 @deffn {Scheme Procedure} hash-table-ref table key [default-thunk]
5351 @deffnx {Scheme Procedure} hash-table-ref/default table key default
5352 Answer the value associated with @var{key} in @var{table}. If
5353 @var{key} is not present, answer the result of invoking the thunk
5354 @var{default-thunk}, which signals an error instead by default.
5356 @code{hash-table-ref/default} is a variant that requires a third
5357 argument, @var{default}, and answers @var{default} itself instead of
5361 @deffn {Scheme Procedure} hash-table-set! table key new-value
5362 Set @var{key} to @var{new-value} in @var{table}.
5365 @deffn {Scheme Procedure} hash-table-delete! table key
5366 Remove the association of @var{key} in @var{table}, if present. If
5370 @deffn {Scheme Procedure} hash-table-exists? table key
5371 Answer whether @var{key} has an association in @var{table}.
5374 @deffn {Scheme Procedure} hash-table-update! table key modifier [default-thunk]
5375 @deffnx {Scheme Procedure} hash-table-update!/default table key modifier default
5376 Replace @var{key}'s associated value in @var{table} by invoking
5377 @var{modifier} with one argument, the old value.
5379 If @var{key} is not present, and @var{default-thunk} is provided,
5380 invoke it with no arguments to get the ``old value'' to be passed to
5381 @var{modifier} as above. If @var{default-thunk} is not provided in
5382 such a case, signal an error.
5384 @code{hash-table-update!/default} is a variant that requires the
5385 fourth argument, which is used directly as the ``old value'' rather
5386 than as a thunk to be invoked to retrieve the ``old value''.
5389 @node SRFI-69 Table properties
5390 @subsubsection Table properties
5392 @deffn {Scheme Procedure} hash-table-size table
5393 Answer the number of associations in @var{table}. This is guaranteed
5394 to run in constant time for non-weak tables.
5397 @deffn {Scheme Procedure} hash-table-keys table
5398 Answer an unordered list of the keys in @var{table}.
5401 @deffn {Scheme Procedure} hash-table-values table
5402 Answer an unordered list of the values in @var{table}.
5405 @deffn {Scheme Procedure} hash-table-walk table proc
5406 Invoke @var{proc} once for each association in @var{table}, passing
5407 the key and value as arguments.
5410 @deffn {Scheme Procedure} hash-table-fold table proc init
5411 Invoke @code{(@var{proc} @var{key} @var{value} @var{previous})} for
5412 each @var{key} and @var{value} in @var{table}, where @var{previous} is
5413 the result of the previous invocation, using @var{init} as the first
5414 @var{previous} value. Answer the final @var{proc} result.
5417 @deffn {Scheme Procedure} hash-table->alist table
5418 Answer an alist where each association in @var{table} is an
5419 association in the result.
5422 @node SRFI-69 Hash table algorithms
5423 @subsubsection Hash table algorithms
5425 Each hash table carries an @dfn{equivalence function} and a @dfn{hash
5426 function}, used to implement key lookups. Beginning users should
5427 follow the rules for consistency of the default @var{hash-proc}
5428 specified above. Advanced users can use these to implement their own
5429 equivalence and hash functions for specialized lookup semantics.
5431 @deffn {Scheme Procedure} hash-table-equivalence-function hash-table
5432 @deffnx {Scheme Procedure} hash-table-hash-function hash-table
5433 Answer the equivalence and hash function of @var{hash-table}, respectively.
5436 @deffn {Scheme Procedure} hash obj [size]
5437 @deffnx {Scheme Procedure} string-hash obj [size]
5438 @deffnx {Scheme Procedure} string-ci-hash obj [size]
5439 @deffnx {Scheme Procedure} hash-by-identity obj [size]
5440 Answer a hash value appropriate for equality predicate @code{equal?},
5441 @code{string=?}, @code{string-ci=?}, and @code{eq?}, respectively.
5444 @code{hash} is a backwards-compatible replacement for Guile's built-in
5448 @subsection SRFI-87 => in case clauses
5451 Starting from version 2.0.6, Guile's core @code{case} syntax supports
5452 @code{=>} in clauses, as specified by SRFI-87/R7RS.
5453 @xref{Conditionals}.
5456 @subsection SRFI-88 Keyword Objects
5458 @cindex keyword objects
5460 @uref{http://srfi.schemers.org/srfi-88/srfi-88.html, SRFI-88} provides
5461 @dfn{keyword objects}, which are equivalent to Guile's keywords
5462 (@pxref{Keywords}). SRFI-88 keywords can be entered using the
5463 @dfn{postfix keyword syntax}, which consists of an identifier followed
5464 by @code{:} (@pxref{Scheme Read, @code{postfix} keyword syntax}).
5465 SRFI-88 can be made available with:
5468 (use-modules (srfi srfi-88))
5471 Doing so installs the right reader option for keyword syntax, using
5472 @code{(read-set! keywords 'postfix)}. It also provides the procedures
5475 @deffn {Scheme Procedure} keyword? obj
5476 Return @code{#t} if @var{obj} is a keyword. This is the same procedure
5477 as the same-named built-in procedure (@pxref{Keyword Procedures,
5481 (keyword? foo:) @result{} #t
5482 (keyword? 'foo:) @result{} #t
5483 (keyword? "foo") @result{} #f
5487 @deffn {Scheme Procedure} keyword->string kw
5488 Return the name of @var{kw} as a string, i.e., without the trailing
5489 colon. The returned string may not be modified, e.g., with
5493 (keyword->string foo:) @result{} "foo"
5497 @deffn {Scheme Procedure} string->keyword str
5498 Return the keyword object whose name is @var{str}.
5501 (keyword->string (string->keyword "a b c")) @result{} "a b c"
5506 @subsection SRFI-98 Accessing environment variables.
5508 @cindex environment variables
5510 This is a portable wrapper around Guile's built-in support for
5511 interacting with the current environment, @xref{Runtime Environment}.
5513 @deffn {Scheme Procedure} get-environment-variable name
5514 Returns a string containing the value of the environment variable
5515 given by the string @code{name}, or @code{#f} if the named
5516 environment variable is not found. This is equivalent to
5517 @code{(getenv name)}.
5520 @deffn {Scheme Procedure} get-environment-variables
5521 Returns the names and values of all the environment variables as an
5522 association list in which both the keys and the values are strings.
5526 @subsection SRFI-105 Curly-infix expressions.
5529 @cindex curly-infix-and-bracket-lists
5531 Guile's built-in reader includes support for SRFI-105 curly-infix
5532 expressions. See @uref{http://srfi.schemers.org/srfi-105/srfi-105.html,
5533 the specification of SRFI-105}. Some examples:
5536 @{n <= 5@} @result{} (<= n 5)
5537 @{a + b + c@} @result{} (+ a b c)
5538 @{a * @{b + c@}@} @result{} (* a (+ b c))
5539 @{(- a) / b@} @result{} (/ (- a) b)
5540 @{-(a) / b@} @result{} (/ (- a) b) as well
5541 @{(f a b) + (g h)@} @result{} (+ (f a b) (g h))
5542 @{f(a b) + g(h)@} @result{} (+ (f a b) (g h)) as well
5543 @{f[a b] + g(h)@} @result{} (+ ($bracket-apply$ f a b) (g h))
5544 '@{a + f(b) + x@} @result{} '(+ a (f b) x)
5545 @{length(x) >= 6@} @result{} (>= (length x) 6)
5546 @{n-1 + n-2@} @result{} (+ n-1 n-2)
5547 @{n * factorial@{n - 1@}@} @result{} (* n (factorial (- n 1)))
5548 @{@{a > 0@} and @{b >= 1@}@} @result{} (and (> a 0) (>= b 1))
5549 @{f@{n - 1@}(x)@} @result{} ((f (- n 1)) x)
5550 @{a . z@} @result{} ($nfx$ a . z)
5551 @{a + b - c@} @result{} ($nfx$ a + b - c)
5554 To enable curly-infix expressions within a file, place the reader
5555 directive @code{#!curly-infix} before the first use of curly-infix
5556 notation. To globally enable curly-infix expressions in Guile's reader,
5557 set the @code{curly-infix} read option.
5559 Guile also implements the following non-standard extension to SRFI-105:
5560 if @code{curly-infix} is enabled and there is no other meaning assigned
5561 to square brackets (i.e. the @code{square-brackets} read option is
5562 turned off), then lists within square brackets are read as normal lists
5563 but with the special symbol @code{$bracket-list$} added to the front.
5564 To enable this combination of read options within a file, use the reader
5565 directive @code{#!curly-infix-and-bracket-lists}. For example:
5568 [a b] @result{} ($bracket-list$ a b)
5569 [a . b] @result{} ($bracket-list$ a . b)
5573 For more information on reader options, @xref{Scheme Read}.
5576 @subsection SRFI-111 Boxes.
5579 @uref{http://srfi.schemers.org/srfi-111/srfi-111.html, SRFI-111}
5580 provides boxes: objects with a single mutable cell.
5582 @deffn {Scheme Procedure} box value
5583 Return a newly allocated box whose contents is initialized to
5587 @deffn {Scheme Procedure} box? obj
5588 Return true if @var{obj} is a box, otherwise return false.
5591 @deffn {Scheme Procedure} unbox box
5592 Return the current contents of @var{box}.
5595 @deffn {Scheme Procedure} set-box! box value
5596 Set the contents of @var{box} to @var{value}.
5599 @c srfi-modules.texi ends here
5602 @c TeX-master: "guile.texi"