2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013
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-30:: Nested multi-line block comments
42 * SRFI-31:: A special form `rec' for recursive evaluation
43 * SRFI-34:: Exception handling.
44 * SRFI-35:: Conditions.
45 * SRFI-37:: args-fold program argument processor
46 * SRFI-38:: External Representation for Data With Shared Structure
47 * SRFI-39:: Parameter objects
49 * SRFI-42:: Eager comprehensions
50 * SRFI-45:: Primitives for expressing iterative lazy algorithms
51 * SRFI-55:: Requiring Features.
52 * SRFI-60:: Integers as bits.
53 * SRFI-61:: A more general `cond' clause
54 * SRFI-67:: Compare procedures
55 * SRFI-69:: Basic hash tables.
56 * SRFI-88:: Keyword objects.
57 * SRFI-98:: Accessing environment variables.
58 * SRFI-105:: Curly-infix expressions.
62 @node About SRFI Usage
63 @subsection About SRFI Usage
65 @c FIXME::martin: Review me!
67 SRFI support in Guile is currently implemented partly in the core
68 library, and partly as add-on modules. That means that some SRFIs are
69 automatically available when the interpreter is started, whereas the
70 other SRFIs require you to use the appropriate support module
73 There are several reasons for this inconsistency. First, the feature
74 checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
75 available immediately, because it must be there when the user wants to
76 check for the Scheme implementation, that is, before she can know that
77 it is safe to use @code{use-modules} to load SRFI support modules. The
78 second reason is that some features defined in SRFIs had been
79 implemented in Guile before the developers started to add SRFI
80 implementations as modules (for example SRFI-13 (@pxref{SRFI-13})). In
81 the future, it is possible that SRFIs in the core library might be
82 factored out into separate modules, requiring explicit module loading
83 when they are needed. So you should be prepared to have to use
84 @code{use-modules} someday in the future to access SRFI-13 bindings. If
85 you want, you can do that already. We have included the module
86 @code{(srfi srfi-13)} in the distribution, which currently does nothing,
87 but ensures that you can write future-safe code.
89 Generally, support for a specific SRFI is made available by using
90 modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
91 number of the SRFI needed. Another possibility is to use the command
92 line option @code{--use-srfi}, which will load the necessary modules
93 automatically (@pxref{Invoking Guile}).
97 @subsection SRFI-0 - cond-expand
100 This SRFI lets a portable Scheme program test for the presence of
101 certain features, and adapt itself by using different blocks of code,
102 or fail if the necessary features are not available. There's no
103 module to load, this is in the Guile core.
105 A program designed only for Guile will generally not need this
106 mechanism, such a program can of course directly use the various
107 documented parts of Guile.
109 @deffn syntax cond-expand (feature body@dots{}) @dots{}
110 Expand to the @var{body} of the first clause whose @var{feature}
111 specification is satisfied. It is an error if no @var{feature} is
114 Features are symbols such as @code{srfi-1}, and a feature
115 specification can use @code{and}, @code{or} and @code{not} forms to
116 test combinations. The last clause can be an @code{else}, to be used
119 For example, define a private version of @code{alist-cons} if SRFI-1
126 (define (alist-cons key val alist)
127 (cons (cons key val) alist))))
130 Or demand a certain set of SRFIs (list operations, string ports,
131 @code{receive} and string operations), failing if they're not
135 (cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13)
141 The Guile core has the following features,
145 guile-2 ;; starting from Guile 2.x
158 Other SRFI feature symbols are defined once their code has been loaded
159 with @code{use-modules}, since only then are their bindings available.
161 The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is
162 a good way to load SRFIs to satisfy @code{cond-expand} when running a
165 Testing the @code{guile} feature allows a program to adapt itself to
166 the Guile module system, but still run on other Scheme systems. For
167 example the following demands SRFI-8 (@code{receive}), but also knows
168 how to load it with the Guile mechanism.
174 (use-modules (srfi srfi-8))))
177 @cindex @code{guile-2} SRFI-0 feature
178 @cindex portability between 2.0 and older versions
179 Likewise, testing the @code{guile-2} feature allows code to be portable
180 between Guile 2.0 and previous versions of Guile. For instance, it
181 makes it possible to write code that accounts for Guile 2.0's compiler,
182 yet be correctly interpreted on 1.8 and earlier versions:
185 (cond-expand (guile-2 (eval-when (compile)
186 ;; This must be evaluated at compile time.
187 (fluid-set! current-reader my-reader)))
189 ;; Earlier versions of Guile do not have a
190 ;; separate compilation phase.
191 (fluid-set! current-reader my-reader)))
194 It should be noted that @code{cond-expand} is separate from the
195 @code{*features*} mechanism (@pxref{Feature Tracking}), feature
196 symbols in one are unrelated to those in the other.
200 @subsection SRFI-1 - List library
204 @c FIXME::martin: Review me!
206 The list library defined in SRFI-1 contains a lot of useful list
207 processing procedures for construction, examining, destructuring and
208 manipulating lists and pairs.
210 Since SRFI-1 also defines some procedures which are already contained
211 in R5RS and thus are supported by the Guile core library, some list
212 and pair procedures which appear in the SRFI-1 document may not appear
213 in this section. So when looking for a particular list/pair
214 processing procedure, you should also have a look at the sections
215 @ref{Lists} and @ref{Pairs}.
218 * SRFI-1 Constructors:: Constructing new lists.
219 * SRFI-1 Predicates:: Testing list for specific properties.
220 * SRFI-1 Selectors:: Selecting elements from lists.
221 * SRFI-1 Length Append etc:: Length calculation and list appending.
222 * SRFI-1 Fold and Map:: Higher-order list processing.
223 * SRFI-1 Filtering and Partitioning:: Filter lists based on predicates.
224 * SRFI-1 Searching:: Search for elements.
225 * SRFI-1 Deleting:: Delete elements from lists.
226 * SRFI-1 Association Lists:: Handle association lists.
227 * SRFI-1 Set Operations:: Use lists for representing sets.
230 @node SRFI-1 Constructors
231 @subsubsection Constructors
232 @cindex list constructor
234 @c FIXME::martin: Review me!
236 New lists can be constructed by calling one of the following
239 @deffn {Scheme Procedure} xcons d a
240 Like @code{cons}, but with interchanged arguments. Useful mostly when
241 passed to higher-order procedures.
244 @deffn {Scheme Procedure} list-tabulate n init-proc
245 Return an @var{n}-element list, where each list element is produced by
246 applying the procedure @var{init-proc} to the corresponding list
247 index. The order in which @var{init-proc} is applied to the indices
251 @deffn {Scheme Procedure} list-copy lst
252 Return a new list containing the elements of the list @var{lst}.
254 This function differs from the core @code{list-copy} (@pxref{List
255 Constructors}) in accepting improper lists too. And if @var{lst} is
256 not a pair at all then it's treated as the final tail of an improper
257 list and simply returned.
260 @deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
261 Return a circular list containing the given arguments @var{elt1}
265 @deffn {Scheme Procedure} iota count [start step]
266 Return a list containing @var{count} numbers, starting from
267 @var{start} and adding @var{step} each time. The default @var{start}
268 is 0, the default @var{step} is 1. For example,
271 (iota 6) @result{} (0 1 2 3 4 5)
272 (iota 4 2.5 -2) @result{} (2.5 0.5 -1.5 -3.5)
275 This function takes its name from the corresponding primitive in the
280 @node SRFI-1 Predicates
281 @subsubsection Predicates
282 @cindex list predicate
284 @c FIXME::martin: Review me!
286 The procedures in this section test specific properties of lists.
288 @deffn {Scheme Procedure} proper-list? obj
289 Return @code{#t} if @var{obj} is a proper list, or @code{#f}
290 otherwise. This is the same as the core @code{list?} (@pxref{List
293 A proper list is a list which ends with the empty list @code{()} in
294 the usual way. The empty list @code{()} itself is a proper list too.
297 (proper-list? '(1 2 3)) @result{} #t
298 (proper-list? '()) @result{} #t
302 @deffn {Scheme Procedure} circular-list? obj
303 Return @code{#t} if @var{obj} is a circular list, or @code{#f}
306 A circular list is a list where at some point the @code{cdr} refers
307 back to a previous pair in the list (either the start or some later
308 point), so that following the @code{cdr}s takes you around in a
312 (define x (list 1 2 3 4))
313 (set-cdr! (last-pair x) (cddr x))
314 x @result{} (1 2 3 4 3 4 3 4 ...)
315 (circular-list? x) @result{} #t
319 @deffn {Scheme Procedure} dotted-list? obj
320 Return @code{#t} if @var{obj} is a dotted list, or @code{#f}
323 A dotted list is a list where the @code{cdr} of the last pair is not
324 the empty list @code{()}. Any non-pair @var{obj} is also considered a
325 dotted list, with length zero.
328 (dotted-list? '(1 2 . 3)) @result{} #t
329 (dotted-list? 99) @result{} #t
333 It will be noted that any Scheme object passes exactly one of the
334 above three tests @code{proper-list?}, @code{circular-list?} and
335 @code{dotted-list?}. Non-lists are @code{dotted-list?}, finite lists
336 are either @code{proper-list?} or @code{dotted-list?}, and infinite
337 lists are @code{circular-list?}.
340 @deffn {Scheme Procedure} null-list? lst
341 Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
342 otherwise. If something else than a proper or circular list is passed
343 as @var{lst}, an error is signalled. This procedure is recommended
344 for checking for the end of a list in contexts where dotted lists are
348 @deffn {Scheme Procedure} not-pair? obj
349 Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
350 This is shorthand notation @code{(not (pair? @var{obj}))} and is
351 supposed to be used for end-of-list checking in contexts where dotted
355 @deffn {Scheme Procedure} list= elt= list1 @dots{}
356 Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
357 List equality is determined by testing whether all lists have the same
358 length and the corresponding elements are equal in the sense of the
359 equality predicate @var{elt=}. If no or only one list is given,
360 @code{#t} is returned.
364 @node SRFI-1 Selectors
365 @subsubsection Selectors
366 @cindex list selector
368 @c FIXME::martin: Review me!
370 @deffn {Scheme Procedure} first pair
371 @deffnx {Scheme Procedure} second pair
372 @deffnx {Scheme Procedure} third pair
373 @deffnx {Scheme Procedure} fourth pair
374 @deffnx {Scheme Procedure} fifth pair
375 @deffnx {Scheme Procedure} sixth pair
376 @deffnx {Scheme Procedure} seventh pair
377 @deffnx {Scheme Procedure} eighth pair
378 @deffnx {Scheme Procedure} ninth pair
379 @deffnx {Scheme Procedure} tenth pair
380 These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
383 @deffn {Scheme Procedure} car+cdr pair
384 Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
387 @deffn {Scheme Procedure} take lst i
388 @deffnx {Scheme Procedure} take! lst i
389 Return a list containing the first @var{i} elements of @var{lst}.
391 @code{take!} may modify the structure of the argument list @var{lst}
392 in order to produce the result.
395 @deffn {Scheme Procedure} drop lst i
396 Return a list containing all but the first @var{i} elements of
400 @deffn {Scheme Procedure} take-right lst i
401 Return a list containing the @var{i} last elements of @var{lst}.
402 The return shares a common tail with @var{lst}.
405 @deffn {Scheme Procedure} drop-right lst i
406 @deffnx {Scheme Procedure} drop-right! lst i
407 Return a list containing all but the @var{i} last elements of
410 @code{drop-right} always returns a new list, even when @var{i} is
411 zero. @code{drop-right!} may modify the structure of the argument
412 list @var{lst} in order to produce the result.
415 @deffn {Scheme Procedure} split-at lst i
416 @deffnx {Scheme Procedure} split-at! lst i
417 Return two values, a list containing the first @var{i} elements of the
418 list @var{lst} and a list containing the remaining elements.
420 @code{split-at!} may modify the structure of the argument list
421 @var{lst} in order to produce the result.
424 @deffn {Scheme Procedure} last lst
425 Return the last element of the non-empty, finite list @var{lst}.
429 @node SRFI-1 Length Append etc
430 @subsubsection Length, Append, Concatenate, etc.
432 @c FIXME::martin: Review me!
434 @deffn {Scheme Procedure} length+ lst
435 Return the length of the argument list @var{lst}. When @var{lst} is a
436 circular list, @code{#f} is returned.
439 @deffn {Scheme Procedure} concatenate list-of-lists
440 @deffnx {Scheme Procedure} concatenate! list-of-lists
441 Construct a list by appending all lists in @var{list-of-lists}.
443 @code{concatenate!} may modify the structure of the given lists in
444 order to produce the result.
446 @code{concatenate} is the same as @code{(apply append
447 @var{list-of-lists})}. It exists because some Scheme implementations
448 have a limit on the number of arguments a function takes, which the
449 @code{apply} might exceed. In Guile there is no such limit.
452 @deffn {Scheme Procedure} append-reverse rev-head tail
453 @deffnx {Scheme Procedure} append-reverse! rev-head tail
454 Reverse @var{rev-head}, append @var{tail} to it, and return the
455 result. This is equivalent to @code{(append (reverse @var{rev-head})
456 @var{tail})}, but its implementation is more efficient.
459 (append-reverse '(1 2 3) '(4 5 6)) @result{} (3 2 1 4 5 6)
462 @code{append-reverse!} may modify @var{rev-head} in order to produce
466 @deffn {Scheme Procedure} zip lst1 lst2 @dots{}
467 Return a list as long as the shortest of the argument lists, where
468 each element is a list. The first list contains the first elements of
469 the argument lists, the second list contains the second elements, and
473 @deffn {Scheme Procedure} unzip1 lst
474 @deffnx {Scheme Procedure} unzip2 lst
475 @deffnx {Scheme Procedure} unzip3 lst
476 @deffnx {Scheme Procedure} unzip4 lst
477 @deffnx {Scheme Procedure} unzip5 lst
478 @code{unzip1} takes a list of lists, and returns a list containing the
479 first elements of each list, @code{unzip2} returns two lists, the
480 first containing the first elements of each lists and the second
481 containing the second elements of each lists, and so on.
484 @deffn {Scheme Procedure} count pred lst1 lst2 @dots{}
485 Return a count of the number of times @var{pred} returns true when
486 called on elements from the given lists.
488 @var{pred} is called with @var{N} parameters @code{(@var{pred}
489 @var{elem1} @dots{} @var{elemN} )}, each element being from the
490 corresponding list. The first call is with the first element of each
491 list, the second with the second element from each, and so on.
493 Counting stops when the end of the shortest list is reached. At least
494 one list must be non-circular.
498 @node SRFI-1 Fold and Map
499 @subsubsection Fold, Unfold & Map
503 @c FIXME::martin: Review me!
505 @deffn {Scheme Procedure} fold proc init lst1 lst2 @dots{}
506 @deffnx {Scheme Procedure} fold-right proc init lst1 lst2 @dots{}
507 Apply @var{proc} to the elements of @var{lst1} @var{lst2} @dots{} to
508 build a result, and return that result.
510 Each @var{proc} call is @code{(@var{proc} @var{elem1} @var{elem2}
511 @dots{} @var{previous})}, where @var{elem1} is from @var{lst1},
512 @var{elem2} is from @var{lst2}, and so on. @var{previous} is the return
513 from the previous call to @var{proc}, or the given @var{init} for the
514 first call. If any list is empty, just @var{init} is returned.
516 @code{fold} works through the list elements from first to last. The
517 following shows a list reversal and the calls it makes,
520 (fold cons '() '(1 2 3))
528 @code{fold-right} works through the list elements from last to first,
529 ie.@: from the right. So for example the following finds the longest
530 string, and the last among equal longest,
533 (fold-right (lambda (str prev)
534 (if (> (string-length str) (string-length prev))
538 '("x" "abc" "xyz" "jk"))
542 If @var{lst1} @var{lst2} @dots{} have different lengths, @code{fold}
543 stops when the end of the shortest is reached; @code{fold-right}
544 commences at the last element of the shortest. Ie.@: elements past the
545 length of the shortest are ignored in the other @var{lst}s. At least
546 one @var{lst} must be non-circular.
548 @code{fold} should be preferred over @code{fold-right} if the order of
549 processing doesn't matter, or can be arranged either way, since
550 @code{fold} is a little more efficient.
552 The way @code{fold} builds a result from iterating is quite general,
553 it can do more than other iterations like say @code{map} or
554 @code{filter}. The following for example removes adjacent duplicate
555 elements from a list,
558 (define (delete-adjacent-duplicates lst)
559 (fold-right (lambda (elem ret)
560 (if (equal? elem (first ret))
565 (delete-adjacent-duplicates '(1 2 3 3 4 4 4 5))
566 @result{} (1 2 3 4 5)
569 Clearly the same sort of thing can be done with a @code{for-each} and
570 a variable in which to build the result, but a self-contained
571 @var{proc} can be re-used in multiple contexts, where a
572 @code{for-each} would have to be written out each time.
575 @deffn {Scheme Procedure} pair-fold proc init lst1 lst2 @dots{}
576 @deffnx {Scheme Procedure} pair-fold-right proc init lst1 lst2 @dots{}
577 The same as @code{fold} and @code{fold-right}, but apply @var{proc} to
578 the pairs of the lists instead of the list elements.
581 @deffn {Scheme Procedure} reduce proc default lst
582 @deffnx {Scheme Procedure} reduce-right proc default lst
583 @code{reduce} is a variant of @code{fold}, where the first call to
584 @var{proc} is on two elements from @var{lst}, rather than one element
585 and a given initial value.
587 If @var{lst} is empty, @code{reduce} returns @var{default} (this is
588 the only use for @var{default}). If @var{lst} has just one element
589 then that's the return value. Otherwise @var{proc} is called on the
590 elements of @var{lst}.
592 Each @var{proc} call is @code{(@var{proc} @var{elem} @var{previous})},
593 where @var{elem} is from @var{lst} (the second and subsequent elements
594 of @var{lst}), and @var{previous} is the return from the previous call
595 to @var{proc}. The first element of @var{lst} is the @var{previous}
596 for the first call to @var{proc}.
598 For example, the following adds a list of numbers, the calls made to
599 @code{+} are shown. (Of course @code{+} accepts multiple arguments
600 and can add a list directly, with @code{apply}.)
603 (reduce + 0 '(5 6 7)) @result{} 18
606 (+ 7 11) @result{} 18
609 @code{reduce} can be used instead of @code{fold} where the @var{init}
610 value is an ``identity'', meaning a value which under @var{proc}
611 doesn't change the result, in this case 0 is an identity since
612 @code{(+ 5 0)} is just 5. @code{reduce} avoids that unnecessary call.
614 @code{reduce-right} is a similar variation on @code{fold-right},
615 working from the end (ie.@: the right) of @var{lst}. The last element
616 of @var{lst} is the @var{previous} for the first call to @var{proc},
617 and the @var{elem} values go from the second last.
619 @code{reduce} should be preferred over @code{reduce-right} if the
620 order of processing doesn't matter, or can be arranged either way,
621 since @code{reduce} is a little more efficient.
624 @deffn {Scheme Procedure} unfold p f g seed [tail-gen]
625 @code{unfold} is defined as follows:
628 (unfold p f g seed) =
629 (if (p seed) (tail-gen seed)
631 (unfold p f g (g seed))))
636 Determines when to stop unfolding.
639 Maps each seed value to the corresponding list element.
642 Maps each seed value to next seed value.
645 The state value for the unfold.
648 Creates the tail of the list; defaults to @code{(lambda (x) '())}.
651 @var{g} produces a series of seed values, which are mapped to list
652 elements by @var{f}. These elements are put into a list in
653 left-to-right order, and @var{p} tells when to stop unfolding.
656 @deffn {Scheme Procedure} unfold-right p f g seed [tail]
657 Construct a list with the following loop.
660 (let lp ((seed seed) (lis tail))
663 (cons (f seed) lis))))
668 Determines when to stop unfolding.
671 Maps each seed value to the corresponding list element.
674 Maps each seed value to next seed value.
677 The state value for the unfold.
680 The tail of the list; defaults to @code{'()}.
685 @deffn {Scheme Procedure} map f lst1 lst2 @dots{}
686 Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
687 return a list containing the results of the procedure applications.
688 This procedure is extended with respect to R5RS, because the argument
689 lists may have different lengths. The result list will have the same
690 length as the shortest argument lists. The order in which @var{f}
691 will be applied to the list element(s) is not specified.
694 @deffn {Scheme Procedure} for-each f lst1 lst2 @dots{}
695 Apply the procedure @var{f} to each pair of corresponding elements of
696 the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not
697 specified. This procedure is extended with respect to R5RS, because
698 the argument lists may have different lengths. The shortest argument
699 list determines the number of times @var{f} is called. @var{f} will
700 be applied to the list elements in left-to-right order.
704 @deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
705 @deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
709 (apply append (map f clist1 clist2 ...))
715 (apply append! (map f clist1 clist2 ...))
718 Map @var{f} over the elements of the lists, just as in the @code{map}
719 function. However, the results of the applications are appended
720 together to make the final result. @code{append-map} uses
721 @code{append} to append the results together; @code{append-map!} uses
724 The dynamic order in which the various applications of @var{f} are
725 made is not specified.
728 @deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
729 Linear-update variant of @code{map} -- @code{map!} is allowed, but not
730 required, to alter the cons cells of @var{lst1} to construct the
733 The dynamic order in which the various applications of @var{f} are
734 made is not specified. In the n-ary case, @var{lst2}, @var{lst3},
735 @dots{} must have at least as many elements as @var{lst1}.
738 @deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{}
739 Like @code{for-each}, but applies the procedure @var{f} to the pairs
740 from which the argument lists are constructed, instead of the list
741 elements. The return value is not specified.
744 @deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
745 Like @code{map}, but only results from the applications of @var{f}
746 which are true are saved in the result list.
750 @node SRFI-1 Filtering and Partitioning
751 @subsubsection Filtering and Partitioning
753 @cindex list partition
755 @c FIXME::martin: Review me!
757 Filtering means to collect all elements from a list which satisfy a
758 specific condition. Partitioning a list means to make two groups of
759 list elements, one which contains the elements satisfying a condition,
760 and the other for the elements which don't.
762 The @code{filter} and @code{filter!} functions are implemented in the
763 Guile core, @xref{List Modification}.
765 @deffn {Scheme Procedure} partition pred lst
766 @deffnx {Scheme Procedure} partition! pred lst
767 Split @var{lst} into those elements which do and don't satisfy the
768 predicate @var{pred}.
770 The return is two values (@pxref{Multiple Values}), the first being a
771 list of all elements from @var{lst} which satisfy @var{pred}, the
772 second a list of those which do not.
774 The elements in the result lists are in the same order as in @var{lst}
775 but the order in which the calls @code{(@var{pred} elem)} are made on
776 the list elements is unspecified.
778 @code{partition} does not change @var{lst}, but one of the returned
779 lists may share a tail with it. @code{partition!} may modify
780 @var{lst} to construct its return.
783 @deffn {Scheme Procedure} remove pred lst
784 @deffnx {Scheme Procedure} remove! pred lst
785 Return a list containing all elements from @var{lst} which do not
786 satisfy the predicate @var{pred}. The elements in the result list
787 have the same order as in @var{lst}. The order in which @var{pred} is
788 applied to the list elements is not specified.
790 @code{remove!} is allowed, but not required to modify the structure of
795 @node SRFI-1 Searching
796 @subsubsection Searching
799 @c FIXME::martin: Review me!
801 The procedures for searching elements in lists either accept a
802 predicate or a comparison object for determining which elements are to
805 @deffn {Scheme Procedure} find pred lst
806 Return the first element of @var{lst} which satisfies the predicate
807 @var{pred} and @code{#f} if no such element is found.
810 @deffn {Scheme Procedure} find-tail pred lst
811 Return the first pair of @var{lst} whose @sc{car} satisfies the
812 predicate @var{pred} and @code{#f} if no such element is found.
815 @deffn {Scheme Procedure} take-while pred lst
816 @deffnx {Scheme Procedure} take-while! pred lst
817 Return the longest initial prefix of @var{lst} whose elements all
818 satisfy the predicate @var{pred}.
820 @code{take-while!} is allowed, but not required to modify the input
821 list while producing the result.
824 @deffn {Scheme Procedure} drop-while pred lst
825 Drop the longest initial prefix of @var{lst} whose elements all
826 satisfy the predicate @var{pred}.
829 @deffn {Scheme Procedure} span pred lst
830 @deffnx {Scheme Procedure} span! pred lst
831 @deffnx {Scheme Procedure} break pred lst
832 @deffnx {Scheme Procedure} break! pred lst
833 @code{span} splits the list @var{lst} into the longest initial prefix
834 whose elements all satisfy the predicate @var{pred}, and the remaining
835 tail. @code{break} inverts the sense of the predicate.
837 @code{span!} and @code{break!} are allowed, but not required to modify
838 the structure of the input list @var{lst} in order to produce the
841 Note that the name @code{break} conflicts with the @code{break}
842 binding established by @code{while} (@pxref{while do}). Applications
843 wanting to use @code{break} from within a @code{while} loop will need
844 to make a new define under a different name.
847 @deffn {Scheme Procedure} any pred lst1 lst2 @dots{}
848 Test whether any set of elements from @var{lst1} @var{lst2} @dots{}
849 satisfies @var{pred}. If so, the return value is the return value from
850 the successful @var{pred} call, or if not, the return value is
853 If there are n list arguments, then @var{pred} must be a predicate
854 taking n arguments. Each @var{pred} call is @code{(@var{pred}
855 @var{elem1} @var{elem2} @dots{} )} taking an element from each
856 @var{lst}. The calls are made successively for the first, second, etc.
857 elements of the lists, stopping when @var{pred} returns non-@code{#f},
858 or when the end of the shortest list is reached.
860 The @var{pred} call on the last set of elements (i.e., when the end of
861 the shortest list has been reached), if that point is reached, is a
865 @deffn {Scheme Procedure} every pred lst1 lst2 @dots{}
866 Test whether every set of elements from @var{lst1} @var{lst2} @dots{}
867 satisfies @var{pred}. If so, the return value is the return from the
868 final @var{pred} call, or if not, the return value is @code{#f}.
870 If there are n list arguments, then @var{pred} must be a predicate
871 taking n arguments. Each @var{pred} call is @code{(@var{pred}
872 @var{elem1} @var{elem2 @dots{}})} taking an element from each
873 @var{lst}. The calls are made successively for the first, second, etc.
874 elements of the lists, stopping if @var{pred} returns @code{#f}, or when
875 the end of any of the lists is reached.
877 The @var{pred} call on the last set of elements (i.e., when the end of
878 the shortest list has been reached) is a tail call.
880 If one of @var{lst1} @var{lst2} @dots{}is empty then no calls to
881 @var{pred} are made, and the return value is @code{#t}.
884 @deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{}
885 Return the index of the first set of elements, one from each of
886 @var{lst1} @var{lst2} @dots{}, which satisfies @var{pred}.
888 @var{pred} is called as @code{(@var{elem1} @var{elem2 @dots{}})}.
889 Searching stops when the end of the shortest @var{lst} is reached.
890 The return index starts from 0 for the first set of elements. If no
891 set of elements pass, then the return value is @code{#f}.
894 (list-index odd? '(2 4 6 9)) @result{} 3
895 (list-index = '(1 2 3) '(3 1 2)) @result{} #f
899 @deffn {Scheme Procedure} member x lst [=]
900 Return the first sublist of @var{lst} whose @sc{car} is equal to
901 @var{x}. If @var{x} does not appear in @var{lst}, return @code{#f}.
903 Equality is determined by @code{equal?}, or by the equality predicate
904 @var{=} if given. @var{=} is called @code{(= @var{x} elem)},
905 ie.@: with the given @var{x} first, so for example to find the first
906 element greater than 5,
909 (member 5 '(3 5 1 7 2 9) <) @result{} (7 2 9)
912 This version of @code{member} extends the core @code{member}
913 (@pxref{List Searching}) by accepting an equality predicate.
917 @node SRFI-1 Deleting
918 @subsubsection Deleting
921 @deffn {Scheme Procedure} delete x lst [=]
922 @deffnx {Scheme Procedure} delete! x lst [=]
923 Return a list containing the elements of @var{lst} but with those
924 equal to @var{x} deleted. The returned elements will be in the same
925 order as they were in @var{lst}.
927 Equality is determined by the @var{=} predicate, or @code{equal?} if
928 not given. An equality call is made just once for each element, but
929 the order in which the calls are made on the elements is unspecified.
931 The equality calls are always @code{(= x elem)}, ie.@: the given @var{x}
932 is first. This means for instance elements greater than 5 can be
933 deleted with @code{(delete 5 lst <)}.
935 @code{delete} does not modify @var{lst}, but the return might share a
936 common tail with @var{lst}. @code{delete!} may modify the structure
937 of @var{lst} to construct its return.
939 These functions extend the core @code{delete} and @code{delete!}
940 (@pxref{List Modification}) in accepting an equality predicate. See
941 also @code{lset-difference} (@pxref{SRFI-1 Set Operations}) for
942 deleting multiple elements from a list.
945 @deffn {Scheme Procedure} delete-duplicates lst [=]
946 @deffnx {Scheme Procedure} delete-duplicates! lst [=]
947 Return a list containing the elements of @var{lst} but without
950 When elements are equal, only the first in @var{lst} is retained.
951 Equal elements can be anywhere in @var{lst}, they don't have to be
952 adjacent. The returned list will have the retained elements in the
953 same order as they were in @var{lst}.
955 Equality is determined by the @var{=} predicate, or @code{equal?} if
956 not given. Calls @code{(= x y)} are made with element @var{x} being
957 before @var{y} in @var{lst}. A call is made at most once for each
958 combination, but the sequence of the calls across the elements is
961 @code{delete-duplicates} does not modify @var{lst}, but the return
962 might share a common tail with @var{lst}. @code{delete-duplicates!}
963 may modify the structure of @var{lst} to construct its return.
965 In the worst case, this is an @math{O(N^2)} algorithm because it must
966 check each element against all those preceding it. For long lists it
967 is more efficient to sort and then compare only adjacent elements.
971 @node SRFI-1 Association Lists
972 @subsubsection Association Lists
973 @cindex association list
976 @c FIXME::martin: Review me!
978 Association lists are described in detail in section @ref{Association
979 Lists}. The present section only documents the additional procedures
980 for dealing with association lists defined by SRFI-1.
982 @deffn {Scheme Procedure} assoc key alist [=]
983 Return the pair from @var{alist} which matches @var{key}. This
984 extends the core @code{assoc} (@pxref{Retrieving Alist Entries}) by
985 taking an optional @var{=} comparison procedure.
987 The default comparison is @code{equal?}. If an @var{=} parameter is
988 given it's called @code{(@var{=} @var{key} @var{alistcar})}, i.e.@: the
989 given target @var{key} is the first argument, and a @code{car} from
990 @var{alist} is second.
992 For example a case-insensitive string lookup,
995 (assoc "yy" '(("XX" . 1) ("YY" . 2)) string-ci=?)
1000 @deffn {Scheme Procedure} alist-cons key datum alist
1001 Cons a new association @var{key} and @var{datum} onto @var{alist} and
1002 return the result. This is equivalent to
1005 (cons (cons @var{key} @var{datum}) @var{alist})
1008 @code{acons} (@pxref{Adding or Setting Alist Entries}) in the Guile
1009 core does the same thing.
1012 @deffn {Scheme Procedure} alist-copy alist
1013 Return a newly allocated copy of @var{alist}, that means that the
1014 spine of the list as well as the pairs are copied.
1017 @deffn {Scheme Procedure} alist-delete key alist [=]
1018 @deffnx {Scheme Procedure} alist-delete! key alist [=]
1019 Return a list containing the elements of @var{alist} but with those
1020 elements whose keys are equal to @var{key} deleted. The returned
1021 elements will be in the same order as they were in @var{alist}.
1023 Equality is determined by the @var{=} predicate, or @code{equal?} if
1024 not given. The order in which elements are tested is unspecified, but
1025 each equality call is made @code{(= key alistkey)}, i.e.@: the given
1026 @var{key} parameter is first and the key from @var{alist} second.
1027 This means for instance all associations with a key greater than 5 can
1028 be removed with @code{(alist-delete 5 alist <)}.
1030 @code{alist-delete} does not modify @var{alist}, but the return might
1031 share a common tail with @var{alist}. @code{alist-delete!} may modify
1032 the list structure of @var{alist} to construct its return.
1036 @node SRFI-1 Set Operations
1037 @subsubsection Set Operations on Lists
1038 @cindex list set operation
1040 Lists can be used to represent sets of objects. The procedures in
1041 this section operate on such lists as sets.
1043 Note that lists are not an efficient way to implement large sets. The
1044 procedures here typically take time @math{@var{m}@cross{}@var{n}} when
1045 operating on @var{m} and @var{n} element lists. Other data structures
1046 like trees, bitsets (@pxref{Bit Vectors}) or hash tables (@pxref{Hash
1047 Tables}) are faster.
1049 All these procedures take an equality predicate as the first argument.
1050 This predicate is used for testing the objects in the list sets for
1051 sameness. This predicate must be consistent with @code{eq?}
1052 (@pxref{Equality}) in the sense that if two list elements are
1053 @code{eq?} then they must also be equal under the predicate. This
1054 simply means a given object must be equal to itself.
1056 @deffn {Scheme Procedure} lset<= = list @dots{}
1057 Return @code{#t} if each list is a subset of the one following it.
1058 I.e., @var{list1} is a subset of @var{list2}, @var{list2} is a subset of
1059 @var{list3}, etc., for as many lists as given. If only one list or no
1060 lists are given, the return value is @code{#t}.
1062 A list @var{x} is a subset of @var{y} if each element of @var{x} is
1063 equal to some element in @var{y}. Elements are compared using the
1064 given @var{=} procedure, called as @code{(@var{=} xelem yelem)}.
1067 (lset<= eq?) @result{} #t
1068 (lset<= eqv? '(1 2 3) '(1)) @result{} #f
1069 (lset<= eqv? '(1 3 2) '(4 3 1 2)) @result{} #t
1073 @deffn {Scheme Procedure} lset= = list @dots{}
1074 Return @code{#t} if all argument lists are set-equal. @var{list1} is
1075 compared to @var{list2}, @var{list2} to @var{list3}, etc., for as many
1076 lists as given. If only one list or no lists are given, the return
1079 Two lists @var{x} and @var{y} are set-equal if each element of @var{x}
1080 is equal to some element of @var{y} and conversely each element of
1081 @var{y} is equal to some element of @var{x}. The order of the
1082 elements in the lists doesn't matter. Element equality is determined
1083 with the given @var{=} procedure, called as @code{(@var{=} xelem
1084 yelem)}, but exactly which calls are made is unspecified.
1087 (lset= eq?) @result{} #t
1088 (lset= eqv? '(1 2 3) '(3 2 1)) @result{} #t
1089 (lset= string-ci=? '("a" "A" "b") '("B" "b" "a")) @result{} #t
1093 @deffn {Scheme Procedure} lset-adjoin = list elem @dots{}
1094 Add to @var{list} any of the given @var{elem}s not already in the list.
1095 @var{elem}s are @code{cons}ed onto the start of @var{list} (so the
1096 return value shares a common tail with @var{list}), but the order that
1097 the @var{elem}s are added is unspecified.
1099 The given @var{=} procedure is used for comparing elements, called as
1100 @code{(@var{=} listelem elem)}, i.e., the second argument is one of
1101 the given @var{elem} parameters.
1104 (lset-adjoin eqv? '(1 2 3) 4 1 5) @result{} (5 4 1 2 3)
1108 @deffn {Scheme Procedure} lset-union = list @dots{}
1109 @deffnx {Scheme Procedure} lset-union! = list @dots{}
1110 Return the union of the argument list sets. The result is built by
1111 taking the union of @var{list1} and @var{list2}, then the union of
1112 that with @var{list3}, etc., for as many lists as given. For one list
1113 argument that list itself is the result, for no list arguments the
1114 result is the empty list.
1116 The union of two lists @var{x} and @var{y} is formed as follows. If
1117 @var{x} is empty then the result is @var{y}. Otherwise start with
1118 @var{x} as the result and consider each @var{y} element (from first to
1119 last). A @var{y} element not equal to something already in the result
1120 is @code{cons}ed onto the result.
1122 The given @var{=} procedure is used for comparing elements, called as
1123 @code{(@var{=} relem yelem)}. The first argument is from the result
1124 accumulated so far, and the second is from the list being union-ed in.
1125 But exactly which calls are made is otherwise unspecified.
1127 Notice that duplicate elements in @var{list1} (or the first non-empty
1128 list) are preserved, but that repeated elements in subsequent lists
1129 are only added once.
1132 (lset-union eqv?) @result{} ()
1133 (lset-union eqv? '(1 2 3)) @result{} (1 2 3)
1134 (lset-union eqv? '(1 2 1 3) '(2 4 5) '(5)) @result{} (5 4 1 2 1 3)
1137 @code{lset-union} doesn't change the given lists but the result may
1138 share a tail with the first non-empty list. @code{lset-union!} can
1139 modify all of the given lists to form the result.
1142 @deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{}
1143 @deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{}
1144 Return the intersection of @var{list1} with the other argument lists,
1145 meaning those elements of @var{list1} which are also in all of
1146 @var{list2} etc. For one list argument, just that list is returned.
1148 The test for an element of @var{list1} to be in the return is simply
1149 that it's equal to some element in each of @var{list2} etc. Notice
1150 this means an element appearing twice in @var{list1} but only once in
1151 each of @var{list2} etc will go into the return twice. The return has
1152 its elements in the same order as they were in @var{list1}.
1154 The given @var{=} procedure is used for comparing elements, called as
1155 @code{(@var{=} elem1 elemN)}. The first argument is from @var{list1}
1156 and the second is from one of the subsequent lists. But exactly which
1157 calls are made and in what order is unspecified.
1160 (lset-intersection eqv? '(x y)) @result{} (x y)
1161 (lset-intersection eqv? '(1 2 3) '(4 3 2)) @result{} (2 3)
1162 (lset-intersection eqv? '(1 1 2 2) '(1 2) '(2 1) '(2)) @result{} (2 2)
1165 The return from @code{lset-intersection} may share a tail with
1166 @var{list1}. @code{lset-intersection!} may modify @var{list1} to form
1170 @deffn {Scheme Procedure} lset-difference = list1 list2 @dots{}
1171 @deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{}
1172 Return @var{list1} with any elements in @var{list2}, @var{list3} etc
1173 removed (ie.@: subtracted). For one list argument, just that list is
1176 The given @var{=} procedure is used for comparing elements, called as
1177 @code{(@var{=} elem1 elemN)}. The first argument is from @var{list1}
1178 and the second from one of the subsequent lists. But exactly which
1179 calls are made and in what order is unspecified.
1182 (lset-difference eqv? '(x y)) @result{} (x y)
1183 (lset-difference eqv? '(1 2 3) '(3 1)) @result{} (2)
1184 (lset-difference eqv? '(1 2 3) '(3) '(2)) @result{} (1)
1187 The return from @code{lset-difference} may share a tail with
1188 @var{list1}. @code{lset-difference!} may modify @var{list1} to form
1192 @deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{}
1193 @deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{}
1194 Return two values (@pxref{Multiple Values}), the difference and
1195 intersection of the argument lists as per @code{lset-difference} and
1196 @code{lset-intersection} above.
1198 For two list arguments this partitions @var{list1} into those elements
1199 of @var{list1} which are in @var{list2} and not in @var{list2}. (But
1200 for more than two arguments there can be elements of @var{list1} which
1201 are neither part of the difference nor the intersection.)
1203 One of the return values from @code{lset-diff+intersection} may share
1204 a tail with @var{list1}. @code{lset-diff+intersection!} may modify
1205 @var{list1} to form its results.
1208 @deffn {Scheme Procedure} lset-xor = list @dots{}
1209 @deffnx {Scheme Procedure} lset-xor! = list @dots{}
1210 Return an XOR of the argument lists. For two lists this means those
1211 elements which are in exactly one of the lists. For more than two
1212 lists it means those elements which appear in an odd number of the
1215 To be precise, the XOR of two lists @var{x} and @var{y} is formed by
1216 taking those elements of @var{x} not equal to any element of @var{y},
1217 plus those elements of @var{y} not equal to any element of @var{x}.
1218 Equality is determined with the given @var{=} procedure, called as
1219 @code{(@var{=} e1 e2)}. One argument is from @var{x} and the other
1220 from @var{y}, but which way around is unspecified. Exactly which
1221 calls are made is also unspecified, as is the order of the elements in
1225 (lset-xor eqv? '(x y)) @result{} (x y)
1226 (lset-xor eqv? '(1 2 3) '(4 3 2)) @result{} (4 1)
1229 The return from @code{lset-xor} may share a tail with one of the list
1230 arguments. @code{lset-xor!} may modify @var{list1} to form its
1236 @subsection SRFI-2 - and-let*
1240 The following syntax can be obtained with
1243 (use-modules (srfi srfi-2))
1249 (use-modules (ice-9 and-let-star))
1252 @deffn {library syntax} and-let* (clause @dots{}) body @dots{}
1253 A combination of @code{and} and @code{let*}.
1255 Each @var{clause} is evaluated in turn, and if @code{#f} is obtained
1256 then evaluation stops and @code{#f} is returned. If all are
1257 non-@code{#f} then @var{body} is evaluated and the last form gives the
1258 return value, or if @var{body} is empty then the result is @code{#t}.
1259 Each @var{clause} should be one of the following,
1263 Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}.
1264 Like @code{let*}, that binding is available to subsequent clauses.
1266 Evaluate @var{expr} and check for @code{#f}.
1268 Get the value bound to @var{symbol} and check for @code{#f}.
1271 Notice that @code{(expr)} has an ``extra'' pair of parentheses, for
1272 instance @code{((eq? x y))}. One way to remember this is to imagine
1273 the @code{symbol} in @code{(symbol expr)} is omitted.
1275 @code{and-let*} is good for calculations where a @code{#f} value means
1276 termination, but where a non-@code{#f} value is going to be needed in
1277 subsequent expressions.
1279 The following illustrates this, it returns text between brackets
1280 @samp{[...]} in a string, or @code{#f} if there are no such brackets
1281 (ie.@: either @code{string-index} gives @code{#f}).
1284 (define (extract-brackets str)
1285 (and-let* ((start (string-index str #\[))
1286 (end (string-index str #\] start)))
1287 (substring str (1+ start) end)))
1290 The following shows plain variables and expressions tested too.
1291 @code{diagnostic-levels} is taken to be an alist associating a
1292 diagnostic type with a level. @code{str} is printed only if the type
1293 is known and its level is high enough.
1296 (define (show-diagnostic type str)
1297 (and-let* (want-diagnostics
1298 (level (assq-ref diagnostic-levels type))
1299 ((>= level current-diagnostic-level)))
1303 The advantage of @code{and-let*} is that an extended sequence of
1304 expressions and tests doesn't require lots of nesting as would arise
1305 from separate @code{and} and @code{let*}, or from @code{cond} with
1312 @subsection SRFI-4 - Homogeneous numeric vector datatypes
1315 SRFI-4 provides an interface to uniform numeric vectors: vectors whose elements
1316 are all of a single numeric type. Guile offers uniform numeric vectors for
1317 signed and unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
1318 floating point values, and, as an extension to SRFI-4, complex floating-point
1319 numbers of these two sizes.
1321 The standard SRFI-4 procedures and data types may be included via loading the
1325 (use-modules (srfi srfi-4))
1328 This module is currently a part of the default Guile environment, but it is a
1329 good practice to explicitly import the module. In the future, using SRFI-4
1330 procedures without importing the SRFI-4 module will cause a deprecation message
1331 to be printed. (Of course, one may call the C functions at any time. Would that
1335 * SRFI-4 Overview:: The warp and weft of uniform numeric vectors.
1336 * SRFI-4 API:: Uniform vectors, from Scheme and from C.
1337 * SRFI-4 Generic Operations:: The general, operating on the specific.
1338 * SRFI-4 and Bytevectors:: SRFI-4 vectors are backed by bytevectors.
1339 * SRFI-4 Extensions:: Guile-specific extensions to the standard.
1342 @node SRFI-4 Overview
1343 @subsubsection SRFI-4 - Overview
1345 Uniform numeric vectors can be useful since they consume less memory
1346 than the non-uniform, general vectors. Also, since the types they can
1347 store correspond directly to C types, it is easier to work with them
1348 efficiently on a low level. Consider image processing as an example,
1349 where you want to apply a filter to some image. While you could store
1350 the pixels of an image in a general vector and write a general
1351 convolution function, things are much more efficient with uniform
1352 vectors: the convolution function knows that all pixels are unsigned
1353 8-bit values (say), and can use a very tight inner loop.
1355 This is implemented in Scheme by having the compiler notice calls to the SRFI-4
1356 accessors, and inline them to appropriate compiled code. From C you have access
1357 to the raw array; functions for efficiently working with uniform numeric vectors
1358 from C are listed at the end of this section.
1360 Uniform numeric vectors are the special case of one dimensional uniform
1363 There are 12 standard kinds of uniform numeric vectors, and they all have their
1364 own complement of constructors, accessors, and so on. Procedures that operate on
1365 a specific kind of uniform numeric vector have a ``tag'' in their name,
1366 indicating the element type.
1370 unsigned 8-bit integers
1373 signed 8-bit integers
1376 unsigned 16-bit integers
1379 signed 16-bit integers
1382 unsigned 32-bit integers
1385 signed 32-bit integers
1388 unsigned 64-bit integers
1391 signed 64-bit integers
1394 the C type @code{float}
1397 the C type @code{double}
1401 In addition, Guile supports uniform arrays of complex numbers, with the
1407 complex numbers in rectangular form with the real and imaginary part
1408 being a @code{float}
1411 complex numbers in rectangular form with the real and imaginary part
1412 being a @code{double}
1416 The external representation (ie.@: read syntax) for these vectors is
1417 similar to normal Scheme vectors, but with an additional tag from the
1418 tables above indicating the vector's type. For example,
1425 Note that the read syntax for floating-point here conflicts with
1426 @code{#f} for false. In Standard Scheme one can write @code{(1 #f3)}
1427 for a three element list @code{(1 #f 3)}, but for Guile @code{(1 #f3)}
1428 is invalid. @code{(1 #f 3)} is almost certainly what one should write
1429 anyway to make the intention clear, so this is rarely a problem.
1433 @subsubsection SRFI-4 - API
1435 Note that the @nicode{c32} and @nicode{c64} functions are only available from
1436 @nicode{(srfi srfi-4 gnu)}.
1438 @deffn {Scheme Procedure} u8vector? obj
1439 @deffnx {Scheme Procedure} s8vector? obj
1440 @deffnx {Scheme Procedure} u16vector? obj
1441 @deffnx {Scheme Procedure} s16vector? obj
1442 @deffnx {Scheme Procedure} u32vector? obj
1443 @deffnx {Scheme Procedure} s32vector? obj
1444 @deffnx {Scheme Procedure} u64vector? obj
1445 @deffnx {Scheme Procedure} s64vector? obj
1446 @deffnx {Scheme Procedure} f32vector? obj
1447 @deffnx {Scheme Procedure} f64vector? obj
1448 @deffnx {Scheme Procedure} c32vector? obj
1449 @deffnx {Scheme Procedure} c64vector? obj
1450 @deffnx {C Function} scm_u8vector_p (obj)
1451 @deffnx {C Function} scm_s8vector_p (obj)
1452 @deffnx {C Function} scm_u16vector_p (obj)
1453 @deffnx {C Function} scm_s16vector_p (obj)
1454 @deffnx {C Function} scm_u32vector_p (obj)
1455 @deffnx {C Function} scm_s32vector_p (obj)
1456 @deffnx {C Function} scm_u64vector_p (obj)
1457 @deffnx {C Function} scm_s64vector_p (obj)
1458 @deffnx {C Function} scm_f32vector_p (obj)
1459 @deffnx {C Function} scm_f64vector_p (obj)
1460 @deffnx {C Function} scm_c32vector_p (obj)
1461 @deffnx {C Function} scm_c64vector_p (obj)
1462 Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1466 @deffn {Scheme Procedure} make-u8vector n [value]
1467 @deffnx {Scheme Procedure} make-s8vector n [value]
1468 @deffnx {Scheme Procedure} make-u16vector n [value]
1469 @deffnx {Scheme Procedure} make-s16vector n [value]
1470 @deffnx {Scheme Procedure} make-u32vector n [value]
1471 @deffnx {Scheme Procedure} make-s32vector n [value]
1472 @deffnx {Scheme Procedure} make-u64vector n [value]
1473 @deffnx {Scheme Procedure} make-s64vector n [value]
1474 @deffnx {Scheme Procedure} make-f32vector n [value]
1475 @deffnx {Scheme Procedure} make-f64vector n [value]
1476 @deffnx {Scheme Procedure} make-c32vector n [value]
1477 @deffnx {Scheme Procedure} make-c64vector n [value]
1478 @deffnx {C Function} scm_make_u8vector (n, value)
1479 @deffnx {C Function} scm_make_s8vector (n, value)
1480 @deffnx {C Function} scm_make_u16vector (n, value)
1481 @deffnx {C Function} scm_make_s16vector (n, value)
1482 @deffnx {C Function} scm_make_u32vector (n, value)
1483 @deffnx {C Function} scm_make_s32vector (n, value)
1484 @deffnx {C Function} scm_make_u64vector (n, value)
1485 @deffnx {C Function} scm_make_s64vector (n, value)
1486 @deffnx {C Function} scm_make_f32vector (n, value)
1487 @deffnx {C Function} scm_make_f64vector (n, value)
1488 @deffnx {C Function} scm_make_c32vector (n, value)
1489 @deffnx {C Function} scm_make_c64vector (n, value)
1490 Return a newly allocated homogeneous numeric vector holding @var{n}
1491 elements of the indicated type. If @var{value} is given, the vector
1492 is initialized with that value, otherwise the contents are
1496 @deffn {Scheme Procedure} u8vector value @dots{}
1497 @deffnx {Scheme Procedure} s8vector value @dots{}
1498 @deffnx {Scheme Procedure} u16vector value @dots{}
1499 @deffnx {Scheme Procedure} s16vector value @dots{}
1500 @deffnx {Scheme Procedure} u32vector value @dots{}
1501 @deffnx {Scheme Procedure} s32vector value @dots{}
1502 @deffnx {Scheme Procedure} u64vector value @dots{}
1503 @deffnx {Scheme Procedure} s64vector value @dots{}
1504 @deffnx {Scheme Procedure} f32vector value @dots{}
1505 @deffnx {Scheme Procedure} f64vector value @dots{}
1506 @deffnx {Scheme Procedure} c32vector value @dots{}
1507 @deffnx {Scheme Procedure} c64vector value @dots{}
1508 @deffnx {C Function} scm_u8vector (values)
1509 @deffnx {C Function} scm_s8vector (values)
1510 @deffnx {C Function} scm_u16vector (values)
1511 @deffnx {C Function} scm_s16vector (values)
1512 @deffnx {C Function} scm_u32vector (values)
1513 @deffnx {C Function} scm_s32vector (values)
1514 @deffnx {C Function} scm_u64vector (values)
1515 @deffnx {C Function} scm_s64vector (values)
1516 @deffnx {C Function} scm_f32vector (values)
1517 @deffnx {C Function} scm_f64vector (values)
1518 @deffnx {C Function} scm_c32vector (values)
1519 @deffnx {C Function} scm_c64vector (values)
1520 Return a newly allocated homogeneous numeric vector of the indicated
1521 type, holding the given parameter @var{value}s. The vector length is
1522 the number of parameters given.
1525 @deffn {Scheme Procedure} u8vector-length vec
1526 @deffnx {Scheme Procedure} s8vector-length vec
1527 @deffnx {Scheme Procedure} u16vector-length vec
1528 @deffnx {Scheme Procedure} s16vector-length vec
1529 @deffnx {Scheme Procedure} u32vector-length vec
1530 @deffnx {Scheme Procedure} s32vector-length vec
1531 @deffnx {Scheme Procedure} u64vector-length vec
1532 @deffnx {Scheme Procedure} s64vector-length vec
1533 @deffnx {Scheme Procedure} f32vector-length vec
1534 @deffnx {Scheme Procedure} f64vector-length vec
1535 @deffnx {Scheme Procedure} c32vector-length vec
1536 @deffnx {Scheme Procedure} c64vector-length vec
1537 @deffnx {C Function} scm_u8vector_length (vec)
1538 @deffnx {C Function} scm_s8vector_length (vec)
1539 @deffnx {C Function} scm_u16vector_length (vec)
1540 @deffnx {C Function} scm_s16vector_length (vec)
1541 @deffnx {C Function} scm_u32vector_length (vec)
1542 @deffnx {C Function} scm_s32vector_length (vec)
1543 @deffnx {C Function} scm_u64vector_length (vec)
1544 @deffnx {C Function} scm_s64vector_length (vec)
1545 @deffnx {C Function} scm_f32vector_length (vec)
1546 @deffnx {C Function} scm_f64vector_length (vec)
1547 @deffnx {C Function} scm_c32vector_length (vec)
1548 @deffnx {C Function} scm_c64vector_length (vec)
1549 Return the number of elements in @var{vec}.
1552 @deffn {Scheme Procedure} u8vector-ref vec i
1553 @deffnx {Scheme Procedure} s8vector-ref vec i
1554 @deffnx {Scheme Procedure} u16vector-ref vec i
1555 @deffnx {Scheme Procedure} s16vector-ref vec i
1556 @deffnx {Scheme Procedure} u32vector-ref vec i
1557 @deffnx {Scheme Procedure} s32vector-ref vec i
1558 @deffnx {Scheme Procedure} u64vector-ref vec i
1559 @deffnx {Scheme Procedure} s64vector-ref vec i
1560 @deffnx {Scheme Procedure} f32vector-ref vec i
1561 @deffnx {Scheme Procedure} f64vector-ref vec i
1562 @deffnx {Scheme Procedure} c32vector-ref vec i
1563 @deffnx {Scheme Procedure} c64vector-ref vec i
1564 @deffnx {C Function} scm_u8vector_ref (vec, i)
1565 @deffnx {C Function} scm_s8vector_ref (vec, i)
1566 @deffnx {C Function} scm_u16vector_ref (vec, i)
1567 @deffnx {C Function} scm_s16vector_ref (vec, i)
1568 @deffnx {C Function} scm_u32vector_ref (vec, i)
1569 @deffnx {C Function} scm_s32vector_ref (vec, i)
1570 @deffnx {C Function} scm_u64vector_ref (vec, i)
1571 @deffnx {C Function} scm_s64vector_ref (vec, i)
1572 @deffnx {C Function} scm_f32vector_ref (vec, i)
1573 @deffnx {C Function} scm_f64vector_ref (vec, i)
1574 @deffnx {C Function} scm_c32vector_ref (vec, i)
1575 @deffnx {C Function} scm_c64vector_ref (vec, i)
1576 Return the element at index @var{i} in @var{vec}. The first element
1577 in @var{vec} is index 0.
1580 @deffn {Scheme Procedure} u8vector-set! vec i value
1581 @deffnx {Scheme Procedure} s8vector-set! vec i value
1582 @deffnx {Scheme Procedure} u16vector-set! vec i value
1583 @deffnx {Scheme Procedure} s16vector-set! vec i value
1584 @deffnx {Scheme Procedure} u32vector-set! vec i value
1585 @deffnx {Scheme Procedure} s32vector-set! vec i value
1586 @deffnx {Scheme Procedure} u64vector-set! vec i value
1587 @deffnx {Scheme Procedure} s64vector-set! vec i value
1588 @deffnx {Scheme Procedure} f32vector-set! vec i value
1589 @deffnx {Scheme Procedure} f64vector-set! vec i value
1590 @deffnx {Scheme Procedure} c32vector-set! vec i value
1591 @deffnx {Scheme Procedure} c64vector-set! vec i value
1592 @deffnx {C Function} scm_u8vector_set_x (vec, i, value)
1593 @deffnx {C Function} scm_s8vector_set_x (vec, i, value)
1594 @deffnx {C Function} scm_u16vector_set_x (vec, i, value)
1595 @deffnx {C Function} scm_s16vector_set_x (vec, i, value)
1596 @deffnx {C Function} scm_u32vector_set_x (vec, i, value)
1597 @deffnx {C Function} scm_s32vector_set_x (vec, i, value)
1598 @deffnx {C Function} scm_u64vector_set_x (vec, i, value)
1599 @deffnx {C Function} scm_s64vector_set_x (vec, i, value)
1600 @deffnx {C Function} scm_f32vector_set_x (vec, i, value)
1601 @deffnx {C Function} scm_f64vector_set_x (vec, i, value)
1602 @deffnx {C Function} scm_c32vector_set_x (vec, i, value)
1603 @deffnx {C Function} scm_c64vector_set_x (vec, i, value)
1604 Set the element at index @var{i} in @var{vec} to @var{value}. The
1605 first element in @var{vec} is index 0. The return value is
1609 @deffn {Scheme Procedure} u8vector->list vec
1610 @deffnx {Scheme Procedure} s8vector->list vec
1611 @deffnx {Scheme Procedure} u16vector->list vec
1612 @deffnx {Scheme Procedure} s16vector->list vec
1613 @deffnx {Scheme Procedure} u32vector->list vec
1614 @deffnx {Scheme Procedure} s32vector->list vec
1615 @deffnx {Scheme Procedure} u64vector->list vec
1616 @deffnx {Scheme Procedure} s64vector->list vec
1617 @deffnx {Scheme Procedure} f32vector->list vec
1618 @deffnx {Scheme Procedure} f64vector->list vec
1619 @deffnx {Scheme Procedure} c32vector->list vec
1620 @deffnx {Scheme Procedure} c64vector->list vec
1621 @deffnx {C Function} scm_u8vector_to_list (vec)
1622 @deffnx {C Function} scm_s8vector_to_list (vec)
1623 @deffnx {C Function} scm_u16vector_to_list (vec)
1624 @deffnx {C Function} scm_s16vector_to_list (vec)
1625 @deffnx {C Function} scm_u32vector_to_list (vec)
1626 @deffnx {C Function} scm_s32vector_to_list (vec)
1627 @deffnx {C Function} scm_u64vector_to_list (vec)
1628 @deffnx {C Function} scm_s64vector_to_list (vec)
1629 @deffnx {C Function} scm_f32vector_to_list (vec)
1630 @deffnx {C Function} scm_f64vector_to_list (vec)
1631 @deffnx {C Function} scm_c32vector_to_list (vec)
1632 @deffnx {C Function} scm_c64vector_to_list (vec)
1633 Return a newly allocated list holding all elements of @var{vec}.
1636 @deffn {Scheme Procedure} list->u8vector lst
1637 @deffnx {Scheme Procedure} list->s8vector lst
1638 @deffnx {Scheme Procedure} list->u16vector lst
1639 @deffnx {Scheme Procedure} list->s16vector lst
1640 @deffnx {Scheme Procedure} list->u32vector lst
1641 @deffnx {Scheme Procedure} list->s32vector lst
1642 @deffnx {Scheme Procedure} list->u64vector lst
1643 @deffnx {Scheme Procedure} list->s64vector lst
1644 @deffnx {Scheme Procedure} list->f32vector lst
1645 @deffnx {Scheme Procedure} list->f64vector lst
1646 @deffnx {Scheme Procedure} list->c32vector lst
1647 @deffnx {Scheme Procedure} list->c64vector lst
1648 @deffnx {C Function} scm_list_to_u8vector (lst)
1649 @deffnx {C Function} scm_list_to_s8vector (lst)
1650 @deffnx {C Function} scm_list_to_u16vector (lst)
1651 @deffnx {C Function} scm_list_to_s16vector (lst)
1652 @deffnx {C Function} scm_list_to_u32vector (lst)
1653 @deffnx {C Function} scm_list_to_s32vector (lst)
1654 @deffnx {C Function} scm_list_to_u64vector (lst)
1655 @deffnx {C Function} scm_list_to_s64vector (lst)
1656 @deffnx {C Function} scm_list_to_f32vector (lst)
1657 @deffnx {C Function} scm_list_to_f64vector (lst)
1658 @deffnx {C Function} scm_list_to_c32vector (lst)
1659 @deffnx {C Function} scm_list_to_c64vector (lst)
1660 Return a newly allocated homogeneous numeric vector of the indicated type,
1661 initialized with the elements of the list @var{lst}.
1664 @deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len)
1665 @deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len)
1666 @deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len)
1667 @deftypefnx {C Function} SCM scm_take_s16vector (const scm_t_int16 *data, size_t len)
1668 @deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len)
1669 @deftypefnx {C Function} SCM scm_take_s32vector (const scm_t_int32 *data, size_t len)
1670 @deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len)
1671 @deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len)
1672 @deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len)
1673 @deftypefnx {C Function} SCM scm_take_f64vector (const double *data, size_t len)
1674 @deftypefnx {C Function} SCM scm_take_c32vector (const float *data, size_t len)
1675 @deftypefnx {C Function} SCM scm_take_c64vector (const double *data, size_t len)
1676 Return a new uniform numeric vector of the indicated type and length
1677 that uses the memory pointed to by @var{data} to store its elements.
1678 This memory will eventually be freed with @code{free}. The argument
1679 @var{len} specifies the number of elements in @var{data}, not its size
1682 The @code{c32} and @code{c64} variants take a pointer to a C array of
1683 @code{float}s or @code{double}s. The real parts of the complex numbers
1684 are at even indices in that array, the corresponding imaginary parts are
1685 at the following odd index.
1688 @deftypefn {C Function} {const scm_t_uint8 *} scm_u8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1689 @deftypefnx {C Function} {const scm_t_int8 *} scm_s8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1690 @deftypefnx {C Function} {const scm_t_uint16 *} scm_u16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1691 @deftypefnx {C Function} {const scm_t_int16 *} scm_s16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1692 @deftypefnx {C Function} {const scm_t_uint32 *} scm_u32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1693 @deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1694 @deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1695 @deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1696 @deftypefnx {C Function} {const float *} scm_f32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1697 @deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1698 @deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1699 @deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1700 Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
1701 returns a pointer to the elements of a uniform numeric vector of the
1705 @deftypefn {C Function} {scm_t_uint8 *} scm_u8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1706 @deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1707 @deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1708 @deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1709 @deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1710 @deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1711 @deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1712 @deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1713 @deftypefnx {C Function} {float *} scm_f32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1714 @deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1715 @deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1716 @deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1717 Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from
1718 C}), but returns a pointer to the elements of a uniform numeric vector
1719 of the indicated kind.
1722 @node SRFI-4 Generic Operations
1723 @subsubsection SRFI-4 - Generic operations
1725 Guile also provides procedures that operate on all types of uniform numeric
1726 vectors. In what is probably a bug, these procedures are currently available in
1727 the default environment as well; however prudent hackers will make sure to
1728 import @code{(srfi srfi-4 gnu)} before using these.
1730 @deftypefn {C Function} int scm_is_uniform_vector (SCM uvec)
1731 Return non-zero when @var{uvec} is a uniform numeric vector, zero
1735 @deftypefn {C Function} size_t scm_c_uniform_vector_length (SCM uvec)
1736 Return the number of elements of @var{uvec} as a @code{size_t}.
1739 @deffn {Scheme Procedure} uniform-vector? obj
1740 @deffnx {C Function} scm_uniform_vector_p (obj)
1741 Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1745 @deffn {Scheme Procedure} uniform-vector-length vec
1746 @deffnx {C Function} scm_uniform_vector_length (vec)
1747 Return the number of elements in @var{vec}.
1750 @deffn {Scheme Procedure} uniform-vector-ref vec i
1751 @deffnx {C Function} scm_uniform_vector_ref (vec, i)
1752 Return the element at index @var{i} in @var{vec}. The first element
1753 in @var{vec} is index 0.
1756 @deffn {Scheme Procedure} uniform-vector-set! vec i value
1757 @deffnx {C Function} scm_uniform_vector_set_x (vec, i, value)
1758 Set the element at index @var{i} in @var{vec} to @var{value}. The
1759 first element in @var{vec} is index 0. The return value is
1763 @deffn {Scheme Procedure} uniform-vector->list vec
1764 @deffnx {C Function} scm_uniform_vector_to_list (vec)
1765 Return a newly allocated list holding all elements of @var{vec}.
1768 @deftypefn {C Function} {const void *} scm_uniform_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1769 Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
1770 returns a pointer to the elements of a uniform numeric vector.
1773 @deftypefn {C Function} {void *} scm_uniform_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1774 Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from
1775 C}), but returns a pointer to the elements of a uniform numeric vector.
1778 Unless you really need to the limited generality of these functions, it
1779 is best to use the type-specific functions, or the array accessors.
1781 @node SRFI-4 and Bytevectors
1782 @subsubsection SRFI-4 - Relation to bytevectors
1784 Guile implements SRFI-4 vectors using bytevectors (@pxref{Bytevectors}). Often
1785 when you have a numeric vector, you end up wanting to write its bytes somewhere,
1786 or have access to the underlying bytes, or read in bytes from somewhere else.
1787 Bytevectors are very good at this sort of thing. But the SRFI-4 APIs are nicer
1788 to use when doing number-crunching, because they are addressed by element and
1791 So as a compromise, Guile allows all bytevector functions to operate on numeric
1792 vectors. They address the underlying bytes in the native endianness, as one
1795 Following the same reasoning, that it's just bytes underneath, Guile also allows
1796 uniform vectors of a given type to be accessed as if they were of any type. One
1797 can fill a @nicode{u32vector}, and access its elements with
1798 @nicode{u8vector-ref}. One can use @nicode{f64vector-ref} on bytevectors. It's
1799 all the same to Guile.
1801 In this way, uniform numeric vectors may be written to and read from
1802 input/output ports using the procedures that operate on bytevectors.
1804 @xref{Bytevectors}, for more information.
1807 @node SRFI-4 Extensions
1808 @subsubsection SRFI-4 - Guile extensions
1810 Guile defines some useful extensions to SRFI-4, which are not available in the
1811 default Guile environment. They may be imported by loading the extensions
1815 (use-modules (srfi srfi-4 gnu))
1818 @deffn {Scheme Procedure} any->u8vector obj
1819 @deffnx {Scheme Procedure} any->s8vector obj
1820 @deffnx {Scheme Procedure} any->u16vector obj
1821 @deffnx {Scheme Procedure} any->s16vector obj
1822 @deffnx {Scheme Procedure} any->u32vector obj
1823 @deffnx {Scheme Procedure} any->s32vector obj
1824 @deffnx {Scheme Procedure} any->u64vector obj
1825 @deffnx {Scheme Procedure} any->s64vector obj
1826 @deffnx {Scheme Procedure} any->f32vector obj
1827 @deffnx {Scheme Procedure} any->f64vector obj
1828 @deffnx {Scheme Procedure} any->c32vector obj
1829 @deffnx {Scheme Procedure} any->c64vector obj
1830 @deffnx {C Function} scm_any_to_u8vector (obj)
1831 @deffnx {C Function} scm_any_to_s8vector (obj)
1832 @deffnx {C Function} scm_any_to_u16vector (obj)
1833 @deffnx {C Function} scm_any_to_s16vector (obj)
1834 @deffnx {C Function} scm_any_to_u32vector (obj)
1835 @deffnx {C Function} scm_any_to_s32vector (obj)
1836 @deffnx {C Function} scm_any_to_u64vector (obj)
1837 @deffnx {C Function} scm_any_to_s64vector (obj)
1838 @deffnx {C Function} scm_any_to_f32vector (obj)
1839 @deffnx {C Function} scm_any_to_f64vector (obj)
1840 @deffnx {C Function} scm_any_to_c32vector (obj)
1841 @deffnx {C Function} scm_any_to_c64vector (obj)
1842 Return a (maybe newly allocated) uniform numeric vector of the indicated
1843 type, initialized with the elements of @var{obj}, which must be a list,
1844 a vector, or a uniform vector. When @var{obj} is already a suitable
1845 uniform numeric vector, it is returned unchanged.
1850 @subsection SRFI-6 - Basic String Ports
1853 SRFI-6 defines the procedures @code{open-input-string},
1854 @code{open-output-string} and @code{get-output-string}.
1856 Note that although versions of these procedures are included in the
1857 Guile core, the core versions are not fully conformant with SRFI-6:
1858 attempts to read or write characters that are not supported by the
1859 current @code{%default-port-encoding} will fail.
1861 We therefore recommend that you import this module, which supports all
1865 (use-modules (srfi srfi-6))
1869 @subsection SRFI-8 - receive
1872 @code{receive} is a syntax for making the handling of multiple-value
1873 procedures easier. It is documented in @xref{Multiple Values}.
1877 @subsection SRFI-9 - define-record-type
1879 This SRFI is a syntax for defining new record types and creating
1880 predicate, constructor, and field getter and setter functions. It is
1881 documented in the ``Compound Data Types'' section of the manual
1882 (@pxref{SRFI-9 Records}).
1886 @subsection SRFI-10 - Hash-Comma Reader Extension
1891 This SRFI implements a reader extension @code{#,()} called hash-comma.
1892 It allows the reader to give new kinds of objects, for use both in
1893 data and as constants or literals in source code. This feature is
1897 (use-modules (srfi srfi-10))
1901 The new read syntax is of the form
1904 #,(@var{tag} @var{arg}@dots{})
1908 where @var{tag} is a symbol and the @var{arg}s are objects taken as
1909 parameters. @var{tag}s are registered with the following procedure.
1911 @deffn {Scheme Procedure} define-reader-ctor tag proc
1912 Register @var{proc} as the constructor for a hash-comma read syntax
1913 starting with symbol @var{tag}, i.e.@: @nicode{#,(@var{tag} arg@dots{})}.
1914 @var{proc} is called with the given arguments @code{(@var{proc}
1915 arg@dots{})} and the object it returns is the result of the read.
1919 For example, a syntax giving a list of @var{N} copies of an object.
1922 (define-reader-ctor 'repeat
1924 (make-list reps obj)))
1926 (display '#,(repeat 99 3))
1930 Notice the quote @nicode{'} when the @nicode{#,( )} is used. The
1931 @code{repeat} handler returns a list and the program must quote to use
1932 it literally, the same as any other list. Ie.
1935 (display '#,(repeat 99 3))
1937 (display '(99 99 99))
1940 When a handler returns an object which is self-evaluating, like a
1941 number or a string, then there's no need for quoting, just as there's
1942 no need when giving those directly as literals. For example an
1946 (define-reader-ctor 'sum
1949 (display #,(sum 123 456)) @print{} 579
1952 A typical use for @nicode{#,()} is to get a read syntax for objects
1953 which don't otherwise have one. For example, the following allows a
1954 hash table to be given literally, with tags and values, ready for fast
1958 (define-reader-ctor 'hash
1960 (let ((table (make-hash-table)))
1961 (for-each (lambda (elem)
1962 (apply hash-set! table elem))
1966 (define (animal->family animal)
1967 (hash-ref '#,(hash ("tiger" "cat")
1972 (animal->family "lion") @result{} "cat"
1975 Or for example the following is a syntax for a compiled regular
1976 expression (@pxref{Regular Expressions}).
1979 (use-modules (ice-9 regex))
1981 (define-reader-ctor 'regexp make-regexp)
1983 (define (extract-angs str)
1984 (let ((match (regexp-exec '#,(regexp "<([A-Z0-9]+)>") str)))
1986 (match:substring match 1))))
1988 (extract-angs "foo <BAR> quux") @result{} "BAR"
1992 @nicode{#,()} is somewhat similar to @code{define-macro}
1993 (@pxref{Macros}) in that handler code is run to produce a result, but
1994 @nicode{#,()} operates at the read stage, so it can appear in data for
1995 @code{read} (@pxref{Scheme Read}), not just in code to be executed.
1997 Because @nicode{#,()} is handled at read-time it has no direct access
1998 to variables etc. A symbol in the arguments is just a symbol, not a
1999 variable reference. The arguments are essentially constants, though
2000 the handler procedure can use them in any complicated way it might
2003 Once @code{(srfi srfi-10)} has loaded, @nicode{#,()} is available
2004 globally, there's no need to use @code{(srfi srfi-10)} in later
2005 modules. Similarly the tags registered are global and can be used
2006 anywhere once registered.
2008 There's no attempt to record what previous @nicode{#,()} forms have
2009 been seen, if two identical forms occur then two calls are made to the
2010 handler procedure. The handler might like to maintain a cache or
2011 similar to avoid making copies of large objects, depending on expected
2014 In code the best uses of @nicode{#,()} are generally when there's a
2015 lot of objects of a particular kind as literals or constants. If
2016 there's just a few then some local variables and initializers are
2017 fine, but that becomes tedious and error prone when there's a lot, and
2018 the anonymous and compact syntax of @nicode{#,()} is much better.
2022 @subsection SRFI-11 - let-values
2027 This module implements the binding forms for multiple values
2028 @code{let-values} and @code{let*-values}. These forms are similar to
2029 @code{let} and @code{let*} (@pxref{Local Bindings}), but they support
2030 binding of the values returned by multiple-valued expressions.
2032 Write @code{(use-modules (srfi srfi-11))} to make the bindings
2036 (let-values (((x y) (values 1 2))
2037 ((z f) (values 3 4)))
2043 @code{let-values} performs all bindings simultaneously, which means that
2044 no expression in the binding clauses may refer to variables bound in the
2045 same clause list. @code{let*-values}, on the other hand, performs the
2046 bindings sequentially, just like @code{let*} does for single-valued
2051 @subsection SRFI-13 - String Library
2054 The SRFI-13 procedures are always available, @xref{Strings}.
2057 @subsection SRFI-14 - Character-set Library
2060 The SRFI-14 data type and procedures are always available,
2061 @xref{Character Sets}.
2064 @subsection SRFI-16 - case-lambda
2066 @cindex variable arity
2067 @cindex arity, variable
2069 SRFI-16 defines a variable-arity @code{lambda} form,
2070 @code{case-lambda}. This form is available in the default Guile
2071 environment. @xref{Case-lambda}, for more information.
2074 @subsection SRFI-17 - Generalized set!
2077 This SRFI implements a generalized @code{set!}, allowing some
2078 ``referencing'' functions to be used as the target location of a
2079 @code{set!}. This feature is available from
2082 (use-modules (srfi srfi-17))
2086 For example @code{vector-ref} is extended so that
2089 (set! (vector-ref vec idx) new-value)
2096 (vector-set! vec idx new-value)
2099 The idea is that a @code{vector-ref} expression identifies a location,
2100 which may be either fetched or stored. The same form is used for the
2101 location in both cases, encouraging visual clarity. This is similar
2102 to the idea of an ``lvalue'' in C.
2104 The mechanism for this kind of @code{set!} is in the Guile core
2105 (@pxref{Procedures with Setters}). This module adds definitions of
2106 the following functions as procedures with setters, allowing them to
2107 be targets of a @code{set!},
2110 @nicode{car}, @nicode{cdr}, @nicode{caar}, @nicode{cadr},
2111 @nicode{cdar}, @nicode{cddr}, @nicode{caaar}, @nicode{caadr},
2112 @nicode{cadar}, @nicode{caddr}, @nicode{cdaar}, @nicode{cdadr},
2113 @nicode{cddar}, @nicode{cdddr}, @nicode{caaaar}, @nicode{caaadr},
2114 @nicode{caadar}, @nicode{caaddr}, @nicode{cadaar}, @nicode{cadadr},
2115 @nicode{caddar}, @nicode{cadddr}, @nicode{cdaaar}, @nicode{cdaadr},
2116 @nicode{cdadar}, @nicode{cdaddr}, @nicode{cddaar}, @nicode{cddadr},
2117 @nicode{cdddar}, @nicode{cddddr}
2119 @nicode{string-ref}, @nicode{vector-ref}
2122 The SRFI specifies @code{setter} (@pxref{Procedures with Setters}) as
2123 a procedure with setter, allowing the setter for a procedure to be
2124 changed, eg.@: @code{(set! (setter foo) my-new-setter-handler)}.
2125 Currently Guile does not implement this, a setter can only be
2126 specified on creation (@code{getter-with-setter} below).
2128 @defun getter-with-setter
2129 The same as the Guile core @code{make-procedure-with-setter}
2130 (@pxref{Procedures with Setters}).
2135 @subsection SRFI-18 - Multithreading support
2138 This is an implementation of the SRFI-18 threading and synchronization
2139 library. The functions and variables described here are provided by
2142 (use-modules (srfi srfi-18))
2145 As a general rule, the data types and functions in this SRFI-18
2146 implementation are compatible with the types and functions in Guile's
2147 core threading code. For example, mutexes created with the SRFI-18
2148 @code{make-mutex} function can be passed to the built-in Guile
2149 function @code{lock-mutex} (@pxref{Mutexes and Condition Variables}),
2150 and mutexes created with the built-in Guile function @code{make-mutex}
2151 can be passed to the SRFI-18 function @code{mutex-lock!}. Cases in
2152 which this does not hold true are noted in the following sections.
2155 * SRFI-18 Threads:: Executing code
2156 * SRFI-18 Mutexes:: Mutual exclusion devices
2157 * SRFI-18 Condition variables:: Synchronizing of groups of threads
2158 * SRFI-18 Time:: Representation of times and durations
2159 * SRFI-18 Exceptions:: Signalling and handling errors
2162 @node SRFI-18 Threads
2163 @subsubsection SRFI-18 Threads
2165 Threads created by SRFI-18 differ in two ways from threads created by
2166 Guile's built-in thread functions. First, a thread created by SRFI-18
2167 @code{make-thread} begins in a blocked state and will not start
2168 execution until @code{thread-start!} is called on it. Second, SRFI-18
2169 threads are constructed with a top-level exception handler that
2170 captures any exceptions that are thrown on thread exit. In all other
2171 regards, SRFI-18 threads are identical to normal Guile threads.
2173 @defun current-thread
2174 Returns the thread that called this function. This is the same
2175 procedure as the same-named built-in procedure @code{current-thread}
2180 Returns @code{#t} if @var{obj} is a thread, @code{#f} otherwise. This
2181 is the same procedure as the same-named built-in procedure
2182 @code{thread?} (@pxref{Threads}).
2185 @defun make-thread thunk [name]
2186 Call @code{thunk} in a new thread and with a new dynamic state,
2187 returning the new thread and optionally assigning it the object name
2188 @var{name}, which may be any Scheme object.
2190 Note that the name @code{make-thread} conflicts with the
2191 @code{(ice-9 threads)} function @code{make-thread}. Applications
2192 wanting to use both of these functions will need to refer to them by
2196 @defun thread-name thread
2197 Returns the name assigned to @var{thread} at the time of its creation,
2198 or @code{#f} if it was not given a name.
2201 @defun thread-specific thread
2202 @defunx thread-specific-set! thread obj
2203 Get or set the ``object-specific'' property of @var{thread}. In
2204 Guile's implementation of SRFI-18, this value is stored as an object
2205 property, and will be @code{#f} if not set.
2208 @defun thread-start! thread
2209 Unblocks @var{thread} and allows it to begin execution if it has not
2213 @defun thread-yield!
2214 If one or more threads are waiting to execute, calling
2215 @code{thread-yield!} forces an immediate context switch to one of them.
2216 Otherwise, @code{thread-yield!} has no effect. @code{thread-yield!}
2217 behaves identically to the Guile built-in function @code{yield}.
2220 @defun thread-sleep! timeout
2221 The current thread waits until the point specified by the time object
2222 @var{timeout} is reached (@pxref{SRFI-18 Time}). This blocks the
2223 thread only if @var{timeout} represents a point in the future. it is
2224 an error for @var{timeout} to be @code{#f}.
2227 @defun thread-terminate! thread
2228 Causes an abnormal termination of @var{thread}. If @var{thread} is
2229 not already terminated, all mutexes owned by @var{thread} become
2230 unlocked/abandoned. If @var{thread} is the current thread,
2231 @code{thread-terminate!} does not return. Otherwise
2232 @code{thread-terminate!} returns an unspecified value; the termination
2233 of @var{thread} will occur before @code{thread-terminate!} returns.
2234 Subsequent attempts to join on @var{thread} will cause a ``terminated
2235 thread exception'' to be raised.
2237 @code{thread-terminate!} is compatible with the thread cancellation
2238 procedures in the core threads API (@pxref{Threads}) in that if a
2239 cleanup handler has been installed for the target thread, it will be
2240 called before the thread exits and its return value (or exception, if
2241 any) will be stored for later retrieval via a call to
2242 @code{thread-join!}.
2245 @defun thread-join! thread [timeout [timeout-val]]
2246 Wait for @var{thread} to terminate and return its exit value. When a
2247 time value @var{timeout} is given, it specifies a point in time where
2248 the waiting should be aborted. When the waiting is aborted,
2249 @var{timeout-val} is returned if it is specified; otherwise, a
2250 @code{join-timeout-exception} exception is raised
2251 (@pxref{SRFI-18 Exceptions}). Exceptions may also be raised if the
2252 thread was terminated by a call to @code{thread-terminate!}
2253 (@code{terminated-thread-exception} will be raised) or if the thread
2254 exited by raising an exception that was handled by the top-level
2255 exception handler (@code{uncaught-exception} will be raised; the
2256 original exception can be retrieved using
2257 @code{uncaught-exception-reason}).
2261 @node SRFI-18 Mutexes
2262 @subsubsection SRFI-18 Mutexes
2264 The behavior of Guile's built-in mutexes is parameterized via a set of
2265 flags passed to the @code{make-mutex} procedure in the core
2266 (@pxref{Mutexes and Condition Variables}). To satisfy the requirements
2267 for mutexes specified by SRFI-18, the @code{make-mutex} procedure
2268 described below sets the following flags:
2271 @code{recursive}: the mutex can be locked recursively
2273 @code{unchecked-unlock}: attempts to unlock a mutex that is already
2274 unlocked will not raise an exception
2276 @code{allow-external-unlock}: the mutex can be unlocked by any thread,
2277 not just the thread that locked it originally
2280 @defun make-mutex [name]
2281 Returns a new mutex, optionally assigning it the object name
2282 @var{name}, which may be any Scheme object. The returned mutex will be
2283 created with the configuration described above. Note that the name
2284 @code{make-mutex} conflicts with Guile core function @code{make-mutex}.
2285 Applications wanting to use both of these functions will need to refer
2286 to them by different names.
2289 @defun mutex-name mutex
2290 Returns the name assigned to @var{mutex} at the time of its creation,
2291 or @code{#f} if it was not given a name.
2294 @defun mutex-specific mutex
2295 @defunx mutex-specific-set! mutex obj
2296 Get or set the ``object-specific'' property of @var{mutex}. In Guile's
2297 implementation of SRFI-18, this value is stored as an object property,
2298 and will be @code{#f} if not set.
2301 @defun mutex-state mutex
2302 Returns information about the state of @var{mutex}. Possible values
2306 thread @code{T}: the mutex is in the locked/owned state and thread T
2307 is the owner of the mutex
2309 symbol @code{not-owned}: the mutex is in the locked/not-owned state
2311 symbol @code{abandoned}: the mutex is in the unlocked/abandoned state
2313 symbol @code{not-abandoned}: the mutex is in the
2314 unlocked/not-abandoned state
2318 @defun mutex-lock! mutex [timeout [thread]]
2319 Lock @var{mutex}, optionally specifying a time object @var{timeout}
2320 after which to abort the lock attempt and a thread @var{thread} giving
2321 a new owner for @var{mutex} different than the current thread. This
2322 procedure has the same behavior as the @code{lock-mutex} procedure in
2326 @defun mutex-unlock! mutex [condition-variable [timeout]]
2327 Unlock @var{mutex}, optionally specifying a condition variable
2328 @var{condition-variable} on which to wait, either indefinitely or,
2329 optionally, until the time object @var{timeout} has passed, to be
2330 signalled. This procedure has the same behavior as the
2331 @code{unlock-mutex} procedure in the core library.
2335 @node SRFI-18 Condition variables
2336 @subsubsection SRFI-18 Condition variables
2338 SRFI-18 does not specify a ``wait'' function for condition variables.
2339 Waiting on a condition variable can be simulated using the SRFI-18
2340 @code{mutex-unlock!} function described in the previous section, or
2341 Guile's built-in @code{wait-condition-variable} procedure can be used.
2343 @defun condition-variable? obj
2344 Returns @code{#t} if @var{obj} is a condition variable, @code{#f}
2345 otherwise. This is the same procedure as the same-named built-in
2347 (@pxref{Mutexes and Condition Variables, @code{condition-variable?}}).
2350 @defun make-condition-variable [name]
2351 Returns a new condition variable, optionally assigning it the object
2352 name @var{name}, which may be any Scheme object. This procedure
2353 replaces a procedure of the same name in the core library.
2356 @defun condition-variable-name condition-variable
2357 Returns the name assigned to @var{condition-variable} at the time of its
2358 creation, or @code{#f} if it was not given a name.
2361 @defun condition-variable-specific condition-variable
2362 @defunx condition-variable-specific-set! condition-variable obj
2363 Get or set the ``object-specific'' property of
2364 @var{condition-variable}. In Guile's implementation of SRFI-18, this
2365 value is stored as an object property, and will be @code{#f} if not
2369 @defun condition-variable-signal! condition-variable
2370 @defunx condition-variable-broadcast! condition-variable
2371 Wake up one thread that is waiting for @var{condition-variable}, in
2372 the case of @code{condition-variable-signal!}, or all threads waiting
2373 for it, in the case of @code{condition-variable-broadcast!}. The
2374 behavior of these procedures is equivalent to that of the procedures
2375 @code{signal-condition-variable} and
2376 @code{broadcast-condition-variable} in the core library.
2381 @subsubsection SRFI-18 Time
2383 The SRFI-18 time functions manipulate time in two formats: a
2384 ``time object'' type that represents an absolute point in time in some
2385 implementation-specific way; and the number of seconds since some
2386 unspecified ``epoch''. In Guile's implementation, the epoch is the
2387 Unix epoch, 00:00:00 UTC, January 1, 1970.
2390 Return the current time as a time object. This procedure replaces
2391 the procedure of the same name in the core library, which returns the
2392 current time in seconds since the epoch.
2396 Returns @code{#t} if @var{obj} is a time object, @code{#f} otherwise.
2399 @defun time->seconds time
2400 @defunx seconds->time seconds
2401 Convert between time objects and numerical values representing the
2402 number of seconds since the epoch. When converting from a time object
2403 to seconds, the return value is the number of seconds between
2404 @var{time} and the epoch. When converting from seconds to a time
2405 object, the return value is a time object that represents a time
2406 @var{seconds} seconds after the epoch.
2410 @node SRFI-18 Exceptions
2411 @subsubsection SRFI-18 Exceptions
2413 SRFI-18 exceptions are identical to the exceptions provided by
2414 Guile's implementation of SRFI-34. The behavior of exception
2415 handlers invoked to handle exceptions thrown from SRFI-18 functions,
2416 however, differs from the conventional behavior of SRFI-34 in that
2417 the continuation of the handler is the same as that of the call to
2418 the function. Handlers are called in a tail-recursive manner; the
2419 exceptions do not ``bubble up''.
2421 @defun current-exception-handler
2422 Returns the current exception handler.
2425 @defun with-exception-handler handler thunk
2426 Installs @var{handler} as the current exception handler and calls the
2427 procedure @var{thunk} with no arguments, returning its value as the
2428 value of the exception. @var{handler} must be a procedure that accepts
2429 a single argument. The current exception handler at the time this
2430 procedure is called will be restored after the call returns.
2434 Raise @var{obj} as an exception. This is the same procedure as the
2435 same-named procedure defined in SRFI 34.
2438 @defun join-timeout-exception? obj
2439 Returns @code{#t} if @var{obj} is an exception raised as the result of
2440 performing a timed join on a thread that does not exit within the
2441 specified timeout, @code{#f} otherwise.
2444 @defun abandoned-mutex-exception? obj
2445 Returns @code{#t} if @var{obj} is an exception raised as the result of
2446 attempting to lock a mutex that has been abandoned by its owner thread,
2447 @code{#f} otherwise.
2450 @defun terminated-thread-exception? obj
2451 Returns @code{#t} if @var{obj} is an exception raised as the result of
2452 joining on a thread that exited as the result of a call to
2453 @code{thread-terminate!}.
2456 @defun uncaught-exception? obj
2457 @defunx uncaught-exception-reason exc
2458 @code{uncaught-exception?} returns @code{#t} if @var{obj} is an
2459 exception thrown as the result of joining a thread that exited by
2460 raising an exception that was handled by the top-level exception
2461 handler installed by @code{make-thread}. When this occurs, the
2462 original exception is preserved as part of the exception thrown by
2463 @code{thread-join!} and can be accessed by calling
2464 @code{uncaught-exception-reason} on that exception. Note that
2465 because this exception-preservation mechanism is a side-effect of
2466 @code{make-thread}, joining on threads that exited as described above
2467 but were created by other means will not raise this
2468 @code{uncaught-exception} error.
2473 @subsection SRFI-19 - Time/Date Library
2478 This is an implementation of the SRFI-19 time/date library. The
2479 functions and variables described here are provided by
2482 (use-modules (srfi srfi-19))
2485 @strong{Caution}: The current code in this module incorrectly extends
2486 the Gregorian calendar leap year rule back prior to the introduction
2487 of those reforms in 1582 (or the appropriate year in various
2488 countries). The Julian calendar was used prior to 1582, and there
2489 were 10 days skipped for the reform, but the code doesn't implement
2492 This will be fixed some time. Until then calculations for 1583
2493 onwards are correct, but prior to that any day/month/year and day of
2494 the week calculations are wrong.
2497 * SRFI-19 Introduction::
2500 * SRFI-19 Time/Date conversions::
2501 * SRFI-19 Date to string::
2502 * SRFI-19 String to date::
2505 @node SRFI-19 Introduction
2506 @subsubsection SRFI-19 Introduction
2508 @cindex universal time
2512 This module implements time and date representations and calculations,
2513 in various time systems, including universal time (UTC) and atomic
2516 For those not familiar with these time systems, TAI is based on a
2517 fixed length second derived from oscillations of certain atoms. UTC
2518 differs from TAI by an integral number of seconds, which is increased
2519 or decreased at announced times to keep UTC aligned to a mean solar
2520 day (the orbit and rotation of the earth are not quite constant).
2523 So far, only increases in the TAI
2530 UTC difference have been needed. Such an increase is a ``leap
2531 second'', an extra second of TAI introduced at the end of a UTC day.
2532 When working entirely within UTC this is never seen, every day simply
2533 has 86400 seconds. But when converting from TAI to a UTC date, an
2534 extra 23:59:60 is present, where normally a day would end at 23:59:59.
2535 Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI
2538 @cindex system clock
2539 In the current implementation, the system clock is assumed to be UTC,
2540 and a table of leap seconds in the code converts to TAI. See comments
2541 in @file{srfi-19.scm} for how to update this table.
2544 @cindex modified julian day
2545 Also, for those not familiar with the terminology, a @dfn{Julian Day}
2546 is a real number which is a count of days and fraction of a day, in
2547 UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan
2548 4713 B.C. A @dfn{Modified Julian Day} is the same, but starting from
2549 1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC. That time
2550 is julian day 2400000.5.
2552 @c The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at
2553 @c noon, UTC), but this is incorrect. It looks like it might have
2554 @c arisen from the code incorrectly treating years a multiple of 100
2555 @c but not 400 prior to 1582 as non-leap years, where instead the Julian
2556 @c calendar should be used so all multiples of 4 before 1582 are leap
2561 @subsubsection SRFI-19 Time
2564 A @dfn{time} object has type, seconds and nanoseconds fields
2565 representing a point in time starting from some epoch. This is an
2566 arbitrary point in time, not just a time of day. Although times are
2567 represented in nanoseconds, the actual resolution may be lower.
2569 The following variables hold the possible time types. For instance
2570 @code{(current-time time-process)} would give the current CPU process
2574 Universal Coordinated Time (UTC).
2579 International Atomic Time (TAI).
2583 @defvar time-monotonic
2584 Monotonic time, meaning a monotonically increasing time starting from
2585 an unspecified epoch.
2587 Note that in the current implementation @code{time-monotonic} is the
2588 same as @code{time-tai}, and unfortunately is therefore affected by
2589 adjustments to the system clock. Perhaps this will change in the
2593 @defvar time-duration
2594 A duration, meaning simply a difference between two times.
2597 @defvar time-process
2598 CPU time spent in the current process, starting from when the process
2600 @cindex process time
2604 CPU time spent in the current thread. Not currently implemented.
2610 Return @code{#t} if @var{obj} is a time object, or @code{#f} if not.
2613 @defun make-time type nanoseconds seconds
2614 Create a time object with the given @var{type}, @var{seconds} and
2618 @defun time-type time
2619 @defunx time-nanosecond time
2620 @defunx time-second time
2621 @defunx set-time-type! time type
2622 @defunx set-time-nanosecond! time nsec
2623 @defunx set-time-second! time sec
2624 Get or set the type, seconds or nanoseconds fields of a time object.
2626 @code{set-time-type!} merely changes the field, it doesn't convert the
2627 time value. For conversions, see @ref{SRFI-19 Time/Date conversions}.
2630 @defun copy-time time
2631 Return a new time object, which is a copy of the given @var{time}.
2634 @defun current-time [type]
2635 Return the current time of the given @var{type}. The default
2636 @var{type} is @code{time-utc}.
2638 Note that the name @code{current-time} conflicts with the Guile core
2639 @code{current-time} function (@pxref{Time}) as well as the SRFI-18
2640 @code{current-time} function (@pxref{SRFI-18 Time}). Applications
2641 wanting to use more than one of these functions will need to refer to
2642 them by different names.
2645 @defun time-resolution [type]
2646 Return the resolution, in nanoseconds, of the given time @var{type}.
2647 The default @var{type} is @code{time-utc}.
2650 @defun time<=? t1 t2
2651 @defunx time<? t1 t2
2652 @defunx time=? t1 t2
2653 @defunx time>=? t1 t2
2654 @defunx time>? t1 t2
2655 Return @code{#t} or @code{#f} according to the respective relation
2656 between time objects @var{t1} and @var{t2}. @var{t1} and @var{t2}
2657 must be the same time type.
2660 @defun time-difference t1 t2
2661 @defunx time-difference! t1 t2
2662 Return a time object of type @code{time-duration} representing the
2663 period between @var{t1} and @var{t2}. @var{t1} and @var{t2} must be
2666 @code{time-difference} returns a new time object,
2667 @code{time-difference!} may modify @var{t1} to form its return.
2670 @defun add-duration time duration
2671 @defunx add-duration! time duration
2672 @defunx subtract-duration time duration
2673 @defunx subtract-duration! time duration
2674 Return a time object which is @var{time} with the given @var{duration}
2675 added or subtracted. @var{duration} must be a time object of type
2676 @code{time-duration}.
2678 @code{add-duration} and @code{subtract-duration} return a new time
2679 object. @code{add-duration!} and @code{subtract-duration!} may modify
2680 the given @var{time} to form their return.
2685 @subsubsection SRFI-19 Date
2688 A @dfn{date} object represents a date in the Gregorian calendar and a
2689 time of day on that date in some timezone.
2691 The fields are year, month, day, hour, minute, second, nanoseconds and
2692 timezone. A date object is immutable, its fields can be read but they
2693 cannot be modified once the object is created.
2696 Return @code{#t} if @var{obj} is a date object, or @code{#f} if not.
2699 @defun make-date nsecs seconds minutes hours date month year zone-offset
2700 Create a new date object.
2702 @c FIXME: What can we say about the ranges of the values. The
2703 @c current code looks it doesn't normalize, but expects then in their
2704 @c usual range already.
2708 @defun date-nanosecond date
2709 Nanoseconds, 0 to 999999999.
2712 @defun date-second date
2713 Seconds, 0 to 59, or 60 for a leap second. 60 is never seen when working
2714 entirely within UTC, it's only when converting to or from TAI.
2717 @defun date-minute date
2721 @defun date-hour date
2725 @defun date-day date
2726 Day of the month, 1 to 31 (or less, according to the month).
2729 @defun date-month date
2733 @defun date-year date
2734 Year, eg.@: 2003. Dates B.C.@: are negative, eg.@: @math{-46} is 46
2735 B.C. There is no year 0, year @math{-1} is followed by year 1.
2738 @defun date-zone-offset date
2739 Time zone, an integer number of seconds east of Greenwich.
2742 @defun date-year-day date
2743 Day of the year, starting from 1 for 1st January.
2746 @defun date-week-day date
2747 Day of the week, starting from 0 for Sunday.
2750 @defun date-week-number date dstartw
2751 Week of the year, ignoring a first partial week. @var{dstartw} is the
2752 day of the week which is taken to start a week, 0 for Sunday, 1 for
2755 @c FIXME: The spec doesn't say whether numbering starts at 0 or 1.
2756 @c The code looks like it's 0, if that's the correct intention.
2760 @c The SRFI text doesn't actually give the default for tz-offset, but
2761 @c the reference implementation has the local timezone and the
2762 @c conversions functions all specify that, so it should be ok to
2763 @c document it here.
2765 @defun current-date [tz-offset]
2766 Return a date object representing the current date/time, in UTC offset
2767 by @var{tz-offset}. @var{tz-offset} is seconds east of Greenwich and
2768 defaults to the local timezone.
2771 @defun current-julian-day
2773 Return the current Julian Day.
2776 @defun current-modified-julian-day
2777 @cindex modified julian day
2778 Return the current Modified Julian Day.
2782 @node SRFI-19 Time/Date conversions
2783 @subsubsection SRFI-19 Time/Date conversions
2784 @cindex time conversion
2785 @cindex date conversion
2787 @defun date->julian-day date
2788 @defunx date->modified-julian-day date
2789 @defunx date->time-monotonic date
2790 @defunx date->time-tai date
2791 @defunx date->time-utc date
2793 @defun julian-day->date jdn [tz-offset]
2794 @defunx julian-day->time-monotonic jdn
2795 @defunx julian-day->time-tai jdn
2796 @defunx julian-day->time-utc jdn
2798 @defun modified-julian-day->date jdn [tz-offset]
2799 @defunx modified-julian-day->time-monotonic jdn
2800 @defunx modified-julian-day->time-tai jdn
2801 @defunx modified-julian-day->time-utc jdn
2803 @defun time-monotonic->date time [tz-offset]
2804 @defunx time-monotonic->time-tai time
2805 @defunx time-monotonic->time-tai! time
2806 @defunx time-monotonic->time-utc time
2807 @defunx time-monotonic->time-utc! time
2809 @defun time-tai->date time [tz-offset]
2810 @defunx time-tai->julian-day time
2811 @defunx time-tai->modified-julian-day time
2812 @defunx time-tai->time-monotonic time
2813 @defunx time-tai->time-monotonic! time
2814 @defunx time-tai->time-utc time
2815 @defunx time-tai->time-utc! time
2817 @defun time-utc->date time [tz-offset]
2818 @defunx time-utc->julian-day time
2819 @defunx time-utc->modified-julian-day time
2820 @defunx time-utc->time-monotonic time
2821 @defunx time-utc->time-monotonic! time
2822 @defunx time-utc->time-tai time
2823 @defunx time-utc->time-tai! time
2825 Convert between dates, times and days of the respective types. For
2826 instance @code{time-tai->time-utc} accepts a @var{time} object of type
2827 @code{time-tai} and returns an object of type @code{time-utc}.
2829 The @code{!} variants may modify their @var{time} argument to form
2830 their return. The plain functions create a new object.
2832 For conversions to dates, @var{tz-offset} is seconds east of
2833 Greenwich. The default is the local timezone, at the given time, as
2834 provided by the system, using @code{localtime} (@pxref{Time}).
2836 On 32-bit systems, @code{localtime} is limited to a 32-bit
2837 @code{time_t}, so a default @var{tz-offset} is only available for
2838 times between Dec 1901 and Jan 2038. For prior dates an application
2839 might like to use the value in 1902, though some locations have zone
2840 changes prior to that. For future dates an application might like to
2841 assume today's rules extend indefinitely. But for correct daylight
2842 savings transitions it will be necessary to take an offset for the
2843 same day and time but a year in range and which has the same starting
2844 weekday and same leap/non-leap (to support rules like last Sunday in
2848 @node SRFI-19 Date to string
2849 @subsubsection SRFI-19 Date to string
2850 @cindex date to string
2851 @cindex string, from date
2853 @defun date->string date [format]
2854 Convert a date to a string under the control of a format.
2855 @var{format} should be a string containing @samp{~} escapes, which
2856 will be expanded as per the following conversion table. The default
2857 @var{format} is @samp{~c}, a locale-dependent date and time.
2859 Many of these conversion characters are the same as POSIX
2860 @code{strftime} (@pxref{Time}), but there are some extras and some
2863 @multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM}
2864 @item @nicode{~~} @tab literal ~
2865 @item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun}
2866 @item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday}
2867 @item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan}
2868 @item @nicode{~B} @tab locale full month, eg.@: @samp{January}
2869 @item @nicode{~c} @tab locale date and time, eg.@: @*
2870 @samp{Fri Jul 14 20:28:42-0400 2000}
2871 @item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31}
2873 @c Spec says d/m/y, reference implementation says m/d/y.
2874 @c Apparently the reference code was the intention, but would like to
2875 @c see an errata published for the spec before contradicting it here.
2877 @c @item @nicode{~D} @tab date @nicode{~d/~m/~y}
2879 @item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31}
2880 @item @nicode{~f} @tab seconds and fractional seconds,
2881 with locale decimal point, eg.@: @samp{5.2}
2882 @item @nicode{~h} @tab same as @nicode{~b}
2883 @item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23}
2884 @item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12}
2885 @item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366}
2886 @item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23}
2887 @item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12}
2888 @item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12}
2889 @item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59}
2890 @item @nicode{~n} @tab newline
2891 @item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999}
2892 @item @nicode{~p} @tab locale AM or PM
2893 @item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p}
2894 @item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC
2895 @item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @*
2896 (usual limit is 59, 60 is a leap second)
2897 @item @nicode{~t} @tab horizontal tab character
2898 @item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S}
2899 @item @nicode{~U} @tab week of year, Sunday first day of week,
2900 @samp{00} to @samp{52}
2901 @item @nicode{~V} @tab week of year, Monday first day of week,
2902 @samp{01} to @samp{53}
2903 @item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6}
2904 @item @nicode{~W} @tab week of year, Monday first day of week,
2905 @samp{00} to @samp{52}
2907 @c The spec has ~x as an apparent duplicate of ~W, and ~X as a locale
2908 @c date. The reference code has ~x as the locale date and ~X as a
2909 @c locale time. The rule is apparently that the code should be
2910 @c believed, but would like to see an errata for the spec before
2911 @c contradicting it here.
2913 @c @item @nicode{~x} @tab week of year, Monday as first day of week,
2914 @c @samp{00} to @samp{53}
2915 @c @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00}
2917 @item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99}
2918 @item @nicode{~Y} @tab year, full, eg.@: @samp{2003}
2919 @item @nicode{~z} @tab time zone, RFC-822 style
2920 @item @nicode{~Z} @tab time zone symbol (not currently implemented)
2921 @item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d}
2922 @item @nicode{~2} @tab ISO-8601 time+zone, @samp{~H:~M:~S~z}
2923 @item @nicode{~3} @tab ISO-8601 time, @samp{~H:~M:~S}
2924 @item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~H:~M:~S~z}
2925 @item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~H:~M:~S}
2929 Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently
2930 described here, since the specification and reference implementation
2933 Conversion is locale-dependent on systems that support it
2934 (@pxref{Accessing Locale Information}). @xref{Locales,
2935 @code{setlocale}}, for information on how to change the current
2939 @node SRFI-19 String to date
2940 @subsubsection SRFI-19 String to date
2941 @cindex string to date
2942 @cindex date, from string
2944 @c FIXME: Can we say what happens when an incomplete date is
2945 @c converted? I.e. fields left as 0, or what? The spec seems to be
2948 @defun string->date input template
2949 Convert an @var{input} string to a date under the control of a
2950 @var{template} string. Return a newly created date object.
2952 Literal characters in @var{template} must match characters in
2953 @var{input} and @samp{~} escapes must match the input forms described
2954 in the table below. ``Skip to'' means characters up to one of the
2955 given type are ignored, or ``no skip'' for no skipping. ``Read'' is
2956 what's then read, and ``Set'' is the field affected in the date
2959 For example @samp{~Y} skips input characters until a digit is reached,
2960 at which point it expects a year and stores that to the year field of
2963 @multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}}
2975 @tab @nicode{char-alphabetic?}
2976 @tab locale abbreviated weekday name
2980 @tab @nicode{char-alphabetic?}
2981 @tab locale full weekday name
2984 @c Note that the SRFI spec says that ~b and ~B don't set anything,
2985 @c but that looks like a mistake. The reference implementation sets
2986 @c the month field, which seems sensible and is what we describe
2990 @tab @nicode{char-alphabetic?}
2991 @tab locale abbreviated month name
2992 @tab @nicode{date-month}
2995 @tab @nicode{char-alphabetic?}
2996 @tab locale full month name
2997 @tab @nicode{date-month}
3000 @tab @nicode{char-numeric?}
3002 @tab @nicode{date-day}
3006 @tab day of month, blank padded
3007 @tab @nicode{date-day}
3010 @tab same as @samp{~b}
3013 @tab @nicode{char-numeric?}
3015 @tab @nicode{date-hour}
3019 @tab hour, blank padded
3020 @tab @nicode{date-hour}
3023 @tab @nicode{char-numeric?}
3025 @tab @nicode{date-month}
3028 @tab @nicode{char-numeric?}
3030 @tab @nicode{date-minute}
3033 @tab @nicode{char-numeric?}
3035 @tab @nicode{date-second}
3040 @tab @nicode{date-year} within 50 years
3043 @tab @nicode{char-numeric?}
3045 @tab @nicode{date-year}
3050 @tab date-zone-offset
3053 Notice that the weekday matching forms don't affect the date object
3054 returned, instead the weekday will be derived from the day, month and
3057 Conversion is locale-dependent on systems that support it
3058 (@pxref{Accessing Locale Information}). @xref{Locales,
3059 @code{setlocale}}, for information on how to change the current
3064 @subsection SRFI-23 - Error Reporting
3067 The SRFI-23 @code{error} procedure is always available.
3070 @subsection SRFI-26 - specializing parameters
3072 @cindex parameter specialize
3073 @cindex argument specialize
3074 @cindex specialize parameter
3076 This SRFI provides a syntax for conveniently specializing selected
3077 parameters of a function. It can be used with,
3080 (use-modules (srfi srfi-26))
3083 @deffn {library syntax} cut slot1 slot2 @dots{}
3084 @deffnx {library syntax} cute slot1 slot2 @dots{}
3085 Return a new procedure which will make a call (@var{slot1} @var{slot2}
3086 @dots{}) but with selected parameters specialized to given expressions.
3088 An example will illustrate the idea. The following is a
3089 specialization of @code{write}, sending output to
3090 @code{my-output-port},
3093 (cut write <> my-output-port)
3095 (lambda (obj) (write obj my-output-port))
3098 The special symbol @code{<>} indicates a slot to be filled by an
3099 argument to the new procedure. @code{my-output-port} on the other
3100 hand is an expression to be evaluated and passed, ie.@: it specializes
3101 the behaviour of @code{write}.
3105 A slot to be filled by an argument from the created procedure.
3106 Arguments are assigned to @code{<>} slots in the order they appear in
3107 the @code{cut} form, there's no way to re-arrange arguments.
3109 The first argument to @code{cut} is usually a procedure (or expression
3110 giving a procedure), but @code{<>} is allowed there too. For example,
3115 (lambda (proc) (proc 1 2 3))
3119 A slot to be filled by all remaining arguments from the new procedure.
3120 This can only occur at the end of a @code{cut} form.
3122 For example, a procedure taking a variable number of arguments like
3123 @code{max} but in addition enforcing a lower bound,
3126 (define my-lower-bound 123)
3128 (cut max my-lower-bound <...>)
3130 (lambda arglist (apply max my-lower-bound arglist))
3134 For @code{cut} the specializing expressions are evaluated each time
3135 the new procedure is called. For @code{cute} they're evaluated just
3136 once, when the new procedure is created. The name @code{cute} stands
3137 for ``@code{cut} with evaluated arguments''. In all cases the
3138 evaluations take place in an unspecified order.
3140 The following illustrates the difference between @code{cut} and
3144 (cut format <> "the time is ~s" (current-time))
3146 (lambda (port) (format port "the time is ~s" (current-time)))
3148 (cute format <> "the time is ~s" (current-time))
3150 (let ((val (current-time)))
3151 (lambda (port) (format port "the time is ~s" val))
3154 (There's no provision for a mixture of @code{cut} and @code{cute}
3155 where some expressions would be evaluated every time but others
3156 evaluated only once.)
3158 @code{cut} is really just a shorthand for the sort of @code{lambda}
3159 forms shown in the above examples. But notice @code{cut} avoids the
3160 need to name unspecialized parameters, and is more compact. Use in
3161 functional programming style or just with @code{map}, @code{for-each}
3162 or similar is typical.
3165 (map (cut * 2 <>) '(1 2 3 4))
3167 (for-each (cut write <> my-port) my-list)
3172 @subsection SRFI-27 - Sources of Random Bits
3175 This subsection is based on the
3176 @uref{http://srfi.schemers.org/srfi-27/srfi-27.html, specification of
3177 SRFI-27} written by Sebastian Egner.
3179 @c The copyright notice and license text of the SRFI-27 specification is
3180 @c reproduced below:
3182 @c Copyright (C) Sebastian Egner (2002). All Rights Reserved.
3184 @c Permission is hereby granted, free of charge, to any person obtaining a
3185 @c copy of this software and associated documentation files (the
3186 @c "Software"), to deal in the Software without restriction, including
3187 @c without limitation the rights to use, copy, modify, merge, publish,
3188 @c distribute, sublicense, and/or sell copies of the Software, and to
3189 @c permit persons to whom the Software is furnished to do so, subject to
3190 @c the following conditions:
3192 @c The above copyright notice and this permission notice shall be included
3193 @c in all copies or substantial portions of the Software.
3195 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3196 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3197 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3198 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3199 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3200 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3201 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3203 This SRFI provides access to a (pseudo) random number generator; for
3204 Guile's built-in random number facilities, which SRFI-27 is implemented
3205 upon, @xref{Random}. With SRFI-27, random numbers are obtained from a
3206 @emph{random source}, which encapsulates a random number generation
3207 algorithm and its state.
3210 * SRFI-27 Default Random Source:: Obtaining random numbers
3211 * SRFI-27 Random Sources:: Creating and manipulating random sources
3212 * SRFI-27 Random Number Generators:: Obtaining random number generators
3215 @node SRFI-27 Default Random Source
3216 @subsubsection The Default Random Source
3219 @defun random-integer n
3220 Return a random number between zero (inclusive) and @var{n} (exclusive),
3221 using the default random source. The numbers returned have a uniform
3226 Return a random number in (0,1), using the default random source. The
3227 numbers returned have a uniform distribution.
3230 @defun default-random-source
3231 A random source from which @code{random-integer} and @code{random-real}
3232 have been derived using @code{random-source-make-integers} and
3233 @code{random-source-make-reals} (@pxref{SRFI-27 Random Number Generators}
3234 for those procedures). Note that an assignment to
3235 @code{default-random-source} does not change @code{random-integer} or
3236 @code{random-real}; it is also strongly recommended not to assign a new
3240 @node SRFI-27 Random Sources
3241 @subsubsection Random Sources
3244 @defun make-random-source
3245 Create a new random source. The stream of random numbers obtained from
3246 each random source created by this procedure will be identical, unless
3247 its state is changed by one of the procedures below.
3250 @defun random-source? object
3251 Tests whether @var{object} is a random source. Random sources are a
3255 @defun random-source-randomize! source
3256 Attempt to set the state of the random source to a truly random value.
3257 The current implementation uses a seed based on the current system time.
3260 @defun random-source-pseudo-randomize! source i j
3261 Changes the state of the random source s into the initial state of the
3262 (@var{i}, @var{j})-th independent random source, where @var{i} and
3263 @var{j} are non-negative integers. This procedure provides a mechanism
3264 to obtain a large number of independent random sources (usually all
3265 derived from the same backbone generator), indexed by two integers. In
3266 contrast to @code{random-source-randomize!}, this procedure is entirely
3270 The state associated with a random state can be obtained an reinstated
3271 with the following procedures:
3273 @defun random-source-state-ref source
3274 @defunx random-source-state-set! source state
3275 Get and set the state of a random source. No assumptions should be made
3276 about the nature of the state object, besides it having an external
3277 representation (i.e.@: it can be passed to @code{write} and subsequently
3281 @node SRFI-27 Random Number Generators
3282 @subsubsection Obtaining random number generator procedures
3285 @defun random-source-make-integers source
3286 Obtains a procedure to generate random integers using the random source
3287 @var{source}. The returned procedure takes a single argument @var{n},
3288 which must be a positive integer, and returns the next uniformly
3289 distributed random integer from the interval @{0, ..., @var{n}-1@} by
3290 advancing the state of @var{source}.
3292 If an application obtains and uses several generators for the same
3293 random source @var{source}, a call to any of these generators advances
3294 the state of @var{source}. Hence, the generators do not produce the
3295 same sequence of random integers each but rather share a state. This
3296 also holds for all other types of generators derived from a fixed random
3299 While the SRFI text specifies that ``Implementations that support
3300 concurrency make sure that the state of a generator is properly
3301 advanced'', this is currently not the case in Guile's implementation of
3302 SRFI-27, as it would cause a severe performance penalty. So in
3303 multi-threaded programs, you either must perform locking on random
3304 sources shared between threads yourself, or use different random sources
3305 for multiple threads.
3308 @defun random-source-make-reals source
3309 @defunx random-source-make-reals source unit
3310 Obtains a procedure to generate random real numbers @math{0 < x < 1}
3311 using the random source @var{source}. The procedure rand is called
3314 The optional parameter @var{unit} determines the type of numbers being
3315 produced by the returned procedure and the quantization of the output.
3316 @var{unit} must be a number such that @math{0 < @var{unit} < 1}. The
3317 numbers created by the returned procedure are of the same numerical type
3318 as @var{unit} and the potential output values are spaced by at most
3319 @var{unit}. One can imagine rand to create numbers as @var{x} *
3320 @var{unit} where @var{x} is a random integer in @{1, ...,
3321 floor(1/unit)-1@}. Note, however, that this need not be the way the
3322 values are actually created and that the actual resolution of rand can
3323 be much higher than unit. In case @var{unit} is absent it defaults to a
3324 reasonably small value (related to the width of the mantissa of an
3325 efficient number format).
3329 @subsection SRFI-30 - Nested Multi-line Comments
3332 Starting from version 2.0, Guile's @code{read} supports SRFI-30/R6RS
3333 nested multi-line comments by default, @ref{Block Comments}.
3336 @subsection SRFI-31 - A special form `rec' for recursive evaluation
3338 @cindex recursive expression
3341 SRFI-31 defines a special form that can be used to create
3342 self-referential expressions more conveniently. The syntax is as
3347 <rec expression> --> (rec <variable> <expression>)
3348 <rec expression> --> (rec (<variable>+) <body>)
3352 The first syntax can be used to create self-referential expressions,
3356 guile> (define tmp (rec ones (cons 1 (delay ones))))
3359 The second syntax can be used to create anonymous recursive functions:
3362 guile> (define tmp (rec (display-n item n)
3364 (begin (display n) (display-n (- n 1))))))
3372 @subsection SRFI-34 - Exception handling for programs
3375 Guile provides an implementation of
3376 @uref{http://srfi.schemers.org/srfi-34/srfi-34.html, SRFI-34's exception
3377 handling mechanisms} as an alternative to its own built-in mechanisms
3378 (@pxref{Exceptions}). It can be made available as follows:
3381 (use-modules (srfi srfi-34))
3384 @c FIXME: Document it.
3388 @subsection SRFI-35 - Conditions
3394 @uref{http://srfi.schemers.org/srfi-35/srfi-35.html, SRFI-35} implements
3395 @dfn{conditions}, a data structure akin to records designed to convey
3396 information about exceptional conditions between parts of a program. It
3397 is normally used in conjunction with SRFI-34's @code{raise}:
3400 (raise (condition (&message
3401 (message "An error occurred"))))
3404 Users can define @dfn{condition types} containing arbitrary information.
3405 Condition types may inherit from one another. This allows the part of
3406 the program that handles (or ``catches'') conditions to get accurate
3407 information about the exceptional condition that arose.
3409 SRFI-35 conditions are made available using:
3412 (use-modules (srfi srfi-35))
3415 The procedures available to manipulate condition types are the
3418 @deffn {Scheme Procedure} make-condition-type id parent field-names
3419 Return a new condition type named @var{id}, inheriting from
3420 @var{parent}, and with the fields whose names are listed in
3421 @var{field-names}. @var{field-names} must be a list of symbols and must
3422 not contain names already used by @var{parent} or one of its supertypes.
3425 @deffn {Scheme Procedure} condition-type? obj
3426 Return true if @var{obj} is a condition type.
3429 Conditions can be created and accessed with the following procedures:
3431 @deffn {Scheme Procedure} make-condition type . field+value
3432 Return a new condition of type @var{type} with fields initialized as
3433 specified by @var{field+value}, a sequence of field names (symbols) and
3434 values as in the following example:
3437 (let ((&ct (make-condition-type 'foo &condition '(a b c))))
3438 (make-condition &ct 'a 1 'b 2 'c 3))
3441 Note that all fields of @var{type} and its supertypes must be specified.
3444 @deffn {Scheme Procedure} make-compound-condition condition1 condition2 @dots{}
3445 Return a new compound condition composed of @var{condition1}
3446 @var{condition2} @enddots{}. The returned condition has the type of
3447 each condition of condition1 condition2 @dots{} (per
3448 @code{condition-has-type?}).
3451 @deffn {Scheme Procedure} condition-has-type? c type
3452 Return true if condition @var{c} has type @var{type}.
3455 @deffn {Scheme Procedure} condition-ref c field-name
3456 Return the value of the field named @var{field-name} from condition @var{c}.
3458 If @var{c} is a compound condition and several underlying condition
3459 types contain a field named @var{field-name}, then the value of the
3460 first such field is returned, using the order in which conditions were
3461 passed to @code{make-compound-condition}.
3464 @deffn {Scheme Procedure} extract-condition c type
3465 Return a condition of condition type @var{type} with the field values
3466 specified by @var{c}.
3468 If @var{c} is a compound condition, extract the field values from the
3469 subcondition belonging to @var{type} that appeared first in the call to
3470 @code{make-compound-condition} that created the condition.
3473 Convenience macros are also available to create condition types and
3476 @deffn {library syntax} define-condition-type type supertype predicate field-spec...
3477 Define a new condition type named @var{type} that inherits from
3478 @var{supertype}. In addition, bind @var{predicate} to a type predicate
3479 that returns true when passed a condition of type @var{type} or any of
3480 its subtypes. @var{field-spec} must have the form @code{(field
3481 accessor)} where @var{field} is the name of field of @var{type} and
3482 @var{accessor} is the name of a procedure to access field @var{field} in
3483 conditions of type @var{type}.
3485 The example below defines condition type @code{&foo}, inheriting from
3486 @code{&condition} with fields @code{a}, @code{b} and @code{c}:
3489 (define-condition-type &foo &condition
3497 @deffn {library syntax} condition type-field-binding1 type-field-binding2 @dots{}
3498 Return a new condition or compound condition, initialized according to
3499 @var{type-field-binding1} @var{type-field-binding2} @enddots{}. Each
3500 @var{type-field-binding} must have the form @code{(type
3501 field-specs...)}, where @var{type} is the name of a variable bound to a
3502 condition type; each @var{field-spec} must have the form
3503 @code{(field-name value)} where @var{field-name} is a symbol denoting
3504 the field being initialized to @var{value}. As for
3505 @code{make-condition}, all fields must be specified.
3507 The following example returns a simple condition:
3510 (condition (&message (message "An error occurred")))
3513 The one below returns a compound condition:
3516 (condition (&message (message "An error occurred"))
3521 Finally, SRFI-35 defines a several standard condition types.
3524 This condition type is the root of all condition types. It has no
3529 A condition type that carries a message describing the nature of the
3530 condition to humans.
3533 @deffn {Scheme Procedure} message-condition? c
3534 Return true if @var{c} is of type @code{&message} or one of its
3538 @deffn {Scheme Procedure} condition-message c
3539 Return the message associated with message condition @var{c}.
3543 This type describes conditions serious enough that they cannot safely be
3544 ignored. It has no fields.
3547 @deffn {Scheme Procedure} serious-condition? c
3548 Return true if @var{c} is of type @code{&serious} or one of its
3553 This condition describes errors, typically caused by something that has
3554 gone wrong in the interaction of the program with the external world or
3558 @deffn {Scheme Procedure} error? c
3559 Return true if @var{c} is of type @code{&error} or one of its subtypes.
3563 @subsection SRFI-37 - args-fold
3566 This is a processor for GNU @code{getopt_long}-style program
3567 arguments. It provides an alternative, less declarative interface
3568 than @code{getopt-long} in @code{(ice-9 getopt-long)}
3569 (@pxref{getopt-long,,The (ice-9 getopt-long) Module}). Unlike
3570 @code{getopt-long}, it supports repeated options and any number of
3571 short and long names per option. Access it with:
3574 (use-modules (srfi srfi-37))
3577 @acronym{SRFI}-37 principally provides an @code{option} type and the
3578 @code{args-fold} function. To use the library, create a set of
3579 options with @code{option} and use it as a specification for invoking
3582 Here is an example of a simple argument processor for the typical
3583 @samp{--version} and @samp{--help} options, which returns a backwards
3584 list of files given on the command line:
3587 (args-fold (cdr (program-arguments))
3588 (let ((display-and-exit-proc
3590 (lambda (opt name arg loads)
3591 (display msg) (quit)))))
3592 (list (option '(#\v "version") #f #f
3593 (display-and-exit-proc "Foo version 42.0\n"))
3594 (option '(#\h "help") #f #f
3595 (display-and-exit-proc
3596 "Usage: foo scheme-file ..."))))
3597 (lambda (opt name arg loads)
3598 (error "Unrecognized option `~A'" name))
3599 (lambda (op loads) (cons op loads))
3603 @deffn {Scheme Procedure} option names required-arg? optional-arg? processor
3604 Return an object that specifies a single kind of program option.
3606 @var{names} is a list of command-line option names, and should consist of
3607 characters for traditional @code{getopt} short options and strings for
3608 @code{getopt_long}-style long options.
3610 @var{required-arg?} and @var{optional-arg?} are mutually exclusive;
3611 one or both must be @code{#f}. If @var{required-arg?}, the option
3612 must be followed by an argument on the command line, such as
3613 @samp{--opt=value} for long options, or an error will be signalled.
3614 If @var{optional-arg?}, an argument will be taken if available.
3616 @var{processor} is a procedure that takes at least 3 arguments, called
3617 when @code{args-fold} encounters the option: the containing option
3618 object, the name used on the command line, and the argument given for
3619 the option (or @code{#f} if none). The rest of the arguments are
3620 @code{args-fold} ``seeds'', and the @var{processor} should return
3624 @deffn {Scheme Procedure} option-names opt
3625 @deffnx {Scheme Procedure} option-required-arg? opt
3626 @deffnx {Scheme Procedure} option-optional-arg? opt
3627 @deffnx {Scheme Procedure} option-processor opt
3628 Return the specified field of @var{opt}, an option object, as
3629 described above for @code{option}.
3632 @deffn {Scheme Procedure} args-fold args options unrecognized-option-proc operand-proc seed @dots{}
3633 Process @var{args}, a list of program arguments such as that returned by
3634 @code{(cdr (program-arguments))}, in order against @var{options}, a list
3635 of option objects as described above. All functions called take the
3636 ``seeds'', or the last multiple-values as multiple arguments, starting
3637 with @var{seed} @dots{}, and must return the new seeds. Return the
3640 Call @code{unrecognized-option-proc}, which is like an option object's
3641 processor, for any options not found in @var{options}.
3643 Call @code{operand-proc} with any items on the command line that are
3644 not named options. This includes arguments after @samp{--}. It is
3645 called with the argument in question, as well as the seeds.
3649 @subsection SRFI-38 - External Representation for Data With Shared Structure
3652 This subsection is based on
3653 @uref{http://srfi.schemers.org/srfi-38/srfi-38.html, the specification
3654 of SRFI-38} written by Ray Dillinger.
3656 @c Copyright (C) Ray Dillinger 2003. All Rights Reserved.
3658 @c Permission is hereby granted, free of charge, to any person obtaining a
3659 @c copy of this software and associated documentation files (the
3660 @c "Software"), to deal in the Software without restriction, including
3661 @c without limitation the rights to use, copy, modify, merge, publish,
3662 @c distribute, sublicense, and/or sell copies of the Software, and to
3663 @c permit persons to whom the Software is furnished to do so, subject to
3664 @c the following conditions:
3666 @c The above copyright notice and this permission notice shall be included
3667 @c in all copies or substantial portions of the Software.
3669 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3670 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3671 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3672 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3673 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3674 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3675 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3677 This SRFI creates an alternative external representation for data
3678 written and read using @code{write-with-shared-structure} and
3679 @code{read-with-shared-structure}. It is identical to the grammar for
3680 external representation for data written and read with @code{write} and
3681 @code{read} given in section 7 of R5RS, except that the single
3685 <datum> --> <simple datum> | <compound datum>
3688 is replaced by the following five productions:
3691 <datum> --> <defining datum> | <nondefining datum> | <defined datum>
3692 <defining datum> --> #<indexnum>=<nondefining datum>
3693 <defined datum> --> #<indexnum>#
3694 <nondefining datum> --> <simple datum> | <compound datum>
3695 <indexnum> --> <digit 10>+
3698 @deffn {Scheme procedure} write-with-shared-structure obj
3699 @deffnx {Scheme procedure} write-with-shared-structure obj port
3700 @deffnx {Scheme procedure} write-with-shared-structure obj port optarg
3702 Writes an external representation of @var{obj} to the given port.
3703 Strings that appear in the written representation are enclosed in
3704 doublequotes, and within those strings backslash and doublequote
3705 characters are escaped by backslashes. Character objects are written
3706 using the @code{#\} notation.
3708 Objects which denote locations rather than values (cons cells, vectors,
3709 and non-zero-length strings in R5RS scheme; also Guile's structs,
3710 bytevectors and ports and hash-tables), if they appear at more than one
3711 point in the data being written, are preceded by @samp{#@var{N}=} the
3712 first time they are written and replaced by @samp{#@var{N}#} all
3713 subsequent times they are written, where @var{N} is a natural number
3714 used to identify that particular object. If objects which denote
3715 locations occur only once in the structure, then
3716 @code{write-with-shared-structure} must produce the same external
3717 representation for those objects as @code{write}.
3719 @code{write-with-shared-structure} terminates in finite time and
3720 produces a finite representation when writing finite data.
3722 @code{write-with-shared-structure} returns an unspecified value. The
3723 @var{port} argument may be omitted, in which case it defaults to the
3724 value returned by @code{(current-output-port)}. The @var{optarg}
3725 argument may also be omitted. If present, its effects on the output and
3726 return value are unspecified but @code{write-with-shared-structure} must
3727 still write a representation that can be read by
3728 @code{read-with-shared-structure}. Some implementations may wish to use
3729 @var{optarg} to specify formatting conventions, numeric radixes, or
3730 return values. Guile's implementation ignores @var{optarg}.
3732 For example, the code
3735 (begin (define a (cons 'val1 'val2))
3737 (write-with-shared-structure a))
3740 should produce the output @code{#1=(val1 . #1#)}. This shows a cons
3741 cell whose @code{cdr} contains itself.
3745 @deffn {Scheme procedure} read-with-shared-structure
3746 @deffnx {Scheme procedure} read-with-shared-structure port
3748 @code{read-with-shared-structure} converts the external representations
3749 of Scheme objects produced by @code{write-with-shared-structure} into
3750 Scheme objects. That is, it is a parser for the nonterminal
3751 @samp{<datum>} in the augmented external representation grammar defined
3752 above. @code{read-with-shared-structure} returns the next object
3753 parsable from the given input port, updating @var{port} to point to the
3754 first character past the end of the external representation of the
3757 If an end-of-file is encountered in the input before any characters are
3758 found that can begin an object, then an end-of-file object is returned.
3759 The port remains open, and further attempts to read it (by
3760 @code{read-with-shared-structure} or @code{read} will also return an
3761 end-of-file object. If an end of file is encountered after the
3762 beginning of an object's external representation, but the external
3763 representation is incomplete and therefore not parsable, an error is
3766 The @var{port} argument may be omitted, in which case it defaults to the
3767 value returned by @code{(current-input-port)}. It is an error to read
3773 @subsection SRFI-39 - Parameters
3776 This SRFI adds support for dynamically-scoped parameters. SRFI 39 is
3777 implemented in the Guile core; there's no module needed to get SRFI-39
3778 itself. Parameters are documented in @ref{Parameters}.
3780 This module does export one extra function: @code{with-parameters*}.
3781 This is a Guile-specific addition to the SRFI, similar to the core
3782 @code{with-fluids*} (@pxref{Fluids and Dynamic States}).
3784 @defun with-parameters* param-list value-list thunk
3785 Establish a new dynamic scope, as per @code{parameterize} above,
3786 taking parameters from @var{param-list} and corresponding values from
3787 @var{value-list}. A call @code{(@var{thunk})} is made in the new
3788 scope and the result from that @var{thunk} is the return from
3789 @code{with-parameters*}.
3793 @subsection SRFI-41 - Streams
3796 This subsection is based on the
3797 @uref{http://srfi.schemers.org/srfi-41/srfi-41.html, specification of
3798 SRFI-41} by Philip L.@: Bewig.
3800 @c The copyright notice and license text of the SRFI-41 specification is
3801 @c reproduced below:
3803 @c Copyright (C) Philip L. Bewig (2007). All Rights Reserved.
3805 @c Permission is hereby granted, free of charge, to any person obtaining a
3806 @c copy of this software and associated documentation files (the
3807 @c "Software"), to deal in the Software without restriction, including
3808 @c without limitation the rights to use, copy, modify, merge, publish,
3809 @c distribute, sublicense, and/or sell copies of the Software, and to
3810 @c permit persons to whom the Software is furnished to do so, subject to
3811 @c the following conditions:
3813 @c The above copyright notice and this permission notice shall be included
3814 @c in all copies or substantial portions of the Software.
3816 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3817 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3818 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3819 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3820 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3821 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3822 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3825 This SRFI implements streams, sometimes called lazy lists, a sequential
3826 data structure containing elements computed only on demand. A stream is
3827 either null or is a pair with a stream in its cdr. Since elements of a
3828 stream are computed only when accessed, streams can be infinite. Once
3829 computed, the value of a stream element is cached in case it is needed
3830 again. SRFI-41 can be made available with:
3833 (use-modules (srfi srfi-41))
3837 * SRFI-41 Stream Fundamentals::
3838 * SRFI-41 Stream Primitives::
3839 * SRFI-41 Stream Library::
3842 @node SRFI-41 Stream Fundamentals
3843 @subsubsection SRFI-41 Stream Fundamentals
3845 SRFI-41 Streams are based on two mutually-recursive abstract data types:
3846 An object of the @code{stream} abstract data type is a promise that,
3847 when forced, is either @code{stream-null} or is an object of type
3848 @code{stream-pair}. An object of the @code{stream-pair} abstract data
3849 type contains a @code{stream-car} and a @code{stream-cdr}, which must be
3850 a @code{stream}. The essential feature of streams is the systematic
3851 suspensions of the recursive promises between the two data types.
3853 The object stored in the @code{stream-car} of a @code{stream-pair} is a
3854 promise that is forced the first time the @code{stream-car} is accessed;
3855 its value is cached in case it is needed again. The object may have any
3856 type, and different stream elements may have different types. If the
3857 @code{stream-car} is never accessed, the object stored there is never
3858 evaluated. Likewise, the @code{stream-cdr} is a promise to return a
3859 stream, and is only forced on demand.
3861 @node SRFI-41 Stream Primitives
3862 @subsubsection SRFI-41 Stream Primitives
3864 This library provides eight operators: constructors for
3865 @code{stream-null} and @code{stream-pair}s, type predicates for streams
3866 and the two kinds of streams, accessors for both fields of a
3867 @code{stream-pair}, and a lambda that creates procedures that return
3870 @defvr {Scheme Variable} stream-null
3871 A promise that, when forced, is a single object, distinguishable from
3872 all other objects, that represents the null stream. @code{stream-null}
3873 is immutable and unique.
3876 @deffn {Scheme Syntax} stream-cons object-expr stream-expr
3877 Creates a newly-allocated stream containing a promise that, when forced,
3878 is a @code{stream-pair} with @var{object-expr} in its @code{stream-car}
3879 and @var{stream-expr} in its @code{stream-cdr}. Neither
3880 @var{object-expr} nor @var{stream-expr} is evaluated when
3881 @code{stream-cons} is called.
3883 Once created, a @code{stream-pair} is immutable; there is no
3884 @code{stream-set-car!} or @code{stream-set-cdr!} that modifies an
3885 existing stream-pair. There is no dotted-pair or improper stream as
3889 @deffn {Scheme Procedure} stream? object
3890 Returns true if @var{object} is a stream, otherwise returns false. If
3891 @var{object} is a stream, its promise will not be forced. If
3892 @code{(stream? obj)} returns true, then one of @code{(stream-null? obj)}
3893 or @code{(stream-pair? obj)} will return true and the other will return
3897 @deffn {Scheme Procedure} stream-null? object
3898 Returns true if @var{object} is the distinguished null stream, otherwise
3899 returns false. If @var{object} is a stream, its promise will be forced.
3902 @deffn {Scheme Procedure} stream-pair? object
3903 Returns true if @var{object} is a @code{stream-pair} constructed by
3904 @code{stream-cons}, otherwise returns false. If @var{object} is a
3905 stream, its promise will be forced.
3908 @deffn {Scheme Procedure} stream-car stream
3909 Returns the object stored in the @code{stream-car} of @var{stream}. An
3910 error is signalled if the argument is not a @code{stream-pair}. This
3911 causes the @var{object-expr} passed to @code{stream-cons} to be
3912 evaluated if it had not yet been; the value is cached in case it is
3916 @deffn {Scheme Procedure} stream-cdr stream
3917 Returns the stream stored in the @code{stream-cdr} of @var{stream}. An
3918 error is signalled if the argument is not a @code{stream-pair}.
3921 @deffn {Scheme Syntax} stream-lambda formals body @dots{}
3922 Creates a procedure that returns a promise to evaluate the @var{body} of
3923 the procedure. The last @var{body} expression to be evaluated must
3924 yield a stream. As with normal @code{lambda}, @var{formals} may be a
3925 single variable name, in which case all the formal arguments are
3926 collected into a single list, or a list of variable names, which may be
3927 null if there are no arguments, proper if there are an exact number of
3928 arguments, or dotted if a fixed number of arguments is to be followed by
3929 zero or more arguments collected into a list. @var{Body} must contain
3930 at least one expression, and may contain internal definitions preceding
3931 any expressions to be evaluated.
3941 (stream-car strm123) @result{} 1
3942 (stream-car (stream-cdr strm123) @result{} 2
3946 (stream-cons (/ 1 0) stream-null))) @result{} #f
3948 (stream? (list 1 2 3)) @result{} #f
3951 (stream-lambda (f x)
3952 (stream-cons x (iter f (f x)))))
3954 (define nats (iter (lambda (x) (+ x 1)) 0))
3956 (stream-car (stream-cdr nats)) @result{} 1
3959 (stream-lambda (s1 s2)
3961 (+ (stream-car s1) (stream-car s2))
3962 (stream-add (stream-cdr s1)
3965 (define evens (stream-add nats nats))
3967 (stream-car evens) @result{} 0
3968 (stream-car (stream-cdr evens)) @result{} 2
3969 (stream-car (stream-cdr (stream-cdr evens))) @result{} 4
3972 @node SRFI-41 Stream Library
3973 @subsubsection SRFI-41 Stream Library
3975 @deffn {Scheme Syntax} define-stream (name args @dots{}) body @dots{}
3976 Creates a procedure that returns a stream, and may appear anywhere a
3977 normal @code{define} may appear, including as an internal definition.
3978 It may contain internal definitions of its own. The defined procedure
3979 takes arguments in the same way as @code{stream-lambda}.
3980 @code{define-stream} is syntactic sugar on @code{stream-lambda}; see
3981 also @code{stream-let}, which is also a sugaring of
3982 @code{stream-lambda}.
3984 A simple version of @code{stream-map} that takes only a single input
3985 stream calls itself recursively:
3988 (define-stream (stream-map proc strm)
3989 (if (stream-null? strm)
3992 (proc (stream-car strm))
3993 (stream-map proc (stream-cdr strm))))))
3997 @deffn {Scheme Procedure} list->stream list
3998 Returns a newly-allocated stream containing the elements from
4002 @deffn {Scheme Procedure} port->stream [port]
4003 Returns a newly-allocated stream containing in its elements the
4004 characters on the port. If @var{port} is not given it defaults to the
4005 current input port. The returned stream has finite length and is
4006 terminated by @code{stream-null}.
4008 It looks like one use of @code{port->stream} would be this:
4012 (with-input-from-file filename
4013 (lambda () (port->stream))))
4016 But that fails, because @code{with-input-from-file} is eager, and closes
4017 the input port prematurely, before the first character is read. To read
4018 a file into a stream, say:
4021 (define-stream (file->stream filename)
4022 (let ((p (open-input-file filename)))
4023 (stream-let loop ((c (read-char p)))
4025 (begin (close-input-port p)
4028 (loop (read-char p)))))))
4032 @deffn {Scheme Syntax} stream object-expr @dots{}
4033 Creates a newly-allocated stream containing in its elements the objects,
4034 in order. The @var{object-expr}s are evaluated when they are accessed,
4035 not when the stream is created. If no objects are given, as in
4036 (stream), the null stream is returned. See also @code{list->stream}.
4039 (define strm123 (stream 1 2 3))
4041 ; (/ 1 0) not evaluated when stream is created
4042 (define s (stream 1 (/ 1 0) -1))
4046 @deffn {Scheme Procedure} stream->list [n] stream
4047 Returns a newly-allocated list containing in its elements the first
4048 @var{n} items in @var{stream}. If @var{stream} has less than @var{n}
4049 items, all the items in the stream will be included in the returned
4050 list. If @var{n} is not given it defaults to infinity, which means that
4051 unless @var{stream} is finite @code{stream->list} will never return.
4055 (stream-map (lambda (x) (* x x))
4057 @result{} (0 1 4 9 16 25 36 49 64 81)
4061 @deffn {Scheme Procedure} stream-append stream @dots{}
4062 Returns a newly-allocated stream containing in its elements those
4063 elements contained in its input @var{stream}s, in order of input. If
4064 any of the input streams is infinite, no elements of any of the
4065 succeeding input streams will appear in the output stream. See also
4066 @code{stream-concat}.
4069 @deffn {Scheme Procedure} stream-concat stream
4070 Takes a @var{stream} consisting of one or more streams and returns a
4071 newly-allocated stream containing all the elements of the input streams.
4072 If any of the streams in the input @var{stream} is infinite, any
4073 remaining streams in the input stream will never appear in the output
4074 stream. See also @code{stream-append}.
4077 @deffn {Scheme Procedure} stream-constant object @dots{}
4078 Returns a newly-allocated stream containing in its elements the
4079 @var{object}s, repeating in succession forever.
4082 (stream-constant 1) @result{} 1 1 1 @dots{}
4083 (stream-constant #t #f) @result{} #t #f #t #f #t #f @dots{}
4087 @deffn {Scheme Procedure} stream-drop n stream
4088 Returns the suffix of the input @var{stream} that starts at the next
4089 element after the first @var{n} elements. The output stream shares
4090 structure with the input @var{stream}; thus, promises forced in one
4091 instance of the stream are also forced in the other instance of the
4092 stream. If the input @var{stream} has less than @var{n} elements,
4093 @code{stream-drop} returns the null stream. See also
4097 @deffn {Scheme Procedure} stream-drop-while pred stream
4098 Returns the suffix of the input @var{stream} that starts at the first
4099 element @var{x} for which @code{(pred x)} returns false. The output
4100 stream shares structure with the input @var{stream}. See also
4101 @code{stream-take-while}.
4104 @deffn {Scheme Procedure} stream-filter pred stream
4105 Returns a newly-allocated stream that contains only those elements
4106 @var{x} of the input @var{stream} which satisfy the predicate
4110 (stream-filter odd? (stream-from 0))
4111 @result{} 1 3 5 7 9 @dots{}
4115 @deffn {Scheme Procedure} stream-fold proc base stream
4116 Applies a binary procedure @var{proc} to @var{base} and the first
4117 element of @var{stream} to compute a new @var{base}, then applies the
4118 procedure to the new @var{base} and the next element of @var{stream} to
4119 compute a succeeding @var{base}, and so on, accumulating a value that is
4120 finally returned as the value of @code{stream-fold} when the end of the
4121 stream is reached. @var{stream} must be finite, or @code{stream-fold}
4122 will enter an infinite loop. See also @code{stream-scan}, which is
4123 similar to @code{stream-fold}, but useful for infinite streams. For
4124 readers familiar with other functional languages, this is a left-fold;
4125 there is no corresponding right-fold, since right-fold relies on finite
4126 streams that are fully-evaluated, in which case they may as well be
4127 converted to a list.
4130 @deffn {Scheme Procedure} stream-for-each proc stream @dots{}
4131 Applies @var{proc} element-wise to corresponding elements of the input
4132 @var{stream}s for side-effects; it returns nothing.
4133 @code{stream-for-each} stops as soon as any of its input streams is
4137 @deffn {Scheme Procedure} stream-from first [step]
4138 Creates a newly-allocated stream that contains @var{first} as its first
4139 element and increments each succeeding element by @var{step}. If
4140 @var{step} is not given it defaults to 1. @var{first} and @var{step}
4141 may be of any numeric type. @code{stream-from} is frequently useful as
4142 a generator in @code{stream-of} expressions. See also
4143 @code{stream-range} for a similar procedure that creates finite streams.
4146 @deffn {Scheme Procedure} stream-iterate proc base
4147 Creates a newly-allocated stream containing @var{base} in its first
4148 element and applies @var{proc} to each element in turn to determine the
4149 succeeding element. See also @code{stream-unfold} and
4150 @code{stream-unfolds}.
4153 @deffn {Scheme Procedure} stream-length stream
4154 Returns the number of elements in the @var{stream}; it does not evaluate
4155 its elements. @code{stream-length} may only be used on finite streams;
4156 it enters an infinite loop with infinite streams.
4159 @deffn {Scheme Syntax} stream-let tag ((var expr) @dots{}) body @dots{}
4160 Creates a local scope that binds each variable to the value of its
4161 corresponding expression. It additionally binds @var{tag} to a
4162 procedure which takes the bound variables as arguments and @var{body} as
4163 its defining expressions, binding the @var{tag} with
4164 @code{stream-lambda}. @var{tag} is in scope within body, and may be
4165 called recursively. When the expanded expression defined by the
4166 @code{stream-let} is evaluated, @code{stream-let} evaluates the
4167 expressions in its @var{body} in an environment containing the
4168 newly-bound variables, returning the value of the last expression
4169 evaluated, which must yield a stream.
4171 @code{stream-let} provides syntactic sugar on @code{stream-lambda}, in
4172 the same manner as normal @code{let} provides syntactic sugar on normal
4173 @code{lambda}. However, unlike normal @code{let}, the @var{tag} is
4174 required, not optional, because unnamed @code{stream-let} is
4177 For example, @code{stream-member} returns the first @code{stream-pair}
4178 of the input @var{strm} with a @code{stream-car} @var{x} that satisfies
4179 @code{(eql? obj x)}, or the null stream if @var{x} is not present in
4183 (define-stream (stream-member eql? obj strm)
4184 (stream-let loop ((strm strm))
4185 (cond ((stream-null? strm) strm)
4186 ((eql? obj (stream-car strm)) strm)
4187 (else (loop (stream-cdr strm))))))
4191 @deffn {Scheme Procedure} stream-map proc stream @dots{}
4192 Applies @var{proc} element-wise to corresponding elements of the input
4193 @var{stream}s, returning a newly-allocated stream containing elements
4194 that are the results of those procedure applications. The output stream
4195 has as many elements as the minimum-length input stream, and may be
4199 @deffn {Scheme Syntax} stream-match stream clause @dots{}
4200 Provides pattern-matching for streams. The input @var{stream} is an
4201 expression that evaluates to a stream. Clauses are of the form
4202 @code{(pattern [fender] expression)}, consisting of a @var{pattern} that
4203 matches a stream of a particular shape, an optional @var{fender} that
4204 must succeed if the pattern is to match, and an @var{expression} that is
4205 evaluated if the pattern matches. There are four types of patterns:
4209 () matches the null stream.
4212 (@var{pat0} @var{pat1} @dots{}) matches a finite stream with length
4213 exactly equal to the number of pattern elements.
4216 (@var{pat0} @var{pat1} @dots{} @code{.} @var{pat-rest}) matches an
4217 infinite stream, or a finite stream with length at least as great as the
4218 number of pattern elements before the literal dot.
4221 @var{pat} matches an entire stream. Should always appear last in the
4222 list of clauses; it's not an error to appear elsewhere, but subsequent
4223 clauses could never match.
4226 Each pattern element may be either:
4230 An identifier, which matches any stream element. Additionally, the
4231 value of the stream element is bound to the variable named by the
4232 identifier, which is in scope in the @var{fender} and @var{expression}
4233 of the corresponding @var{clause}. Each identifier in a single pattern
4237 A literal underscore (@code{_}), which matches any stream element but
4238 creates no bindings.
4241 The @var{pattern}s are tested in order, left-to-right, until a matching
4242 pattern is found; if @var{fender} is present, it must evaluate to a true
4243 value for the match to be successful. Pattern variables are bound in
4244 the corresponding @var{fender} and @var{expression}. Once the matching
4245 @var{pattern} is found, the corresponding @var{expression} is evaluated
4246 and returned as the result of the match. An error is signaled if no
4247 pattern matches the input @var{stream}.
4249 @code{stream-match} is often used to distinguish null streams from
4250 non-null streams, binding @var{head} and @var{tail}:
4256 ((head . tail) (+ 1 (len tail)))))
4259 Fenders can test the common case where two stream elements must be
4260 identical; the @code{else} pattern is an identifier bound to the entire
4261 stream, not a keyword as in @code{cond}.
4265 ((x y . _) (equal? x y) 'ok)
4269 A more complex example uses two nested matchers to match two different
4270 stream arguments; @code{(stream-merge lt? . strms)} stably merges two or
4271 more streams ordered by the @code{lt?} predicate:
4274 (define-stream (stream-merge lt? . strms)
4275 (define-stream (merge xx yy)
4276 (stream-match xx (() yy) ((x . xs)
4277 (stream-match yy (() xx) ((y . ys)
4279 (stream-cons y (merge xx ys))
4280 (stream-cons x (merge xs yy))))))))
4281 (stream-let loop ((strms strms))
4282 (cond ((null? strms) stream-null)
4283 ((null? (cdr strms)) (car strms))
4284 (else (merge (car strms)
4285 (apply stream-merge lt?
4290 @deffn {Scheme Syntax} stream-of expr clause @dots{}
4291 Provides the syntax of stream comprehensions, which generate streams by
4292 means of looping expressions. The result is a stream of objects of the
4293 type returned by @var{expr}. There are four types of clauses:
4297 (@var{var} @code{in} @var{stream-expr}) loops over the elements of
4298 @var{stream-expr}, in order from the start of the stream, binding each
4299 element of the stream in turn to @var{var}. @code{stream-from} and
4300 @code{stream-range} are frequently useful as generators for
4304 (@var{var} @code{is} @var{expr}) binds @var{var} to the value obtained
4305 by evaluating @var{expr}.
4308 (@var{pred} @var{expr}) includes in the output stream only those
4309 elements @var{x} which satisfy the predicate @var{pred}.
4312 The scope of variables bound in the stream comprehension is the clauses
4313 to the right of the binding clause (but not the binding clause itself)
4314 plus the result expression.
4316 When two or more generators are present, the loops are processed as if
4317 they are nested from left to right; that is, the rightmost generator
4318 varies fastest. A consequence of this is that only the first generator
4319 may be infinite and all subsequent generators must be finite. If no
4320 generators are present, the result of a stream comprehension is a stream
4321 containing the result expression; thus, @samp{(stream-of 1)} produces a
4322 finite stream containing only the element 1.
4326 (x in (stream-range 0 10))
4328 @result{} 0 4 16 36 64
4330 (stream-of (list a b)
4331 (a in (stream-range 1 4))
4332 (b in (stream-range 1 3)))
4333 @result{} (1 1) (1 2) (2 1) (2 2) (3 1) (3 2)
4335 (stream-of (list i j)
4336 (i in (stream-range 1 5))
4337 (j in (stream-range (+ i 1) 5)))
4338 @result{} (1 2) (1 3) (1 4) (2 3) (2 4) (3 4)
4342 @deffn {Scheme Procedure} stream-range first past [step]
4343 Creates a newly-allocated stream that contains @var{first} as its first
4344 element and increments each succeeding element by @var{step}. The
4345 stream is finite and ends before @var{past}, which is not an element of
4346 the stream. If @var{step} is not given it defaults to 1 if @var{first}
4347 is less than past and -1 otherwise. @var{first}, @var{past} and
4348 @var{step} may be of any real numeric type. @code{stream-range} is
4349 frequently useful as a generator in @code{stream-of} expressions. See
4350 also @code{stream-from} for a similar procedure that creates infinite
4354 (stream-range 0 10) @result{} 0 1 2 3 4 5 6 7 8 9
4355 (stream-range 0 10 2) @result{} 0 2 4 6 8
4358 Successive elements of the stream are calculated by adding @var{step} to
4359 @var{first}, so if any of @var{first}, @var{past} or @var{step} are
4360 inexact, the length of the output stream may differ from
4361 @code{(ceiling (- (/ (- past first) step) 1)}.
4364 @deffn {Scheme Procedure} stream-ref stream n
4365 Returns the @var{n}th element of stream, counting from zero. An error
4366 is signaled if @var{n} is greater than or equal to the length of stream.
4371 (stream-scan * 1 (stream-from 1))
4376 @deffn {Scheme Procedure} stream-reverse stream
4377 Returns a newly-allocated stream containing the elements of the input
4378 @var{stream} but in reverse order. @code{stream-reverse} may only be
4379 used with finite streams; it enters an infinite loop with infinite
4380 streams. @code{stream-reverse} does not force evaluation of the
4381 elements of the stream.
4384 @deffn {Scheme Procedure} stream-scan proc base stream
4385 Accumulates the partial folds of an input @var{stream} into a
4386 newly-allocated output stream. The output stream is the @var{base}
4387 followed by @code{(stream-fold proc base (stream-take i stream))} for
4388 each of the first @var{i} elements of @var{stream}.
4391 (stream-scan + 0 (stream-from 1))
4392 @result{} (stream 0 1 3 6 10 15 @dots{})
4394 (stream-scan * 1 (stream-from 1))
4395 @result{} (stream 1 1 2 6 24 120 @dots{})
4399 @deffn {Scheme Procedure} stream-take n stream
4400 Returns a newly-allocated stream containing the first @var{n} elements
4401 of the input @var{stream}. If the input @var{stream} has less than
4402 @var{n} elements, so does the output stream. See also
4406 @deffn {Scheme Procedure} stream-take-while pred stream
4407 Takes a predicate and a @code{stream} and returns a newly-allocated
4408 stream containing those elements @code{x} that form the maximal prefix
4409 of the input stream which satisfy @var{pred}. See also
4410 @code{stream-drop-while}.
4413 @deffn {Scheme Procedure} stream-unfold map pred gen base
4414 The fundamental recursive stream constructor. It constructs a stream by
4415 repeatedly applying @var{gen} to successive values of @var{base}, in the
4416 manner of @code{stream-iterate}, then applying @var{map} to each of the
4417 values so generated, appending each of the mapped values to the output
4418 stream as long as @code{(pred? base)} returns a true value. See also
4419 @code{stream-iterate} and @code{stream-unfolds}.
4421 The expression below creates the finite stream @samp{0 1 4 9 16 25 36 49
4422 64 81}. Initially the @var{base} is 0, which is less than 10, so
4423 @var{map} squares the @var{base} and the mapped value becomes the first
4424 element of the output stream. Then @var{gen} increments the @var{base}
4425 by 1, so it becomes 1; this is less than 10, so @var{map} squares the
4426 new @var{base} and 1 becomes the second element of the output stream.
4427 And so on, until the base becomes 10, when @var{pred} stops the
4428 recursion and stream-null ends the output stream.
4432 (lambda (x) (expt x 2)) ; map
4433 (lambda (x) (< x 10)) ; pred?
4434 (lambda (x) (+ x 1)) ; gen
4439 @deffn {Scheme Procedure} stream-unfolds proc seed
4440 Returns @var{n} newly-allocated streams containing those elements
4441 produced by successive calls to the generator @var{proc}, which takes
4442 the current @var{seed} as its argument and returns @var{n}+1 values
4444 (@var{proc} @var{seed}) @result{} @var{seed} @var{result_0} @dots{} @var{result_n-1}
4446 where the returned @var{seed} is the input @var{seed} to the next call
4447 to the generator and @var{result_i} indicates how to produce the next
4448 element of the @var{i}th result stream:
4452 (@var{value}): @var{value} is the next car of the result stream.
4455 @code{#f}: no value produced by this iteration of the generator
4456 @var{proc} for the result stream.
4459 (): the end of the result stream.
4462 It may require multiple calls of @var{proc} to produce the next element
4463 of any particular result stream. See also @code{stream-iterate} and
4464 @code{stream-unfold}.
4467 (define (stream-partition pred? strm)
4470 (if (stream-null? s)
4472 (let ((a (stream-car s))
4475 (values d (list a) #f)
4476 (values d #f (list a))))))
4481 (stream-partition odd?
4482 (stream-range 1 6)))
4483 (lambda (odds evens)
4484 (list (stream->list odds)
4485 (stream->list evens))))
4486 @result{} ((1 3 5) (2 4))
4490 @deffn {Scheme Procedure} stream-zip stream @dots{}
4491 Returns a newly-allocated stream in which each element is a list (not a
4492 stream) of the corresponding elements of the input @var{stream}s. The
4493 output stream is as long as the shortest input @var{stream}, if any of
4494 the input @var{stream}s is finite, or is infinite if all the input
4495 @var{stream}s are infinite.
4499 @subsection SRFI-42 - Eager Comprehensions
4502 See @uref{http://srfi.schemers.org/srfi-42/srfi-42.html, the
4503 specification of SRFI-42}.
4506 @subsection SRFI-45 - Primitives for Expressing Iterative Lazy Algorithms
4509 This subsection is based on @uref{http://srfi.schemers.org/srfi-45/srfi-45.html, the
4510 specification of SRFI-45} written by Andr@'e van Tonder.
4512 @c Copyright (C) André van Tonder (2003). All Rights Reserved.
4514 @c Permission is hereby granted, free of charge, to any person obtaining a
4515 @c copy of this software and associated documentation files (the
4516 @c "Software"), to deal in the Software without restriction, including
4517 @c without limitation the rights to use, copy, modify, merge, publish,
4518 @c distribute, sublicense, and/or sell copies of the Software, and to
4519 @c permit persons to whom the Software is furnished to do so, subject to
4520 @c the following conditions:
4522 @c The above copyright notice and this permission notice shall be included
4523 @c in all copies or substantial portions of the Software.
4525 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
4526 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
4527 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
4528 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
4529 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
4530 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
4531 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
4533 Lazy evaluation is traditionally simulated in Scheme using @code{delay}
4534 and @code{force}. However, these primitives are not powerful enough to
4535 express a large class of lazy algorithms that are iterative. Indeed, it
4536 is folklore in the Scheme community that typical iterative lazy
4537 algorithms written using delay and force will often require unbounded
4540 This SRFI provides set of three operations: @{@code{lazy}, @code{delay},
4541 @code{force}@}, which allow the programmer to succinctly express lazy
4542 algorithms while retaining bounded space behavior in cases that are
4543 properly tail-recursive. A general recipe for using these primitives is
4544 provided. An additional procedure @code{eager} is provided for the
4545 construction of eager promises in cases where efficiency is a concern.
4547 Although this SRFI redefines @code{delay} and @code{force}, the
4548 extension is conservative in the sense that the semantics of the subset
4549 @{@code{delay}, @code{force}@} in isolation (i.e., as long as the
4550 program does not use @code{lazy}) agrees with that in R5RS. In other
4551 words, no program that uses the R5RS definitions of delay and force will
4552 break if those definition are replaced by the SRFI-45 definitions of
4555 Guile also adds @code{promise?} to the list of exports, which is not
4556 part of the official SRFI-45.
4558 @deffn {Scheme Procedure} promise? obj
4559 Return true if @var{obj} is an SRFI-45 promise, otherwise return false.
4562 @deffn {Scheme Syntax} delay expression
4563 Takes an expression of arbitrary type @var{a} and returns a promise of
4564 type @code{(Promise @var{a})} which at some point in the future may be
4565 asked (by the @code{force} procedure) to evaluate the expression and
4566 deliver the resulting value.
4569 @deffn {Scheme Syntax} lazy expression
4570 Takes an expression of type @code{(Promise @var{a})} and returns a
4571 promise of type @code{(Promise @var{a})} which at some point in the
4572 future may be asked (by the @code{force} procedure) to evaluate the
4573 expression and deliver the resulting promise.
4576 @deffn {Scheme Procedure} force expression
4577 Takes an argument of type @code{(Promise @var{a})} and returns a value
4578 of type @var{a} as follows: If a value of type @var{a} has been computed
4579 for the promise, this value is returned. Otherwise, the promise is
4580 first evaluated, then overwritten by the obtained promise or value, and
4581 then force is again applied (iteratively) to the promise.
4584 @deffn {Scheme Procedure} eager expression
4585 Takes an argument of type @var{a} and returns a value of type
4586 @code{(Promise @var{a})}. As opposed to @code{delay}, the argument is
4587 evaluated eagerly. Semantically, writing @code{(eager expression)} is
4588 equivalent to writing
4591 (let ((value expression)) (delay value)).
4594 However, the former is more efficient since it does not require
4595 unnecessary creation and evaluation of thunks. We also have the
4599 (delay expression) = (lazy (eager expression))
4603 The following reduction rules may be helpful for reasoning about these
4604 primitives. However, they do not express the memoization and memory
4605 usage semantics specified above:
4608 (force (delay expression)) -> expression
4609 (force (lazy expression)) -> (force expression)
4610 (force (eager value)) -> value
4613 @subsubheading Correct usage
4615 We now provide a general recipe for using the primitives @{@code{lazy},
4616 @code{delay}, @code{force}@} to express lazy algorithms in Scheme. The
4617 transformation is best described by way of an example: Consider the
4618 stream-filter algorithm, expressed in a hypothetical lazy language as
4621 (define (stream-filter p? s)
4626 (cons h (stream-filter p? t))
4627 (stream-filter p? t)))))
4630 This algorithm can be expressed as follows in Scheme:
4633 (define (stream-filter p? s)
4635 (if (null? (force s)) (delay '())
4636 (let ((h (car (force s)))
4637 (t (cdr (force s))))
4639 (delay (cons h (stream-filter p? t)))
4640 (stream-filter p? t))))))
4647 wrap all constructors (e.g., @code{'()}, @code{cons}) with @code{delay},
4649 apply @code{force} to arguments of deconstructors (e.g., @code{car},
4650 @code{cdr} and @code{null?}),
4652 wrap procedure bodies with @code{(lazy ...)}.
4656 @subsection SRFI-55 - Requiring Features
4659 SRFI-55 provides @code{require-extension} which is a portable
4660 mechanism to load selected SRFI modules. This is implemented in the
4661 Guile core, there's no module needed to get SRFI-55 itself.
4663 @deffn {library syntax} require-extension clause1 clause2 @dots{}
4664 Require the features of @var{clause1} @var{clause2} @dots{} , throwing
4665 an error if any are unavailable.
4667 A @var{clause} is of the form @code{(@var{identifier} arg...)}. The
4668 only @var{identifier} currently supported is @code{srfi} and the
4669 arguments are SRFI numbers. For example to get SRFI-1 and SRFI-6,
4672 (require-extension (srfi 1 6))
4675 @code{require-extension} can only be used at the top-level.
4677 A Guile-specific program can simply @code{use-modules} to load SRFIs
4678 not already in the core, @code{require-extension} is for programs
4679 designed to be portable to other Scheme implementations.
4684 @subsection SRFI-60 - Integers as Bits
4686 @cindex integers as bits
4687 @cindex bitwise logical
4689 This SRFI provides various functions for treating integers as bits and
4690 for bitwise manipulations. These functions can be obtained with,
4693 (use-modules (srfi srfi-60))
4696 Integers are treated as infinite precision twos-complement, the same
4697 as in the core logical functions (@pxref{Bitwise Operations}). And
4698 likewise bit indexes start from 0 for the least significant bit. The
4699 following functions in this SRFI are already in the Guile core,
4708 @code{integer-length},
4714 @defun bitwise-and n1 ...
4715 @defunx bitwise-ior n1 ...
4716 @defunx bitwise-xor n1 ...
4717 @defunx bitwise-not n
4718 @defunx any-bits-set? j k
4719 @defunx bit-set? index n
4720 @defunx arithmetic-shift n count
4721 @defunx bit-field n start end
4723 Aliases for @code{logand}, @code{logior}, @code{logxor},
4724 @code{lognot}, @code{logtest}, @code{logbit?}, @code{ash},
4725 @code{bit-extract} and @code{logcount} respectively.
4727 Note that the name @code{bit-count} conflicts with @code{bit-count} in
4728 the core (@pxref{Bit Vectors}).
4731 @defun bitwise-if mask n1 n0
4732 @defunx bitwise-merge mask n1 n0
4733 Return an integer with bits selected from @var{n1} and @var{n0}
4734 according to @var{mask}. Those bits where @var{mask} has 1s are taken
4735 from @var{n1}, and those where @var{mask} has 0s are taken from
4739 (bitwise-if 3 #b0101 #b1010) @result{} 9
4743 @defun log2-binary-factors n
4744 @defunx first-set-bit n
4745 Return a count of how many factors of 2 are present in @var{n}. This
4746 is also the bit index of the lowest 1 bit in @var{n}. If @var{n} is
4747 0, the return is @math{-1}.
4750 (log2-binary-factors 6) @result{} 1
4751 (log2-binary-factors -8) @result{} 3
4755 @defun copy-bit index n newbit
4756 Return @var{n} with the bit at @var{index} set according to
4757 @var{newbit}. @var{newbit} should be @code{#t} to set the bit to 1,
4758 or @code{#f} to set it to 0. Bits other than at @var{index} are
4759 unchanged in the return.
4762 (copy-bit 1 #b0101 #t) @result{} 7
4766 @defun copy-bit-field n newbits start end
4767 Return @var{n} with the bits from @var{start} (inclusive) to @var{end}
4768 (exclusive) changed to the value @var{newbits}.
4770 The least significant bit in @var{newbits} goes to @var{start}, the
4771 next to @math{@var{start}+1}, etc. Anything in @var{newbits} past the
4772 @var{end} given is ignored.
4775 (copy-bit-field #b10000 #b11 1 3) @result{} #b10110
4779 @defun rotate-bit-field n count start end
4780 Return @var{n} with the bit field from @var{start} (inclusive) to
4781 @var{end} (exclusive) rotated upwards by @var{count} bits.
4783 @var{count} can be positive or negative, and it can be more than the
4784 field width (it'll be reduced modulo the width).
4787 (rotate-bit-field #b0110 2 1 4) @result{} #b1010
4791 @defun reverse-bit-field n start end
4792 Return @var{n} with the bits from @var{start} (inclusive) to @var{end}
4793 (exclusive) reversed.
4796 (reverse-bit-field #b101001 2 4) @result{} #b100101
4800 @defun integer->list n [len]
4801 Return bits from @var{n} in the form of a list of @code{#t} for 1 and
4802 @code{#f} for 0. The least significant @var{len} bits are returned,
4803 and the first list element is the most significant of those bits. If
4804 @var{len} is not given, the default is @code{(integer-length @var{n})}
4805 (@pxref{Bitwise Operations}).
4808 (integer->list 6) @result{} (#t #t #f)
4809 (integer->list 1 4) @result{} (#f #f #f #t)
4813 @defun list->integer lst
4814 @defunx booleans->integer bool@dots{}
4815 Return an integer formed bitwise from the given @var{lst} list of
4816 booleans, or for @code{booleans->integer} from the @var{bool}
4819 Each boolean is @code{#t} for a 1 and @code{#f} for a 0. The first
4820 element becomes the most significant bit in the return.
4823 (list->integer '(#t #f #t #f)) @result{} 10
4829 @subsection SRFI-61 - A more general @code{cond} clause
4831 This SRFI extends RnRS @code{cond} to support test expressions that
4832 return multiple values, as well as arbitrary definitions of test
4833 success. SRFI 61 is implemented in the Guile core; there's no module
4834 needed to get SRFI-61 itself. Extended @code{cond} is documented in
4835 @ref{Conditionals,, Simple Conditional Evaluation}.
4838 @subsection SRFI-67 - Compare procedures
4841 See @uref{http://srfi.schemers.org/srfi-67/srfi-67.html, the
4842 specification of SRFI-67}.
4845 @subsection SRFI-69 - Basic hash tables
4848 This is a portable wrapper around Guile's built-in hash table and weak
4849 table support. @xref{Hash Tables}, for information on that built-in
4850 support. Above that, this hash-table interface provides association
4851 of equality and hash functions with tables at creation time, so
4852 variants of each function are not required, as well as a procedure
4853 that takes care of most uses for Guile hash table handles, which this
4854 SRFI does not provide as such.
4859 (use-modules (srfi srfi-69))
4863 * SRFI-69 Creating hash tables::
4864 * SRFI-69 Accessing table items::
4865 * SRFI-69 Table properties::
4866 * SRFI-69 Hash table algorithms::
4869 @node SRFI-69 Creating hash tables
4870 @subsubsection Creating hash tables
4872 @deffn {Scheme Procedure} make-hash-table [equal-proc hash-proc #:weak weakness start-size]
4873 Create and answer a new hash table with @var{equal-proc} as the
4874 equality function and @var{hash-proc} as the hashing function.
4876 By default, @var{equal-proc} is @code{equal?}. It can be any
4877 two-argument procedure, and should answer whether two keys are the
4878 same for this table's purposes.
4880 My default @var{hash-proc} assumes that @code{equal-proc} is no
4881 coarser than @code{equal?} unless it is literally @code{string-ci=?}.
4882 If provided, @var{hash-proc} should be a two-argument procedure that
4883 takes a key and the current table size, and answers a reasonably good
4884 hash integer between 0 (inclusive) and the size (exclusive).
4886 @var{weakness} should be @code{#f} or a symbol indicating how ``weak''
4891 An ordinary non-weak hash table. This is the default.
4894 When the key has no more non-weak references at GC, remove that entry.
4897 When the value has no more non-weak references at GC, remove that
4901 When either has no more non-weak references at GC, remove the
4905 As a legacy of the time when Guile couldn't grow hash tables,
4906 @var{start-size} is an optional integer argument that specifies the
4907 approximate starting size for the hash table, which will be rounded to
4908 an algorithmically-sounder number.
4911 By @dfn{coarser} than @code{equal?}, we mean that for all @var{x} and
4912 @var{y} values where @code{(@var{equal-proc} @var{x} @var{y})},
4913 @code{(equal? @var{x} @var{y})} as well. If that does not hold for
4914 your @var{equal-proc}, you must provide a @var{hash-proc}.
4916 In the case of weak tables, remember that @dfn{references} above
4917 always refers to @code{eq?}-wise references. Just because you have a
4918 reference to some string @code{"foo"} doesn't mean that an association
4919 with key @code{"foo"} in a weak-key table @emph{won't} be collected;
4920 it only counts as a reference if the two @code{"foo"}s are @code{eq?},
4921 regardless of @var{equal-proc}. As such, it is usually only sensible
4922 to use @code{eq?} and @code{hashq} as the equivalence and hash
4923 functions for a weak table. @xref{Weak References}, for more
4924 information on Guile's built-in weak table support.
4926 @deffn {Scheme Procedure} alist->hash-table alist [equal-proc hash-proc #:weak weakness start-size]
4927 As with @code{make-hash-table}, but initialize it with the
4928 associations in @var{alist}. Where keys are repeated in @var{alist},
4929 the leftmost association takes precedence.
4932 @node SRFI-69 Accessing table items
4933 @subsubsection Accessing table items
4935 @deffn {Scheme Procedure} hash-table-ref table key [default-thunk]
4936 @deffnx {Scheme Procedure} hash-table-ref/default table key default
4937 Answer the value associated with @var{key} in @var{table}. If
4938 @var{key} is not present, answer the result of invoking the thunk
4939 @var{default-thunk}, which signals an error instead by default.
4941 @code{hash-table-ref/default} is a variant that requires a third
4942 argument, @var{default}, and answers @var{default} itself instead of
4946 @deffn {Scheme Procedure} hash-table-set! table key new-value
4947 Set @var{key} to @var{new-value} in @var{table}.
4950 @deffn {Scheme Procedure} hash-table-delete! table key
4951 Remove the association of @var{key} in @var{table}, if present. If
4955 @deffn {Scheme Procedure} hash-table-exists? table key
4956 Answer whether @var{key} has an association in @var{table}.
4959 @deffn {Scheme Procedure} hash-table-update! table key modifier [default-thunk]
4960 @deffnx {Scheme Procedure} hash-table-update!/default table key modifier default
4961 Replace @var{key}'s associated value in @var{table} by invoking
4962 @var{modifier} with one argument, the old value.
4964 If @var{key} is not present, and @var{default-thunk} is provided,
4965 invoke it with no arguments to get the ``old value'' to be passed to
4966 @var{modifier} as above. If @var{default-thunk} is not provided in
4967 such a case, signal an error.
4969 @code{hash-table-update!/default} is a variant that requires the
4970 fourth argument, which is used directly as the ``old value'' rather
4971 than as a thunk to be invoked to retrieve the ``old value''.
4974 @node SRFI-69 Table properties
4975 @subsubsection Table properties
4977 @deffn {Scheme Procedure} hash-table-size table
4978 Answer the number of associations in @var{table}. This is guaranteed
4979 to run in constant time for non-weak tables.
4982 @deffn {Scheme Procedure} hash-table-keys table
4983 Answer an unordered list of the keys in @var{table}.
4986 @deffn {Scheme Procedure} hash-table-values table
4987 Answer an unordered list of the values in @var{table}.
4990 @deffn {Scheme Procedure} hash-table-walk table proc
4991 Invoke @var{proc} once for each association in @var{table}, passing
4992 the key and value as arguments.
4995 @deffn {Scheme Procedure} hash-table-fold table proc init
4996 Invoke @code{(@var{proc} @var{key} @var{value} @var{previous})} for
4997 each @var{key} and @var{value} in @var{table}, where @var{previous} is
4998 the result of the previous invocation, using @var{init} as the first
4999 @var{previous} value. Answer the final @var{proc} result.
5002 @deffn {Scheme Procedure} hash-table->alist table
5003 Answer an alist where each association in @var{table} is an
5004 association in the result.
5007 @node SRFI-69 Hash table algorithms
5008 @subsubsection Hash table algorithms
5010 Each hash table carries an @dfn{equivalence function} and a @dfn{hash
5011 function}, used to implement key lookups. Beginning users should
5012 follow the rules for consistency of the default @var{hash-proc}
5013 specified above. Advanced users can use these to implement their own
5014 equivalence and hash functions for specialized lookup semantics.
5016 @deffn {Scheme Procedure} hash-table-equivalence-function hash-table
5017 @deffnx {Scheme Procedure} hash-table-hash-function hash-table
5018 Answer the equivalence and hash function of @var{hash-table}, respectively.
5021 @deffn {Scheme Procedure} hash obj [size]
5022 @deffnx {Scheme Procedure} string-hash obj [size]
5023 @deffnx {Scheme Procedure} string-ci-hash obj [size]
5024 @deffnx {Scheme Procedure} hash-by-identity obj [size]
5025 Answer a hash value appropriate for equality predicate @code{equal?},
5026 @code{string=?}, @code{string-ci=?}, and @code{eq?}, respectively.
5029 @code{hash} is a backwards-compatible replacement for Guile's built-in
5033 @subsection SRFI-88 Keyword Objects
5035 @cindex keyword objects
5037 @uref{http://srfi.schemers.org/srfi-88/srfi-88.html, SRFI-88} provides
5038 @dfn{keyword objects}, which are equivalent to Guile's keywords
5039 (@pxref{Keywords}). SRFI-88 keywords can be entered using the
5040 @dfn{postfix keyword syntax}, which consists of an identifier followed
5041 by @code{:} (@pxref{Scheme Read, @code{postfix} keyword syntax}).
5042 SRFI-88 can be made available with:
5045 (use-modules (srfi srfi-88))
5048 Doing so installs the right reader option for keyword syntax, using
5049 @code{(read-set! keywords 'postfix)}. It also provides the procedures
5052 @deffn {Scheme Procedure} keyword? obj
5053 Return @code{#t} if @var{obj} is a keyword. This is the same procedure
5054 as the same-named built-in procedure (@pxref{Keyword Procedures,
5058 (keyword? foo:) @result{} #t
5059 (keyword? 'foo:) @result{} #t
5060 (keyword? "foo") @result{} #f
5064 @deffn {Scheme Procedure} keyword->string kw
5065 Return the name of @var{kw} as a string, i.e., without the trailing
5066 colon. The returned string may not be modified, e.g., with
5070 (keyword->string foo:) @result{} "foo"
5074 @deffn {Scheme Procedure} string->keyword str
5075 Return the keyword object whose name is @var{str}.
5078 (keyword->string (string->keyword "a b c")) @result{} "a b c"
5083 @subsection SRFI-98 Accessing environment variables.
5085 @cindex environment variables
5087 This is a portable wrapper around Guile's built-in support for
5088 interacting with the current environment, @xref{Runtime Environment}.
5090 @deffn {Scheme Procedure} get-environment-variable name
5091 Returns a string containing the value of the environment variable
5092 given by the string @code{name}, or @code{#f} if the named
5093 environment variable is not found. This is equivalent to
5094 @code{(getenv name)}.
5097 @deffn {Scheme Procedure} get-environment-variables
5098 Returns the names and values of all the environment variables as an
5099 association list in which both the keys and the values are strings.
5103 @subsection SRFI-105 Curly-infix expressions.
5106 @cindex curly-infix-and-bracket-lists
5108 Guile's built-in reader includes support for SRFI-105 curly-infix
5109 expressions. See @uref{http://srfi.schemers.org/srfi-105/srfi-105.html,
5110 the specification of SRFI-105}. Some examples:
5113 @{n <= 5@} @result{} (<= n 5)
5114 @{a + b + c@} @result{} (+ a b c)
5115 @{a * @{b + c@}@} @result{} (* a (+ b c))
5116 @{(- a) / b@} @result{} (/ (- a) b)
5117 @{-(a) / b@} @result{} (/ (- a) b) as well
5118 @{(f a b) + (g h)@} @result{} (+ (f a b) (g h))
5119 @{f(a b) + g(h)@} @result{} (+ (f a b) (g h)) as well
5120 @{f[a b] + g(h)@} @result{} (+ ($bracket-apply$ f a b) (g h))
5121 '@{a + f(b) + x@} @result{} '(+ a (f b) x)
5122 @{length(x) >= 6@} @result{} (>= (length x) 6)
5123 @{n-1 + n-2@} @result{} (+ n-1 n-2)
5124 @{n * factorial@{n - 1@}@} @result{} (* n (factorial (- n 1)))
5125 @{@{a > 0@} and @{b >= 1@}@} @result{} (and (> a 0) (>= b 1))
5126 @{f@{n - 1@}(x)@} @result{} ((f (- n 1)) x)
5127 @{a . z@} @result{} ($nfx$ a . z)
5128 @{a + b - c@} @result{} ($nfx$ a + b - c)
5131 To enable curly-infix expressions within a file, place the reader
5132 directive @code{#!curly-infix} before the first use of curly-infix
5133 notation. To globally enable curly-infix expressions in Guile's reader,
5134 set the @code{curly-infix} read option.
5136 Guile also implements the following non-standard extension to SRFI-105:
5137 if @code{curly-infix} is enabled and there is no other meaning assigned
5138 to square brackets (i.e. the @code{square-brackets} read option is
5139 turned off), then lists within square brackets are read as normal lists
5140 but with the special symbol @code{$bracket-list$} added to the front.
5141 To enable this combination of read options within a file, use the reader
5142 directive @code{#!curly-infix-and-bracket-lists}. For example:
5145 [a b] @result{} ($bracket-list$ a b)
5146 [a . b] @result{} ($bracket-list$ a . b)
5150 For more information on reader options, @xref{Scheme Read}.
5152 @c srfi-modules.texi ends here
5155 @c TeX-master: "guile.texi"