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
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-26:: Specializing parameters
39 * SRFI-27:: Sources of Random Bits
40 * SRFI-30:: Nested multi-line block comments
41 * SRFI-31:: A special form `rec' for recursive evaluation
42 * SRFI-34:: Exception handling.
43 * SRFI-35:: Conditions.
44 * SRFI-37:: args-fold program argument processor
45 * SRFI-38:: External Representation for Data With Shared Structure
46 * SRFI-39:: Parameter objects
47 * SRFI-42:: Eager comprehensions
48 * SRFI-45:: Primitives for expressing iterative lazy algorithms
49 * SRFI-55:: Requiring Features.
50 * SRFI-60:: Integers as bits.
51 * SRFI-61:: A more general `cond' clause
52 * SRFI-67:: Compare procedures
53 * SRFI-69:: Basic hash tables.
54 * SRFI-88:: Keyword objects.
55 * SRFI-98:: Accessing environment variables.
59 @node About SRFI Usage
60 @subsection About SRFI Usage
62 @c FIXME::martin: Review me!
64 SRFI support in Guile is currently implemented partly in the core
65 library, and partly as add-on modules. That means that some SRFIs are
66 automatically available when the interpreter is started, whereas the
67 other SRFIs require you to use the appropriate support module
70 There are several reasons for this inconsistency. First, the feature
71 checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
72 available immediately, because it must be there when the user wants to
73 check for the Scheme implementation, that is, before she can know that
74 it is safe to use @code{use-modules} to load SRFI support modules. The
75 second reason is that some features defined in SRFIs had been
76 implemented in Guile before the developers started to add SRFI
77 implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In
78 the future, it is possible that SRFIs in the core library might be
79 factored out into separate modules, requiring explicit module loading
80 when they are needed. So you should be prepared to have to use
81 @code{use-modules} someday in the future to access SRFI-6 bindings. If
82 you want, you can do that already. We have included the module
83 @code{(srfi srfi-6)} in the distribution, which currently does nothing,
84 but ensures that you can write future-safe code.
86 Generally, support for a specific SRFI is made available by using
87 modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
88 number of the SRFI needed. Another possibility is to use the command
89 line option @code{--use-srfi}, which will load the necessary modules
90 automatically (@pxref{Invoking Guile}).
94 @subsection SRFI-0 - cond-expand
97 This SRFI lets a portable Scheme program test for the presence of
98 certain features, and adapt itself by using different blocks of code,
99 or fail if the necessary features are not available. There's no
100 module to load, this is in the Guile core.
102 A program designed only for Guile will generally not need this
103 mechanism, such a program can of course directly use the various
104 documented parts of Guile.
106 @deffn syntax cond-expand (feature body@dots{}) @dots{}
107 Expand to the @var{body} of the first clause whose @var{feature}
108 specification is satisfied. It is an error if no @var{feature} is
111 Features are symbols such as @code{srfi-1}, and a feature
112 specification can use @code{and}, @code{or} and @code{not} forms to
113 test combinations. The last clause can be an @code{else}, to be used
116 For example, define a private version of @code{alist-cons} if SRFI-1
123 (define (alist-cons key val alist)
124 (cons (cons key val) alist))))
127 Or demand a certain set of SRFIs (list operations, string ports,
128 @code{receive} and string operations), failing if they're not
132 (cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13)
138 The Guile core has the following features,
142 guile-2 ;; starting from Guile 2.x
151 Other SRFI feature symbols are defined once their code has been loaded
152 with @code{use-modules}, since only then are their bindings available.
154 The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is
155 a good way to load SRFIs to satisfy @code{cond-expand} when running a
158 Testing the @code{guile} feature allows a program to adapt itself to
159 the Guile module system, but still run on other Scheme systems. For
160 example the following demands SRFI-8 (@code{receive}), but also knows
161 how to load it with the Guile mechanism.
167 (use-modules (srfi srfi-8))))
170 @cindex @code{guile-2} SRFI-0 feature
171 @cindex portability between 2.0 and older versions
172 Likewise, testing the @code{guile-2} feature allows code to be portable
173 between Guile 2.0 and previous versions of Guile. For instance, it
174 makes it possible to write code that accounts for Guile 2.0's compiler,
175 yet be correctly interpreted on 1.8 and earlier versions:
178 (cond-expand (guile-2 (eval-when (compile)
179 ;; This must be evaluated at compile time.
180 (fluid-set! current-reader my-reader)))
182 ;; Earlier versions of Guile do not have a
183 ;; separate compilation phase.
184 (fluid-set! current-reader my-reader)))
187 It should be noted that @code{cond-expand} is separate from the
188 @code{*features*} mechanism (@pxref{Feature Tracking}), feature
189 symbols in one are unrelated to those in the other.
193 @subsection SRFI-1 - List library
197 @c FIXME::martin: Review me!
199 The list library defined in SRFI-1 contains a lot of useful list
200 processing procedures for construction, examining, destructuring and
201 manipulating lists and pairs.
203 Since SRFI-1 also defines some procedures which are already contained
204 in R5RS and thus are supported by the Guile core library, some list
205 and pair procedures which appear in the SRFI-1 document may not appear
206 in this section. So when looking for a particular list/pair
207 processing procedure, you should also have a look at the sections
208 @ref{Lists} and @ref{Pairs}.
211 * SRFI-1 Constructors:: Constructing new lists.
212 * SRFI-1 Predicates:: Testing list for specific properties.
213 * SRFI-1 Selectors:: Selecting elements from lists.
214 * SRFI-1 Length Append etc:: Length calculation and list appending.
215 * SRFI-1 Fold and Map:: Higher-order list processing.
216 * SRFI-1 Filtering and Partitioning:: Filter lists based on predicates.
217 * SRFI-1 Searching:: Search for elements.
218 * SRFI-1 Deleting:: Delete elements from lists.
219 * SRFI-1 Association Lists:: Handle association lists.
220 * SRFI-1 Set Operations:: Use lists for representing sets.
223 @node SRFI-1 Constructors
224 @subsubsection Constructors
225 @cindex list constructor
227 @c FIXME::martin: Review me!
229 New lists can be constructed by calling one of the following
232 @deffn {Scheme Procedure} xcons d a
233 Like @code{cons}, but with interchanged arguments. Useful mostly when
234 passed to higher-order procedures.
237 @deffn {Scheme Procedure} list-tabulate n init-proc
238 Return an @var{n}-element list, where each list element is produced by
239 applying the procedure @var{init-proc} to the corresponding list
240 index. The order in which @var{init-proc} is applied to the indices
244 @deffn {Scheme Procedure} list-copy lst
245 Return a new list containing the elements of the list @var{lst}.
247 This function differs from the core @code{list-copy} (@pxref{List
248 Constructors}) in accepting improper lists too. And if @var{lst} is
249 not a pair at all then it's treated as the final tail of an improper
250 list and simply returned.
253 @deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
254 Return a circular list containing the given arguments @var{elt1}
258 @deffn {Scheme Procedure} iota count [start step]
259 Return a list containing @var{count} numbers, starting from
260 @var{start} and adding @var{step} each time. The default @var{start}
261 is 0, the default @var{step} is 1. For example,
264 (iota 6) @result{} (0 1 2 3 4 5)
265 (iota 4 2.5 -2) @result{} (2.5 0.5 -1.5 -3.5)
268 This function takes its name from the corresponding primitive in the
273 @node SRFI-1 Predicates
274 @subsubsection Predicates
275 @cindex list predicate
277 @c FIXME::martin: Review me!
279 The procedures in this section test specific properties of lists.
281 @deffn {Scheme Procedure} proper-list? obj
282 Return @code{#t} if @var{obj} is a proper list, or @code{#f}
283 otherwise. This is the same as the core @code{list?} (@pxref{List
286 A proper list is a list which ends with the empty list @code{()} in
287 the usual way. The empty list @code{()} itself is a proper list too.
290 (proper-list? '(1 2 3)) @result{} #t
291 (proper-list? '()) @result{} #t
295 @deffn {Scheme Procedure} circular-list? obj
296 Return @code{#t} if @var{obj} is a circular list, or @code{#f}
299 A circular list is a list where at some point the @code{cdr} refers
300 back to a previous pair in the list (either the start or some later
301 point), so that following the @code{cdr}s takes you around in a
305 (define x (list 1 2 3 4))
306 (set-cdr! (last-pair x) (cddr x))
307 x @result{} (1 2 3 4 3 4 3 4 ...)
308 (circular-list? x) @result{} #t
312 @deffn {Scheme Procedure} dotted-list? obj
313 Return @code{#t} if @var{obj} is a dotted list, or @code{#f}
316 A dotted list is a list where the @code{cdr} of the last pair is not
317 the empty list @code{()}. Any non-pair @var{obj} is also considered a
318 dotted list, with length zero.
321 (dotted-list? '(1 2 . 3)) @result{} #t
322 (dotted-list? 99) @result{} #t
326 It will be noted that any Scheme object passes exactly one of the
327 above three tests @code{proper-list?}, @code{circular-list?} and
328 @code{dotted-list?}. Non-lists are @code{dotted-list?}, finite lists
329 are either @code{proper-list?} or @code{dotted-list?}, and infinite
330 lists are @code{circular-list?}.
333 @deffn {Scheme Procedure} null-list? lst
334 Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
335 otherwise. If something else than a proper or circular list is passed
336 as @var{lst}, an error is signalled. This procedure is recommended
337 for checking for the end of a list in contexts where dotted lists are
341 @deffn {Scheme Procedure} not-pair? obj
342 Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
343 This is shorthand notation @code{(not (pair? @var{obj}))} and is
344 supposed to be used for end-of-list checking in contexts where dotted
348 @deffn {Scheme Procedure} list= elt= list1 @dots{}
349 Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
350 List equality is determined by testing whether all lists have the same
351 length and the corresponding elements are equal in the sense of the
352 equality predicate @var{elt=}. If no or only one list is given,
353 @code{#t} is returned.
357 @node SRFI-1 Selectors
358 @subsubsection Selectors
359 @cindex list selector
361 @c FIXME::martin: Review me!
363 @deffn {Scheme Procedure} first pair
364 @deffnx {Scheme Procedure} second pair
365 @deffnx {Scheme Procedure} third pair
366 @deffnx {Scheme Procedure} fourth pair
367 @deffnx {Scheme Procedure} fifth pair
368 @deffnx {Scheme Procedure} sixth pair
369 @deffnx {Scheme Procedure} seventh pair
370 @deffnx {Scheme Procedure} eighth pair
371 @deffnx {Scheme Procedure} ninth pair
372 @deffnx {Scheme Procedure} tenth pair
373 These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
376 @deffn {Scheme Procedure} car+cdr pair
377 Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
380 @deffn {Scheme Procedure} take lst i
381 @deffnx {Scheme Procedure} take! lst i
382 Return a list containing the first @var{i} elements of @var{lst}.
384 @code{take!} may modify the structure of the argument list @var{lst}
385 in order to produce the result.
388 @deffn {Scheme Procedure} drop lst i
389 Return a list containing all but the first @var{i} elements of
393 @deffn {Scheme Procedure} take-right lst i
394 Return a list containing the @var{i} last elements of @var{lst}.
395 The return shares a common tail with @var{lst}.
398 @deffn {Scheme Procedure} drop-right lst i
399 @deffnx {Scheme Procedure} drop-right! lst i
400 Return a list containing all but the @var{i} last elements of
403 @code{drop-right} always returns a new list, even when @var{i} is
404 zero. @code{drop-right!} may modify the structure of the argument
405 list @var{lst} in order to produce the result.
408 @deffn {Scheme Procedure} split-at lst i
409 @deffnx {Scheme Procedure} split-at! lst i
410 Return two values, a list containing the first @var{i} elements of the
411 list @var{lst} and a list containing the remaining elements.
413 @code{split-at!} may modify the structure of the argument list
414 @var{lst} in order to produce the result.
417 @deffn {Scheme Procedure} last lst
418 Return the last element of the non-empty, finite list @var{lst}.
422 @node SRFI-1 Length Append etc
423 @subsubsection Length, Append, Concatenate, etc.
425 @c FIXME::martin: Review me!
427 @deffn {Scheme Procedure} length+ lst
428 Return the length of the argument list @var{lst}. When @var{lst} is a
429 circular list, @code{#f} is returned.
432 @deffn {Scheme Procedure} concatenate list-of-lists
433 @deffnx {Scheme Procedure} concatenate! list-of-lists
434 Construct a list by appending all lists in @var{list-of-lists}.
436 @code{concatenate!} may modify the structure of the given lists in
437 order to produce the result.
439 @code{concatenate} is the same as @code{(apply append
440 @var{list-of-lists})}. It exists because some Scheme implementations
441 have a limit on the number of arguments a function takes, which the
442 @code{apply} might exceed. In Guile there is no such limit.
445 @deffn {Scheme Procedure} append-reverse rev-head tail
446 @deffnx {Scheme Procedure} append-reverse! rev-head tail
447 Reverse @var{rev-head}, append @var{tail} to it, and return the
448 result. This is equivalent to @code{(append (reverse @var{rev-head})
449 @var{tail})}, but its implementation is more efficient.
452 (append-reverse '(1 2 3) '(4 5 6)) @result{} (3 2 1 4 5 6)
455 @code{append-reverse!} may modify @var{rev-head} in order to produce
459 @deffn {Scheme Procedure} zip lst1 lst2 @dots{}
460 Return a list as long as the shortest of the argument lists, where
461 each element is a list. The first list contains the first elements of
462 the argument lists, the second list contains the second elements, and
466 @deffn {Scheme Procedure} unzip1 lst
467 @deffnx {Scheme Procedure} unzip2 lst
468 @deffnx {Scheme Procedure} unzip3 lst
469 @deffnx {Scheme Procedure} unzip4 lst
470 @deffnx {Scheme Procedure} unzip5 lst
471 @code{unzip1} takes a list of lists, and returns a list containing the
472 first elements of each list, @code{unzip2} returns two lists, the
473 first containing the first elements of each lists and the second
474 containing the second elements of each lists, and so on.
477 @deffn {Scheme Procedure} count pred lst1 @dots{} lstN
478 Return a count of the number of times @var{pred} returns true when
479 called on elements from the given lists.
481 @var{pred} is called with @var{N} parameters @code{(@var{pred}
482 @var{elem1} @dots{} @var{elemN})}, each element being from the
483 corresponding @var{lst1} @dots{} @var{lstN}. The first call is with
484 the first element of each list, the second with the second element
485 from each, and so on.
487 Counting stops when the end of the shortest list is reached. At least
488 one list must be non-circular.
492 @node SRFI-1 Fold and Map
493 @subsubsection Fold, Unfold & Map
497 @c FIXME::martin: Review me!
499 @deffn {Scheme Procedure} fold proc init lst1 @dots{} lstN
500 @deffnx {Scheme Procedure} fold-right proc init lst1 @dots{} lstN
501 Apply @var{proc} to the elements of @var{lst1} @dots{} @var{lstN} to
502 build a result, and return that result.
504 Each @var{proc} call is @code{(@var{proc} @var{elem1} @dots{}
505 @var{elemN} @var{previous})}, where @var{elem1} is from @var{lst1},
506 through @var{elemN} from @var{lstN}. @var{previous} is the return
507 from the previous call to @var{proc}, or the given @var{init} for the
508 first call. If any list is empty, just @var{init} is returned.
510 @code{fold} works through the list elements from first to last. The
511 following shows a list reversal and the calls it makes,
514 (fold cons '() '(1 2 3))
522 @code{fold-right} works through the list elements from last to first,
523 ie.@: from the right. So for example the following finds the longest
524 string, and the last among equal longest,
527 (fold-right (lambda (str prev)
528 (if (> (string-length str) (string-length prev))
532 '("x" "abc" "xyz" "jk"))
536 If @var{lst1} through @var{lstN} have different lengths, @code{fold}
537 stops when the end of the shortest is reached; @code{fold-right}
538 commences at the last element of the shortest. Ie.@: elements past
539 the length of the shortest are ignored in the other @var{lst}s. At
540 least one @var{lst} must be non-circular.
542 @code{fold} should be preferred over @code{fold-right} if the order of
543 processing doesn't matter, or can be arranged either way, since
544 @code{fold} is a little more efficient.
546 The way @code{fold} builds a result from iterating is quite general,
547 it can do more than other iterations like say @code{map} or
548 @code{filter}. The following for example removes adjacent duplicate
549 elements from a list,
552 (define (delete-adjacent-duplicates lst)
553 (fold-right (lambda (elem ret)
554 (if (equal? elem (first ret))
559 (delete-adjacent-duplicates '(1 2 3 3 4 4 4 5))
560 @result{} (1 2 3 4 5)
563 Clearly the same sort of thing can be done with a @code{for-each} and
564 a variable in which to build the result, but a self-contained
565 @var{proc} can be re-used in multiple contexts, where a
566 @code{for-each} would have to be written out each time.
569 @deffn {Scheme Procedure} pair-fold proc init lst1 @dots{} lstN
570 @deffnx {Scheme Procedure} pair-fold-right proc init lst1 @dots{} lstN
571 The same as @code{fold} and @code{fold-right}, but apply @var{proc} to
572 the pairs of the lists instead of the list elements.
575 @deffn {Scheme Procedure} reduce proc default lst
576 @deffnx {Scheme Procedure} reduce-right proc default lst
577 @code{reduce} is a variant of @code{fold}, where the first call to
578 @var{proc} is on two elements from @var{lst}, rather than one element
579 and a given initial value.
581 If @var{lst} is empty, @code{reduce} returns @var{default} (this is
582 the only use for @var{default}). If @var{lst} has just one element
583 then that's the return value. Otherwise @var{proc} is called on the
584 elements of @var{lst}.
586 Each @var{proc} call is @code{(@var{proc} @var{elem} @var{previous})},
587 where @var{elem} is from @var{lst} (the second and subsequent elements
588 of @var{lst}), and @var{previous} is the return from the previous call
589 to @var{proc}. The first element of @var{lst} is the @var{previous}
590 for the first call to @var{proc}.
592 For example, the following adds a list of numbers, the calls made to
593 @code{+} are shown. (Of course @code{+} accepts multiple arguments
594 and can add a list directly, with @code{apply}.)
597 (reduce + 0 '(5 6 7)) @result{} 18
600 (+ 7 11) @result{} 18
603 @code{reduce} can be used instead of @code{fold} where the @var{init}
604 value is an ``identity'', meaning a value which under @var{proc}
605 doesn't change the result, in this case 0 is an identity since
606 @code{(+ 5 0)} is just 5. @code{reduce} avoids that unnecessary call.
608 @code{reduce-right} is a similar variation on @code{fold-right},
609 working from the end (ie.@: the right) of @var{lst}. The last element
610 of @var{lst} is the @var{previous} for the first call to @var{proc},
611 and the @var{elem} values go from the second last.
613 @code{reduce} should be preferred over @code{reduce-right} if the
614 order of processing doesn't matter, or can be arranged either way,
615 since @code{reduce} is a little more efficient.
618 @deffn {Scheme Procedure} unfold p f g seed [tail-gen]
619 @code{unfold} is defined as follows:
622 (unfold p f g seed) =
623 (if (p seed) (tail-gen seed)
625 (unfold p f g (g seed))))
630 Determines when to stop unfolding.
633 Maps each seed value to the corresponding list element.
636 Maps each seed value to next seed value.
639 The state value for the unfold.
642 Creates the tail of the list; defaults to @code{(lambda (x) '())}.
645 @var{g} produces a series of seed values, which are mapped to list
646 elements by @var{f}. These elements are put into a list in
647 left-to-right order, and @var{p} tells when to stop unfolding.
650 @deffn {Scheme Procedure} unfold-right p f g seed [tail]
651 Construct a list with the following loop.
654 (let lp ((seed seed) (lis tail))
657 (cons (f seed) lis))))
662 Determines when to stop unfolding.
665 Maps each seed value to the corresponding list element.
668 Maps each seed value to next seed value.
671 The state value for the unfold.
674 Creates the tail of the list; defaults to @code{(lambda (x) '())}.
679 @deffn {Scheme Procedure} map f lst1 lst2 @dots{}
680 Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
681 return a list containing the results of the procedure applications.
682 This procedure is extended with respect to R5RS, because the argument
683 lists may have different lengths. The result list will have the same
684 length as the shortest argument lists. The order in which @var{f}
685 will be applied to the list element(s) is not specified.
688 @deffn {Scheme Procedure} for-each f lst1 lst2 @dots{}
689 Apply the procedure @var{f} to each pair of corresponding elements of
690 the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not
691 specified. This procedure is extended with respect to R5RS, because
692 the argument lists may have different lengths. The shortest argument
693 list determines the number of times @var{f} is called. @var{f} will
694 be applied to the list elements in left-to-right order.
698 @deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
699 @deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
703 (apply append (map f clist1 clist2 ...))
709 (apply append! (map f clist1 clist2 ...))
712 Map @var{f} over the elements of the lists, just as in the @code{map}
713 function. However, the results of the applications are appended
714 together to make the final result. @code{append-map} uses
715 @code{append} to append the results together; @code{append-map!} uses
718 The dynamic order in which the various applications of @var{f} are
719 made is not specified.
722 @deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
723 Linear-update variant of @code{map} -- @code{map!} is allowed, but not
724 required, to alter the cons cells of @var{lst1} to construct the
727 The dynamic order in which the various applications of @var{f} are
728 made is not specified. In the n-ary case, @var{lst2}, @var{lst3},
729 @dots{} must have at least as many elements as @var{lst1}.
732 @deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{}
733 Like @code{for-each}, but applies the procedure @var{f} to the pairs
734 from which the argument lists are constructed, instead of the list
735 elements. The return value is not specified.
738 @deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
739 Like @code{map}, but only results from the applications of @var{f}
740 which are true are saved in the result list.
744 @node SRFI-1 Filtering and Partitioning
745 @subsubsection Filtering and Partitioning
747 @cindex list partition
749 @c FIXME::martin: Review me!
751 Filtering means to collect all elements from a list which satisfy a
752 specific condition. Partitioning a list means to make two groups of
753 list elements, one which contains the elements satisfying a condition,
754 and the other for the elements which don't.
756 The @code{filter} and @code{filter!} functions are implemented in the
757 Guile core, @xref{List Modification}.
759 @deffn {Scheme Procedure} partition pred lst
760 @deffnx {Scheme Procedure} partition! pred lst
761 Split @var{lst} into those elements which do and don't satisfy the
762 predicate @var{pred}.
764 The return is two values (@pxref{Multiple Values}), the first being a
765 list of all elements from @var{lst} which satisfy @var{pred}, the
766 second a list of those which do not.
768 The elements in the result lists are in the same order as in @var{lst}
769 but the order in which the calls @code{(@var{pred} elem)} are made on
770 the list elements is unspecified.
772 @code{partition} does not change @var{lst}, but one of the returned
773 lists may share a tail with it. @code{partition!} may modify
774 @var{lst} to construct its return.
777 @deffn {Scheme Procedure} remove pred lst
778 @deffnx {Scheme Procedure} remove! pred lst
779 Return a list containing all elements from @var{lst} which do not
780 satisfy the predicate @var{pred}. The elements in the result list
781 have the same order as in @var{lst}. The order in which @var{pred} is
782 applied to the list elements is not specified.
784 @code{remove!} is allowed, but not required to modify the structure of
789 @node SRFI-1 Searching
790 @subsubsection Searching
793 @c FIXME::martin: Review me!
795 The procedures for searching elements in lists either accept a
796 predicate or a comparison object for determining which elements are to
799 @deffn {Scheme Procedure} find pred lst
800 Return the first element of @var{lst} which satisfies the predicate
801 @var{pred} and @code{#f} if no such element is found.
804 @deffn {Scheme Procedure} find-tail pred lst
805 Return the first pair of @var{lst} whose @sc{car} satisfies the
806 predicate @var{pred} and @code{#f} if no such element is found.
809 @deffn {Scheme Procedure} take-while pred lst
810 @deffnx {Scheme Procedure} take-while! pred lst
811 Return the longest initial prefix of @var{lst} whose elements all
812 satisfy the predicate @var{pred}.
814 @code{take-while!} is allowed, but not required to modify the input
815 list while producing the result.
818 @deffn {Scheme Procedure} drop-while pred lst
819 Drop the longest initial prefix of @var{lst} whose elements all
820 satisfy the predicate @var{pred}.
823 @deffn {Scheme Procedure} span pred lst
824 @deffnx {Scheme Procedure} span! pred lst
825 @deffnx {Scheme Procedure} break pred lst
826 @deffnx {Scheme Procedure} break! pred lst
827 @code{span} splits the list @var{lst} into the longest initial prefix
828 whose elements all satisfy the predicate @var{pred}, and the remaining
829 tail. @code{break} inverts the sense of the predicate.
831 @code{span!} and @code{break!} are allowed, but not required to modify
832 the structure of the input list @var{lst} in order to produce the
835 Note that the name @code{break} conflicts with the @code{break}
836 binding established by @code{while} (@pxref{while do}). Applications
837 wanting to use @code{break} from within a @code{while} loop will need
838 to make a new define under a different name.
841 @deffn {Scheme Procedure} any pred lst1 lst2 @dots{} lstN
842 Test whether any set of elements from @var{lst1} @dots{} lstN
843 satisfies @var{pred}. If so the return value is the return from the
844 successful @var{pred} call, or if not the return is @code{#f}.
846 Each @var{pred} call is @code{(@var{pred} @var{elem1} @dots{}
847 @var{elemN})} taking an element from each @var{lst}. The calls are
848 made successively for the first, second, etc elements of the lists,
849 stopping when @var{pred} returns non-@code{#f}, or when the end of the
850 shortest list is reached.
852 The @var{pred} call on the last set of elements (ie.@: when the end of
853 the shortest list has been reached), if that point is reached, is a
857 @deffn {Scheme Procedure} every pred lst1 lst2 @dots{} lstN
858 Test whether every set of elements from @var{lst1} @dots{} lstN
859 satisfies @var{pred}. If so the return value is the return from the
860 final @var{pred} call, or if not the return is @code{#f}.
862 Each @var{pred} call is @code{(@var{pred} @var{elem1} @dots{}
863 @var{elemN})} taking an element from each @var{lst}. The calls are
864 made successively for the first, second, etc elements of the lists,
865 stopping if @var{pred} returns @code{#f}, or when the end of any of
866 the lists is reached.
868 The @var{pred} call on the last set of elements (ie.@: when the end of
869 the shortest list has been reached) is a tail call.
871 If one of @var{lst1} @dots{} @var{lstN} is empty then no calls to
872 @var{pred} are made, and the return is @code{#t}.
875 @deffn {Scheme Procedure} list-index pred lst1 @dots{} lstN
876 Return the index of the first set of elements, one from each of
877 @var{lst1}@dots{}@var{lstN}, which satisfies @var{pred}.
879 @var{pred} is called as @code{(@var{pred} elem1 @dots{} elemN)}.
880 Searching stops when the end of the shortest @var{lst} is reached.
881 The return index starts from 0 for the first set of elements. If no
882 set of elements pass then the return is @code{#f}.
885 (list-index odd? '(2 4 6 9)) @result{} 3
886 (list-index = '(1 2 3) '(3 1 2)) @result{} #f
890 @deffn {Scheme Procedure} member x lst [=]
891 Return the first sublist of @var{lst} whose @sc{car} is equal to
892 @var{x}. If @var{x} does not appear in @var{lst}, return @code{#f}.
894 Equality is determined by @code{equal?}, or by the equality predicate
895 @var{=} if given. @var{=} is called @code{(= @var{x} elem)},
896 ie.@: with the given @var{x} first, so for example to find the first
897 element greater than 5,
900 (member 5 '(3 5 1 7 2 9) <) @result{} (7 2 9)
903 This version of @code{member} extends the core @code{member}
904 (@pxref{List Searching}) by accepting an equality predicate.
908 @node SRFI-1 Deleting
909 @subsubsection Deleting
912 @deffn {Scheme Procedure} delete x lst [=]
913 @deffnx {Scheme Procedure} delete! x lst [=]
914 Return a list containing the elements of @var{lst} but with those
915 equal to @var{x} deleted. The returned elements will be in the same
916 order as they were in @var{lst}.
918 Equality is determined by the @var{=} predicate, or @code{equal?} if
919 not given. An equality call is made just once for each element, but
920 the order in which the calls are made on the elements is unspecified.
922 The equality calls are always @code{(= x elem)}, ie.@: the given @var{x}
923 is first. This means for instance elements greater than 5 can be
924 deleted with @code{(delete 5 lst <)}.
926 @code{delete} does not modify @var{lst}, but the return might share a
927 common tail with @var{lst}. @code{delete!} may modify the structure
928 of @var{lst} to construct its return.
930 These functions extend the core @code{delete} and @code{delete!}
931 (@pxref{List Modification}) in accepting an equality predicate. See
932 also @code{lset-difference} (@pxref{SRFI-1 Set Operations}) for
933 deleting multiple elements from a list.
936 @deffn {Scheme Procedure} delete-duplicates lst [=]
937 @deffnx {Scheme Procedure} delete-duplicates! lst [=]
938 Return a list containing the elements of @var{lst} but without
941 When elements are equal, only the first in @var{lst} is retained.
942 Equal elements can be anywhere in @var{lst}, they don't have to be
943 adjacent. The returned list will have the retained elements in the
944 same order as they were in @var{lst}.
946 Equality is determined by the @var{=} predicate, or @code{equal?} if
947 not given. Calls @code{(= x y)} are made with element @var{x} being
948 before @var{y} in @var{lst}. A call is made at most once for each
949 combination, but the sequence of the calls across the elements is
952 @code{delete-duplicates} does not modify @var{lst}, but the return
953 might share a common tail with @var{lst}. @code{delete-duplicates!}
954 may modify the structure of @var{lst} to construct its return.
956 In the worst case, this is an @math{O(N^2)} algorithm because it must
957 check each element against all those preceding it. For long lists it
958 is more efficient to sort and then compare only adjacent elements.
962 @node SRFI-1 Association Lists
963 @subsubsection Association Lists
964 @cindex association list
967 @c FIXME::martin: Review me!
969 Association lists are described in detail in section @ref{Association
970 Lists}. The present section only documents the additional procedures
971 for dealing with association lists defined by SRFI-1.
973 @deffn {Scheme Procedure} assoc key alist [=]
974 Return the pair from @var{alist} which matches @var{key}. This
975 extends the core @code{assoc} (@pxref{Retrieving Alist Entries}) by
976 taking an optional @var{=} comparison procedure.
978 The default comparison is @code{equal?}. If an @var{=} parameter is
979 given it's called @code{(@var{=} @var{key} @var{alistcar})}, i.e.@: the
980 given target @var{key} is the first argument, and a @code{car} from
981 @var{alist} is second.
983 For example a case-insensitive string lookup,
986 (assoc "yy" '(("XX" . 1) ("YY" . 2)) string-ci=?)
991 @deffn {Scheme Procedure} alist-cons key datum alist
992 Cons a new association @var{key} and @var{datum} onto @var{alist} and
993 return the result. This is equivalent to
996 (cons (cons @var{key} @var{datum}) @var{alist})
999 @code{acons} (@pxref{Adding or Setting Alist Entries}) in the Guile
1000 core does the same thing.
1003 @deffn {Scheme Procedure} alist-copy alist
1004 Return a newly allocated copy of @var{alist}, that means that the
1005 spine of the list as well as the pairs are copied.
1008 @deffn {Scheme Procedure} alist-delete key alist [=]
1009 @deffnx {Scheme Procedure} alist-delete! key alist [=]
1010 Return a list containing the elements of @var{alist} but with those
1011 elements whose keys are equal to @var{key} deleted. The returned
1012 elements will be in the same order as they were in @var{alist}.
1014 Equality is determined by the @var{=} predicate, or @code{equal?} if
1015 not given. The order in which elements are tested is unspecified, but
1016 each equality call is made @code{(= key alistkey)}, i.e.@: the given
1017 @var{key} parameter is first and the key from @var{alist} second.
1018 This means for instance all associations with a key greater than 5 can
1019 be removed with @code{(alist-delete 5 alist <)}.
1021 @code{alist-delete} does not modify @var{alist}, but the return might
1022 share a common tail with @var{alist}. @code{alist-delete!} may modify
1023 the list structure of @var{alist} to construct its return.
1027 @node SRFI-1 Set Operations
1028 @subsubsection Set Operations on Lists
1029 @cindex list set operation
1031 Lists can be used to represent sets of objects. The procedures in
1032 this section operate on such lists as sets.
1034 Note that lists are not an efficient way to implement large sets. The
1035 procedures here typically take time @math{@var{m}@cross{}@var{n}} when
1036 operating on @var{m} and @var{n} element lists. Other data structures
1037 like trees, bitsets (@pxref{Bit Vectors}) or hash tables (@pxref{Hash
1038 Tables}) are faster.
1040 All these procedures take an equality predicate as the first argument.
1041 This predicate is used for testing the objects in the list sets for
1042 sameness. This predicate must be consistent with @code{eq?}
1043 (@pxref{Equality}) in the sense that if two list elements are
1044 @code{eq?} then they must also be equal under the predicate. This
1045 simply means a given object must be equal to itself.
1047 @deffn {Scheme Procedure} lset<= = list1 list2 @dots{}
1048 Return @code{#t} if each list is a subset of the one following it.
1049 Ie.@: @var{list1} a subset of @var{list2}, @var{list2} a subset of
1050 @var{list3}, etc, for as many lists as given. If only one list or no
1051 lists are given then the return is @code{#t}.
1053 A list @var{x} is a subset of @var{y} if each element of @var{x} is
1054 equal to some element in @var{y}. Elements are compared using the
1055 given @var{=} procedure, called as @code{(@var{=} xelem yelem)}.
1058 (lset<= eq?) @result{} #t
1059 (lset<= eqv? '(1 2 3) '(1)) @result{} #f
1060 (lset<= eqv? '(1 3 2) '(4 3 1 2)) @result{} #t
1064 @deffn {Scheme Procedure} lset= = list1 list2 @dots{}
1065 Return @code{#t} if all argument lists are set-equal. @var{list1} is
1066 compared to @var{list2}, @var{list2} to @var{list3}, etc, for as many
1067 lists as given. If only one list or no lists are given then the
1068 return is @code{#t}.
1070 Two lists @var{x} and @var{y} are set-equal if each element of @var{x}
1071 is equal to some element of @var{y} and conversely each element of
1072 @var{y} is equal to some element of @var{x}. The order of the
1073 elements in the lists doesn't matter. Element equality is determined
1074 with the given @var{=} procedure, called as @code{(@var{=} xelem
1075 yelem)}, but exactly which calls are made is unspecified.
1078 (lset= eq?) @result{} #t
1079 (lset= eqv? '(1 2 3) '(3 2 1)) @result{} #t
1080 (lset= string-ci=? '("a" "A" "b") '("B" "b" "a")) @result{} #t
1084 @deffn {Scheme Procedure} lset-adjoin = list elem1 @dots{}
1085 Add to @var{list} any of the given @var{elem}s not already in the
1086 list. @var{elem}s are @code{cons}ed onto the start of @var{list} (so
1087 the return shares a common tail with @var{list}), but the order
1088 they're added is unspecified.
1090 The given @var{=} procedure is used for comparing elements, called as
1091 @code{(@var{=} listelem elem)}, ie.@: the second argument is one of
1092 the given @var{elem} parameters.
1095 (lset-adjoin eqv? '(1 2 3) 4 1 5) @result{} (5 4 1 2 3)
1099 @deffn {Scheme Procedure} lset-union = list1 list2 @dots{}
1100 @deffnx {Scheme Procedure} lset-union! = list1 list2 @dots{}
1101 Return the union of the argument list sets. The result is built by
1102 taking the union of @var{list1} and @var{list2}, then the union of
1103 that with @var{list3}, etc, for as many lists as given. For one list
1104 argument that list itself is the result, for no list arguments the
1105 result is the empty list.
1107 The union of two lists @var{x} and @var{y} is formed as follows. If
1108 @var{x} is empty then the result is @var{y}. Otherwise start with
1109 @var{x} as the result and consider each @var{y} element (from first to
1110 last). A @var{y} element not equal to something already in the result
1111 is @code{cons}ed onto the result.
1113 The given @var{=} procedure is used for comparing elements, called as
1114 @code{(@var{=} relem yelem)}. The first argument is from the result
1115 accumulated so far, and the second is from the list being union-ed in.
1116 But exactly which calls are made is otherwise unspecified.
1118 Notice that duplicate elements in @var{list1} (or the first non-empty
1119 list) are preserved, but that repeated elements in subsequent lists
1120 are only added once.
1123 (lset-union eqv?) @result{} ()
1124 (lset-union eqv? '(1 2 3)) @result{} (1 2 3)
1125 (lset-union eqv? '(1 2 1 3) '(2 4 5) '(5)) @result{} (5 4 1 2 1 3)
1128 @code{lset-union} doesn't change the given lists but the result may
1129 share a tail with the first non-empty list. @code{lset-union!} can
1130 modify all of the given lists to form the result.
1133 @deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{}
1134 @deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{}
1135 Return the intersection of @var{list1} with the other argument lists,
1136 meaning those elements of @var{list1} which are also in all of
1137 @var{list2} etc. For one list argument, just that list is returned.
1139 The test for an element of @var{list1} to be in the return is simply
1140 that it's equal to some element in each of @var{list2} etc. Notice
1141 this means an element appearing twice in @var{list1} but only once in
1142 each of @var{list2} etc will go into the return twice. The return has
1143 its elements in the same order as they were in @var{list1}.
1145 The given @var{=} procedure is used for comparing elements, called as
1146 @code{(@var{=} elem1 elemN)}. The first argument is from @var{list1}
1147 and the second is from one of the subsequent lists. But exactly which
1148 calls are made and in what order is unspecified.
1151 (lset-intersection eqv? '(x y)) @result{} (x y)
1152 (lset-intersection eqv? '(1 2 3) '(4 3 2)) @result{} (2 3)
1153 (lset-intersection eqv? '(1 1 2 2) '(1 2) '(2 1) '(2)) @result{} (2 2)
1156 The return from @code{lset-intersection} may share a tail with
1157 @var{list1}. @code{lset-intersection!} may modify @var{list1} to form
1161 @deffn {Scheme Procedure} lset-difference = list1 list2 @dots{}
1162 @deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{}
1163 Return @var{list1} with any elements in @var{list2}, @var{list3} etc
1164 removed (ie.@: subtracted). For one list argument, just that list is
1167 The given @var{=} procedure is used for comparing elements, called as
1168 @code{(@var{=} elem1 elemN)}. The first argument is from @var{list1}
1169 and the second from one of the subsequent lists. But exactly which
1170 calls are made and in what order is unspecified.
1173 (lset-difference eqv? '(x y)) @result{} (x y)
1174 (lset-difference eqv? '(1 2 3) '(3 1)) @result{} (2)
1175 (lset-difference eqv? '(1 2 3) '(3) '(2)) @result{} (1)
1178 The return from @code{lset-difference} may share a tail with
1179 @var{list1}. @code{lset-difference!} may modify @var{list1} to form
1183 @deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{}
1184 @deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{}
1185 Return two values (@pxref{Multiple Values}), the difference and
1186 intersection of the argument lists as per @code{lset-difference} and
1187 @code{lset-intersection} above.
1189 For two list arguments this partitions @var{list1} into those elements
1190 of @var{list1} which are in @var{list2} and not in @var{list2}. (But
1191 for more than two arguments there can be elements of @var{list1} which
1192 are neither part of the difference nor the intersection.)
1194 One of the return values from @code{lset-diff+intersection} may share
1195 a tail with @var{list1}. @code{lset-diff+intersection!} may modify
1196 @var{list1} to form its results.
1199 @deffn {Scheme Procedure} lset-xor = list1 list2 @dots{}
1200 @deffnx {Scheme Procedure} lset-xor! = list1 list2 @dots{}
1201 Return an XOR of the argument lists. For two lists this means those
1202 elements which are in exactly one of the lists. For more than two
1203 lists it means those elements which appear in an odd number of the
1206 To be precise, the XOR of two lists @var{x} and @var{y} is formed by
1207 taking those elements of @var{x} not equal to any element of @var{y},
1208 plus those elements of @var{y} not equal to any element of @var{x}.
1209 Equality is determined with the given @var{=} procedure, called as
1210 @code{(@var{=} e1 e2)}. One argument is from @var{x} and the other
1211 from @var{y}, but which way around is unspecified. Exactly which
1212 calls are made is also unspecified, as is the order of the elements in
1216 (lset-xor eqv? '(x y)) @result{} (x y)
1217 (lset-xor eqv? '(1 2 3) '(4 3 2)) @result{} (4 1)
1220 The return from @code{lset-xor} may share a tail with one of the list
1221 arguments. @code{lset-xor!} may modify @var{list1} to form its
1227 @subsection SRFI-2 - and-let*
1231 The following syntax can be obtained with
1234 (use-modules (srfi srfi-2))
1237 @deffn {library syntax} and-let* (clause @dots{}) body @dots{}
1238 A combination of @code{and} and @code{let*}.
1240 Each @var{clause} is evaluated in turn, and if @code{#f} is obtained
1241 then evaluation stops and @code{#f} is returned. If all are
1242 non-@code{#f} then @var{body} is evaluated and the last form gives the
1243 return value, or if @var{body} is empty then the result is @code{#t}.
1244 Each @var{clause} should be one of the following,
1248 Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}.
1249 Like @code{let*}, that binding is available to subsequent clauses.
1251 Evaluate @var{expr} and check for @code{#f}.
1253 Get the value bound to @var{symbol} and check for @code{#f}.
1256 Notice that @code{(expr)} has an ``extra'' pair of parentheses, for
1257 instance @code{((eq? x y))}. One way to remember this is to imagine
1258 the @code{symbol} in @code{(symbol expr)} is omitted.
1260 @code{and-let*} is good for calculations where a @code{#f} value means
1261 termination, but where a non-@code{#f} value is going to be needed in
1262 subsequent expressions.
1264 The following illustrates this, it returns text between brackets
1265 @samp{[...]} in a string, or @code{#f} if there are no such brackets
1266 (ie.@: either @code{string-index} gives @code{#f}).
1269 (define (extract-brackets str)
1270 (and-let* ((start (string-index str #\[))
1271 (end (string-index str #\] start)))
1272 (substring str (1+ start) end)))
1275 The following shows plain variables and expressions tested too.
1276 @code{diagnostic-levels} is taken to be an alist associating a
1277 diagnostic type with a level. @code{str} is printed only if the type
1278 is known and its level is high enough.
1281 (define (show-diagnostic type str)
1282 (and-let* (want-diagnostics
1283 (level (assq-ref diagnostic-levels type))
1284 ((>= level current-diagnostic-level)))
1288 The advantage of @code{and-let*} is that an extended sequence of
1289 expressions and tests doesn't require lots of nesting as would arise
1290 from separate @code{and} and @code{let*}, or from @code{cond} with
1297 @subsection SRFI-4 - Homogeneous numeric vector datatypes
1300 SRFI-4 provides an interface to uniform numeric vectors: vectors whose elements
1301 are all of a single numeric type. Guile offers uniform numeric vectors for
1302 signed and unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
1303 floating point values, and, as an extension to SRFI-4, complex floating-point
1304 numbers of these two sizes.
1306 The standard SRFI-4 procedures and data types may be included via loading the
1310 (use-modules (srfi srfi-4))
1313 This module is currently a part of the default Guile environment, but it is a
1314 good practice to explicitly import the module. In the future, using SRFI-4
1315 procedures without importing the SRFI-4 module will cause a deprecation message
1316 to be printed. (Of course, one may call the C functions at any time. Would that
1320 * SRFI-4 Overview:: The warp and weft of uniform numeric vectors.
1321 * SRFI-4 API:: Uniform vectors, from Scheme and from C.
1322 * SRFI-4 Generic Operations:: The general, operating on the specific.
1323 * SRFI-4 and Bytevectors:: SRFI-4 vectors are backed by bytevectors.
1324 * SRFI-4 Extensions:: Guile-specific extensions to the standard.
1327 @node SRFI-4 Overview
1328 @subsubsection SRFI-4 - Overview
1330 Uniform numeric vectors can be useful since they consume less memory
1331 than the non-uniform, general vectors. Also, since the types they can
1332 store correspond directly to C types, it is easier to work with them
1333 efficiently on a low level. Consider image processing as an example,
1334 where you want to apply a filter to some image. While you could store
1335 the pixels of an image in a general vector and write a general
1336 convolution function, things are much more efficient with uniform
1337 vectors: the convolution function knows that all pixels are unsigned
1338 8-bit values (say), and can use a very tight inner loop.
1340 This is implemented in Scheme by having the compiler notice calls to the SRFI-4
1341 accessors, and inline them to appropriate compiled code. From C you have access
1342 to the raw array; functions for efficiently working with uniform numeric vectors
1343 from C are listed at the end of this section.
1345 Uniform numeric vectors are the special case of one dimensional uniform
1348 There are 12 standard kinds of uniform numeric vectors, and they all have their
1349 own complement of constructors, accessors, and so on. Procedures that operate on
1350 a specific kind of uniform numeric vector have a ``tag'' in their name,
1351 indicating the element type.
1355 unsigned 8-bit integers
1358 signed 8-bit integers
1361 unsigned 16-bit integers
1364 signed 16-bit integers
1367 unsigned 32-bit integers
1370 signed 32-bit integers
1373 unsigned 64-bit integers
1376 signed 64-bit integers
1379 the C type @code{float}
1382 the C type @code{double}
1386 In addition, Guile supports uniform arrays of complex numbers, with the
1392 complex numbers in rectangular form with the real and imaginary part
1393 being a @code{float}
1396 complex numbers in rectangular form with the real and imaginary part
1397 being a @code{double}
1401 The external representation (ie.@: read syntax) for these vectors is
1402 similar to normal Scheme vectors, but with an additional tag from the
1403 tables above indicating the vector's type. For example,
1410 Note that the read syntax for floating-point here conflicts with
1411 @code{#f} for false. In Standard Scheme one can write @code{(1 #f3)}
1412 for a three element list @code{(1 #f 3)}, but for Guile @code{(1 #f3)}
1413 is invalid. @code{(1 #f 3)} is almost certainly what one should write
1414 anyway to make the intention clear, so this is rarely a problem.
1418 @subsubsection SRFI-4 - API
1420 Note that the @nicode{c32} and @nicode{c64} functions are only available from
1421 @nicode{(srfi srfi-4 gnu)}.
1423 @deffn {Scheme Procedure} u8vector? obj
1424 @deffnx {Scheme Procedure} s8vector? obj
1425 @deffnx {Scheme Procedure} u16vector? obj
1426 @deffnx {Scheme Procedure} s16vector? obj
1427 @deffnx {Scheme Procedure} u32vector? obj
1428 @deffnx {Scheme Procedure} s32vector? obj
1429 @deffnx {Scheme Procedure} u64vector? obj
1430 @deffnx {Scheme Procedure} s64vector? obj
1431 @deffnx {Scheme Procedure} f32vector? obj
1432 @deffnx {Scheme Procedure} f64vector? obj
1433 @deffnx {Scheme Procedure} c32vector? obj
1434 @deffnx {Scheme Procedure} c64vector? obj
1435 @deffnx {C Function} scm_u8vector_p (obj)
1436 @deffnx {C Function} scm_s8vector_p (obj)
1437 @deffnx {C Function} scm_u16vector_p (obj)
1438 @deffnx {C Function} scm_s16vector_p (obj)
1439 @deffnx {C Function} scm_u32vector_p (obj)
1440 @deffnx {C Function} scm_s32vector_p (obj)
1441 @deffnx {C Function} scm_u64vector_p (obj)
1442 @deffnx {C Function} scm_s64vector_p (obj)
1443 @deffnx {C Function} scm_f32vector_p (obj)
1444 @deffnx {C Function} scm_f64vector_p (obj)
1445 @deffnx {C Function} scm_c32vector_p (obj)
1446 @deffnx {C Function} scm_c64vector_p (obj)
1447 Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1451 @deffn {Scheme Procedure} make-u8vector n [value]
1452 @deffnx {Scheme Procedure} make-s8vector n [value]
1453 @deffnx {Scheme Procedure} make-u16vector n [value]
1454 @deffnx {Scheme Procedure} make-s16vector n [value]
1455 @deffnx {Scheme Procedure} make-u32vector n [value]
1456 @deffnx {Scheme Procedure} make-s32vector n [value]
1457 @deffnx {Scheme Procedure} make-u64vector n [value]
1458 @deffnx {Scheme Procedure} make-s64vector n [value]
1459 @deffnx {Scheme Procedure} make-f32vector n [value]
1460 @deffnx {Scheme Procedure} make-f64vector n [value]
1461 @deffnx {Scheme Procedure} make-c32vector n [value]
1462 @deffnx {Scheme Procedure} make-c64vector n [value]
1463 @deffnx {C Function} scm_make_u8vector n [value]
1464 @deffnx {C Function} scm_make_s8vector n [value]
1465 @deffnx {C Function} scm_make_u16vector n [value]
1466 @deffnx {C Function} scm_make_s16vector n [value]
1467 @deffnx {C Function} scm_make_u32vector n [value]
1468 @deffnx {C Function} scm_make_s32vector n [value]
1469 @deffnx {C Function} scm_make_u64vector n [value]
1470 @deffnx {C Function} scm_make_s64vector n [value]
1471 @deffnx {C Function} scm_make_f32vector n [value]
1472 @deffnx {C Function} scm_make_f64vector n [value]
1473 @deffnx {C Function} scm_make_c32vector n [value]
1474 @deffnx {C Function} scm_make_c64vector n [value]
1475 Return a newly allocated homogeneous numeric vector holding @var{n}
1476 elements of the indicated type. If @var{value} is given, the vector
1477 is initialized with that value, otherwise the contents are
1481 @deffn {Scheme Procedure} u8vector value @dots{}
1482 @deffnx {Scheme Procedure} s8vector value @dots{}
1483 @deffnx {Scheme Procedure} u16vector value @dots{}
1484 @deffnx {Scheme Procedure} s16vector value @dots{}
1485 @deffnx {Scheme Procedure} u32vector value @dots{}
1486 @deffnx {Scheme Procedure} s32vector value @dots{}
1487 @deffnx {Scheme Procedure} u64vector value @dots{}
1488 @deffnx {Scheme Procedure} s64vector value @dots{}
1489 @deffnx {Scheme Procedure} f32vector value @dots{}
1490 @deffnx {Scheme Procedure} f64vector value @dots{}
1491 @deffnx {Scheme Procedure} c32vector value @dots{}
1492 @deffnx {Scheme Procedure} c64vector value @dots{}
1493 @deffnx {C Function} scm_u8vector (values)
1494 @deffnx {C Function} scm_s8vector (values)
1495 @deffnx {C Function} scm_u16vector (values)
1496 @deffnx {C Function} scm_s16vector (values)
1497 @deffnx {C Function} scm_u32vector (values)
1498 @deffnx {C Function} scm_s32vector (values)
1499 @deffnx {C Function} scm_u64vector (values)
1500 @deffnx {C Function} scm_s64vector (values)
1501 @deffnx {C Function} scm_f32vector (values)
1502 @deffnx {C Function} scm_f64vector (values)
1503 @deffnx {C Function} scm_c32vector (values)
1504 @deffnx {C Function} scm_c64vector (values)
1505 Return a newly allocated homogeneous numeric vector of the indicated
1506 type, holding the given parameter @var{value}s. The vector length is
1507 the number of parameters given.
1510 @deffn {Scheme Procedure} u8vector-length vec
1511 @deffnx {Scheme Procedure} s8vector-length vec
1512 @deffnx {Scheme Procedure} u16vector-length vec
1513 @deffnx {Scheme Procedure} s16vector-length vec
1514 @deffnx {Scheme Procedure} u32vector-length vec
1515 @deffnx {Scheme Procedure} s32vector-length vec
1516 @deffnx {Scheme Procedure} u64vector-length vec
1517 @deffnx {Scheme Procedure} s64vector-length vec
1518 @deffnx {Scheme Procedure} f32vector-length vec
1519 @deffnx {Scheme Procedure} f64vector-length vec
1520 @deffnx {Scheme Procedure} c32vector-length vec
1521 @deffnx {Scheme Procedure} c64vector-length vec
1522 @deffnx {C Function} scm_u8vector_length (vec)
1523 @deffnx {C Function} scm_s8vector_length (vec)
1524 @deffnx {C Function} scm_u16vector_length (vec)
1525 @deffnx {C Function} scm_s16vector_length (vec)
1526 @deffnx {C Function} scm_u32vector_length (vec)
1527 @deffnx {C Function} scm_s32vector_length (vec)
1528 @deffnx {C Function} scm_u64vector_length (vec)
1529 @deffnx {C Function} scm_s64vector_length (vec)
1530 @deffnx {C Function} scm_f32vector_length (vec)
1531 @deffnx {C Function} scm_f64vector_length (vec)
1532 @deffnx {C Function} scm_c32vector_length (vec)
1533 @deffnx {C Function} scm_c64vector_length (vec)
1534 Return the number of elements in @var{vec}.
1537 @deffn {Scheme Procedure} u8vector-ref vec i
1538 @deffnx {Scheme Procedure} s8vector-ref vec i
1539 @deffnx {Scheme Procedure} u16vector-ref vec i
1540 @deffnx {Scheme Procedure} s16vector-ref vec i
1541 @deffnx {Scheme Procedure} u32vector-ref vec i
1542 @deffnx {Scheme Procedure} s32vector-ref vec i
1543 @deffnx {Scheme Procedure} u64vector-ref vec i
1544 @deffnx {Scheme Procedure} s64vector-ref vec i
1545 @deffnx {Scheme Procedure} f32vector-ref vec i
1546 @deffnx {Scheme Procedure} f64vector-ref vec i
1547 @deffnx {Scheme Procedure} c32vector-ref vec i
1548 @deffnx {Scheme Procedure} c64vector-ref vec i
1549 @deffnx {C Function} scm_u8vector_ref (vec i)
1550 @deffnx {C Function} scm_s8vector_ref (vec i)
1551 @deffnx {C Function} scm_u16vector_ref (vec i)
1552 @deffnx {C Function} scm_s16vector_ref (vec i)
1553 @deffnx {C Function} scm_u32vector_ref (vec i)
1554 @deffnx {C Function} scm_s32vector_ref (vec i)
1555 @deffnx {C Function} scm_u64vector_ref (vec i)
1556 @deffnx {C Function} scm_s64vector_ref (vec i)
1557 @deffnx {C Function} scm_f32vector_ref (vec i)
1558 @deffnx {C Function} scm_f64vector_ref (vec i)
1559 @deffnx {C Function} scm_c32vector_ref (vec i)
1560 @deffnx {C Function} scm_c64vector_ref (vec i)
1561 Return the element at index @var{i} in @var{vec}. The first element
1562 in @var{vec} is index 0.
1565 @deffn {Scheme Procedure} u8vector-set! vec i value
1566 @deffnx {Scheme Procedure} s8vector-set! vec i value
1567 @deffnx {Scheme Procedure} u16vector-set! vec i value
1568 @deffnx {Scheme Procedure} s16vector-set! vec i value
1569 @deffnx {Scheme Procedure} u32vector-set! vec i value
1570 @deffnx {Scheme Procedure} s32vector-set! vec i value
1571 @deffnx {Scheme Procedure} u64vector-set! vec i value
1572 @deffnx {Scheme Procedure} s64vector-set! vec i value
1573 @deffnx {Scheme Procedure} f32vector-set! vec i value
1574 @deffnx {Scheme Procedure} f64vector-set! vec i value
1575 @deffnx {Scheme Procedure} c32vector-set! vec i value
1576 @deffnx {Scheme Procedure} c64vector-set! vec i value
1577 @deffnx {C Function} scm_u8vector_set_x (vec i value)
1578 @deffnx {C Function} scm_s8vector_set_x (vec i value)
1579 @deffnx {C Function} scm_u16vector_set_x (vec i value)
1580 @deffnx {C Function} scm_s16vector_set_x (vec i value)
1581 @deffnx {C Function} scm_u32vector_set_x (vec i value)
1582 @deffnx {C Function} scm_s32vector_set_x (vec i value)
1583 @deffnx {C Function} scm_u64vector_set_x (vec i value)
1584 @deffnx {C Function} scm_s64vector_set_x (vec i value)
1585 @deffnx {C Function} scm_f32vector_set_x (vec i value)
1586 @deffnx {C Function} scm_f64vector_set_x (vec i value)
1587 @deffnx {C Function} scm_c32vector_set_x (vec i value)
1588 @deffnx {C Function} scm_c64vector_set_x (vec i value)
1589 Set the element at index @var{i} in @var{vec} to @var{value}. The
1590 first element in @var{vec} is index 0. The return value is
1594 @deffn {Scheme Procedure} u8vector->list vec
1595 @deffnx {Scheme Procedure} s8vector->list vec
1596 @deffnx {Scheme Procedure} u16vector->list vec
1597 @deffnx {Scheme Procedure} s16vector->list vec
1598 @deffnx {Scheme Procedure} u32vector->list vec
1599 @deffnx {Scheme Procedure} s32vector->list vec
1600 @deffnx {Scheme Procedure} u64vector->list vec
1601 @deffnx {Scheme Procedure} s64vector->list vec
1602 @deffnx {Scheme Procedure} f32vector->list vec
1603 @deffnx {Scheme Procedure} f64vector->list vec
1604 @deffnx {Scheme Procedure} c32vector->list vec
1605 @deffnx {Scheme Procedure} c64vector->list vec
1606 @deffnx {C Function} scm_u8vector_to_list (vec)
1607 @deffnx {C Function} scm_s8vector_to_list (vec)
1608 @deffnx {C Function} scm_u16vector_to_list (vec)
1609 @deffnx {C Function} scm_s16vector_to_list (vec)
1610 @deffnx {C Function} scm_u32vector_to_list (vec)
1611 @deffnx {C Function} scm_s32vector_to_list (vec)
1612 @deffnx {C Function} scm_u64vector_to_list (vec)
1613 @deffnx {C Function} scm_s64vector_to_list (vec)
1614 @deffnx {C Function} scm_f32vector_to_list (vec)
1615 @deffnx {C Function} scm_f64vector_to_list (vec)
1616 @deffnx {C Function} scm_c32vector_to_list (vec)
1617 @deffnx {C Function} scm_c64vector_to_list (vec)
1618 Return a newly allocated list holding all elements of @var{vec}.
1621 @deffn {Scheme Procedure} list->u8vector lst
1622 @deffnx {Scheme Procedure} list->s8vector lst
1623 @deffnx {Scheme Procedure} list->u16vector lst
1624 @deffnx {Scheme Procedure} list->s16vector lst
1625 @deffnx {Scheme Procedure} list->u32vector lst
1626 @deffnx {Scheme Procedure} list->s32vector lst
1627 @deffnx {Scheme Procedure} list->u64vector lst
1628 @deffnx {Scheme Procedure} list->s64vector lst
1629 @deffnx {Scheme Procedure} list->f32vector lst
1630 @deffnx {Scheme Procedure} list->f64vector lst
1631 @deffnx {Scheme Procedure} list->c32vector lst
1632 @deffnx {Scheme Procedure} list->c64vector lst
1633 @deffnx {C Function} scm_list_to_u8vector (lst)
1634 @deffnx {C Function} scm_list_to_s8vector (lst)
1635 @deffnx {C Function} scm_list_to_u16vector (lst)
1636 @deffnx {C Function} scm_list_to_s16vector (lst)
1637 @deffnx {C Function} scm_list_to_u32vector (lst)
1638 @deffnx {C Function} scm_list_to_s32vector (lst)
1639 @deffnx {C Function} scm_list_to_u64vector (lst)
1640 @deffnx {C Function} scm_list_to_s64vector (lst)
1641 @deffnx {C Function} scm_list_to_f32vector (lst)
1642 @deffnx {C Function} scm_list_to_f64vector (lst)
1643 @deffnx {C Function} scm_list_to_c32vector (lst)
1644 @deffnx {C Function} scm_list_to_c64vector (lst)
1645 Return a newly allocated homogeneous numeric vector of the indicated type,
1646 initialized with the elements of the list @var{lst}.
1649 @deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len)
1650 @deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len)
1651 @deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len)
1652 @deftypefnx {C Function} SCM scm_take_s16vector (const scm_t_int16 *data, size_t len)
1653 @deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len)
1654 @deftypefnx {C Function} SCM scm_take_s32vector (const scm_t_int32 *data, size_t len)
1655 @deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len)
1656 @deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len)
1657 @deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len)
1658 @deftypefnx {C Function} SCM scm_take_f64vector (const double *data, size_t len)
1659 @deftypefnx {C Function} SCM scm_take_c32vector (const float *data, size_t len)
1660 @deftypefnx {C Function} SCM scm_take_c64vector (const double *data, size_t len)
1661 Return a new uniform numeric vector of the indicated type and length
1662 that uses the memory pointed to by @var{data} to store its elements.
1663 This memory will eventually be freed with @code{free}. The argument
1664 @var{len} specifies the number of elements in @var{data}, not its size
1667 The @code{c32} and @code{c64} variants take a pointer to a C array of
1668 @code{float}s or @code{double}s. The real parts of the complex numbers
1669 are at even indices in that array, the corresponding imaginary parts are
1670 at the following odd index.
1673 @deftypefn {C Function} {const scm_t_uint8 *} scm_u8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1674 @deftypefnx {C Function} {const scm_t_int8 *} scm_s8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1675 @deftypefnx {C Function} {const scm_t_uint16 *} scm_u16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1676 @deftypefnx {C Function} {const scm_t_int16 *} scm_s16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1677 @deftypefnx {C Function} {const scm_t_uint32 *} scm_u32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1678 @deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1679 @deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1680 @deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1681 @deftypefnx {C Function} {const float *} scm_f32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1682 @deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1683 @deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1684 @deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1685 Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
1686 returns a pointer to the elements of a uniform numeric vector of the
1690 @deftypefn {C Function} {scm_t_uint8 *} scm_u8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1691 @deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1692 @deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1693 @deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1694 @deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1695 @deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1696 @deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1697 @deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1698 @deftypefnx {C Function} {float *} scm_f32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1699 @deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1700 @deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1701 @deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1702 Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from
1703 C}), but returns a pointer to the elements of a uniform numeric vector
1704 of the indicated kind.
1707 @node SRFI-4 Generic Operations
1708 @subsubsection SRFI-4 - Generic operations
1710 Guile also provides procedures that operate on all types of uniform numeric
1711 vectors. In what is probably a bug, these procedures are currently available in
1712 the default environment as well; however prudent hackers will make sure to
1713 import @code{(srfi srfi-4 gnu)} before using these.
1715 @deftypefn {C Function} int scm_is_uniform_vector (SCM uvec)
1716 Return non-zero when @var{uvec} is a uniform numeric vector, zero
1720 @deftypefn {C Function} size_t scm_c_uniform_vector_length (SCM uvec)
1721 Return the number of elements of @var{uvec} as a @code{size_t}.
1724 @deffn {Scheme Procedure} uniform-vector? obj
1725 @deffnx {C Function} scm_uniform_vector_p (obj)
1726 Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1730 @deffn {Scheme Procedure} uniform-vector-length vec
1731 @deffnx {C Function} scm_uniform_vector_length (vec)
1732 Return the number of elements in @var{vec}.
1735 @deffn {Scheme Procedure} uniform-vector-ref vec i
1736 @deffnx {C Function} scm_uniform_vector_ref (vec i)
1737 Return the element at index @var{i} in @var{vec}. The first element
1738 in @var{vec} is index 0.
1741 @deffn {Scheme Procedure} uniform-vector-set! vec i value
1742 @deffnx {C Function} scm_uniform_vector_set_x (vec i value)
1743 Set the element at index @var{i} in @var{vec} to @var{value}. The
1744 first element in @var{vec} is index 0. The return value is
1748 @deffn {Scheme Procedure} uniform-vector->list vec
1749 @deffnx {C Function} scm_uniform_vector_to_list (vec)
1750 Return a newly allocated list holding all elements of @var{vec}.
1753 @deftypefn {C Function} {const void *} scm_uniform_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1754 Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
1755 returns a pointer to the elements of a uniform numeric vector.
1758 @deftypefn {C Function} {void *} scm_uniform_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1759 Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from
1760 C}), but returns a pointer to the elements of a uniform numeric vector.
1763 Unless you really need to the limited generality of these functions, it is best
1764 to use the type-specific functions, or the generalized vector accessors.
1766 @node SRFI-4 and Bytevectors
1767 @subsubsection SRFI-4 - Relation to bytevectors
1769 Guile implements SRFI-4 vectors using bytevectors (@pxref{Bytevectors}). Often
1770 when you have a numeric vector, you end up wanting to write its bytes somewhere,
1771 or have access to the underlying bytes, or read in bytes from somewhere else.
1772 Bytevectors are very good at this sort of thing. But the SRFI-4 APIs are nicer
1773 to use when doing number-crunching, because they are addressed by element and
1776 So as a compromise, Guile allows all bytevector functions to operate on numeric
1777 vectors. They address the underlying bytes in the native endianness, as one
1780 Following the same reasoning, that it's just bytes underneath, Guile also allows
1781 uniform vectors of a given type to be accessed as if they were of any type. One
1782 can fill a @nicode{u32vector}, and access its elements with
1783 @nicode{u8vector-ref}. One can use @nicode{f64vector-ref} on bytevectors. It's
1784 all the same to Guile.
1786 In this way, uniform numeric vectors may be written to and read from
1787 input/output ports using the procedures that operate on bytevectors.
1789 @xref{Bytevectors}, for more information.
1792 @node SRFI-4 Extensions
1793 @subsubsection SRFI-4 - Guile extensions
1795 Guile defines some useful extensions to SRFI-4, which are not available in the
1796 default Guile environment. They may be imported by loading the extensions
1800 (use-modules (srfi srfi-4 gnu))
1803 @deffn {Scheme Procedure} any->u8vector obj
1804 @deffnx {Scheme Procedure} any->s8vector obj
1805 @deffnx {Scheme Procedure} any->u16vector obj
1806 @deffnx {Scheme Procedure} any->s16vector obj
1807 @deffnx {Scheme Procedure} any->u32vector obj
1808 @deffnx {Scheme Procedure} any->s32vector obj
1809 @deffnx {Scheme Procedure} any->u64vector obj
1810 @deffnx {Scheme Procedure} any->s64vector obj
1811 @deffnx {Scheme Procedure} any->f32vector obj
1812 @deffnx {Scheme Procedure} any->f64vector obj
1813 @deffnx {Scheme Procedure} any->c32vector obj
1814 @deffnx {Scheme Procedure} any->c64vector obj
1815 @deffnx {C Function} scm_any_to_u8vector (obj)
1816 @deffnx {C Function} scm_any_to_s8vector (obj)
1817 @deffnx {C Function} scm_any_to_u16vector (obj)
1818 @deffnx {C Function} scm_any_to_s16vector (obj)
1819 @deffnx {C Function} scm_any_to_u32vector (obj)
1820 @deffnx {C Function} scm_any_to_s32vector (obj)
1821 @deffnx {C Function} scm_any_to_u64vector (obj)
1822 @deffnx {C Function} scm_any_to_s64vector (obj)
1823 @deffnx {C Function} scm_any_to_f32vector (obj)
1824 @deffnx {C Function} scm_any_to_f64vector (obj)
1825 @deffnx {C Function} scm_any_to_c32vector (obj)
1826 @deffnx {C Function} scm_any_to_c64vector (obj)
1827 Return a (maybe newly allocated) uniform numeric vector of the indicated
1828 type, initialized with the elements of @var{obj}, which must be a list,
1829 a vector, or a uniform vector. When @var{obj} is already a suitable
1830 uniform numeric vector, it is returned unchanged.
1835 @subsection SRFI-6 - Basic String Ports
1838 SRFI-6 defines the procedures @code{open-input-string},
1839 @code{open-output-string} and @code{get-output-string}. These
1840 procedures are included in the Guile core, so using this module does not
1841 make any difference at the moment. But it is possible that support for
1842 SRFI-6 will be factored out of the core library in the future, so using
1843 this module does not hurt, after all.
1846 @subsection SRFI-8 - receive
1849 @code{receive} is a syntax for making the handling of multiple-value
1850 procedures easier. It is documented in @xref{Multiple Values}.
1854 @subsection SRFI-9 - define-record-type
1858 This SRFI is a syntax for defining new record types and creating
1859 predicate, constructor, and field getter and setter functions. In
1860 Guile this is simply an alternate interface to the core record
1861 functionality (@pxref{Records}). It can be used with,
1864 (use-modules (srfi srfi-9))
1867 @deffn {library syntax} define-record-type type @* (constructor fieldname @dots{}) @* predicate @* (fieldname accessor [modifier]) @dots{}
1869 Create a new record type, and make various @code{define}s for using
1870 it. This syntax can only occur at the top-level, not nested within
1873 @var{type} is bound to the record type, which is as per the return
1874 from the core @code{make-record-type}. @var{type} also provides the
1875 name for the record, as per @code{record-type-name}.
1877 @var{constructor} is bound to a function to be called as
1878 @code{(@var{constructor} fieldval @dots{})} to create a new record of
1879 this type. The arguments are initial values for the fields, one
1880 argument for each field, in the order they appear in the
1881 @code{define-record-type} form.
1883 The @var{fieldname}s provide the names for the record fields, as per
1884 the core @code{record-type-fields} etc, and are referred to in the
1885 subsequent accessor/modifier forms.
1887 @var{predicate} is bound to a function to be called as
1888 @code{(@var{predicate} obj)}. It returns @code{#t} or @code{#f}
1889 according to whether @var{obj} is a record of this type.
1891 Each @var{accessor} is bound to a function to be called
1892 @code{(@var{accessor} record)} to retrieve the respective field from a
1893 @var{record}. Similarly each @var{modifier} is bound to a function to
1894 be called @code{(@var{modifier} record val)} to set the respective
1895 field in a @var{record}.
1899 An example will illustrate typical usage,
1902 (define-record-type employee-type
1903 (make-employee name age salary)
1905 (name get-employee-name)
1906 (age get-employee-age set-employee-age)
1907 (salary get-employee-salary set-employee-salary))
1910 This creates a new employee data type, with name, age and salary
1911 fields. Accessor functions are created for each field, but no
1912 modifier function for the name (the intention in this example being
1913 that it's established only when an employee object is created). These
1914 can all then be used as for example,
1917 employee-type @result{} #<record-type employee-type>
1919 (define fred (make-employee "Fred" 45 20000.00))
1921 (employee? fred) @result{} #t
1922 (get-employee-age fred) @result{} 45
1923 (set-employee-salary fred 25000.00) ;; pay rise
1926 The functions created by @code{define-record-type} are ordinary
1927 top-level @code{define}s. They can be redefined or @code{set!} as
1928 desired, exported from a module, etc.
1930 @unnumberedsubsubsec Custom Printers
1932 You may use @code{set-record-type-printer!} to customize the default printing
1933 behavior of records. This is a Guile extension and is not part of SRFI-9. It
1934 is located in the @nicode{(srfi srfi-9 gnu)} module.
1936 @deffn {Scheme Syntax} set-record-type-printer! name thunk
1937 Where @var{type} corresponds to the first argument of @code{define-record-type},
1938 and @var{thunk} is a procedure accepting two arguments, the record to print, and
1943 This example prints the employee's name in brackets, for instance @code{[Fred]}.
1946 (set-record-type-printer! employee-type
1947 (lambda (record port)
1948 (write-char #\[ port)
1949 (display (get-employee-name record) port)
1950 (write-char #\] port)))
1954 @subsection SRFI-10 - Hash-Comma Reader Extension
1959 This SRFI implements a reader extension @code{#,()} called hash-comma.
1960 It allows the reader to give new kinds of objects, for use both in
1961 data and as constants or literals in source code. This feature is
1965 (use-modules (srfi srfi-10))
1969 The new read syntax is of the form
1972 #,(@var{tag} @var{arg}@dots{})
1976 where @var{tag} is a symbol and the @var{arg}s are objects taken as
1977 parameters. @var{tag}s are registered with the following procedure.
1979 @deffn {Scheme Procedure} define-reader-ctor tag proc
1980 Register @var{proc} as the constructor for a hash-comma read syntax
1981 starting with symbol @var{tag}, i.e.@: @nicode{#,(@var{tag} arg@dots{})}.
1982 @var{proc} is called with the given arguments @code{(@var{proc}
1983 arg@dots{})} and the object it returns is the result of the read.
1987 For example, a syntax giving a list of @var{N} copies of an object.
1990 (define-reader-ctor 'repeat
1992 (make-list reps obj)))
1994 (display '#,(repeat 99 3))
1998 Notice the quote @nicode{'} when the @nicode{#,( )} is used. The
1999 @code{repeat} handler returns a list and the program must quote to use
2000 it literally, the same as any other list. Ie.
2003 (display '#,(repeat 99 3))
2005 (display '(99 99 99))
2008 When a handler returns an object which is self-evaluating, like a
2009 number or a string, then there's no need for quoting, just as there's
2010 no need when giving those directly as literals. For example an
2014 (define-reader-ctor 'sum
2017 (display #,(sum 123 456)) @print{} 579
2020 A typical use for @nicode{#,()} is to get a read syntax for objects
2021 which don't otherwise have one. For example, the following allows a
2022 hash table to be given literally, with tags and values, ready for fast
2026 (define-reader-ctor 'hash
2028 (let ((table (make-hash-table)))
2029 (for-each (lambda (elem)
2030 (apply hash-set! table elem))
2034 (define (animal->family animal)
2035 (hash-ref '#,(hash ("tiger" "cat")
2040 (animal->family "lion") @result{} "cat"
2043 Or for example the following is a syntax for a compiled regular
2044 expression (@pxref{Regular Expressions}).
2047 (use-modules (ice-9 regex))
2049 (define-reader-ctor 'regexp make-regexp)
2051 (define (extract-angs str)
2052 (let ((match (regexp-exec '#,(regexp "<([A-Z0-9]+)>") str)))
2054 (match:substring match 1))))
2056 (extract-angs "foo <BAR> quux") @result{} "BAR"
2060 @nicode{#,()} is somewhat similar to @code{define-macro}
2061 (@pxref{Macros}) in that handler code is run to produce a result, but
2062 @nicode{#,()} operates at the read stage, so it can appear in data for
2063 @code{read} (@pxref{Scheme Read}), not just in code to be executed.
2065 Because @nicode{#,()} is handled at read-time it has no direct access
2066 to variables etc. A symbol in the arguments is just a symbol, not a
2067 variable reference. The arguments are essentially constants, though
2068 the handler procedure can use them in any complicated way it might
2071 Once @code{(srfi srfi-10)} has loaded, @nicode{#,()} is available
2072 globally, there's no need to use @code{(srfi srfi-10)} in later
2073 modules. Similarly the tags registered are global and can be used
2074 anywhere once registered.
2076 There's no attempt to record what previous @nicode{#,()} forms have
2077 been seen, if two identical forms occur then two calls are made to the
2078 handler procedure. The handler might like to maintain a cache or
2079 similar to avoid making copies of large objects, depending on expected
2082 In code the best uses of @nicode{#,()} are generally when there's a
2083 lot of objects of a particular kind as literals or constants. If
2084 there's just a few then some local variables and initializers are
2085 fine, but that becomes tedious and error prone when there's a lot, and
2086 the anonymous and compact syntax of @nicode{#,()} is much better.
2090 @subsection SRFI-11 - let-values
2095 This module implements the binding forms for multiple values
2096 @code{let-values} and @code{let*-values}. These forms are similar to
2097 @code{let} and @code{let*} (@pxref{Local Bindings}), but they support
2098 binding of the values returned by multiple-valued expressions.
2100 Write @code{(use-modules (srfi srfi-11))} to make the bindings
2104 (let-values (((x y) (values 1 2))
2105 ((z f) (values 3 4)))
2111 @code{let-values} performs all bindings simultaneously, which means that
2112 no expression in the binding clauses may refer to variables bound in the
2113 same clause list. @code{let*-values}, on the other hand, performs the
2114 bindings sequentially, just like @code{let*} does for single-valued
2119 @subsection SRFI-13 - String Library
2122 The SRFI-13 procedures are always available, @xref{Strings}.
2125 @subsection SRFI-14 - Character-set Library
2128 The SRFI-14 data type and procedures are always available,
2129 @xref{Character Sets}.
2132 @subsection SRFI-16 - case-lambda
2134 @cindex variable arity
2135 @cindex arity, variable
2137 SRFI-16 defines a variable-arity @code{lambda} form,
2138 @code{case-lambda}. This form is available in the default Guile
2139 environment. @xref{Case-lambda}, for more information.
2142 @subsection SRFI-17 - Generalized set!
2145 This SRFI implements a generalized @code{set!}, allowing some
2146 ``referencing'' functions to be used as the target location of a
2147 @code{set!}. This feature is available from
2150 (use-modules (srfi srfi-17))
2154 For example @code{vector-ref} is extended so that
2157 (set! (vector-ref vec idx) new-value)
2164 (vector-set! vec idx new-value)
2167 The idea is that a @code{vector-ref} expression identifies a location,
2168 which may be either fetched or stored. The same form is used for the
2169 location in both cases, encouraging visual clarity. This is similar
2170 to the idea of an ``lvalue'' in C.
2172 The mechanism for this kind of @code{set!} is in the Guile core
2173 (@pxref{Procedures with Setters}). This module adds definitions of
2174 the following functions as procedures with setters, allowing them to
2175 be targets of a @code{set!},
2178 @nicode{car}, @nicode{cdr}, @nicode{caar}, @nicode{cadr},
2179 @nicode{cdar}, @nicode{cddr}, @nicode{caaar}, @nicode{caadr},
2180 @nicode{cadar}, @nicode{caddr}, @nicode{cdaar}, @nicode{cdadr},
2181 @nicode{cddar}, @nicode{cdddr}, @nicode{caaaar}, @nicode{caaadr},
2182 @nicode{caadar}, @nicode{caaddr}, @nicode{cadaar}, @nicode{cadadr},
2183 @nicode{caddar}, @nicode{cadddr}, @nicode{cdaaar}, @nicode{cdaadr},
2184 @nicode{cdadar}, @nicode{cdaddr}, @nicode{cddaar}, @nicode{cddadr},
2185 @nicode{cdddar}, @nicode{cddddr}
2187 @nicode{string-ref}, @nicode{vector-ref}
2190 The SRFI specifies @code{setter} (@pxref{Procedures with Setters}) as
2191 a procedure with setter, allowing the setter for a procedure to be
2192 changed, eg.@: @code{(set! (setter foo) my-new-setter-handler)}.
2193 Currently Guile does not implement this, a setter can only be
2194 specified on creation (@code{getter-with-setter} below).
2196 @defun getter-with-setter
2197 The same as the Guile core @code{make-procedure-with-setter}
2198 (@pxref{Procedures with Setters}).
2203 @subsection SRFI-18 - Multithreading support
2206 This is an implementation of the SRFI-18 threading and synchronization
2207 library. The functions and variables described here are provided by
2210 (use-modules (srfi srfi-18))
2213 As a general rule, the data types and functions in this SRFI-18
2214 implementation are compatible with the types and functions in Guile's
2215 core threading code. For example, mutexes created with the SRFI-18
2216 @code{make-mutex} function can be passed to the built-in Guile
2217 function @code{lock-mutex} (@pxref{Mutexes and Condition Variables}),
2218 and mutexes created with the built-in Guile function @code{make-mutex}
2219 can be passed to the SRFI-18 function @code{mutex-lock!}. Cases in
2220 which this does not hold true are noted in the following sections.
2223 * SRFI-18 Threads:: Executing code
2224 * SRFI-18 Mutexes:: Mutual exclusion devices
2225 * SRFI-18 Condition variables:: Synchronizing of groups of threads
2226 * SRFI-18 Time:: Representation of times and durations
2227 * SRFI-18 Exceptions:: Signalling and handling errors
2230 @node SRFI-18 Threads
2231 @subsubsection SRFI-18 Threads
2233 Threads created by SRFI-18 differ in two ways from threads created by
2234 Guile's built-in thread functions. First, a thread created by SRFI-18
2235 @code{make-thread} begins in a blocked state and will not start
2236 execution until @code{thread-start!} is called on it. Second, SRFI-18
2237 threads are constructed with a top-level exception handler that
2238 captures any exceptions that are thrown on thread exit. In all other
2239 regards, SRFI-18 threads are identical to normal Guile threads.
2241 @defun current-thread
2242 Returns the thread that called this function. This is the same
2243 procedure as the same-named built-in procedure @code{current-thread}
2248 Returns @code{#t} if @var{obj} is a thread, @code{#f} otherwise. This
2249 is the same procedure as the same-named built-in procedure
2250 @code{thread?} (@pxref{Threads}).
2253 @defun make-thread thunk [name]
2254 Call @code{thunk} in a new thread and with a new dynamic state,
2255 returning the new thread and optionally assigning it the object name
2256 @var{name}, which may be any Scheme object.
2258 Note that the name @code{make-thread} conflicts with the
2259 @code{(ice-9 threads)} function @code{make-thread}. Applications
2260 wanting to use both of these functions will need to refer to them by
2264 @defun thread-name thread
2265 Returns the name assigned to @var{thread} at the time of its creation,
2266 or @code{#f} if it was not given a name.
2269 @defun thread-specific thread
2270 @defunx thread-specific-set! thread obj
2271 Get or set the ``object-specific'' property of @var{thread}. In
2272 Guile's implementation of SRFI-18, this value is stored as an object
2273 property, and will be @code{#f} if not set.
2276 @defun thread-start! thread
2277 Unblocks @var{thread} and allows it to begin execution if it has not
2281 @defun thread-yield!
2282 If one or more threads are waiting to execute, calling
2283 @code{thread-yield!} forces an immediate context switch to one of them.
2284 Otherwise, @code{thread-yield!} has no effect. @code{thread-yield!}
2285 behaves identically to the Guile built-in function @code{yield}.
2288 @defun thread-sleep! timeout
2289 The current thread waits until the point specified by the time object
2290 @var{timeout} is reached (@pxref{SRFI-18 Time}). This blocks the
2291 thread only if @var{timeout} represents a point in the future. it is
2292 an error for @var{timeout} to be @code{#f}.
2295 @defun thread-terminate! thread
2296 Causes an abnormal termination of @var{thread}. If @var{thread} is
2297 not already terminated, all mutexes owned by @var{thread} become
2298 unlocked/abandoned. If @var{thread} is the current thread,
2299 @code{thread-terminate!} does not return. Otherwise
2300 @code{thread-terminate!} returns an unspecified value; the termination
2301 of @var{thread} will occur before @code{thread-terminate!} returns.
2302 Subsequent attempts to join on @var{thread} will cause a ``terminated
2303 thread exception'' to be raised.
2305 @code{thread-terminate!} is compatible with the thread cancellation
2306 procedures in the core threads API (@pxref{Threads}) in that if a
2307 cleanup handler has been installed for the target thread, it will be
2308 called before the thread exits and its return value (or exception, if
2309 any) will be stored for later retrieval via a call to
2310 @code{thread-join!}.
2313 @defun thread-join! thread [timeout [timeout-val]]
2314 Wait for @var{thread} to terminate and return its exit value. When a
2315 time value @var{timeout} is given, it specifies a point in time where
2316 the waiting should be aborted. When the waiting is aborted,
2317 @var{timeoutval} is returned if it is specified; otherwise, a
2318 @code{join-timeout-exception} exception is raised
2319 (@pxref{SRFI-18 Exceptions}). Exceptions may also be raised if the
2320 thread was terminated by a call to @code{thread-terminate!}
2321 (@code{terminated-thread-exception} will be raised) or if the thread
2322 exited by raising an exception that was handled by the top-level
2323 exception handler (@code{uncaught-exception} will be raised; the
2324 original exception can be retrieved using
2325 @code{uncaught-exception-reason}).
2329 @node SRFI-18 Mutexes
2330 @subsubsection SRFI-18 Mutexes
2332 The behavior of Guile's built-in mutexes is parameterized via a set of
2333 flags passed to the @code{make-mutex} procedure in the core
2334 (@pxref{Mutexes and Condition Variables}). To satisfy the requirements
2335 for mutexes specified by SRFI-18, the @code{make-mutex} procedure
2336 described below sets the following flags:
2339 @code{recursive}: the mutex can be locked recursively
2341 @code{unchecked-unlock}: attempts to unlock a mutex that is already
2342 unlocked will not raise an exception
2344 @code{allow-external-unlock}: the mutex can be unlocked by any thread,
2345 not just the thread that locked it originally
2348 @defun make-mutex [name]
2349 Returns a new mutex, optionally assigning it the object name
2350 @var{name}, which may be any Scheme object. The returned mutex will be
2351 created with the configuration described above. Note that the name
2352 @code{make-mutex} conflicts with Guile core function @code{make-mutex}.
2353 Applications wanting to use both of these functions will need to refer
2354 to them by different names.
2357 @defun mutex-name mutex
2358 Returns the name assigned to @var{mutex} at the time of its creation,
2359 or @code{#f} if it was not given a name.
2362 @defun mutex-specific mutex
2363 @defunx mutex-specific-set! mutex obj
2364 Get or set the ``object-specific'' property of @var{mutex}. In Guile's
2365 implementation of SRFI-18, this value is stored as an object property,
2366 and will be @code{#f} if not set.
2369 @defun mutex-state mutex
2370 Returns information about the state of @var{mutex}. Possible values
2374 thread @code{T}: the mutex is in the locked/owned state and thread T
2375 is the owner of the mutex
2377 symbol @code{not-owned}: the mutex is in the locked/not-owned state
2379 symbol @code{abandoned}: the mutex is in the unlocked/abandoned state
2381 symbol @code{not-abandoned}: the mutex is in the
2382 unlocked/not-abandoned state
2386 @defun mutex-lock! mutex [timeout [thread]]
2387 Lock @var{mutex}, optionally specifying a time object @var{timeout}
2388 after which to abort the lock attempt and a thread @var{thread} giving
2389 a new owner for @var{mutex} different than the current thread. This
2390 procedure has the same behavior as the @code{lock-mutex} procedure in
2394 @defun mutex-unlock! mutex [condition-variable [timeout]]
2395 Unlock @var{mutex}, optionally specifying a condition variable
2396 @var{condition-variable} on which to wait, either indefinitely or,
2397 optionally, until the time object @var{timeout} has passed, to be
2398 signalled. This procedure has the same behavior as the
2399 @code{unlock-mutex} procedure in the core library.
2403 @node SRFI-18 Condition variables
2404 @subsubsection SRFI-18 Condition variables
2406 SRFI-18 does not specify a ``wait'' function for condition variables.
2407 Waiting on a condition variable can be simulated using the SRFI-18
2408 @code{mutex-unlock!} function described in the previous section, or
2409 Guile's built-in @code{wait-condition-variable} procedure can be used.
2411 @defun condition-variable? obj
2412 Returns @code{#t} if @var{obj} is a condition variable, @code{#f}
2413 otherwise. This is the same procedure as the same-named built-in
2415 (@pxref{Mutexes and Condition Variables, @code{condition-variable?}}).
2418 @defun make-condition-variable [name]
2419 Returns a new condition variable, optionally assigning it the object
2420 name @var{name}, which may be any Scheme object. This procedure
2421 replaces a procedure of the same name in the core library.
2424 @defun condition-variable-name condition-variable
2425 Returns the name assigned to @var{thread} at the time of its creation,
2426 or @code{#f} if it was not given a name.
2429 @defun condition-variable-specific condition-variable
2430 @defunx condition-variable-specific-set! condition-variable obj
2431 Get or set the ``object-specific'' property of
2432 @var{condition-variable}. In Guile's implementation of SRFI-18, this
2433 value is stored as an object property, and will be @code{#f} if not
2437 @defun condition-variable-signal! condition-variable
2438 @defunx condition-variable-broadcast! condition-variable
2439 Wake up one thread that is waiting for @var{condition-variable}, in
2440 the case of @code{condition-variable-signal!}, or all threads waiting
2441 for it, in the case of @code{condition-variable-broadcast!}. The
2442 behavior of these procedures is equivalent to that of the procedures
2443 @code{signal-condition-variable} and
2444 @code{broadcast-condition-variable} in the core library.
2449 @subsubsection SRFI-18 Time
2451 The SRFI-18 time functions manipulate time in two formats: a
2452 ``time object'' type that represents an absolute point in time in some
2453 implementation-specific way; and the number of seconds since some
2454 unspecified ``epoch''. In Guile's implementation, the epoch is the
2455 Unix epoch, 00:00:00 UTC, January 1, 1970.
2458 Return the current time as a time object. This procedure replaces
2459 the procedure of the same name in the core library, which returns the
2460 current time in seconds since the epoch.
2464 Returns @code{#t} if @var{obj} is a time object, @code{#f} otherwise.
2467 @defun time->seconds time
2468 @defunx seconds->time seconds
2469 Convert between time objects and numerical values representing the
2470 number of seconds since the epoch. When converting from a time object
2471 to seconds, the return value is the number of seconds between
2472 @var{time} and the epoch. When converting from seconds to a time
2473 object, the return value is a time object that represents a time
2474 @var{seconds} seconds after the epoch.
2478 @node SRFI-18 Exceptions
2479 @subsubsection SRFI-18 Exceptions
2481 SRFI-18 exceptions are identical to the exceptions provided by
2482 Guile's implementation of SRFI-34. The behavior of exception
2483 handlers invoked to handle exceptions thrown from SRFI-18 functions,
2484 however, differs from the conventional behavior of SRFI-34 in that
2485 the continuation of the handler is the same as that of the call to
2486 the function. Handlers are called in a tail-recursive manner; the
2487 exceptions do not ``bubble up''.
2489 @defun current-exception-handler
2490 Returns the current exception handler.
2493 @defun with-exception-handler handler thunk
2494 Installs @var{handler} as the current exception handler and calls the
2495 procedure @var{thunk} with no arguments, returning its value as the
2496 value of the exception. @var{handler} must be a procedure that accepts
2497 a single argument. The current exception handler at the time this
2498 procedure is called will be restored after the call returns.
2502 Raise @var{obj} as an exception. This is the same procedure as the
2503 same-named procedure defined in SRFI 34.
2506 @defun join-timeout-exception? obj
2507 Returns @code{#t} if @var{obj} is an exception raised as the result of
2508 performing a timed join on a thread that does not exit within the
2509 specified timeout, @code{#f} otherwise.
2512 @defun abandoned-mutex-exception? obj
2513 Returns @code{#t} if @var{obj} is an exception raised as the result of
2514 attempting to lock a mutex that has been abandoned by its owner thread,
2515 @code{#f} otherwise.
2518 @defun terminated-thread-exception? obj
2519 Returns @code{#t} if @var{obj} is an exception raised as the result of
2520 joining on a thread that exited as the result of a call to
2521 @code{thread-terminate!}.
2524 @defun uncaught-exception? obj
2525 @defunx uncaught-exception-reason exc
2526 @code{uncaught-exception?} returns @code{#t} if @var{obj} is an
2527 exception thrown as the result of joining a thread that exited by
2528 raising an exception that was handled by the top-level exception
2529 handler installed by @code{make-thread}. When this occurs, the
2530 original exception is preserved as part of the exception thrown by
2531 @code{thread-join!} and can be accessed by calling
2532 @code{uncaught-exception-reason} on that exception. Note that
2533 because this exception-preservation mechanism is a side-effect of
2534 @code{make-thread}, joining on threads that exited as described above
2535 but were created by other means will not raise this
2536 @code{uncaught-exception} error.
2541 @subsection SRFI-19 - Time/Date Library
2546 This is an implementation of the SRFI-19 time/date library. The
2547 functions and variables described here are provided by
2550 (use-modules (srfi srfi-19))
2553 @strong{Caution}: The current code in this module incorrectly extends
2554 the Gregorian calendar leap year rule back prior to the introduction
2555 of those reforms in 1582 (or the appropriate year in various
2556 countries). The Julian calendar was used prior to 1582, and there
2557 were 10 days skipped for the reform, but the code doesn't implement
2560 This will be fixed some time. Until then calculations for 1583
2561 onwards are correct, but prior to that any day/month/year and day of
2562 the week calculations are wrong.
2565 * SRFI-19 Introduction::
2568 * SRFI-19 Time/Date conversions::
2569 * SRFI-19 Date to string::
2570 * SRFI-19 String to date::
2573 @node SRFI-19 Introduction
2574 @subsubsection SRFI-19 Introduction
2576 @cindex universal time
2580 This module implements time and date representations and calculations,
2581 in various time systems, including universal time (UTC) and atomic
2584 For those not familiar with these time systems, TAI is based on a
2585 fixed length second derived from oscillations of certain atoms. UTC
2586 differs from TAI by an integral number of seconds, which is increased
2587 or decreased at announced times to keep UTC aligned to a mean solar
2588 day (the orbit and rotation of the earth are not quite constant).
2591 So far, only increases in the TAI
2598 UTC difference have been needed. Such an increase is a ``leap
2599 second'', an extra second of TAI introduced at the end of a UTC day.
2600 When working entirely within UTC this is never seen, every day simply
2601 has 86400 seconds. But when converting from TAI to a UTC date, an
2602 extra 23:59:60 is present, where normally a day would end at 23:59:59.
2603 Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI
2606 @cindex system clock
2607 In the current implementation, the system clock is assumed to be UTC,
2608 and a table of leap seconds in the code converts to TAI. See comments
2609 in @file{srfi-19.scm} for how to update this table.
2612 @cindex modified julian day
2613 Also, for those not familiar with the terminology, a @dfn{Julian Day}
2614 is a real number which is a count of days and fraction of a day, in
2615 UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan
2616 4713 B.C. A @dfn{Modified Julian Day} is the same, but starting from
2617 1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC. That time
2618 is julian day 2400000.5.
2620 @c The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at
2621 @c noon, UTC), but this is incorrect. It looks like it might have
2622 @c arisen from the code incorrectly treating years a multiple of 100
2623 @c but not 400 prior to 1582 as non-leap years, where instead the Julian
2624 @c calendar should be used so all multiples of 4 before 1582 are leap
2629 @subsubsection SRFI-19 Time
2632 A @dfn{time} object has type, seconds and nanoseconds fields
2633 representing a point in time starting from some epoch. This is an
2634 arbitrary point in time, not just a time of day. Although times are
2635 represented in nanoseconds, the actual resolution may be lower.
2637 The following variables hold the possible time types. For instance
2638 @code{(current-time time-process)} would give the current CPU process
2642 Universal Coordinated Time (UTC).
2647 International Atomic Time (TAI).
2651 @defvar time-monotonic
2652 Monotonic time, meaning a monotonically increasing time starting from
2653 an unspecified epoch.
2655 Note that in the current implementation @code{time-monotonic} is the
2656 same as @code{time-tai}, and unfortunately is therefore affected by
2657 adjustments to the system clock. Perhaps this will change in the
2661 @defvar time-duration
2662 A duration, meaning simply a difference between two times.
2665 @defvar time-process
2666 CPU time spent in the current process, starting from when the process
2668 @cindex process time
2672 CPU time spent in the current thread. Not currently implemented.
2678 Return @code{#t} if @var{obj} is a time object, or @code{#f} if not.
2681 @defun make-time type nanoseconds seconds
2682 Create a time object with the given @var{type}, @var{seconds} and
2686 @defun time-type time
2687 @defunx time-nanosecond time
2688 @defunx time-second time
2689 @defunx set-time-type! time type
2690 @defunx set-time-nanosecond! time nsec
2691 @defunx set-time-second! time sec
2692 Get or set the type, seconds or nanoseconds fields of a time object.
2694 @code{set-time-type!} merely changes the field, it doesn't convert the
2695 time value. For conversions, see @ref{SRFI-19 Time/Date conversions}.
2698 @defun copy-time time
2699 Return a new time object, which is a copy of the given @var{time}.
2702 @defun current-time [type]
2703 Return the current time of the given @var{type}. The default
2704 @var{type} is @code{time-utc}.
2706 Note that the name @code{current-time} conflicts with the Guile core
2707 @code{current-time} function (@pxref{Time}) as well as the SRFI-18
2708 @code{current-time} function (@pxref{SRFI-18 Time}). Applications
2709 wanting to use more than one of these functions will need to refer to
2710 them by different names.
2713 @defun time-resolution [type]
2714 Return the resolution, in nanoseconds, of the given time @var{type}.
2715 The default @var{type} is @code{time-utc}.
2718 @defun time<=? t1 t2
2719 @defunx time<? t1 t2
2720 @defunx time=? t1 t2
2721 @defunx time>=? t1 t2
2722 @defunx time>? t1 t2
2723 Return @code{#t} or @code{#f} according to the respective relation
2724 between time objects @var{t1} and @var{t2}. @var{t1} and @var{t2}
2725 must be the same time type.
2728 @defun time-difference t1 t2
2729 @defunx time-difference! t1 t2
2730 Return a time object of type @code{time-duration} representing the
2731 period between @var{t1} and @var{t2}. @var{t1} and @var{t2} must be
2734 @code{time-difference} returns a new time object,
2735 @code{time-difference!} may modify @var{t1} to form its return.
2738 @defun add-duration time duration
2739 @defunx add-duration! time duration
2740 @defunx subtract-duration time duration
2741 @defunx subtract-duration! time duration
2742 Return a time object which is @var{time} with the given @var{duration}
2743 added or subtracted. @var{duration} must be a time object of type
2744 @code{time-duration}.
2746 @code{add-duration} and @code{subtract-duration} return a new time
2747 object. @code{add-duration!} and @code{subtract-duration!} may modify
2748 the given @var{time} to form their return.
2753 @subsubsection SRFI-19 Date
2756 A @dfn{date} object represents a date in the Gregorian calendar and a
2757 time of day on that date in some timezone.
2759 The fields are year, month, day, hour, minute, second, nanoseconds and
2760 timezone. A date object is immutable, its fields can be read but they
2761 cannot be modified once the object is created.
2764 Return @code{#t} if @var{obj} is a date object, or @code{#f} if not.
2767 @defun make-date nsecs seconds minutes hours date month year zone-offset
2768 Create a new date object.
2770 @c FIXME: What can we say about the ranges of the values. The
2771 @c current code looks it doesn't normalize, but expects then in their
2772 @c usual range already.
2776 @defun date-nanosecond date
2777 Nanoseconds, 0 to 999999999.
2780 @defun date-second date
2781 Seconds, 0 to 59, or 60 for a leap second. 60 is never seen when working
2782 entirely within UTC, it's only when converting to or from TAI.
2785 @defun date-minute date
2789 @defun date-hour date
2793 @defun date-day date
2794 Day of the month, 1 to 31 (or less, according to the month).
2797 @defun date-month date
2801 @defun date-year date
2802 Year, eg.@: 2003. Dates B.C.@: are negative, eg.@: @math{-46} is 46
2803 B.C. There is no year 0, year @math{-1} is followed by year 1.
2806 @defun date-zone-offset date
2807 Time zone, an integer number of seconds east of Greenwich.
2810 @defun date-year-day date
2811 Day of the year, starting from 1 for 1st January.
2814 @defun date-week-day date
2815 Day of the week, starting from 0 for Sunday.
2818 @defun date-week-number date dstartw
2819 Week of the year, ignoring a first partial week. @var{dstartw} is the
2820 day of the week which is taken to start a week, 0 for Sunday, 1 for
2823 @c FIXME: The spec doesn't say whether numbering starts at 0 or 1.
2824 @c The code looks like it's 0, if that's the correct intention.
2828 @c The SRFI text doesn't actually give the default for tz-offset, but
2829 @c the reference implementation has the local timezone and the
2830 @c conversions functions all specify that, so it should be ok to
2831 @c document it here.
2833 @defun current-date [tz-offset]
2834 Return a date object representing the current date/time, in UTC offset
2835 by @var{tz-offset}. @var{tz-offset} is seconds east of Greenwich and
2836 defaults to the local timezone.
2839 @defun current-julian-day
2841 Return the current Julian Day.
2844 @defun current-modified-julian-day
2845 @cindex modified julian day
2846 Return the current Modified Julian Day.
2850 @node SRFI-19 Time/Date conversions
2851 @subsubsection SRFI-19 Time/Date conversions
2852 @cindex time conversion
2853 @cindex date conversion
2855 @defun date->julian-day date
2856 @defunx date->modified-julian-day date
2857 @defunx date->time-monotonic date
2858 @defunx date->time-tai date
2859 @defunx date->time-utc date
2861 @defun julian-day->date jdn [tz-offset]
2862 @defunx julian-day->time-monotonic jdn
2863 @defunx julian-day->time-tai jdn
2864 @defunx julian-day->time-utc jdn
2866 @defun modified-julian-day->date jdn [tz-offset]
2867 @defunx modified-julian-day->time-monotonic jdn
2868 @defunx modified-julian-day->time-tai jdn
2869 @defunx modified-julian-day->time-utc jdn
2871 @defun time-monotonic->date time [tz-offset]
2872 @defunx time-monotonic->time-tai time
2873 @defunx time-monotonic->time-tai! time
2874 @defunx time-monotonic->time-utc time
2875 @defunx time-monotonic->time-utc! time
2877 @defun time-tai->date time [tz-offset]
2878 @defunx time-tai->julian-day time
2879 @defunx time-tai->modified-julian-day time
2880 @defunx time-tai->time-monotonic time
2881 @defunx time-tai->time-monotonic! time
2882 @defunx time-tai->time-utc time
2883 @defunx time-tai->time-utc! time
2885 @defun time-utc->date time [tz-offset]
2886 @defunx time-utc->julian-day time
2887 @defunx time-utc->modified-julian-day time
2888 @defunx time-utc->time-monotonic time
2889 @defunx time-utc->time-monotonic! time
2890 @defunx time-utc->time-tai time
2891 @defunx time-utc->time-tai! time
2893 Convert between dates, times and days of the respective types. For
2894 instance @code{time-tai->time-utc} accepts a @var{time} object of type
2895 @code{time-tai} and returns an object of type @code{time-utc}.
2897 The @code{!} variants may modify their @var{time} argument to form
2898 their return. The plain functions create a new object.
2900 For conversions to dates, @var{tz-offset} is seconds east of
2901 Greenwich. The default is the local timezone, at the given time, as
2902 provided by the system, using @code{localtime} (@pxref{Time}).
2904 On 32-bit systems, @code{localtime} is limited to a 32-bit
2905 @code{time_t}, so a default @var{tz-offset} is only available for
2906 times between Dec 1901 and Jan 2038. For prior dates an application
2907 might like to use the value in 1902, though some locations have zone
2908 changes prior to that. For future dates an application might like to
2909 assume today's rules extend indefinitely. But for correct daylight
2910 savings transitions it will be necessary to take an offset for the
2911 same day and time but a year in range and which has the same starting
2912 weekday and same leap/non-leap (to support rules like last Sunday in
2916 @node SRFI-19 Date to string
2917 @subsubsection SRFI-19 Date to string
2918 @cindex date to string
2919 @cindex string, from date
2921 @defun date->string date [format]
2922 Convert a date to a string under the control of a format.
2923 @var{format} should be a string containing @samp{~} escapes, which
2924 will be expanded as per the following conversion table. The default
2925 @var{format} is @samp{~c}, a locale-dependent date and time.
2927 Many of these conversion characters are the same as POSIX
2928 @code{strftime} (@pxref{Time}), but there are some extras and some
2931 @multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM}
2932 @item @nicode{~~} @tab literal ~
2933 @item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun}
2934 @item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday}
2935 @item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan}
2936 @item @nicode{~B} @tab locale full month, eg.@: @samp{January}
2937 @item @nicode{~c} @tab locale date and time, eg.@: @*
2938 @samp{Fri Jul 14 20:28:42-0400 2000}
2939 @item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31}
2941 @c Spec says d/m/y, reference implementation says m/d/y.
2942 @c Apparently the reference code was the intention, but would like to
2943 @c see an errata published for the spec before contradicting it here.
2945 @c @item @nicode{~D} @tab date @nicode{~d/~m/~y}
2947 @item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31}
2948 @item @nicode{~f} @tab seconds and fractional seconds,
2949 with locale decimal point, eg.@: @samp{5.2}
2950 @item @nicode{~h} @tab same as @nicode{~b}
2951 @item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23}
2952 @item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12}
2953 @item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366}
2954 @item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23}
2955 @item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12}
2956 @item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12}
2957 @item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59}
2958 @item @nicode{~n} @tab newline
2959 @item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999}
2960 @item @nicode{~p} @tab locale AM or PM
2961 @item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p}
2962 @item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC
2963 @item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @*
2964 (usual limit is 59, 60 is a leap second)
2965 @item @nicode{~t} @tab horizontal tab character
2966 @item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S}
2967 @item @nicode{~U} @tab week of year, Sunday first day of week,
2968 @samp{00} to @samp{52}
2969 @item @nicode{~V} @tab week of year, Monday first day of week,
2970 @samp{01} to @samp{53}
2971 @item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6}
2972 @item @nicode{~W} @tab week of year, Monday first day of week,
2973 @samp{00} to @samp{52}
2975 @c The spec has ~x as an apparent duplicate of ~W, and ~X as a locale
2976 @c date. The reference code has ~x as the locale date and ~X as a
2977 @c locale time. The rule is apparently that the code should be
2978 @c believed, but would like to see an errata for the spec before
2979 @c contradicting it here.
2981 @c @item @nicode{~x} @tab week of year, Monday as first day of week,
2982 @c @samp{00} to @samp{53}
2983 @c @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00}
2985 @item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99}
2986 @item @nicode{~Y} @tab year, full, eg.@: @samp{2003}
2987 @item @nicode{~z} @tab time zone, RFC-822 style
2988 @item @nicode{~Z} @tab time zone symbol (not currently implemented)
2989 @item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d}
2990 @item @nicode{~2} @tab ISO-8601 time+zone, @samp{~k:~M:~S~z}
2991 @item @nicode{~3} @tab ISO-8601 time, @samp{~k:~M:~S}
2992 @item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~k:~M:~S~z}
2993 @item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~k:~M:~S}
2997 Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently
2998 described here, since the specification and reference implementation
3001 Conversion is locale-dependent on systems that support it
3002 (@pxref{Accessing Locale Information}). @xref{Locales,
3003 @code{setlocale}}, for information on how to change the current
3007 @node SRFI-19 String to date
3008 @subsubsection SRFI-19 String to date
3009 @cindex string to date
3010 @cindex date, from string
3012 @c FIXME: Can we say what happens when an incomplete date is
3013 @c converted? I.e. fields left as 0, or what? The spec seems to be
3016 @defun string->date input template
3017 Convert an @var{input} string to a date under the control of a
3018 @var{template} string. Return a newly created date object.
3020 Literal characters in @var{template} must match characters in
3021 @var{input} and @samp{~} escapes must match the input forms described
3022 in the table below. ``Skip to'' means characters up to one of the
3023 given type are ignored, or ``no skip'' for no skipping. ``Read'' is
3024 what's then read, and ``Set'' is the field affected in the date
3027 For example @samp{~Y} skips input characters until a digit is reached,
3028 at which point it expects a year and stores that to the year field of
3031 @multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}}
3043 @tab @nicode{char-alphabetic?}
3044 @tab locale abbreviated weekday name
3048 @tab @nicode{char-alphabetic?}
3049 @tab locale full weekday name
3052 @c Note that the SRFI spec says that ~b and ~B don't set anything,
3053 @c but that looks like a mistake. The reference implementation sets
3054 @c the month field, which seems sensible and is what we describe
3058 @tab @nicode{char-alphabetic?}
3059 @tab locale abbreviated month name
3060 @tab @nicode{date-month}
3063 @tab @nicode{char-alphabetic?}
3064 @tab locale full month name
3065 @tab @nicode{date-month}
3068 @tab @nicode{char-numeric?}
3070 @tab @nicode{date-day}
3074 @tab day of month, blank padded
3075 @tab @nicode{date-day}
3078 @tab same as @samp{~b}
3081 @tab @nicode{char-numeric?}
3083 @tab @nicode{date-hour}
3087 @tab hour, blank padded
3088 @tab @nicode{date-hour}
3091 @tab @nicode{char-numeric?}
3093 @tab @nicode{date-month}
3096 @tab @nicode{char-numeric?}
3098 @tab @nicode{date-minute}
3101 @tab @nicode{char-numeric?}
3103 @tab @nicode{date-second}
3108 @tab @nicode{date-year} within 50 years
3111 @tab @nicode{char-numeric?}
3113 @tab @nicode{date-year}
3118 @tab date-zone-offset
3121 Notice that the weekday matching forms don't affect the date object
3122 returned, instead the weekday will be derived from the day, month and
3125 Conversion is locale-dependent on systems that support it
3126 (@pxref{Accessing Locale Information}). @xref{Locales,
3127 @code{setlocale}}, for information on how to change the current
3133 @subsection SRFI-26 - specializing parameters
3135 @cindex parameter specialize
3136 @cindex argument specialize
3137 @cindex specialize parameter
3139 This SRFI provides a syntax for conveniently specializing selected
3140 parameters of a function. It can be used with,
3143 (use-modules (srfi srfi-26))
3146 @deffn {library syntax} cut slot @dots{}
3147 @deffnx {library syntax} cute slot @dots{}
3148 Return a new procedure which will make a call (@var{slot} @dots{}) but
3149 with selected parameters specialized to given expressions.
3151 An example will illustrate the idea. The following is a
3152 specialization of @code{write}, sending output to
3153 @code{my-output-port},
3156 (cut write <> my-output-port)
3158 (lambda (obj) (write obj my-output-port))
3161 The special symbol @code{<>} indicates a slot to be filled by an
3162 argument to the new procedure. @code{my-output-port} on the other
3163 hand is an expression to be evaluated and passed, ie.@: it specializes
3164 the behaviour of @code{write}.
3168 A slot to be filled by an argument from the created procedure.
3169 Arguments are assigned to @code{<>} slots in the order they appear in
3170 the @code{cut} form, there's no way to re-arrange arguments.
3172 The first argument to @code{cut} is usually a procedure (or expression
3173 giving a procedure), but @code{<>} is allowed there too. For example,
3178 (lambda (proc) (proc 1 2 3))
3182 A slot to be filled by all remaining arguments from the new procedure.
3183 This can only occur at the end of a @code{cut} form.
3185 For example, a procedure taking a variable number of arguments like
3186 @code{max} but in addition enforcing a lower bound,
3189 (define my-lower-bound 123)
3191 (cut max my-lower-bound <...>)
3193 (lambda arglist (apply max my-lower-bound arglist))
3197 For @code{cut} the specializing expressions are evaluated each time
3198 the new procedure is called. For @code{cute} they're evaluated just
3199 once, when the new procedure is created. The name @code{cute} stands
3200 for ``@code{cut} with evaluated arguments''. In all cases the
3201 evaluations take place in an unspecified order.
3203 The following illustrates the difference between @code{cut} and
3207 (cut format <> "the time is ~s" (current-time))
3209 (lambda (port) (format port "the time is ~s" (current-time)))
3211 (cute format <> "the time is ~s" (current-time))
3213 (let ((val (current-time)))
3214 (lambda (port) (format port "the time is ~s" val))
3217 (There's no provision for a mixture of @code{cut} and @code{cute}
3218 where some expressions would be evaluated every time but others
3219 evaluated only once.)
3221 @code{cut} is really just a shorthand for the sort of @code{lambda}
3222 forms shown in the above examples. But notice @code{cut} avoids the
3223 need to name unspecialized parameters, and is more compact. Use in
3224 functional programming style or just with @code{map}, @code{for-each}
3225 or similar is typical.
3228 (map (cut * 2 <>) '(1 2 3 4))
3230 (for-each (cut write <> my-port) my-list)
3235 @subsection SRFI-27 - Sources of Random Bits
3238 This subsection is based on the
3239 @uref{http://srfi.schemers.org/srfi-27/srfi-27.html, specification of
3240 SRFI-27} written by Sebastian Egner.
3242 @c The copyright notice and license text of the SRFI-27 specification is
3243 @c reproduced below:
3245 @c Copyright (C) Sebastian Egner (2002). All Rights Reserved.
3247 @c Permission is hereby granted, free of charge, to any person obtaining a
3248 @c copy of this software and associated documentation files (the
3249 @c "Software"), to deal in the Software without restriction, including
3250 @c without limitation the rights to use, copy, modify, merge, publish,
3251 @c distribute, sublicense, and/or sell copies of the Software, and to
3252 @c permit persons to whom the Software is furnished to do so, subject to
3253 @c the following conditions:
3255 @c The above copyright notice and this permission notice shall be included
3256 @c in all copies or substantial portions of the Software.
3258 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3259 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3260 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3261 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3262 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3263 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3264 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3266 This SRFI provides access to a (pseudo) random number generator; for
3267 Guile's built-in random number facilities, which SRFI-27 is implemented
3268 upon, @xref{Random}. With SRFI-27, random numbers are obtained from a
3269 @emph{random source}, which encapsulates a random number generation
3270 algorithm and its state.
3273 * SRFI-27 Default Random Source:: Obtaining random numbers
3274 * SRFI-27 Random Sources:: Creating and manipulating random sources
3275 * SRFI-27 Random Number Generators:: Obtaining random number generators
3278 @node SRFI-27 Default Random Source
3279 @subsubsection The Default Random Source
3282 @defun random-integer n
3283 Return a random number between zero (inclusive) and @var{n} (exclusive),
3284 using the default random source. The numbers returned have a uniform
3289 Return a random number in (0,1), using the default random source. The
3290 numbers returned have a uniform distribution.
3293 @defun default-random-source
3294 A random source from which @code{random-integer} and @code{random-real}
3295 have been derived using @code{random-source-make-integers} and
3296 @code{random-source-make-reals} (@pxref{SRFI-27 Random Number Generators}
3297 for those procedures). Note that an assignment to
3298 @code{default-random-source} does not change @code{random-integer} or
3299 @code{random-real}; it is also strongly recommended not to assign a new
3303 @node SRFI-27 Random Sources
3304 @subsubsection Random Sources
3307 @defun make-random-source
3308 Create a new random source. The stream of random numbers obtained from
3309 each random source created by this procedure will be identical, unless
3310 its state is changed by one of the procedures below.
3313 @defun random-source? object
3314 Tests whether @var{object} is a random source. Random sources are a
3318 @defun random-source-randomize! source
3319 Attempt to set the state of the random source to a truly random value.
3320 The current implementation uses a seed based on the current system time.
3323 @defun random-source-pseudo-randomize! source i j
3324 Changes the state of the random source s into the initial state of the
3325 (@var{i}, @var{j})-th independent random source, where @var{i} and
3326 @var{j} are non-negative integers. This procedure provides a mechanism
3327 to obtain a large number of independent random sources (usually all
3328 derived from the same backbone generator), indexed by two integers. In
3329 contrast to @code{random-source-randomize!}, this procedure is entirely
3333 The state associated with a random state can be obtained an reinstated
3334 with the following procedures:
3336 @defun random-source-state-ref source
3337 @defunx random-source-state-set! source state
3338 Get and set the state of a random source. No assumptions should be made
3339 about the nature of the state object, besides it having an external
3340 representation (i.e.@: it can be passed to @code{write} and subsequently
3344 @node SRFI-27 Random Number Generators
3345 @subsubsection Obtaining random number generator procedures
3348 @defun random-source-make-integers source
3349 Obtains a procedure to generate random integers using the random source
3350 @var{source}. The returned procedure takes a single argument @var{n},
3351 which must be a positive integer, and returns the next uniformly
3352 distributed random integer from the interval @{0, ..., @var{n}-1@} by
3353 advancing the state of @var{source}.
3355 If an application obtains and uses several generators for the same
3356 random source @var{source}, a call to any of these generators advances
3357 the state of @var{source}. Hence, the generators do not produce the
3358 same sequence of random integers each but rather share a state. This
3359 also holds for all other types of generators derived from a fixed random
3362 While the SRFI text specifies that ``Implementations that support
3363 concurrency make sure that the state of a generator is properly
3364 advanced'', this is currently not the case in Guile's implementation of
3365 SRFI-27, as it would cause a severe performance penalty. So in
3366 multi-threaded programs, you either must perform locking on random
3367 sources shared between threads yourself, or use different random sources
3368 for multiple threads.
3371 @defun random-source-make-reals source
3372 @defunx random-source-make-reals source unit
3373 Obtains a procedure to generate random real numbers @math{0 < x < 1}
3374 using the random source @var{source}. The procedure rand is called
3377 The optional parameter @var{unit} determines the type of numbers being
3378 produced by the returned procedure and the quantization of the output.
3379 @var{unit} must be a number such that @math{0 < @var{unit} < 1}. The
3380 numbers created by the returned procedure are of the same numerical type
3381 as @var{unit} and the potential output values are spaced by at most
3382 @var{unit}. One can imagine rand to create numbers as @var{x} *
3383 @var{unit} where @var{x} is a random integer in @{1, ...,
3384 floor(1/unit)-1@}. Note, however, that this need not be the way the
3385 values are actually created and that the actual resolution of rand can
3386 be much higher than unit. In case @var{unit} is absent it defaults to a
3387 reasonably small value (related to the width of the mantissa of an
3388 efficient number format).
3392 @subsection SRFI-30 - Nested Multi-line Comments
3395 Starting from version 2.0, Guile's @code{read} supports SRFI-30/R6RS
3396 nested multi-line comments by default, @ref{Block Comments}.
3399 @subsection SRFI-31 - A special form `rec' for recursive evaluation
3401 @cindex recursive expression
3404 SRFI-31 defines a special form that can be used to create
3405 self-referential expressions more conveniently. The syntax is as
3410 <rec expression> --> (rec <variable> <expression>)
3411 <rec expression> --> (rec (<variable>+) <body>)
3415 The first syntax can be used to create self-referential expressions,
3419 guile> (define tmp (rec ones (cons 1 (delay ones))))
3422 The second syntax can be used to create anonymous recursive functions:
3425 guile> (define tmp (rec (display-n item n)
3427 (begin (display n) (display-n (- n 1))))))
3435 @subsection SRFI-34 - Exception handling for programs
3438 Guile provides an implementation of
3439 @uref{http://srfi.schemers.org/srfi-34/srfi-34.html, SRFI-34's exception
3440 handling mechanisms} as an alternative to its own built-in mechanisms
3441 (@pxref{Exceptions}). It can be made available as follows:
3444 (use-modules (srfi srfi-34))
3447 @c FIXME: Document it.
3451 @subsection SRFI-35 - Conditions
3457 @uref{http://srfi.schemers.org/srfi-35/srfi-35.html, SRFI-35} implements
3458 @dfn{conditions}, a data structure akin to records designed to convey
3459 information about exceptional conditions between parts of a program. It
3460 is normally used in conjunction with SRFI-34's @code{raise}:
3463 (raise (condition (&message
3464 (message "An error occurred"))))
3467 Users can define @dfn{condition types} containing arbitrary information.
3468 Condition types may inherit from one another. This allows the part of
3469 the program that handles (or ``catches'') conditions to get accurate
3470 information about the exceptional condition that arose.
3472 SRFI-35 conditions are made available using:
3475 (use-modules (srfi srfi-35))
3478 The procedures available to manipulate condition types are the
3481 @deffn {Scheme Procedure} make-condition-type id parent field-names
3482 Return a new condition type named @var{id}, inheriting from
3483 @var{parent}, and with the fields whose names are listed in
3484 @var{field-names}. @var{field-names} must be a list of symbols and must
3485 not contain names already used by @var{parent} or one of its supertypes.
3488 @deffn {Scheme Procedure} condition-type? obj
3489 Return true if @var{obj} is a condition type.
3492 Conditions can be created and accessed with the following procedures:
3494 @deffn {Scheme Procedure} make-condition type . field+value
3495 Return a new condition of type @var{type} with fields initialized as
3496 specified by @var{field+value}, a sequence of field names (symbols) and
3497 values as in the following example:
3500 (let ((&ct (make-condition-type 'foo &condition '(a b c))))
3501 (make-condition &ct 'a 1 'b 2 'c 3))
3504 Note that all fields of @var{type} and its supertypes must be specified.
3507 @deffn {Scheme Procedure} make-compound-condition . conditions
3508 Return a new compound condition composed of @var{conditions}. The
3509 returned condition has the type of each condition of @var{conditions}
3510 (per @code{condition-has-type?}).
3513 @deffn {Scheme Procedure} condition-has-type? c type
3514 Return true if condition @var{c} has type @var{type}.
3517 @deffn {Scheme Procedure} condition-ref c field-name
3518 Return the value of the field named @var{field-name} from condition @var{c}.
3520 If @var{c} is a compound condition and several underlying condition
3521 types contain a field named @var{field-name}, then the value of the
3522 first such field is returned, using the order in which conditions were
3523 passed to @var{make-compound-condition}.
3526 @deffn {Scheme Procedure} extract-condition c type
3527 Return a condition of condition type @var{type} with the field values
3528 specified by @var{c}.
3530 If @var{c} is a compound condition, extract the field values from the
3531 subcondition belonging to @var{type} that appeared first in the call to
3532 @code{make-compound-condition} that created the condition.
3535 Convenience macros are also available to create condition types and
3538 @deffn {library syntax} define-condition-type type supertype predicate field-spec...
3539 Define a new condition type named @var{type} that inherits from
3540 @var{supertype}. In addition, bind @var{predicate} to a type predicate
3541 that returns true when passed a condition of type @var{type} or any of
3542 its subtypes. @var{field-spec} must have the form @code{(field
3543 accessor)} where @var{field} is the name of field of @var{type} and
3544 @var{accessor} is the name of a procedure to access field @var{field} in
3545 conditions of type @var{type}.
3547 The example below defines condition type @code{&foo}, inheriting from
3548 @code{&condition} with fields @code{a}, @code{b} and @code{c}:
3551 (define-condition-type &foo &condition
3559 @deffn {library syntax} condition type-field-bindings...
3560 Return a new condition, or compound condition, initialized according to
3561 @var{type-field-bindings}. Each @var{type-field-binding} must have the
3562 form @code{(type field-specs...)}, where @var{type} is the name of a
3563 variable bound to condition type; each @var{field-spec} must have the
3564 form @code{(field-name value)} where @var{field-name} is a symbol
3565 denoting the field being initialized to @var{value}. As for
3566 @code{make-condition}, all fields must be specified.
3568 The following example returns a simple condition:
3571 (condition (&message (message "An error occurred")))
3574 The one below returns a compound condition:
3577 (condition (&message (message "An error occurred"))
3582 Finally, SRFI-35 defines a several standard condition types.
3585 This condition type is the root of all condition types. It has no
3590 A condition type that carries a message describing the nature of the
3591 condition to humans.
3594 @deffn {Scheme Procedure} message-condition? c
3595 Return true if @var{c} is of type @code{&message} or one of its
3599 @deffn {Scheme Procedure} condition-message c
3600 Return the message associated with message condition @var{c}.
3604 This type describes conditions serious enough that they cannot safely be
3605 ignored. It has no fields.
3608 @deffn {Scheme Procedure} serious-condition? c
3609 Return true if @var{c} is of type @code{&serious} or one of its
3614 This condition describes errors, typically caused by something that has
3615 gone wrong in the interaction of the program with the external world or
3619 @deffn {Scheme Procedure} error? c
3620 Return true if @var{c} is of type @code{&error} or one of its subtypes.
3624 @subsection SRFI-37 - args-fold
3627 This is a processor for GNU @code{getopt_long}-style program
3628 arguments. It provides an alternative, less declarative interface
3629 than @code{getopt-long} in @code{(ice-9 getopt-long)}
3630 (@pxref{getopt-long,,The (ice-9 getopt-long) Module}). Unlike
3631 @code{getopt-long}, it supports repeated options and any number of
3632 short and long names per option. Access it with:
3635 (use-modules (srfi srfi-37))
3638 @acronym{SRFI}-37 principally provides an @code{option} type and the
3639 @code{args-fold} function. To use the library, create a set of
3640 options with @code{option} and use it as a specification for invoking
3643 Here is an example of a simple argument processor for the typical
3644 @samp{--version} and @samp{--help} options, which returns a backwards
3645 list of files given on the command line:
3648 (args-fold (cdr (program-arguments))
3649 (let ((display-and-exit-proc
3651 (lambda (opt name arg loads)
3652 (display msg) (quit)))))
3653 (list (option '(#\v "version") #f #f
3654 (display-and-exit-proc "Foo version 42.0\n"))
3655 (option '(#\h "help") #f #f
3656 (display-and-exit-proc
3657 "Usage: foo scheme-file ..."))))
3658 (lambda (opt name arg loads)
3659 (error "Unrecognized option `~A'" name))
3660 (lambda (op loads) (cons op loads))
3664 @deffn {Scheme Procedure} option names required-arg? optional-arg? processor
3665 Return an object that specifies a single kind of program option.
3667 @var{names} is a list of command-line option names, and should consist of
3668 characters for traditional @code{getopt} short options and strings for
3669 @code{getopt_long}-style long options.
3671 @var{required-arg?} and @var{optional-arg?} are mutually exclusive;
3672 one or both must be @code{#f}. If @var{required-arg?}, the option
3673 must be followed by an argument on the command line, such as
3674 @samp{--opt=value} for long options, or an error will be signalled.
3675 If @var{optional-arg?}, an argument will be taken if available.
3677 @var{processor} is a procedure that takes at least 3 arguments, called
3678 when @code{args-fold} encounters the option: the containing option
3679 object, the name used on the command line, and the argument given for
3680 the option (or @code{#f} if none). The rest of the arguments are
3681 @code{args-fold} ``seeds'', and the @var{processor} should return
3685 @deffn {Scheme Procedure} option-names opt
3686 @deffnx {Scheme Procedure} option-required-arg? opt
3687 @deffnx {Scheme Procedure} option-optional-arg? opt
3688 @deffnx {Scheme Procedure} option-processor opt
3689 Return the specified field of @var{opt}, an option object, as
3690 described above for @code{option}.
3693 @deffn {Scheme Procedure} args-fold args options unrecognized-option-proc operand-proc seeds @dots{}
3694 Process @var{args}, a list of program arguments such as that returned
3695 by @code{(cdr (program-arguments))}, in order against @var{options}, a
3696 list of option objects as described above. All functions called take
3697 the ``seeds'', or the last multiple-values as multiple arguments,
3698 starting with @var{seeds}, and must return the new seeds. Return the
3701 Call @code{unrecognized-option-proc}, which is like an option object's
3702 processor, for any options not found in @var{options}.
3704 Call @code{operand-proc} with any items on the command line that are
3705 not named options. This includes arguments after @samp{--}. It is
3706 called with the argument in question, as well as the seeds.
3710 @subsection SRFI-38 - External Representation for Data With Shared Structure
3713 This subsection is based on
3714 @uref{http://srfi.schemers.org/srfi-38/srfi-38.html, the specification
3715 of SRFI-38} written by Ray Dillinger.
3717 @c Copyright (C) Ray Dillinger 2003. All Rights Reserved.
3719 @c Permission is hereby granted, free of charge, to any person obtaining a
3720 @c copy of this software and associated documentation files (the
3721 @c "Software"), to deal in the Software without restriction, including
3722 @c without limitation the rights to use, copy, modify, merge, publish,
3723 @c distribute, sublicense, and/or sell copies of the Software, and to
3724 @c permit persons to whom the Software is furnished to do so, subject to
3725 @c the following conditions:
3727 @c The above copyright notice and this permission notice shall be included
3728 @c in all copies or substantial portions of the Software.
3730 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3731 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3732 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3733 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3734 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3735 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3736 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3738 This SRFI creates an alternative external representation for data
3739 written and read using @code{write-with-shared-structure} and
3740 @code{read-with-shared-structure}. It is identical to the grammar for
3741 external representation for data written and read with @code{write} and
3742 @code{read} given in section 7 of R5RS, except that the single
3746 <datum> --> <simple datum> | <compound datum>
3749 is replaced by the following five productions:
3752 <datum> --> <defining datum> | <nondefining datum> | <defined datum>
3753 <defining datum> --> #<indexnum>=<nondefining datum>
3754 <defined datum> --> #<indexnum>#
3755 <nondefining datum> --> <simple datum> | <compound datum>
3756 <indexnum> --> <digit 10>+
3759 @deffn {Scheme procedure} write-with-shared-structure obj
3760 @deffnx {Scheme procedure} write-with-shared-structure obj port
3761 @deffnx {Scheme procedure} write-with-shared-structure obj port optarg
3763 Writes an external representation of @var{obj} to the given port.
3764 Strings that appear in the written representation are enclosed in
3765 doublequotes, and within those strings backslash and doublequote
3766 characters are escaped by backslashes. Character objects are written
3767 using the @code{#\} notation.
3769 Objects which denote locations rather than values (cons cells, vectors,
3770 and non-zero-length strings in R5RS scheme; also Guile's structs,
3771 bytevectors and ports and hash-tables), if they appear at more than one
3772 point in the data being written, are preceded by @samp{#@var{N}=} the
3773 first time they are written and replaced by @samp{#@var{N}#} all
3774 subsequent times they are written, where @var{N} is a natural number
3775 used to identify that particular object. If objects which denote
3776 locations occur only once in the structure, then
3777 @code{write-with-shared-structure} must produce the same external
3778 representation for those objects as @code{write}.
3780 @code{write-with-shared-structure} terminates in finite time and
3781 produces a finite representation when writing finite data.
3783 @code{write-with-shared-structure} returns an unspecified value. The
3784 @var{port} argument may be omitted, in which case it defaults to the
3785 value returned by @code{(current-output-port)}. The @var{optarg}
3786 argument may also be omitted. If present, its effects on the output and
3787 return value are unspecified but @code{write-with-shared-structure} must
3788 still write a representation that can be read by
3789 @code{read-with-shared-structure}. Some implementations may wish to use
3790 @var{optarg} to specify formatting conventions, numeric radixes, or
3791 return values. Guile's implementation ignores @var{optarg}.
3793 For example, the code
3796 (begin (define a (cons 'val1 'val2))
3798 (write-with-shared-structure a))
3801 should produce the output @code{#1=(val1 . #1#)}. This shows a cons
3802 cell whose @code{cdr} contains itself.
3806 @deffn {Scheme procedure} read-with-shared-structure
3807 @deffnx {Scheme procedure} read-with-shared-structure port
3809 @code{read-with-shared-structure} converts the external representations
3810 of Scheme objects produced by @code{write-with-shared-structure} into
3811 Scheme objects. That is, it is a parser for the nonterminal
3812 @samp{<datum>} in the augmented external representation grammar defined
3813 above. @code{read-with-shared-structure} returns the next object
3814 parsable from the given input port, updating @var{port} to point to the
3815 first character past the end of the external representation of the
3818 If an end-of-file is encountered in the input before any characters are
3819 found that can begin an object, then an end-of-file object is returned.
3820 The port remains open, and further attempts to read it (by
3821 @code{read-with-shared-structure} or @code{read} will also return an
3822 end-of-file object. If an end of file is encountered after the
3823 beginning of an object's external representation, but the external
3824 representation is incomplete and therefore not parsable, an error is
3827 The @var{port} argument may be omitted, in which case it defaults to the
3828 value returned by @code{(current-input-port)}. It is an error to read
3834 @subsection SRFI-39 - Parameters
3836 @cindex parameter object
3839 This SRFI provides parameter objects, which implement dynamically
3840 bound locations for values. The functions below are available from
3843 (use-modules (srfi srfi-39))
3846 A parameter object is a procedure. Called with no arguments it
3847 returns its value, called with one argument it sets the value.
3850 (define my-param (make-parameter 123))
3851 (my-param) @result{} 123
3853 (my-param) @result{} 456
3856 The @code{parameterize} special form establishes new locations for
3857 parameters, those new locations having effect within the dynamic scope
3858 of the @code{parameterize} body. Leaving restores the previous
3859 locations, or re-entering through a saved continuation will again use
3863 (parameterize ((my-param 789))
3864 (my-param) @result{} 789
3866 (my-param) @result{} 456
3869 Parameters are like dynamically bound variables in other Lisp dialects.
3870 They allow an application to establish parameter settings (as the name
3871 suggests) just for the execution of a particular bit of code,
3872 restoring when done. Examples of such parameters might be
3873 case-sensitivity for a search, or a prompt for user input.
3875 Global variables are not as good as parameter objects for this sort of
3876 thing. Changes to them are visible to all threads, but in Guile
3877 parameter object locations are per-thread, thereby truly limiting the
3878 effect of @code{parameterize} to just its dynamic execution.
3880 Passing arguments to functions is thread-safe, but that soon becomes
3881 tedious when there's more than a few or when they need to pass down
3882 through several layers of calls before reaching the point they should
3883 affect. And introducing a new setting to existing code is often
3884 easier with a parameter object than adding arguments.
3888 @defun make-parameter init [converter]
3889 Return a new parameter object, with initial value @var{init}.
3891 A parameter object is a procedure. When called @code{(param)} it
3892 returns its value, or a call @code{(param val)} sets its value. For
3896 (define my-param (make-parameter 123))
3897 (my-param) @result{} 123
3900 (my-param) @result{} 456
3903 If a @var{converter} is given, then a call @code{(@var{converter}
3904 val)} is made for each value set, its return is the value stored.
3905 Such a call is made for the @var{init} initial value too.
3907 A @var{converter} allows values to be validated, or put into a
3908 canonical form. For example,
3911 (define my-param (make-parameter 123
3913 (if (not (number? val))
3914 (error "must be a number"))
3915 (inexact->exact val))))
3917 (my-param) @result{} 3/4
3921 @deffn {library syntax} parameterize ((param value) @dots{}) body @dots{}
3922 Establish a new dynamic scope with the given @var{param}s bound to new
3923 locations and set to the given @var{value}s. @var{body} is evaluated
3924 in that environment, the result is the return from the last form in
3927 Each @var{param} is an expression which is evaluated to get the
3928 parameter object. Often this will just be the name of a variable
3929 holding the object, but it can be anything that evaluates to a
3932 The @var{param} expressions and @var{value} expressions are all
3933 evaluated before establishing the new dynamic bindings, and they're
3934 evaluated in an unspecified order.
3939 (define prompt (make-parameter "Type something: "))
3944 (parameterize ((prompt "Type a number: "))
3950 @deffn {Parameter object} current-input-port [new-port]
3951 @deffnx {Parameter object} current-output-port [new-port]
3952 @deffnx {Parameter object} current-error-port [new-port]
3953 This SRFI extends the core @code{current-input-port} and
3954 @code{current-output-port}, making them parameter objects. The
3955 Guile-specific @code{current-error-port} is extended too, for
3956 consistency. (@pxref{Default Ports}.)
3958 This is an upwardly compatible extension, a plain call like
3959 @code{(current-input-port)} still returns the current input port, and
3960 @code{set-current-input-port} can still be used. But the port can now
3961 also be set with @code{(current-input-port my-port)} and bound
3962 dynamically with @code{parameterize}.
3965 @defun with-parameters* param-list value-list thunk
3966 Establish a new dynamic scope, as per @code{parameterize} above,
3967 taking parameters from @var{param-list} and corresponding values from
3968 @var{values-list}. A call @code{(@var{thunk})} is made in the new
3969 scope and the result from that @var{thunk} is the return from
3970 @code{with-parameters*}.
3972 This function is a Guile-specific addition to the SRFI, it's similar
3973 to the core @code{with-fluids*} (@pxref{Fluids and Dynamic States}).
3978 Parameter objects are implemented using fluids (@pxref{Fluids and
3979 Dynamic States}), so each dynamic state has it's own parameter
3980 locations. That includes the separate locations when outside any
3981 @code{parameterize} form. When a parameter is created it gets a
3982 separate initial location in each dynamic state, all initialized to
3983 the given @var{init} value.
3985 As alluded to above, because each thread usually has a separate
3986 dynamic state, each thread has it's own locations behind parameter
3987 objects, and changes in one thread are not visible to any other. When
3988 a new dynamic state or thread is created, the values of parameters in
3989 the originating context are copied, into new locations.
3991 SRFI-39 doesn't specify the interaction between parameter objects and
3992 threads, so the threading behaviour described here should be regarded
3996 @subsection SRFI-42 - Eager Comprehensions
3999 See @uref{http://srfi.schemers.org/srfi-42/srfi-42.html, the
4000 specification of SRFI-42}.
4003 @subsection SRFI-45 - Primitives for Expressing Iterative Lazy Algorithms
4006 This subsection is based on @uref{http://srfi.schemers.org/srfi-45/srfi-45.html, the
4007 specification of SRFI-45} written by Andr@'e van Tonder.
4009 @c Copyright (C) André van Tonder (2003). All Rights Reserved.
4011 @c Permission is hereby granted, free of charge, to any person obtaining a
4012 @c copy of this software and associated documentation files (the
4013 @c "Software"), to deal in the Software without restriction, including
4014 @c without limitation the rights to use, copy, modify, merge, publish,
4015 @c distribute, sublicense, and/or sell copies of the Software, and to
4016 @c permit persons to whom the Software is furnished to do so, subject to
4017 @c the following conditions:
4019 @c The above copyright notice and this permission notice shall be included
4020 @c in all copies or substantial portions of the Software.
4022 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
4023 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
4024 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
4025 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
4026 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
4027 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
4028 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
4030 Lazy evaluation is traditionally simulated in Scheme using @code{delay}
4031 and @code{force}. However, these primitives are not powerful enough to
4032 express a large class of lazy algorithms that are iterative. Indeed, it
4033 is folklore in the Scheme community that typical iterative lazy
4034 algorithms written using delay and force will often require unbounded
4037 This SRFI provides set of three operations: @{@code{lazy}, @code{delay},
4038 @code{force}@}, which allow the programmer to succinctly express lazy
4039 algorithms while retaining bounded space behavior in cases that are
4040 properly tail-recursive. A general recipe for using these primitives is
4041 provided. An additional procedure @code{eager} is provided for the
4042 construction of eager promises in cases where efficiency is a concern.
4044 Although this SRFI redefines @code{delay} and @code{force}, the
4045 extension is conservative in the sense that the semantics of the subset
4046 @{@code{delay}, @code{force}@} in isolation (i.e., as long as the
4047 program does not use @code{lazy}) agrees with that in R5RS. In other
4048 words, no program that uses the R5RS definitions of delay and force will
4049 break if those definition are replaced by the SRFI-45 definitions of
4052 @deffn {Scheme Syntax} delay expression
4053 Takes an expression of arbitrary type @var{a} and returns a promise of
4054 type @code{(Promise @var{a})} which at some point in the future may be
4055 asked (by the @code{force} procedure) to evaluate the expression and
4056 deliver the resulting value.
4059 @deffn {Scheme Syntax} lazy expression
4060 Takes an expression of type @code{(Promise @var{a})} and returns a
4061 promise of type @code{(Promise @var{a})} which at some point in the
4062 future may be asked (by the @code{force} procedure) to evaluate the
4063 expression and deliver the resulting promise.
4066 @deffn {Scheme Procedure} force expression
4067 Takes an argument of type @code{(Promise @var{a})} and returns a value
4068 of type @var{a} as follows: If a value of type @var{a} has been computed
4069 for the promise, this value is returned. Otherwise, the promise is
4070 first evaluated, then overwritten by the obtained promise or value, and
4071 then force is again applied (iteratively) to the promise.
4074 @deffn {Scheme Procedure} eager expression
4075 Takes an argument of type @var{a} and returns a value of type
4076 @code{(Promise @var{a})}. As opposed to @code{delay}, the argument is
4077 evaluated eagerly. Semantically, writing @code{(eager expression)} is
4078 equivalent to writing
4081 (let ((value expression)) (delay value)).
4084 However, the former is more efficient since it does not require
4085 unnecessary creation and evaluation of thunks. We also have the
4089 (delay expression) = (lazy (eager expression))
4093 The following reduction rules may be helpful for reasoning about these
4094 primitives. However, they do not express the memoization and memory
4095 usage semantics specified above:
4098 (force (delay expression)) -> expression
4099 (force (lazy expression)) -> (force expression)
4100 (force (eager value)) -> value
4103 @subsubheading Correct usage
4105 We now provide a general recipe for using the primitives @{@code{lazy},
4106 @code{delay}, @code{force}@} to express lazy algorithms in Scheme. The
4107 transformation is best described by way of an example: Consider the
4108 stream-filter algorithm, expressed in a hypothetical lazy language as
4111 (define (stream-filter p? s)
4116 (cons h (stream-filter p? t))
4117 (stream-filter p? t)))))
4120 This algorithm can be expressed as follows in Scheme:
4123 (define (stream-filter p? s)
4125 (if (null? (force s)) (delay '())
4126 (let ((h (car (force s)))
4127 (t (cdr (force s))))
4129 (delay (cons h (stream-filter p? t)))
4130 (stream-filter p? t))))))
4137 wrap all constructors (e.g., @code{'()}, @code{cons}) with @code{delay},
4139 apply @code{force} to arguments of deconstructors (e.g., @code{car},
4140 @code{cdr} and @code{null?}),
4142 wrap procedure bodies with @code{(lazy ...)}.
4146 @subsection SRFI-55 - Requiring Features
4149 SRFI-55 provides @code{require-extension} which is a portable
4150 mechanism to load selected SRFI modules. This is implemented in the
4151 Guile core, there's no module needed to get SRFI-55 itself.
4153 @deffn {library syntax} require-extension clause@dots{}
4154 Require each of the given @var{clause} features, throwing an error if
4155 any are unavailable.
4157 A @var{clause} is of the form @code{(@var{identifier} arg...)}. The
4158 only @var{identifier} currently supported is @code{srfi} and the
4159 arguments are SRFI numbers. For example to get SRFI-1 and SRFI-6,
4162 (require-extension (srfi 1 6))
4165 @code{require-extension} can only be used at the top-level.
4167 A Guile-specific program can simply @code{use-modules} to load SRFIs
4168 not already in the core, @code{require-extension} is for programs
4169 designed to be portable to other Scheme implementations.
4174 @subsection SRFI-60 - Integers as Bits
4176 @cindex integers as bits
4177 @cindex bitwise logical
4179 This SRFI provides various functions for treating integers as bits and
4180 for bitwise manipulations. These functions can be obtained with,
4183 (use-modules (srfi srfi-60))
4186 Integers are treated as infinite precision twos-complement, the same
4187 as in the core logical functions (@pxref{Bitwise Operations}). And
4188 likewise bit indexes start from 0 for the least significant bit. The
4189 following functions in this SRFI are already in the Guile core,
4198 @code{integer-length},
4204 @defun bitwise-and n1 ...
4205 @defunx bitwise-ior n1 ...
4206 @defunx bitwise-xor n1 ...
4207 @defunx bitwise-not n
4208 @defunx any-bits-set? j k
4209 @defunx bit-set? index n
4210 @defunx arithmetic-shift n count
4211 @defunx bit-field n start end
4213 Aliases for @code{logand}, @code{logior}, @code{logxor},
4214 @code{lognot}, @code{logtest}, @code{logbit?}, @code{ash},
4215 @code{bit-extract} and @code{logcount} respectively.
4217 Note that the name @code{bit-count} conflicts with @code{bit-count} in
4218 the core (@pxref{Bit Vectors}).
4221 @defun bitwise-if mask n1 n0
4222 @defunx bitwise-merge mask n1 n0
4223 Return an integer with bits selected from @var{n1} and @var{n0}
4224 according to @var{mask}. Those bits where @var{mask} has 1s are taken
4225 from @var{n1}, and those where @var{mask} has 0s are taken from
4229 (bitwise-if 3 #b0101 #b1010) @result{} 9
4233 @defun log2-binary-factors n
4234 @defunx first-set-bit n
4235 Return a count of how many factors of 2 are present in @var{n}. This
4236 is also the bit index of the lowest 1 bit in @var{n}. If @var{n} is
4237 0, the return is @math{-1}.
4240 (log2-binary-factors 6) @result{} 1
4241 (log2-binary-factors -8) @result{} 3
4245 @defun copy-bit index n newbit
4246 Return @var{n} with the bit at @var{index} set according to
4247 @var{newbit}. @var{newbit} should be @code{#t} to set the bit to 1,
4248 or @code{#f} to set it to 0. Bits other than at @var{index} are
4249 unchanged in the return.
4252 (copy-bit 1 #b0101 #t) @result{} 7
4256 @defun copy-bit-field n newbits start end
4257 Return @var{n} with the bits from @var{start} (inclusive) to @var{end}
4258 (exclusive) changed to the value @var{newbits}.
4260 The least significant bit in @var{newbits} goes to @var{start}, the
4261 next to @math{@var{start}+1}, etc. Anything in @var{newbits} past the
4262 @var{end} given is ignored.
4265 (copy-bit-field #b10000 #b11 1 3) @result{} #b10110
4269 @defun rotate-bit-field n count start end
4270 Return @var{n} with the bit field from @var{start} (inclusive) to
4271 @var{end} (exclusive) rotated upwards by @var{count} bits.
4273 @var{count} can be positive or negative, and it can be more than the
4274 field width (it'll be reduced modulo the width).
4277 (rotate-bit-field #b0110 2 1 4) @result{} #b1010
4281 @defun reverse-bit-field n start end
4282 Return @var{n} with the bits from @var{start} (inclusive) to @var{end}
4283 (exclusive) reversed.
4286 (reverse-bit-field #b101001 2 4) @result{} #b100101
4290 @defun integer->list n [len]
4291 Return bits from @var{n} in the form of a list of @code{#t} for 1 and
4292 @code{#f} for 0. The least significant @var{len} bits are returned,
4293 and the first list element is the most significant of those bits. If
4294 @var{len} is not given, the default is @code{(integer-length @var{n})}
4295 (@pxref{Bitwise Operations}).
4298 (integer->list 6) @result{} (#t #t #f)
4299 (integer->list 1 4) @result{} (#f #f #f #t)
4303 @defun list->integer lst
4304 @defunx booleans->integer bool@dots{}
4305 Return an integer formed bitwise from the given @var{lst} list of
4306 booleans, or for @code{booleans->integer} from the @var{bool}
4309 Each boolean is @code{#t} for a 1 and @code{#f} for a 0. The first
4310 element becomes the most significant bit in the return.
4313 (list->integer '(#t #f #t #f)) @result{} 10
4319 @subsection SRFI-61 - A more general @code{cond} clause
4321 This SRFI extends RnRS @code{cond} to support test expressions that
4322 return multiple values, as well as arbitrary definitions of test
4323 success. SRFI 61 is implemented in the Guile core; there's no module
4324 needed to get SRFI-61 itself. Extended @code{cond} is documented in
4325 @ref{if cond case,, Simple Conditional Evaluation}.
4328 @subsection SRFI-67 - Compare procedures
4331 See @uref{http://srfi.schemers.org/srfi-67/srfi-67.html, the
4332 specification of SRFI-67}.
4335 @subsection SRFI-69 - Basic hash tables
4338 This is a portable wrapper around Guile's built-in hash table and weak
4339 table support. @xref{Hash Tables}, for information on that built-in
4340 support. Above that, this hash-table interface provides association
4341 of equality and hash functions with tables at creation time, so
4342 variants of each function are not required, as well as a procedure
4343 that takes care of most uses for Guile hash table handles, which this
4344 SRFI does not provide as such.
4349 (use-modules (srfi srfi-69))
4353 * SRFI-69 Creating hash tables::
4354 * SRFI-69 Accessing table items::
4355 * SRFI-69 Table properties::
4356 * SRFI-69 Hash table algorithms::
4359 @node SRFI-69 Creating hash tables
4360 @subsubsection Creating hash tables
4362 @deffn {Scheme Procedure} make-hash-table [equal-proc hash-proc #:weak weakness start-size]
4363 Create and answer a new hash table with @var{equal-proc} as the
4364 equality function and @var{hash-proc} as the hashing function.
4366 By default, @var{equal-proc} is @code{equal?}. It can be any
4367 two-argument procedure, and should answer whether two keys are the
4368 same for this table's purposes.
4370 My default @var{hash-proc} assumes that @code{equal-proc} is no
4371 coarser than @code{equal?} unless it is literally @code{string-ci=?}.
4372 If provided, @var{hash-proc} should be a two-argument procedure that
4373 takes a key and the current table size, and answers a reasonably good
4374 hash integer between 0 (inclusive) and the size (exclusive).
4376 @var{weakness} should be @code{#f} or a symbol indicating how ``weak''
4381 An ordinary non-weak hash table. This is the default.
4384 When the key has no more non-weak references at GC, remove that entry.
4387 When the value has no more non-weak references at GC, remove that
4391 When either has no more non-weak references at GC, remove the
4395 As a legacy of the time when Guile couldn't grow hash tables,
4396 @var{start-size} is an optional integer argument that specifies the
4397 approximate starting size for the hash table, which will be rounded to
4398 an algorithmically-sounder number.
4401 By @dfn{coarser} than @code{equal?}, we mean that for all @var{x} and
4402 @var{y} values where @code{(@var{equal-proc} @var{x} @var{y})},
4403 @code{(equal? @var{x} @var{y})} as well. If that does not hold for
4404 your @var{equal-proc}, you must provide a @var{hash-proc}.
4406 In the case of weak tables, remember that @dfn{references} above
4407 always refers to @code{eq?}-wise references. Just because you have a
4408 reference to some string @code{"foo"} doesn't mean that an association
4409 with key @code{"foo"} in a weak-key table @emph{won't} be collected;
4410 it only counts as a reference if the two @code{"foo"}s are @code{eq?},
4411 regardless of @var{equal-proc}. As such, it is usually only sensible
4412 to use @code{eq?} and @code{hashq} as the equivalence and hash
4413 functions for a weak table. @xref{Weak References}, for more
4414 information on Guile's built-in weak table support.
4416 @deffn {Scheme Procedure} alist->hash-table alist [equal-proc hash-proc #:weak weakness start-size]
4417 As with @code{make-hash-table}, but initialize it with the
4418 associations in @var{alist}. Where keys are repeated in @var{alist},
4419 the leftmost association takes precedence.
4422 @node SRFI-69 Accessing table items
4423 @subsubsection Accessing table items
4425 @deffn {Scheme Procedure} hash-table-ref table key [default-thunk]
4426 @deffnx {Scheme Procedure} hash-table-ref/default table key default
4427 Answer the value associated with @var{key} in @var{table}. If
4428 @var{key} is not present, answer the result of invoking the thunk
4429 @var{default-thunk}, which signals an error instead by default.
4431 @code{hash-table-ref/default} is a variant that requires a third
4432 argument, @var{default}, and answers @var{default} itself instead of
4436 @deffn {Scheme Procedure} hash-table-set! table key new-value
4437 Set @var{key} to @var{new-value} in @var{table}.
4440 @deffn {Scheme Procedure} hash-table-delete! table key
4441 Remove the association of @var{key} in @var{table}, if present. If
4445 @deffn {Scheme Procedure} hash-table-exists? table key
4446 Answer whether @var{key} has an association in @var{table}.
4449 @deffn {Scheme Procedure} hash-table-update! table key modifier [default-thunk]
4450 @deffnx {Scheme Procedure} hash-table-update!/default table key modifier default
4451 Replace @var{key}'s associated value in @var{table} by invoking
4452 @var{modifier} with one argument, the old value.
4454 If @var{key} is not present, and @var{default-thunk} is provided,
4455 invoke it with no arguments to get the ``old value'' to be passed to
4456 @var{modifier} as above. If @var{default-thunk} is not provided in
4457 such a case, signal an error.
4459 @code{hash-table-update!/default} is a variant that requires the
4460 fourth argument, which is used directly as the ``old value'' rather
4461 than as a thunk to be invoked to retrieve the ``old value''.
4464 @node SRFI-69 Table properties
4465 @subsubsection Table properties
4467 @deffn {Scheme Procedure} hash-table-size table
4468 Answer the number of associations in @var{table}. This is guaranteed
4469 to run in constant time for non-weak tables.
4472 @deffn {Scheme Procedure} hash-table-keys table
4473 Answer an unordered list of the keys in @var{table}.
4476 @deffn {Scheme Procedure} hash-table-values table
4477 Answer an unordered list of the values in @var{table}.
4480 @deffn {Scheme Procedure} hash-table-walk table proc
4481 Invoke @var{proc} once for each association in @var{table}, passing
4482 the key and value as arguments.
4485 @deffn {Scheme Procedure} hash-table-fold table proc init
4486 Invoke @code{(@var{proc} @var{key} @var{value} @var{previous})} for
4487 each @var{key} and @var{value} in @var{table}, where @var{previous} is
4488 the result of the previous invocation, using @var{init} as the first
4489 @var{previous} value. Answer the final @var{proc} result.
4492 @deffn {Scheme Procedure} hash-table->alist table
4493 Answer an alist where each association in @var{table} is an
4494 association in the result.
4497 @node SRFI-69 Hash table algorithms
4498 @subsubsection Hash table algorithms
4500 Each hash table carries an @dfn{equivalence function} and a @dfn{hash
4501 function}, used to implement key lookups. Beginning users should
4502 follow the rules for consistency of the default @var{hash-proc}
4503 specified above. Advanced users can use these to implement their own
4504 equivalence and hash functions for specialized lookup semantics.
4506 @deffn {Scheme Procedure} hash-table-equivalence-function hash-table
4507 @deffnx {Scheme Procedure} hash-table-hash-function hash-table
4508 Answer the equivalence and hash function of @var{hash-table}, respectively.
4511 @deffn {Scheme Procedure} hash obj [size]
4512 @deffnx {Scheme Procedure} string-hash obj [size]
4513 @deffnx {Scheme Procedure} string-ci-hash obj [size]
4514 @deffnx {Scheme Procedure} hash-by-identity obj [size]
4515 Answer a hash value appropriate for equality predicate @code{equal?},
4516 @code{string=?}, @code{string-ci=?}, and @code{eq?}, respectively.
4519 @code{hash} is a backwards-compatible replacement for Guile's built-in
4523 @subsection SRFI-88 Keyword Objects
4525 @cindex keyword objects
4527 @uref{http://srfi.schemers.org/srfi-88/srfi-88.html, SRFI-88} provides
4528 @dfn{keyword objects}, which are equivalent to Guile's keywords
4529 (@pxref{Keywords}). SRFI-88 keywords can be entered using the
4530 @dfn{postfix keyword syntax}, which consists of an identifier followed
4531 by @code{:} (@pxref{Scheme Read, @code{postfix} keyword syntax}).
4532 SRFI-88 can be made available with:
4535 (use-modules (srfi srfi-88))
4538 Doing so installs the right reader option for keyword syntax, using
4539 @code{(read-set! keywords 'postfix)}. It also provides the procedures
4542 @deffn {Scheme Procedure} keyword? obj
4543 Return @code{#t} if @var{obj} is a keyword. This is the same procedure
4544 as the same-named built-in procedure (@pxref{Keyword Procedures,
4548 (keyword? foo:) @result{} #t
4549 (keyword? 'foo:) @result{} #t
4550 (keyword? "foo") @result{} #f
4554 @deffn {Scheme Procedure} keyword->string kw
4555 Return the name of @var{kw} as a string, i.e., without the trailing
4556 colon. The returned string may not be modified, e.g., with
4560 (keyword->string foo:) @result{} "foo"
4564 @deffn {Scheme Procedure} string->keyword str
4565 Return the keyword object whose name is @var{str}.
4568 (keyword->string (string->keyword "a b c")) @result{} "a b c"
4573 @subsection SRFI-98 Accessing environment variables.
4575 @cindex environment variables
4577 This is a portable wrapper around Guile's built-in support for
4578 interacting with the current environment, @xref{Runtime Environment}.
4580 @deffn {Scheme Procedure} get-environment-variable name
4581 Returns a string containing the value of the environment variable
4582 given by the string @code{name}, or @code{#f} if the named
4583 environment variable is not found. This is equivalent to
4584 @code{(getenv name)}.
4587 @deffn {Scheme Procedure} get-environment-variables
4588 Returns the names and values of all the environment variables as an
4589 association list in which both the keys and the values are strings.
4592 @c srfi-modules.texi ends here
4595 @c TeX-master: "guile.texi"