2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @section SRFI Support Modules
11 SRFI is an acronym for Scheme Request For Implementation. The SRFI
12 documents define a lot of syntactic and procedure extensions to standard
13 Scheme as defined in R5RS.
15 Guile has support for a number of SRFIs. This chapter gives an overview
16 over the available SRFIs and some usage hints. For complete
17 documentation, design rationales and further examples, we advise you to
18 get the relevant SRFI documents from the SRFI home page
19 @url{http://srfi.schemers.org/}.
22 * About SRFI Usage:: What to know about Guile's SRFI support.
23 * SRFI-0:: cond-expand
24 * SRFI-1:: List library.
26 * SRFI-4:: Homogeneous numeric vector datatypes.
27 * SRFI-6:: Basic String Ports.
29 * SRFI-9:: define-record-type.
30 * SRFI-10:: Hash-Comma Reader Extension.
31 * SRFI-11:: let-values and let*-values.
32 * SRFI-13:: String library.
33 * SRFI-14:: Character-set library.
34 * SRFI-16:: case-lambda
35 * SRFI-17:: Generalized set!
36 * SRFI-18:: Multithreading support
37 * SRFI-19:: Time/Date library.
38 * SRFI-23:: Error reporting
39 * SRFI-26:: Specializing parameters
40 * SRFI-27:: Sources of Random Bits
41 * SRFI-30:: Nested multi-line block comments
42 * SRFI-31:: A special form `rec' for recursive evaluation
43 * SRFI-34:: Exception handling.
44 * SRFI-35:: Conditions.
45 * SRFI-37:: args-fold program argument processor
46 * SRFI-38:: External Representation for Data With Shared Structure
47 * SRFI-39:: Parameter objects
48 * SRFI-42:: Eager comprehensions
49 * SRFI-45:: Primitives for expressing iterative lazy algorithms
50 * SRFI-55:: Requiring Features.
51 * SRFI-60:: Integers as bits.
52 * SRFI-61:: A more general `cond' clause
53 * SRFI-67:: Compare procedures
54 * SRFI-69:: Basic hash tables.
55 * SRFI-88:: Keyword objects.
56 * SRFI-98:: Accessing environment variables.
57 * SRFI-105:: Curly-infix expressions.
61 @node About SRFI Usage
62 @subsection About SRFI Usage
64 @c FIXME::martin: Review me!
66 SRFI support in Guile is currently implemented partly in the core
67 library, and partly as add-on modules. That means that some SRFIs are
68 automatically available when the interpreter is started, whereas the
69 other SRFIs require you to use the appropriate support module
72 There are several reasons for this inconsistency. First, the feature
73 checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
74 available immediately, because it must be there when the user wants to
75 check for the Scheme implementation, that is, before she can know that
76 it is safe to use @code{use-modules} to load SRFI support modules. The
77 second reason is that some features defined in SRFIs had been
78 implemented in Guile before the developers started to add SRFI
79 implementations as modules (for example SRFI-13 (@pxref{SRFI-13})). In
80 the future, it is possible that SRFIs in the core library might be
81 factored out into separate modules, requiring explicit module loading
82 when they are needed. So you should be prepared to have to use
83 @code{use-modules} someday in the future to access SRFI-13 bindings. If
84 you want, you can do that already. We have included the module
85 @code{(srfi srfi-13)} in the distribution, which currently does nothing,
86 but ensures that you can write future-safe code.
88 Generally, support for a specific SRFI is made available by using
89 modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
90 number of the SRFI needed. Another possibility is to use the command
91 line option @code{--use-srfi}, which will load the necessary modules
92 automatically (@pxref{Invoking Guile}).
96 @subsection SRFI-0 - cond-expand
99 This SRFI lets a portable Scheme program test for the presence of
100 certain features, and adapt itself by using different blocks of code,
101 or fail if the necessary features are not available. There's no
102 module to load, this is in the Guile core.
104 A program designed only for Guile will generally not need this
105 mechanism, such a program can of course directly use the various
106 documented parts of Guile.
108 @deffn syntax cond-expand (feature body@dots{}) @dots{}
109 Expand to the @var{body} of the first clause whose @var{feature}
110 specification is satisfied. It is an error if no @var{feature} is
113 Features are symbols such as @code{srfi-1}, and a feature
114 specification can use @code{and}, @code{or} and @code{not} forms to
115 test combinations. The last clause can be an @code{else}, to be used
118 For example, define a private version of @code{alist-cons} if SRFI-1
125 (define (alist-cons key val alist)
126 (cons (cons key val) alist))))
129 Or demand a certain set of SRFIs (list operations, string ports,
130 @code{receive} and string operations), failing if they're not
134 (cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13)
140 The Guile core has the following features,
144 guile-2 ;; starting from Guile 2.x
157 Other SRFI feature symbols are defined once their code has been loaded
158 with @code{use-modules}, since only then are their bindings available.
160 The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is
161 a good way to load SRFIs to satisfy @code{cond-expand} when running a
164 Testing the @code{guile} feature allows a program to adapt itself to
165 the Guile module system, but still run on other Scheme systems. For
166 example the following demands SRFI-8 (@code{receive}), but also knows
167 how to load it with the Guile mechanism.
173 (use-modules (srfi srfi-8))))
176 @cindex @code{guile-2} SRFI-0 feature
177 @cindex portability between 2.0 and older versions
178 Likewise, testing the @code{guile-2} feature allows code to be portable
179 between Guile 2.0 and previous versions of Guile. For instance, it
180 makes it possible to write code that accounts for Guile 2.0's compiler,
181 yet be correctly interpreted on 1.8 and earlier versions:
184 (cond-expand (guile-2 (eval-when (compile)
185 ;; This must be evaluated at compile time.
186 (fluid-set! current-reader my-reader)))
188 ;; Earlier versions of Guile do not have a
189 ;; separate compilation phase.
190 (fluid-set! current-reader my-reader)))
193 It should be noted that @code{cond-expand} is separate from the
194 @code{*features*} mechanism (@pxref{Feature Tracking}), feature
195 symbols in one are unrelated to those in the other.
199 @subsection SRFI-1 - List library
203 @c FIXME::martin: Review me!
205 The list library defined in SRFI-1 contains a lot of useful list
206 processing procedures for construction, examining, destructuring and
207 manipulating lists and pairs.
209 Since SRFI-1 also defines some procedures which are already contained
210 in R5RS and thus are supported by the Guile core library, some list
211 and pair procedures which appear in the SRFI-1 document may not appear
212 in this section. So when looking for a particular list/pair
213 processing procedure, you should also have a look at the sections
214 @ref{Lists} and @ref{Pairs}.
217 * SRFI-1 Constructors:: Constructing new lists.
218 * SRFI-1 Predicates:: Testing list for specific properties.
219 * SRFI-1 Selectors:: Selecting elements from lists.
220 * SRFI-1 Length Append etc:: Length calculation and list appending.
221 * SRFI-1 Fold and Map:: Higher-order list processing.
222 * SRFI-1 Filtering and Partitioning:: Filter lists based on predicates.
223 * SRFI-1 Searching:: Search for elements.
224 * SRFI-1 Deleting:: Delete elements from lists.
225 * SRFI-1 Association Lists:: Handle association lists.
226 * SRFI-1 Set Operations:: Use lists for representing sets.
229 @node SRFI-1 Constructors
230 @subsubsection Constructors
231 @cindex list constructor
233 @c FIXME::martin: Review me!
235 New lists can be constructed by calling one of the following
238 @deffn {Scheme Procedure} xcons d a
239 Like @code{cons}, but with interchanged arguments. Useful mostly when
240 passed to higher-order procedures.
243 @deffn {Scheme Procedure} list-tabulate n init-proc
244 Return an @var{n}-element list, where each list element is produced by
245 applying the procedure @var{init-proc} to the corresponding list
246 index. The order in which @var{init-proc} is applied to the indices
250 @deffn {Scheme Procedure} list-copy lst
251 Return a new list containing the elements of the list @var{lst}.
253 This function differs from the core @code{list-copy} (@pxref{List
254 Constructors}) in accepting improper lists too. And if @var{lst} is
255 not a pair at all then it's treated as the final tail of an improper
256 list and simply returned.
259 @deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
260 Return a circular list containing the given arguments @var{elt1}
264 @deffn {Scheme Procedure} iota count [start step]
265 Return a list containing @var{count} numbers, starting from
266 @var{start} and adding @var{step} each time. The default @var{start}
267 is 0, the default @var{step} is 1. For example,
270 (iota 6) @result{} (0 1 2 3 4 5)
271 (iota 4 2.5 -2) @result{} (2.5 0.5 -1.5 -3.5)
274 This function takes its name from the corresponding primitive in the
279 @node SRFI-1 Predicates
280 @subsubsection Predicates
281 @cindex list predicate
283 @c FIXME::martin: Review me!
285 The procedures in this section test specific properties of lists.
287 @deffn {Scheme Procedure} proper-list? obj
288 Return @code{#t} if @var{obj} is a proper list, or @code{#f}
289 otherwise. This is the same as the core @code{list?} (@pxref{List
292 A proper list is a list which ends with the empty list @code{()} in
293 the usual way. The empty list @code{()} itself is a proper list too.
296 (proper-list? '(1 2 3)) @result{} #t
297 (proper-list? '()) @result{} #t
301 @deffn {Scheme Procedure} circular-list? obj
302 Return @code{#t} if @var{obj} is a circular list, or @code{#f}
305 A circular list is a list where at some point the @code{cdr} refers
306 back to a previous pair in the list (either the start or some later
307 point), so that following the @code{cdr}s takes you around in a
311 (define x (list 1 2 3 4))
312 (set-cdr! (last-pair x) (cddr x))
313 x @result{} (1 2 3 4 3 4 3 4 ...)
314 (circular-list? x) @result{} #t
318 @deffn {Scheme Procedure} dotted-list? obj
319 Return @code{#t} if @var{obj} is a dotted list, or @code{#f}
322 A dotted list is a list where the @code{cdr} of the last pair is not
323 the empty list @code{()}. Any non-pair @var{obj} is also considered a
324 dotted list, with length zero.
327 (dotted-list? '(1 2 . 3)) @result{} #t
328 (dotted-list? 99) @result{} #t
332 It will be noted that any Scheme object passes exactly one of the
333 above three tests @code{proper-list?}, @code{circular-list?} and
334 @code{dotted-list?}. Non-lists are @code{dotted-list?}, finite lists
335 are either @code{proper-list?} or @code{dotted-list?}, and infinite
336 lists are @code{circular-list?}.
339 @deffn {Scheme Procedure} null-list? lst
340 Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
341 otherwise. If something else than a proper or circular list is passed
342 as @var{lst}, an error is signalled. This procedure is recommended
343 for checking for the end of a list in contexts where dotted lists are
347 @deffn {Scheme Procedure} not-pair? obj
348 Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
349 This is shorthand notation @code{(not (pair? @var{obj}))} and is
350 supposed to be used for end-of-list checking in contexts where dotted
354 @deffn {Scheme Procedure} list= elt= list1 @dots{}
355 Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
356 List equality is determined by testing whether all lists have the same
357 length and the corresponding elements are equal in the sense of the
358 equality predicate @var{elt=}. If no or only one list is given,
359 @code{#t} is returned.
363 @node SRFI-1 Selectors
364 @subsubsection Selectors
365 @cindex list selector
367 @c FIXME::martin: Review me!
369 @deffn {Scheme Procedure} first pair
370 @deffnx {Scheme Procedure} second pair
371 @deffnx {Scheme Procedure} third pair
372 @deffnx {Scheme Procedure} fourth pair
373 @deffnx {Scheme Procedure} fifth pair
374 @deffnx {Scheme Procedure} sixth pair
375 @deffnx {Scheme Procedure} seventh pair
376 @deffnx {Scheme Procedure} eighth pair
377 @deffnx {Scheme Procedure} ninth pair
378 @deffnx {Scheme Procedure} tenth pair
379 These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
382 @deffn {Scheme Procedure} car+cdr pair
383 Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
386 @deffn {Scheme Procedure} take lst i
387 @deffnx {Scheme Procedure} take! lst i
388 Return a list containing the first @var{i} elements of @var{lst}.
390 @code{take!} may modify the structure of the argument list @var{lst}
391 in order to produce the result.
394 @deffn {Scheme Procedure} drop lst i
395 Return a list containing all but the first @var{i} elements of
399 @deffn {Scheme Procedure} take-right lst i
400 Return a list containing the @var{i} last elements of @var{lst}.
401 The return shares a common tail with @var{lst}.
404 @deffn {Scheme Procedure} drop-right lst i
405 @deffnx {Scheme Procedure} drop-right! lst i
406 Return a list containing all but the @var{i} last elements of
409 @code{drop-right} always returns a new list, even when @var{i} is
410 zero. @code{drop-right!} may modify the structure of the argument
411 list @var{lst} in order to produce the result.
414 @deffn {Scheme Procedure} split-at lst i
415 @deffnx {Scheme Procedure} split-at! lst i
416 Return two values, a list containing the first @var{i} elements of the
417 list @var{lst} and a list containing the remaining elements.
419 @code{split-at!} may modify the structure of the argument list
420 @var{lst} in order to produce the result.
423 @deffn {Scheme Procedure} last lst
424 Return the last element of the non-empty, finite list @var{lst}.
428 @node SRFI-1 Length Append etc
429 @subsubsection Length, Append, Concatenate, etc.
431 @c FIXME::martin: Review me!
433 @deffn {Scheme Procedure} length+ lst
434 Return the length of the argument list @var{lst}. When @var{lst} is a
435 circular list, @code{#f} is returned.
438 @deffn {Scheme Procedure} concatenate list-of-lists
439 @deffnx {Scheme Procedure} concatenate! list-of-lists
440 Construct a list by appending all lists in @var{list-of-lists}.
442 @code{concatenate!} may modify the structure of the given lists in
443 order to produce the result.
445 @code{concatenate} is the same as @code{(apply append
446 @var{list-of-lists})}. It exists because some Scheme implementations
447 have a limit on the number of arguments a function takes, which the
448 @code{apply} might exceed. In Guile there is no such limit.
451 @deffn {Scheme Procedure} append-reverse rev-head tail
452 @deffnx {Scheme Procedure} append-reverse! rev-head tail
453 Reverse @var{rev-head}, append @var{tail} to it, and return the
454 result. This is equivalent to @code{(append (reverse @var{rev-head})
455 @var{tail})}, but its implementation is more efficient.
458 (append-reverse '(1 2 3) '(4 5 6)) @result{} (3 2 1 4 5 6)
461 @code{append-reverse!} may modify @var{rev-head} in order to produce
465 @deffn {Scheme Procedure} zip lst1 lst2 @dots{}
466 Return a list as long as the shortest of the argument lists, where
467 each element is a list. The first list contains the first elements of
468 the argument lists, the second list contains the second elements, and
472 @deffn {Scheme Procedure} unzip1 lst
473 @deffnx {Scheme Procedure} unzip2 lst
474 @deffnx {Scheme Procedure} unzip3 lst
475 @deffnx {Scheme Procedure} unzip4 lst
476 @deffnx {Scheme Procedure} unzip5 lst
477 @code{unzip1} takes a list of lists, and returns a list containing the
478 first elements of each list, @code{unzip2} returns two lists, the
479 first containing the first elements of each lists and the second
480 containing the second elements of each lists, and so on.
483 @deffn {Scheme Procedure} count pred lst1 lst2 @dots{}
484 Return a count of the number of times @var{pred} returns true when
485 called on elements from the given lists.
487 @var{pred} is called with @var{N} parameters @code{(@var{pred}
488 @var{elem1} @dots{} @var{elemN} )}, each element being from the
489 corresponding list. The first call is with the first element of each
490 list, the second with the second element from each, and so on.
492 Counting stops when the end of the shortest list is reached. At least
493 one list must be non-circular.
497 @node SRFI-1 Fold and Map
498 @subsubsection Fold, Unfold & Map
502 @c FIXME::martin: Review me!
504 @deffn {Scheme Procedure} fold proc init lst1 lst2 @dots{}
505 @deffnx {Scheme Procedure} fold-right proc init lst1 lst2 @dots{}
506 Apply @var{proc} to the elements of @var{lst1} @var{lst2} @dots{} to
507 build a result, and return that result.
509 Each @var{proc} call is @code{(@var{proc} @var{elem1} @var{elem2}
510 @dots{} @var{previous})}, where @var{elem1} is from @var{lst1},
511 @var{elem2} is from @var{lst2}, and so on. @var{previous} is the return
512 from the previous call to @var{proc}, or the given @var{init} for the
513 first call. If any list is empty, just @var{init} is returned.
515 @code{fold} works through the list elements from first to last. The
516 following shows a list reversal and the calls it makes,
519 (fold cons '() '(1 2 3))
527 @code{fold-right} works through the list elements from last to first,
528 ie.@: from the right. So for example the following finds the longest
529 string, and the last among equal longest,
532 (fold-right (lambda (str prev)
533 (if (> (string-length str) (string-length prev))
537 '("x" "abc" "xyz" "jk"))
541 If @var{lst1} @var{lst2} @dots{} have different lengths, @code{fold}
542 stops when the end of the shortest is reached; @code{fold-right}
543 commences at the last element of the shortest. Ie.@: elements past the
544 length of the shortest are ignored in the other @var{lst}s. At least
545 one @var{lst} must be non-circular.
547 @code{fold} should be preferred over @code{fold-right} if the order of
548 processing doesn't matter, or can be arranged either way, since
549 @code{fold} is a little more efficient.
551 The way @code{fold} builds a result from iterating is quite general,
552 it can do more than other iterations like say @code{map} or
553 @code{filter}. The following for example removes adjacent duplicate
554 elements from a list,
557 (define (delete-adjacent-duplicates lst)
558 (fold-right (lambda (elem ret)
559 (if (equal? elem (first ret))
564 (delete-adjacent-duplicates '(1 2 3 3 4 4 4 5))
565 @result{} (1 2 3 4 5)
568 Clearly the same sort of thing can be done with a @code{for-each} and
569 a variable in which to build the result, but a self-contained
570 @var{proc} can be re-used in multiple contexts, where a
571 @code{for-each} would have to be written out each time.
574 @deffn {Scheme Procedure} pair-fold proc init lst1 lst2 @dots{}
575 @deffnx {Scheme Procedure} pair-fold-right proc init lst1 lst2 @dots{}
576 The same as @code{fold} and @code{fold-right}, but apply @var{proc} to
577 the pairs of the lists instead of the list elements.
580 @deffn {Scheme Procedure} reduce proc default lst
581 @deffnx {Scheme Procedure} reduce-right proc default lst
582 @code{reduce} is a variant of @code{fold}, where the first call to
583 @var{proc} is on two elements from @var{lst}, rather than one element
584 and a given initial value.
586 If @var{lst} is empty, @code{reduce} returns @var{default} (this is
587 the only use for @var{default}). If @var{lst} has just one element
588 then that's the return value. Otherwise @var{proc} is called on the
589 elements of @var{lst}.
591 Each @var{proc} call is @code{(@var{proc} @var{elem} @var{previous})},
592 where @var{elem} is from @var{lst} (the second and subsequent elements
593 of @var{lst}), and @var{previous} is the return from the previous call
594 to @var{proc}. The first element of @var{lst} is the @var{previous}
595 for the first call to @var{proc}.
597 For example, the following adds a list of numbers, the calls made to
598 @code{+} are shown. (Of course @code{+} accepts multiple arguments
599 and can add a list directly, with @code{apply}.)
602 (reduce + 0 '(5 6 7)) @result{} 18
605 (+ 7 11) @result{} 18
608 @code{reduce} can be used instead of @code{fold} where the @var{init}
609 value is an ``identity'', meaning a value which under @var{proc}
610 doesn't change the result, in this case 0 is an identity since
611 @code{(+ 5 0)} is just 5. @code{reduce} avoids that unnecessary call.
613 @code{reduce-right} is a similar variation on @code{fold-right},
614 working from the end (ie.@: the right) of @var{lst}. The last element
615 of @var{lst} is the @var{previous} for the first call to @var{proc},
616 and the @var{elem} values go from the second last.
618 @code{reduce} should be preferred over @code{reduce-right} if the
619 order of processing doesn't matter, or can be arranged either way,
620 since @code{reduce} is a little more efficient.
623 @deffn {Scheme Procedure} unfold p f g seed [tail-gen]
624 @code{unfold} is defined as follows:
627 (unfold p f g seed) =
628 (if (p seed) (tail-gen seed)
630 (unfold p f g (g seed))))
635 Determines when to stop unfolding.
638 Maps each seed value to the corresponding list element.
641 Maps each seed value to next seed value.
644 The state value for the unfold.
647 Creates the tail of the list; defaults to @code{(lambda (x) '())}.
650 @var{g} produces a series of seed values, which are mapped to list
651 elements by @var{f}. These elements are put into a list in
652 left-to-right order, and @var{p} tells when to stop unfolding.
655 @deffn {Scheme Procedure} unfold-right p f g seed [tail]
656 Construct a list with the following loop.
659 (let lp ((seed seed) (lis tail))
662 (cons (f seed) lis))))
667 Determines when to stop unfolding.
670 Maps each seed value to the corresponding list element.
673 Maps each seed value to next seed value.
676 The state value for the unfold.
679 Creates the tail of the list; defaults to @code{(lambda (x) '())}.
684 @deffn {Scheme Procedure} map f lst1 lst2 @dots{}
685 Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
686 return a list containing the results of the procedure applications.
687 This procedure is extended with respect to R5RS, because the argument
688 lists may have different lengths. The result list will have the same
689 length as the shortest argument lists. The order in which @var{f}
690 will be applied to the list element(s) is not specified.
693 @deffn {Scheme Procedure} for-each f lst1 lst2 @dots{}
694 Apply the procedure @var{f} to each pair of corresponding elements of
695 the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not
696 specified. This procedure is extended with respect to R5RS, because
697 the argument lists may have different lengths. The shortest argument
698 list determines the number of times @var{f} is called. @var{f} will
699 be applied to the list elements in left-to-right order.
703 @deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
704 @deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
708 (apply append (map f clist1 clist2 ...))
714 (apply append! (map f clist1 clist2 ...))
717 Map @var{f} over the elements of the lists, just as in the @code{map}
718 function. However, the results of the applications are appended
719 together to make the final result. @code{append-map} uses
720 @code{append} to append the results together; @code{append-map!} uses
723 The dynamic order in which the various applications of @var{f} are
724 made is not specified.
727 @deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
728 Linear-update variant of @code{map} -- @code{map!} is allowed, but not
729 required, to alter the cons cells of @var{lst1} to construct the
732 The dynamic order in which the various applications of @var{f} are
733 made is not specified. In the n-ary case, @var{lst2}, @var{lst3},
734 @dots{} must have at least as many elements as @var{lst1}.
737 @deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{}
738 Like @code{for-each}, but applies the procedure @var{f} to the pairs
739 from which the argument lists are constructed, instead of the list
740 elements. The return value is not specified.
743 @deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
744 Like @code{map}, but only results from the applications of @var{f}
745 which are true are saved in the result list.
749 @node SRFI-1 Filtering and Partitioning
750 @subsubsection Filtering and Partitioning
752 @cindex list partition
754 @c FIXME::martin: Review me!
756 Filtering means to collect all elements from a list which satisfy a
757 specific condition. Partitioning a list means to make two groups of
758 list elements, one which contains the elements satisfying a condition,
759 and the other for the elements which don't.
761 The @code{filter} and @code{filter!} functions are implemented in the
762 Guile core, @xref{List Modification}.
764 @deffn {Scheme Procedure} partition pred lst
765 @deffnx {Scheme Procedure} partition! pred lst
766 Split @var{lst} into those elements which do and don't satisfy the
767 predicate @var{pred}.
769 The return is two values (@pxref{Multiple Values}), the first being a
770 list of all elements from @var{lst} which satisfy @var{pred}, the
771 second a list of those which do not.
773 The elements in the result lists are in the same order as in @var{lst}
774 but the order in which the calls @code{(@var{pred} elem)} are made on
775 the list elements is unspecified.
777 @code{partition} does not change @var{lst}, but one of the returned
778 lists may share a tail with it. @code{partition!} may modify
779 @var{lst} to construct its return.
782 @deffn {Scheme Procedure} remove pred lst
783 @deffnx {Scheme Procedure} remove! pred lst
784 Return a list containing all elements from @var{lst} which do not
785 satisfy the predicate @var{pred}. The elements in the result list
786 have the same order as in @var{lst}. The order in which @var{pred} is
787 applied to the list elements is not specified.
789 @code{remove!} is allowed, but not required to modify the structure of
794 @node SRFI-1 Searching
795 @subsubsection Searching
798 @c FIXME::martin: Review me!
800 The procedures for searching elements in lists either accept a
801 predicate or a comparison object for determining which elements are to
804 @deffn {Scheme Procedure} find pred lst
805 Return the first element of @var{lst} which satisfies the predicate
806 @var{pred} and @code{#f} if no such element is found.
809 @deffn {Scheme Procedure} find-tail pred lst
810 Return the first pair of @var{lst} whose @sc{car} satisfies the
811 predicate @var{pred} and @code{#f} if no such element is found.
814 @deffn {Scheme Procedure} take-while pred lst
815 @deffnx {Scheme Procedure} take-while! pred lst
816 Return the longest initial prefix of @var{lst} whose elements all
817 satisfy the predicate @var{pred}.
819 @code{take-while!} is allowed, but not required to modify the input
820 list while producing the result.
823 @deffn {Scheme Procedure} drop-while pred lst
824 Drop the longest initial prefix of @var{lst} whose elements all
825 satisfy the predicate @var{pred}.
828 @deffn {Scheme Procedure} span pred lst
829 @deffnx {Scheme Procedure} span! pred lst
830 @deffnx {Scheme Procedure} break pred lst
831 @deffnx {Scheme Procedure} break! pred lst
832 @code{span} splits the list @var{lst} into the longest initial prefix
833 whose elements all satisfy the predicate @var{pred}, and the remaining
834 tail. @code{break} inverts the sense of the predicate.
836 @code{span!} and @code{break!} are allowed, but not required to modify
837 the structure of the input list @var{lst} in order to produce the
840 Note that the name @code{break} conflicts with the @code{break}
841 binding established by @code{while} (@pxref{while do}). Applications
842 wanting to use @code{break} from within a @code{while} loop will need
843 to make a new define under a different name.
846 @deffn {Scheme Procedure} any pred lst1 lst2 @dots{}
847 Test whether any set of elements from @var{lst1} @var{lst2} @dots{}
848 satisfies @var{pred}. If so, the return value is the return value from
849 the successful @var{pred} call, or if not, the return value is
852 If there are n list arguments, then @var{pred} must be a predicate
853 taking n arguments. Each @var{pred} call is @code{(@var{pred}
854 @var{elem1} @var{elem2} @dots{} )} taking an element from each
855 @var{lst}. The calls are made successively for the first, second, etc.
856 elements of the lists, stopping when @var{pred} returns non-@code{#f},
857 or when the end of the shortest list is reached.
859 The @var{pred} call on the last set of elements (i.e., when the end of
860 the shortest list has been reached), if that point is reached, is a
864 @deffn {Scheme Procedure} every pred lst1 lst2 @dots{}
865 Test whether every set of elements from @var{lst1} @var{lst2} @dots{}
866 satisfies @var{pred}. If so, the return value is the return from the
867 final @var{pred} call, or if not, the return value is @code{#f}.
869 If there are n list arguments, then @var{pred} must be a predicate
870 taking n arguments. Each @var{pred} call is @code{(@var{pred}
871 @var{elem1} @var{elem2 @dots{}})} taking an element from each
872 @var{lst}. The calls are made successively for the first, second, etc.
873 elements of the lists, stopping if @var{pred} returns @code{#f}, or when
874 the end of any of the lists is reached.
876 The @var{pred} call on the last set of elements (i.e., when the end of
877 the shortest list has been reached) is a tail call.
879 If one of @var{lst1} @var{lst2} @dots{}is empty then no calls to
880 @var{pred} are made, and the return value is @code{#t}.
883 @deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{}
884 Return the index of the first set of elements, one from each of
885 @var{lst1} @var{lst2} @dots{}, which satisfies @var{pred}.
887 @var{pred} is called as @code{(@var{elem1} @var{elem2 @dots{}})}.
888 Searching stops when the end of the shortest @var{lst} is reached.
889 The return index starts from 0 for the first set of elements. If no
890 set of elements pass, then the return value is @code{#f}.
893 (list-index odd? '(2 4 6 9)) @result{} 3
894 (list-index = '(1 2 3) '(3 1 2)) @result{} #f
898 @deffn {Scheme Procedure} member x lst [=]
899 Return the first sublist of @var{lst} whose @sc{car} is equal to
900 @var{x}. If @var{x} does not appear in @var{lst}, return @code{#f}.
902 Equality is determined by @code{equal?}, or by the equality predicate
903 @var{=} if given. @var{=} is called @code{(= @var{x} elem)},
904 ie.@: with the given @var{x} first, so for example to find the first
905 element greater than 5,
908 (member 5 '(3 5 1 7 2 9) <) @result{} (7 2 9)
911 This version of @code{member} extends the core @code{member}
912 (@pxref{List Searching}) by accepting an equality predicate.
916 @node SRFI-1 Deleting
917 @subsubsection Deleting
920 @deffn {Scheme Procedure} delete x lst [=]
921 @deffnx {Scheme Procedure} delete! x lst [=]
922 Return a list containing the elements of @var{lst} but with those
923 equal to @var{x} deleted. The returned elements will be in the same
924 order as they were in @var{lst}.
926 Equality is determined by the @var{=} predicate, or @code{equal?} if
927 not given. An equality call is made just once for each element, but
928 the order in which the calls are made on the elements is unspecified.
930 The equality calls are always @code{(= x elem)}, ie.@: the given @var{x}
931 is first. This means for instance elements greater than 5 can be
932 deleted with @code{(delete 5 lst <)}.
934 @code{delete} does not modify @var{lst}, but the return might share a
935 common tail with @var{lst}. @code{delete!} may modify the structure
936 of @var{lst} to construct its return.
938 These functions extend the core @code{delete} and @code{delete!}
939 (@pxref{List Modification}) in accepting an equality predicate. See
940 also @code{lset-difference} (@pxref{SRFI-1 Set Operations}) for
941 deleting multiple elements from a list.
944 @deffn {Scheme Procedure} delete-duplicates lst [=]
945 @deffnx {Scheme Procedure} delete-duplicates! lst [=]
946 Return a list containing the elements of @var{lst} but without
949 When elements are equal, only the first in @var{lst} is retained.
950 Equal elements can be anywhere in @var{lst}, they don't have to be
951 adjacent. The returned list will have the retained elements in the
952 same order as they were in @var{lst}.
954 Equality is determined by the @var{=} predicate, or @code{equal?} if
955 not given. Calls @code{(= x y)} are made with element @var{x} being
956 before @var{y} in @var{lst}. A call is made at most once for each
957 combination, but the sequence of the calls across the elements is
960 @code{delete-duplicates} does not modify @var{lst}, but the return
961 might share a common tail with @var{lst}. @code{delete-duplicates!}
962 may modify the structure of @var{lst} to construct its return.
964 In the worst case, this is an @math{O(N^2)} algorithm because it must
965 check each element against all those preceding it. For long lists it
966 is more efficient to sort and then compare only adjacent elements.
970 @node SRFI-1 Association Lists
971 @subsubsection Association Lists
972 @cindex association list
975 @c FIXME::martin: Review me!
977 Association lists are described in detail in section @ref{Association
978 Lists}. The present section only documents the additional procedures
979 for dealing with association lists defined by SRFI-1.
981 @deffn {Scheme Procedure} assoc key alist [=]
982 Return the pair from @var{alist} which matches @var{key}. This
983 extends the core @code{assoc} (@pxref{Retrieving Alist Entries}) by
984 taking an optional @var{=} comparison procedure.
986 The default comparison is @code{equal?}. If an @var{=} parameter is
987 given it's called @code{(@var{=} @var{key} @var{alistcar})}, i.e.@: the
988 given target @var{key} is the first argument, and a @code{car} from
989 @var{alist} is second.
991 For example a case-insensitive string lookup,
994 (assoc "yy" '(("XX" . 1) ("YY" . 2)) string-ci=?)
999 @deffn {Scheme Procedure} alist-cons key datum alist
1000 Cons a new association @var{key} and @var{datum} onto @var{alist} and
1001 return the result. This is equivalent to
1004 (cons (cons @var{key} @var{datum}) @var{alist})
1007 @code{acons} (@pxref{Adding or Setting Alist Entries}) in the Guile
1008 core does the same thing.
1011 @deffn {Scheme Procedure} alist-copy alist
1012 Return a newly allocated copy of @var{alist}, that means that the
1013 spine of the list as well as the pairs are copied.
1016 @deffn {Scheme Procedure} alist-delete key alist [=]
1017 @deffnx {Scheme Procedure} alist-delete! key alist [=]
1018 Return a list containing the elements of @var{alist} but with those
1019 elements whose keys are equal to @var{key} deleted. The returned
1020 elements will be in the same order as they were in @var{alist}.
1022 Equality is determined by the @var{=} predicate, or @code{equal?} if
1023 not given. The order in which elements are tested is unspecified, but
1024 each equality call is made @code{(= key alistkey)}, i.e.@: the given
1025 @var{key} parameter is first and the key from @var{alist} second.
1026 This means for instance all associations with a key greater than 5 can
1027 be removed with @code{(alist-delete 5 alist <)}.
1029 @code{alist-delete} does not modify @var{alist}, but the return might
1030 share a common tail with @var{alist}. @code{alist-delete!} may modify
1031 the list structure of @var{alist} to construct its return.
1035 @node SRFI-1 Set Operations
1036 @subsubsection Set Operations on Lists
1037 @cindex list set operation
1039 Lists can be used to represent sets of objects. The procedures in
1040 this section operate on such lists as sets.
1042 Note that lists are not an efficient way to implement large sets. The
1043 procedures here typically take time @math{@var{m}@cross{}@var{n}} when
1044 operating on @var{m} and @var{n} element lists. Other data structures
1045 like trees, bitsets (@pxref{Bit Vectors}) or hash tables (@pxref{Hash
1046 Tables}) are faster.
1048 All these procedures take an equality predicate as the first argument.
1049 This predicate is used for testing the objects in the list sets for
1050 sameness. This predicate must be consistent with @code{eq?}
1051 (@pxref{Equality}) in the sense that if two list elements are
1052 @code{eq?} then they must also be equal under the predicate. This
1053 simply means a given object must be equal to itself.
1055 @deffn {Scheme Procedure} lset<= = list @dots{}
1056 Return @code{#t} if each list is a subset of the one following it.
1057 I.e., @var{list1} is a subset of @var{list2}, @var{list2} is a subset of
1058 @var{list3}, etc., for as many lists as given. If only one list or no
1059 lists are given, the return value is @code{#t}.
1061 A list @var{x} is a subset of @var{y} if each element of @var{x} is
1062 equal to some element in @var{y}. Elements are compared using the
1063 given @var{=} procedure, called as @code{(@var{=} xelem yelem)}.
1066 (lset<= eq?) @result{} #t
1067 (lset<= eqv? '(1 2 3) '(1)) @result{} #f
1068 (lset<= eqv? '(1 3 2) '(4 3 1 2)) @result{} #t
1072 @deffn {Scheme Procedure} lset= = list @dots{}
1073 Return @code{#t} if all argument lists are set-equal. @var{list1} is
1074 compared to @var{list2}, @var{list2} to @var{list3}, etc., for as many
1075 lists as given. If only one list or no lists are given, the return
1078 Two lists @var{x} and @var{y} are set-equal if each element of @var{x}
1079 is equal to some element of @var{y} and conversely each element of
1080 @var{y} is equal to some element of @var{x}. The order of the
1081 elements in the lists doesn't matter. Element equality is determined
1082 with the given @var{=} procedure, called as @code{(@var{=} xelem
1083 yelem)}, but exactly which calls are made is unspecified.
1086 (lset= eq?) @result{} #t
1087 (lset= eqv? '(1 2 3) '(3 2 1)) @result{} #t
1088 (lset= string-ci=? '("a" "A" "b") '("B" "b" "a")) @result{} #t
1092 @deffn {Scheme Procedure} lset-adjoin = list elem @dots{}
1093 Add to @var{list} any of the given @var{elem}s not already in the list.
1094 @var{elem}s are @code{cons}ed onto the start of @var{list} (so the
1095 return value shares a common tail with @var{list}), but the order that
1096 the @var{elem}s are added is unspecified.
1098 The given @var{=} procedure is used for comparing elements, called as
1099 @code{(@var{=} listelem elem)}, i.e., the second argument is one of
1100 the given @var{elem} parameters.
1103 (lset-adjoin eqv? '(1 2 3) 4 1 5) @result{} (5 4 1 2 3)
1107 @deffn {Scheme Procedure} lset-union = list @dots{}
1108 @deffnx {Scheme Procedure} lset-union! = list @dots{}
1109 Return the union of the argument list sets. The result is built by
1110 taking the union of @var{list1} and @var{list2}, then the union of
1111 that with @var{list3}, etc., for as many lists as given. For one list
1112 argument that list itself is the result, for no list arguments the
1113 result is the empty list.
1115 The union of two lists @var{x} and @var{y} is formed as follows. If
1116 @var{x} is empty then the result is @var{y}. Otherwise start with
1117 @var{x} as the result and consider each @var{y} element (from first to
1118 last). A @var{y} element not equal to something already in the result
1119 is @code{cons}ed onto the result.
1121 The given @var{=} procedure is used for comparing elements, called as
1122 @code{(@var{=} relem yelem)}. The first argument is from the result
1123 accumulated so far, and the second is from the list being union-ed in.
1124 But exactly which calls are made is otherwise unspecified.
1126 Notice that duplicate elements in @var{list1} (or the first non-empty
1127 list) are preserved, but that repeated elements in subsequent lists
1128 are only added once.
1131 (lset-union eqv?) @result{} ()
1132 (lset-union eqv? '(1 2 3)) @result{} (1 2 3)
1133 (lset-union eqv? '(1 2 1 3) '(2 4 5) '(5)) @result{} (5 4 1 2 1 3)
1136 @code{lset-union} doesn't change the given lists but the result may
1137 share a tail with the first non-empty list. @code{lset-union!} can
1138 modify all of the given lists to form the result.
1141 @deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{}
1142 @deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{}
1143 Return the intersection of @var{list1} with the other argument lists,
1144 meaning those elements of @var{list1} which are also in all of
1145 @var{list2} etc. For one list argument, just that list is returned.
1147 The test for an element of @var{list1} to be in the return is simply
1148 that it's equal to some element in each of @var{list2} etc. Notice
1149 this means an element appearing twice in @var{list1} but only once in
1150 each of @var{list2} etc will go into the return twice. The return has
1151 its elements in the same order as they were in @var{list1}.
1153 The given @var{=} procedure is used for comparing elements, called as
1154 @code{(@var{=} elem1 elemN)}. The first argument is from @var{list1}
1155 and the second is from one of the subsequent lists. But exactly which
1156 calls are made and in what order is unspecified.
1159 (lset-intersection eqv? '(x y)) @result{} (x y)
1160 (lset-intersection eqv? '(1 2 3) '(4 3 2)) @result{} (2 3)
1161 (lset-intersection eqv? '(1 1 2 2) '(1 2) '(2 1) '(2)) @result{} (2 2)
1164 The return from @code{lset-intersection} may share a tail with
1165 @var{list1}. @code{lset-intersection!} may modify @var{list1} to form
1169 @deffn {Scheme Procedure} lset-difference = list1 list2 @dots{}
1170 @deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{}
1171 Return @var{list1} with any elements in @var{list2}, @var{list3} etc
1172 removed (ie.@: subtracted). For one list argument, just that list is
1175 The given @var{=} procedure is used for comparing elements, called as
1176 @code{(@var{=} elem1 elemN)}. The first argument is from @var{list1}
1177 and the second from one of the subsequent lists. But exactly which
1178 calls are made and in what order is unspecified.
1181 (lset-difference eqv? '(x y)) @result{} (x y)
1182 (lset-difference eqv? '(1 2 3) '(3 1)) @result{} (2)
1183 (lset-difference eqv? '(1 2 3) '(3) '(2)) @result{} (1)
1186 The return from @code{lset-difference} may share a tail with
1187 @var{list1}. @code{lset-difference!} may modify @var{list1} to form
1191 @deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{}
1192 @deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{}
1193 Return two values (@pxref{Multiple Values}), the difference and
1194 intersection of the argument lists as per @code{lset-difference} and
1195 @code{lset-intersection} above.
1197 For two list arguments this partitions @var{list1} into those elements
1198 of @var{list1} which are in @var{list2} and not in @var{list2}. (But
1199 for more than two arguments there can be elements of @var{list1} which
1200 are neither part of the difference nor the intersection.)
1202 One of the return values from @code{lset-diff+intersection} may share
1203 a tail with @var{list1}. @code{lset-diff+intersection!} may modify
1204 @var{list1} to form its results.
1207 @deffn {Scheme Procedure} lset-xor = list @dots{}
1208 @deffnx {Scheme Procedure} lset-xor! = list @dots{}
1209 Return an XOR of the argument lists. For two lists this means those
1210 elements which are in exactly one of the lists. For more than two
1211 lists it means those elements which appear in an odd number of the
1214 To be precise, the XOR of two lists @var{x} and @var{y} is formed by
1215 taking those elements of @var{x} not equal to any element of @var{y},
1216 plus those elements of @var{y} not equal to any element of @var{x}.
1217 Equality is determined with the given @var{=} procedure, called as
1218 @code{(@var{=} e1 e2)}. One argument is from @var{x} and the other
1219 from @var{y}, but which way around is unspecified. Exactly which
1220 calls are made is also unspecified, as is the order of the elements in
1224 (lset-xor eqv? '(x y)) @result{} (x y)
1225 (lset-xor eqv? '(1 2 3) '(4 3 2)) @result{} (4 1)
1228 The return from @code{lset-xor} may share a tail with one of the list
1229 arguments. @code{lset-xor!} may modify @var{list1} to form its
1235 @subsection SRFI-2 - and-let*
1239 The following syntax can be obtained with
1242 (use-modules (srfi srfi-2))
1248 (use-modules (ice-9 and-let-star))
1251 @deffn {library syntax} and-let* (clause @dots{}) body @dots{}
1252 A combination of @code{and} and @code{let*}.
1254 Each @var{clause} is evaluated in turn, and if @code{#f} is obtained
1255 then evaluation stops and @code{#f} is returned. If all are
1256 non-@code{#f} then @var{body} is evaluated and the last form gives the
1257 return value, or if @var{body} is empty then the result is @code{#t}.
1258 Each @var{clause} should be one of the following,
1262 Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}.
1263 Like @code{let*}, that binding is available to subsequent clauses.
1265 Evaluate @var{expr} and check for @code{#f}.
1267 Get the value bound to @var{symbol} and check for @code{#f}.
1270 Notice that @code{(expr)} has an ``extra'' pair of parentheses, for
1271 instance @code{((eq? x y))}. One way to remember this is to imagine
1272 the @code{symbol} in @code{(symbol expr)} is omitted.
1274 @code{and-let*} is good for calculations where a @code{#f} value means
1275 termination, but where a non-@code{#f} value is going to be needed in
1276 subsequent expressions.
1278 The following illustrates this, it returns text between brackets
1279 @samp{[...]} in a string, or @code{#f} if there are no such brackets
1280 (ie.@: either @code{string-index} gives @code{#f}).
1283 (define (extract-brackets str)
1284 (and-let* ((start (string-index str #\[))
1285 (end (string-index str #\] start)))
1286 (substring str (1+ start) end)))
1289 The following shows plain variables and expressions tested too.
1290 @code{diagnostic-levels} is taken to be an alist associating a
1291 diagnostic type with a level. @code{str} is printed only if the type
1292 is known and its level is high enough.
1295 (define (show-diagnostic type str)
1296 (and-let* (want-diagnostics
1297 (level (assq-ref diagnostic-levels type))
1298 ((>= level current-diagnostic-level)))
1302 The advantage of @code{and-let*} is that an extended sequence of
1303 expressions and tests doesn't require lots of nesting as would arise
1304 from separate @code{and} and @code{let*}, or from @code{cond} with
1311 @subsection SRFI-4 - Homogeneous numeric vector datatypes
1314 SRFI-4 provides an interface to uniform numeric vectors: vectors whose elements
1315 are all of a single numeric type. Guile offers uniform numeric vectors for
1316 signed and unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
1317 floating point values, and, as an extension to SRFI-4, complex floating-point
1318 numbers of these two sizes.
1320 The standard SRFI-4 procedures and data types may be included via loading the
1324 (use-modules (srfi srfi-4))
1327 This module is currently a part of the default Guile environment, but it is a
1328 good practice to explicitly import the module. In the future, using SRFI-4
1329 procedures without importing the SRFI-4 module will cause a deprecation message
1330 to be printed. (Of course, one may call the C functions at any time. Would that
1334 * SRFI-4 Overview:: The warp and weft of uniform numeric vectors.
1335 * SRFI-4 API:: Uniform vectors, from Scheme and from C.
1336 * SRFI-4 Generic Operations:: The general, operating on the specific.
1337 * SRFI-4 and Bytevectors:: SRFI-4 vectors are backed by bytevectors.
1338 * SRFI-4 Extensions:: Guile-specific extensions to the standard.
1341 @node SRFI-4 Overview
1342 @subsubsection SRFI-4 - Overview
1344 Uniform numeric vectors can be useful since they consume less memory
1345 than the non-uniform, general vectors. Also, since the types they can
1346 store correspond directly to C types, it is easier to work with them
1347 efficiently on a low level. Consider image processing as an example,
1348 where you want to apply a filter to some image. While you could store
1349 the pixels of an image in a general vector and write a general
1350 convolution function, things are much more efficient with uniform
1351 vectors: the convolution function knows that all pixels are unsigned
1352 8-bit values (say), and can use a very tight inner loop.
1354 This is implemented in Scheme by having the compiler notice calls to the SRFI-4
1355 accessors, and inline them to appropriate compiled code. From C you have access
1356 to the raw array; functions for efficiently working with uniform numeric vectors
1357 from C are listed at the end of this section.
1359 Uniform numeric vectors are the special case of one dimensional uniform
1362 There are 12 standard kinds of uniform numeric vectors, and they all have their
1363 own complement of constructors, accessors, and so on. Procedures that operate on
1364 a specific kind of uniform numeric vector have a ``tag'' in their name,
1365 indicating the element type.
1369 unsigned 8-bit integers
1372 signed 8-bit integers
1375 unsigned 16-bit integers
1378 signed 16-bit integers
1381 unsigned 32-bit integers
1384 signed 32-bit integers
1387 unsigned 64-bit integers
1390 signed 64-bit integers
1393 the C type @code{float}
1396 the C type @code{double}
1400 In addition, Guile supports uniform arrays of complex numbers, with the
1406 complex numbers in rectangular form with the real and imaginary part
1407 being a @code{float}
1410 complex numbers in rectangular form with the real and imaginary part
1411 being a @code{double}
1415 The external representation (ie.@: read syntax) for these vectors is
1416 similar to normal Scheme vectors, but with an additional tag from the
1417 tables above indicating the vector's type. For example,
1424 Note that the read syntax for floating-point here conflicts with
1425 @code{#f} for false. In Standard Scheme one can write @code{(1 #f3)}
1426 for a three element list @code{(1 #f 3)}, but for Guile @code{(1 #f3)}
1427 is invalid. @code{(1 #f 3)} is almost certainly what one should write
1428 anyway to make the intention clear, so this is rarely a problem.
1432 @subsubsection SRFI-4 - API
1434 Note that the @nicode{c32} and @nicode{c64} functions are only available from
1435 @nicode{(srfi srfi-4 gnu)}.
1437 @deffn {Scheme Procedure} u8vector? obj
1438 @deffnx {Scheme Procedure} s8vector? obj
1439 @deffnx {Scheme Procedure} u16vector? obj
1440 @deffnx {Scheme Procedure} s16vector? obj
1441 @deffnx {Scheme Procedure} u32vector? obj
1442 @deffnx {Scheme Procedure} s32vector? obj
1443 @deffnx {Scheme Procedure} u64vector? obj
1444 @deffnx {Scheme Procedure} s64vector? obj
1445 @deffnx {Scheme Procedure} f32vector? obj
1446 @deffnx {Scheme Procedure} f64vector? obj
1447 @deffnx {Scheme Procedure} c32vector? obj
1448 @deffnx {Scheme Procedure} c64vector? obj
1449 @deffnx {C Function} scm_u8vector_p (obj)
1450 @deffnx {C Function} scm_s8vector_p (obj)
1451 @deffnx {C Function} scm_u16vector_p (obj)
1452 @deffnx {C Function} scm_s16vector_p (obj)
1453 @deffnx {C Function} scm_u32vector_p (obj)
1454 @deffnx {C Function} scm_s32vector_p (obj)
1455 @deffnx {C Function} scm_u64vector_p (obj)
1456 @deffnx {C Function} scm_s64vector_p (obj)
1457 @deffnx {C Function} scm_f32vector_p (obj)
1458 @deffnx {C Function} scm_f64vector_p (obj)
1459 @deffnx {C Function} scm_c32vector_p (obj)
1460 @deffnx {C Function} scm_c64vector_p (obj)
1461 Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1465 @deffn {Scheme Procedure} make-u8vector n [value]
1466 @deffnx {Scheme Procedure} make-s8vector n [value]
1467 @deffnx {Scheme Procedure} make-u16vector n [value]
1468 @deffnx {Scheme Procedure} make-s16vector n [value]
1469 @deffnx {Scheme Procedure} make-u32vector n [value]
1470 @deffnx {Scheme Procedure} make-s32vector n [value]
1471 @deffnx {Scheme Procedure} make-u64vector n [value]
1472 @deffnx {Scheme Procedure} make-s64vector n [value]
1473 @deffnx {Scheme Procedure} make-f32vector n [value]
1474 @deffnx {Scheme Procedure} make-f64vector n [value]
1475 @deffnx {Scheme Procedure} make-c32vector n [value]
1476 @deffnx {Scheme Procedure} make-c64vector n [value]
1477 @deffnx {C Function} scm_make_u8vector (n, value)
1478 @deffnx {C Function} scm_make_s8vector (n, value)
1479 @deffnx {C Function} scm_make_u16vector (n, value)
1480 @deffnx {C Function} scm_make_s16vector (n, value)
1481 @deffnx {C Function} scm_make_u32vector (n, value)
1482 @deffnx {C Function} scm_make_s32vector (n, value)
1483 @deffnx {C Function} scm_make_u64vector (n, value)
1484 @deffnx {C Function} scm_make_s64vector (n, value)
1485 @deffnx {C Function} scm_make_f32vector (n, value)
1486 @deffnx {C Function} scm_make_f64vector (n, value)
1487 @deffnx {C Function} scm_make_c32vector (n, value)
1488 @deffnx {C Function} scm_make_c64vector (n, value)
1489 Return a newly allocated homogeneous numeric vector holding @var{n}
1490 elements of the indicated type. If @var{value} is given, the vector
1491 is initialized with that value, otherwise the contents are
1495 @deffn {Scheme Procedure} u8vector value @dots{}
1496 @deffnx {Scheme Procedure} s8vector value @dots{}
1497 @deffnx {Scheme Procedure} u16vector value @dots{}
1498 @deffnx {Scheme Procedure} s16vector value @dots{}
1499 @deffnx {Scheme Procedure} u32vector value @dots{}
1500 @deffnx {Scheme Procedure} s32vector value @dots{}
1501 @deffnx {Scheme Procedure} u64vector value @dots{}
1502 @deffnx {Scheme Procedure} s64vector value @dots{}
1503 @deffnx {Scheme Procedure} f32vector value @dots{}
1504 @deffnx {Scheme Procedure} f64vector value @dots{}
1505 @deffnx {Scheme Procedure} c32vector value @dots{}
1506 @deffnx {Scheme Procedure} c64vector value @dots{}
1507 @deffnx {C Function} scm_u8vector (values)
1508 @deffnx {C Function} scm_s8vector (values)
1509 @deffnx {C Function} scm_u16vector (values)
1510 @deffnx {C Function} scm_s16vector (values)
1511 @deffnx {C Function} scm_u32vector (values)
1512 @deffnx {C Function} scm_s32vector (values)
1513 @deffnx {C Function} scm_u64vector (values)
1514 @deffnx {C Function} scm_s64vector (values)
1515 @deffnx {C Function} scm_f32vector (values)
1516 @deffnx {C Function} scm_f64vector (values)
1517 @deffnx {C Function} scm_c32vector (values)
1518 @deffnx {C Function} scm_c64vector (values)
1519 Return a newly allocated homogeneous numeric vector of the indicated
1520 type, holding the given parameter @var{value}s. The vector length is
1521 the number of parameters given.
1524 @deffn {Scheme Procedure} u8vector-length vec
1525 @deffnx {Scheme Procedure} s8vector-length vec
1526 @deffnx {Scheme Procedure} u16vector-length vec
1527 @deffnx {Scheme Procedure} s16vector-length vec
1528 @deffnx {Scheme Procedure} u32vector-length vec
1529 @deffnx {Scheme Procedure} s32vector-length vec
1530 @deffnx {Scheme Procedure} u64vector-length vec
1531 @deffnx {Scheme Procedure} s64vector-length vec
1532 @deffnx {Scheme Procedure} f32vector-length vec
1533 @deffnx {Scheme Procedure} f64vector-length vec
1534 @deffnx {Scheme Procedure} c32vector-length vec
1535 @deffnx {Scheme Procedure} c64vector-length vec
1536 @deffnx {C Function} scm_u8vector_length (vec)
1537 @deffnx {C Function} scm_s8vector_length (vec)
1538 @deffnx {C Function} scm_u16vector_length (vec)
1539 @deffnx {C Function} scm_s16vector_length (vec)
1540 @deffnx {C Function} scm_u32vector_length (vec)
1541 @deffnx {C Function} scm_s32vector_length (vec)
1542 @deffnx {C Function} scm_u64vector_length (vec)
1543 @deffnx {C Function} scm_s64vector_length (vec)
1544 @deffnx {C Function} scm_f32vector_length (vec)
1545 @deffnx {C Function} scm_f64vector_length (vec)
1546 @deffnx {C Function} scm_c32vector_length (vec)
1547 @deffnx {C Function} scm_c64vector_length (vec)
1548 Return the number of elements in @var{vec}.
1551 @deffn {Scheme Procedure} u8vector-ref vec i
1552 @deffnx {Scheme Procedure} s8vector-ref vec i
1553 @deffnx {Scheme Procedure} u16vector-ref vec i
1554 @deffnx {Scheme Procedure} s16vector-ref vec i
1555 @deffnx {Scheme Procedure} u32vector-ref vec i
1556 @deffnx {Scheme Procedure} s32vector-ref vec i
1557 @deffnx {Scheme Procedure} u64vector-ref vec i
1558 @deffnx {Scheme Procedure} s64vector-ref vec i
1559 @deffnx {Scheme Procedure} f32vector-ref vec i
1560 @deffnx {Scheme Procedure} f64vector-ref vec i
1561 @deffnx {Scheme Procedure} c32vector-ref vec i
1562 @deffnx {Scheme Procedure} c64vector-ref vec i
1563 @deffnx {C Function} scm_u8vector_ref (vec, i)
1564 @deffnx {C Function} scm_s8vector_ref (vec, i)
1565 @deffnx {C Function} scm_u16vector_ref (vec, i)
1566 @deffnx {C Function} scm_s16vector_ref (vec, i)
1567 @deffnx {C Function} scm_u32vector_ref (vec, i)
1568 @deffnx {C Function} scm_s32vector_ref (vec, i)
1569 @deffnx {C Function} scm_u64vector_ref (vec, i)
1570 @deffnx {C Function} scm_s64vector_ref (vec, i)
1571 @deffnx {C Function} scm_f32vector_ref (vec, i)
1572 @deffnx {C Function} scm_f64vector_ref (vec, i)
1573 @deffnx {C Function} scm_c32vector_ref (vec, i)
1574 @deffnx {C Function} scm_c64vector_ref (vec, i)
1575 Return the element at index @var{i} in @var{vec}. The first element
1576 in @var{vec} is index 0.
1579 @deffn {Scheme Procedure} u8vector-set! vec i value
1580 @deffnx {Scheme Procedure} s8vector-set! vec i value
1581 @deffnx {Scheme Procedure} u16vector-set! vec i value
1582 @deffnx {Scheme Procedure} s16vector-set! vec i value
1583 @deffnx {Scheme Procedure} u32vector-set! vec i value
1584 @deffnx {Scheme Procedure} s32vector-set! vec i value
1585 @deffnx {Scheme Procedure} u64vector-set! vec i value
1586 @deffnx {Scheme Procedure} s64vector-set! vec i value
1587 @deffnx {Scheme Procedure} f32vector-set! vec i value
1588 @deffnx {Scheme Procedure} f64vector-set! vec i value
1589 @deffnx {Scheme Procedure} c32vector-set! vec i value
1590 @deffnx {Scheme Procedure} c64vector-set! vec i value
1591 @deffnx {C Function} scm_u8vector_set_x (vec, i, value)
1592 @deffnx {C Function} scm_s8vector_set_x (vec, i, value)
1593 @deffnx {C Function} scm_u16vector_set_x (vec, i, value)
1594 @deffnx {C Function} scm_s16vector_set_x (vec, i, value)
1595 @deffnx {C Function} scm_u32vector_set_x (vec, i, value)
1596 @deffnx {C Function} scm_s32vector_set_x (vec, i, value)
1597 @deffnx {C Function} scm_u64vector_set_x (vec, i, value)
1598 @deffnx {C Function} scm_s64vector_set_x (vec, i, value)
1599 @deffnx {C Function} scm_f32vector_set_x (vec, i, value)
1600 @deffnx {C Function} scm_f64vector_set_x (vec, i, value)
1601 @deffnx {C Function} scm_c32vector_set_x (vec, i, value)
1602 @deffnx {C Function} scm_c64vector_set_x (vec, i, value)
1603 Set the element at index @var{i} in @var{vec} to @var{value}. The
1604 first element in @var{vec} is index 0. The return value is
1608 @deffn {Scheme Procedure} u8vector->list vec
1609 @deffnx {Scheme Procedure} s8vector->list vec
1610 @deffnx {Scheme Procedure} u16vector->list vec
1611 @deffnx {Scheme Procedure} s16vector->list vec
1612 @deffnx {Scheme Procedure} u32vector->list vec
1613 @deffnx {Scheme Procedure} s32vector->list vec
1614 @deffnx {Scheme Procedure} u64vector->list vec
1615 @deffnx {Scheme Procedure} s64vector->list vec
1616 @deffnx {Scheme Procedure} f32vector->list vec
1617 @deffnx {Scheme Procedure} f64vector->list vec
1618 @deffnx {Scheme Procedure} c32vector->list vec
1619 @deffnx {Scheme Procedure} c64vector->list vec
1620 @deffnx {C Function} scm_u8vector_to_list (vec)
1621 @deffnx {C Function} scm_s8vector_to_list (vec)
1622 @deffnx {C Function} scm_u16vector_to_list (vec)
1623 @deffnx {C Function} scm_s16vector_to_list (vec)
1624 @deffnx {C Function} scm_u32vector_to_list (vec)
1625 @deffnx {C Function} scm_s32vector_to_list (vec)
1626 @deffnx {C Function} scm_u64vector_to_list (vec)
1627 @deffnx {C Function} scm_s64vector_to_list (vec)
1628 @deffnx {C Function} scm_f32vector_to_list (vec)
1629 @deffnx {C Function} scm_f64vector_to_list (vec)
1630 @deffnx {C Function} scm_c32vector_to_list (vec)
1631 @deffnx {C Function} scm_c64vector_to_list (vec)
1632 Return a newly allocated list holding all elements of @var{vec}.
1635 @deffn {Scheme Procedure} list->u8vector lst
1636 @deffnx {Scheme Procedure} list->s8vector lst
1637 @deffnx {Scheme Procedure} list->u16vector lst
1638 @deffnx {Scheme Procedure} list->s16vector lst
1639 @deffnx {Scheme Procedure} list->u32vector lst
1640 @deffnx {Scheme Procedure} list->s32vector lst
1641 @deffnx {Scheme Procedure} list->u64vector lst
1642 @deffnx {Scheme Procedure} list->s64vector lst
1643 @deffnx {Scheme Procedure} list->f32vector lst
1644 @deffnx {Scheme Procedure} list->f64vector lst
1645 @deffnx {Scheme Procedure} list->c32vector lst
1646 @deffnx {Scheme Procedure} list->c64vector lst
1647 @deffnx {C Function} scm_list_to_u8vector (lst)
1648 @deffnx {C Function} scm_list_to_s8vector (lst)
1649 @deffnx {C Function} scm_list_to_u16vector (lst)
1650 @deffnx {C Function} scm_list_to_s16vector (lst)
1651 @deffnx {C Function} scm_list_to_u32vector (lst)
1652 @deffnx {C Function} scm_list_to_s32vector (lst)
1653 @deffnx {C Function} scm_list_to_u64vector (lst)
1654 @deffnx {C Function} scm_list_to_s64vector (lst)
1655 @deffnx {C Function} scm_list_to_f32vector (lst)
1656 @deffnx {C Function} scm_list_to_f64vector (lst)
1657 @deffnx {C Function} scm_list_to_c32vector (lst)
1658 @deffnx {C Function} scm_list_to_c64vector (lst)
1659 Return a newly allocated homogeneous numeric vector of the indicated type,
1660 initialized with the elements of the list @var{lst}.
1663 @deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len)
1664 @deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len)
1665 @deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len)
1666 @deftypefnx {C Function} SCM scm_take_s16vector (const scm_t_int16 *data, size_t len)
1667 @deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len)
1668 @deftypefnx {C Function} SCM scm_take_s32vector (const scm_t_int32 *data, size_t len)
1669 @deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len)
1670 @deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len)
1671 @deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len)
1672 @deftypefnx {C Function} SCM scm_take_f64vector (const double *data, size_t len)
1673 @deftypefnx {C Function} SCM scm_take_c32vector (const float *data, size_t len)
1674 @deftypefnx {C Function} SCM scm_take_c64vector (const double *data, size_t len)
1675 Return a new uniform numeric vector of the indicated type and length
1676 that uses the memory pointed to by @var{data} to store its elements.
1677 This memory will eventually be freed with @code{free}. The argument
1678 @var{len} specifies the number of elements in @var{data}, not its size
1681 The @code{c32} and @code{c64} variants take a pointer to a C array of
1682 @code{float}s or @code{double}s. The real parts of the complex numbers
1683 are at even indices in that array, the corresponding imaginary parts are
1684 at the following odd index.
1687 @deftypefn {C Function} {const scm_t_uint8 *} scm_u8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1688 @deftypefnx {C Function} {const scm_t_int8 *} scm_s8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1689 @deftypefnx {C Function} {const scm_t_uint16 *} scm_u16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1690 @deftypefnx {C Function} {const scm_t_int16 *} scm_s16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1691 @deftypefnx {C Function} {const scm_t_uint32 *} scm_u32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1692 @deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1693 @deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1694 @deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1695 @deftypefnx {C Function} {const float *} scm_f32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1696 @deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1697 @deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1698 @deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1699 Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
1700 returns a pointer to the elements of a uniform numeric vector of the
1704 @deftypefn {C Function} {scm_t_uint8 *} scm_u8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1705 @deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1706 @deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1707 @deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1708 @deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1709 @deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1710 @deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1711 @deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1712 @deftypefnx {C Function} {float *} scm_f32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1713 @deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1714 @deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1715 @deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1716 Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from
1717 C}), but returns a pointer to the elements of a uniform numeric vector
1718 of the indicated kind.
1721 @node SRFI-4 Generic Operations
1722 @subsubsection SRFI-4 - Generic operations
1724 Guile also provides procedures that operate on all types of uniform numeric
1725 vectors. In what is probably a bug, these procedures are currently available in
1726 the default environment as well; however prudent hackers will make sure to
1727 import @code{(srfi srfi-4 gnu)} before using these.
1729 @deftypefn {C Function} int scm_is_uniform_vector (SCM uvec)
1730 Return non-zero when @var{uvec} is a uniform numeric vector, zero
1734 @deftypefn {C Function} size_t scm_c_uniform_vector_length (SCM uvec)
1735 Return the number of elements of @var{uvec} as a @code{size_t}.
1738 @deffn {Scheme Procedure} uniform-vector? obj
1739 @deffnx {C Function} scm_uniform_vector_p (obj)
1740 Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1744 @deffn {Scheme Procedure} uniform-vector-length vec
1745 @deffnx {C Function} scm_uniform_vector_length (vec)
1746 Return the number of elements in @var{vec}.
1749 @deffn {Scheme Procedure} uniform-vector-ref vec i
1750 @deffnx {C Function} scm_uniform_vector_ref (vec, i)
1751 Return the element at index @var{i} in @var{vec}. The first element
1752 in @var{vec} is index 0.
1755 @deffn {Scheme Procedure} uniform-vector-set! vec i value
1756 @deffnx {C Function} scm_uniform_vector_set_x (vec, i, value)
1757 Set the element at index @var{i} in @var{vec} to @var{value}. The
1758 first element in @var{vec} is index 0. The return value is
1762 @deffn {Scheme Procedure} uniform-vector->list vec
1763 @deffnx {C Function} scm_uniform_vector_to_list (vec)
1764 Return a newly allocated list holding all elements of @var{vec}.
1767 @deftypefn {C Function} {const void *} scm_uniform_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1768 Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
1769 returns a pointer to the elements of a uniform numeric vector.
1772 @deftypefn {C Function} {void *} scm_uniform_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1773 Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from
1774 C}), but returns a pointer to the elements of a uniform numeric vector.
1777 Unless you really need to the limited generality of these functions, it
1778 is best to use the type-specific functions, or the array accessors.
1780 @node SRFI-4 and Bytevectors
1781 @subsubsection SRFI-4 - Relation to bytevectors
1783 Guile implements SRFI-4 vectors using bytevectors (@pxref{Bytevectors}). Often
1784 when you have a numeric vector, you end up wanting to write its bytes somewhere,
1785 or have access to the underlying bytes, or read in bytes from somewhere else.
1786 Bytevectors are very good at this sort of thing. But the SRFI-4 APIs are nicer
1787 to use when doing number-crunching, because they are addressed by element and
1790 So as a compromise, Guile allows all bytevector functions to operate on numeric
1791 vectors. They address the underlying bytes in the native endianness, as one
1794 Following the same reasoning, that it's just bytes underneath, Guile also allows
1795 uniform vectors of a given type to be accessed as if they were of any type. One
1796 can fill a @nicode{u32vector}, and access its elements with
1797 @nicode{u8vector-ref}. One can use @nicode{f64vector-ref} on bytevectors. It's
1798 all the same to Guile.
1800 In this way, uniform numeric vectors may be written to and read from
1801 input/output ports using the procedures that operate on bytevectors.
1803 @xref{Bytevectors}, for more information.
1806 @node SRFI-4 Extensions
1807 @subsubsection SRFI-4 - Guile extensions
1809 Guile defines some useful extensions to SRFI-4, which are not available in the
1810 default Guile environment. They may be imported by loading the extensions
1814 (use-modules (srfi srfi-4 gnu))
1817 @deffn {Scheme Procedure} any->u8vector obj
1818 @deffnx {Scheme Procedure} any->s8vector obj
1819 @deffnx {Scheme Procedure} any->u16vector obj
1820 @deffnx {Scheme Procedure} any->s16vector obj
1821 @deffnx {Scheme Procedure} any->u32vector obj
1822 @deffnx {Scheme Procedure} any->s32vector obj
1823 @deffnx {Scheme Procedure} any->u64vector obj
1824 @deffnx {Scheme Procedure} any->s64vector obj
1825 @deffnx {Scheme Procedure} any->f32vector obj
1826 @deffnx {Scheme Procedure} any->f64vector obj
1827 @deffnx {Scheme Procedure} any->c32vector obj
1828 @deffnx {Scheme Procedure} any->c64vector obj
1829 @deffnx {C Function} scm_any_to_u8vector (obj)
1830 @deffnx {C Function} scm_any_to_s8vector (obj)
1831 @deffnx {C Function} scm_any_to_u16vector (obj)
1832 @deffnx {C Function} scm_any_to_s16vector (obj)
1833 @deffnx {C Function} scm_any_to_u32vector (obj)
1834 @deffnx {C Function} scm_any_to_s32vector (obj)
1835 @deffnx {C Function} scm_any_to_u64vector (obj)
1836 @deffnx {C Function} scm_any_to_s64vector (obj)
1837 @deffnx {C Function} scm_any_to_f32vector (obj)
1838 @deffnx {C Function} scm_any_to_f64vector (obj)
1839 @deffnx {C Function} scm_any_to_c32vector (obj)
1840 @deffnx {C Function} scm_any_to_c64vector (obj)
1841 Return a (maybe newly allocated) uniform numeric vector of the indicated
1842 type, initialized with the elements of @var{obj}, which must be a list,
1843 a vector, or a uniform vector. When @var{obj} is already a suitable
1844 uniform numeric vector, it is returned unchanged.
1849 @subsection SRFI-6 - Basic String Ports
1852 SRFI-6 defines the procedures @code{open-input-string},
1853 @code{open-output-string} and @code{get-output-string}.
1855 Note that although versions of these procedures are included in the
1856 Guile core, the core versions are not fully conformant with SRFI-6:
1857 attempts to read or write characters that are not supported by the
1858 current @code{%default-port-encoding} will fail.
1860 We therefore recommend that you import this module, which supports all
1864 (use-modules (srfi srfi-6))
1868 @subsection SRFI-8 - receive
1871 @code{receive} is a syntax for making the handling of multiple-value
1872 procedures easier. It is documented in @xref{Multiple Values}.
1876 @subsection SRFI-9 - define-record-type
1878 This SRFI is a syntax for defining new record types and creating
1879 predicate, constructor, and field getter and setter functions. It is
1880 documented in the ``Compound Data Types'' section of the manual
1881 (@pxref{SRFI-9 Records}).
1885 @subsection SRFI-10 - Hash-Comma Reader Extension
1890 This SRFI implements a reader extension @code{#,()} called hash-comma.
1891 It allows the reader to give new kinds of objects, for use both in
1892 data and as constants or literals in source code. This feature is
1896 (use-modules (srfi srfi-10))
1900 The new read syntax is of the form
1903 #,(@var{tag} @var{arg}@dots{})
1907 where @var{tag} is a symbol and the @var{arg}s are objects taken as
1908 parameters. @var{tag}s are registered with the following procedure.
1910 @deffn {Scheme Procedure} define-reader-ctor tag proc
1911 Register @var{proc} as the constructor for a hash-comma read syntax
1912 starting with symbol @var{tag}, i.e.@: @nicode{#,(@var{tag} arg@dots{})}.
1913 @var{proc} is called with the given arguments @code{(@var{proc}
1914 arg@dots{})} and the object it returns is the result of the read.
1918 For example, a syntax giving a list of @var{N} copies of an object.
1921 (define-reader-ctor 'repeat
1923 (make-list reps obj)))
1925 (display '#,(repeat 99 3))
1929 Notice the quote @nicode{'} when the @nicode{#,( )} is used. The
1930 @code{repeat} handler returns a list and the program must quote to use
1931 it literally, the same as any other list. Ie.
1934 (display '#,(repeat 99 3))
1936 (display '(99 99 99))
1939 When a handler returns an object which is self-evaluating, like a
1940 number or a string, then there's no need for quoting, just as there's
1941 no need when giving those directly as literals. For example an
1945 (define-reader-ctor 'sum
1948 (display #,(sum 123 456)) @print{} 579
1951 A typical use for @nicode{#,()} is to get a read syntax for objects
1952 which don't otherwise have one. For example, the following allows a
1953 hash table to be given literally, with tags and values, ready for fast
1957 (define-reader-ctor 'hash
1959 (let ((table (make-hash-table)))
1960 (for-each (lambda (elem)
1961 (apply hash-set! table elem))
1965 (define (animal->family animal)
1966 (hash-ref '#,(hash ("tiger" "cat")
1971 (animal->family "lion") @result{} "cat"
1974 Or for example the following is a syntax for a compiled regular
1975 expression (@pxref{Regular Expressions}).
1978 (use-modules (ice-9 regex))
1980 (define-reader-ctor 'regexp make-regexp)
1982 (define (extract-angs str)
1983 (let ((match (regexp-exec '#,(regexp "<([A-Z0-9]+)>") str)))
1985 (match:substring match 1))))
1987 (extract-angs "foo <BAR> quux") @result{} "BAR"
1991 @nicode{#,()} is somewhat similar to @code{define-macro}
1992 (@pxref{Macros}) in that handler code is run to produce a result, but
1993 @nicode{#,()} operates at the read stage, so it can appear in data for
1994 @code{read} (@pxref{Scheme Read}), not just in code to be executed.
1996 Because @nicode{#,()} is handled at read-time it has no direct access
1997 to variables etc. A symbol in the arguments is just a symbol, not a
1998 variable reference. The arguments are essentially constants, though
1999 the handler procedure can use them in any complicated way it might
2002 Once @code{(srfi srfi-10)} has loaded, @nicode{#,()} is available
2003 globally, there's no need to use @code{(srfi srfi-10)} in later
2004 modules. Similarly the tags registered are global and can be used
2005 anywhere once registered.
2007 There's no attempt to record what previous @nicode{#,()} forms have
2008 been seen, if two identical forms occur then two calls are made to the
2009 handler procedure. The handler might like to maintain a cache or
2010 similar to avoid making copies of large objects, depending on expected
2013 In code the best uses of @nicode{#,()} are generally when there's a
2014 lot of objects of a particular kind as literals or constants. If
2015 there's just a few then some local variables and initializers are
2016 fine, but that becomes tedious and error prone when there's a lot, and
2017 the anonymous and compact syntax of @nicode{#,()} is much better.
2021 @subsection SRFI-11 - let-values
2026 This module implements the binding forms for multiple values
2027 @code{let-values} and @code{let*-values}. These forms are similar to
2028 @code{let} and @code{let*} (@pxref{Local Bindings}), but they support
2029 binding of the values returned by multiple-valued expressions.
2031 Write @code{(use-modules (srfi srfi-11))} to make the bindings
2035 (let-values (((x y) (values 1 2))
2036 ((z f) (values 3 4)))
2042 @code{let-values} performs all bindings simultaneously, which means that
2043 no expression in the binding clauses may refer to variables bound in the
2044 same clause list. @code{let*-values}, on the other hand, performs the
2045 bindings sequentially, just like @code{let*} does for single-valued
2050 @subsection SRFI-13 - String Library
2053 The SRFI-13 procedures are always available, @xref{Strings}.
2056 @subsection SRFI-14 - Character-set Library
2059 The SRFI-14 data type and procedures are always available,
2060 @xref{Character Sets}.
2063 @subsection SRFI-16 - case-lambda
2065 @cindex variable arity
2066 @cindex arity, variable
2068 SRFI-16 defines a variable-arity @code{lambda} form,
2069 @code{case-lambda}. This form is available in the default Guile
2070 environment. @xref{Case-lambda}, for more information.
2073 @subsection SRFI-17 - Generalized set!
2076 This SRFI implements a generalized @code{set!}, allowing some
2077 ``referencing'' functions to be used as the target location of a
2078 @code{set!}. This feature is available from
2081 (use-modules (srfi srfi-17))
2085 For example @code{vector-ref} is extended so that
2088 (set! (vector-ref vec idx) new-value)
2095 (vector-set! vec idx new-value)
2098 The idea is that a @code{vector-ref} expression identifies a location,
2099 which may be either fetched or stored. The same form is used for the
2100 location in both cases, encouraging visual clarity. This is similar
2101 to the idea of an ``lvalue'' in C.
2103 The mechanism for this kind of @code{set!} is in the Guile core
2104 (@pxref{Procedures with Setters}). This module adds definitions of
2105 the following functions as procedures with setters, allowing them to
2106 be targets of a @code{set!},
2109 @nicode{car}, @nicode{cdr}, @nicode{caar}, @nicode{cadr},
2110 @nicode{cdar}, @nicode{cddr}, @nicode{caaar}, @nicode{caadr},
2111 @nicode{cadar}, @nicode{caddr}, @nicode{cdaar}, @nicode{cdadr},
2112 @nicode{cddar}, @nicode{cdddr}, @nicode{caaaar}, @nicode{caaadr},
2113 @nicode{caadar}, @nicode{caaddr}, @nicode{cadaar}, @nicode{cadadr},
2114 @nicode{caddar}, @nicode{cadddr}, @nicode{cdaaar}, @nicode{cdaadr},
2115 @nicode{cdadar}, @nicode{cdaddr}, @nicode{cddaar}, @nicode{cddadr},
2116 @nicode{cdddar}, @nicode{cddddr}
2118 @nicode{string-ref}, @nicode{vector-ref}
2121 The SRFI specifies @code{setter} (@pxref{Procedures with Setters}) as
2122 a procedure with setter, allowing the setter for a procedure to be
2123 changed, eg.@: @code{(set! (setter foo) my-new-setter-handler)}.
2124 Currently Guile does not implement this, a setter can only be
2125 specified on creation (@code{getter-with-setter} below).
2127 @defun getter-with-setter
2128 The same as the Guile core @code{make-procedure-with-setter}
2129 (@pxref{Procedures with Setters}).
2134 @subsection SRFI-18 - Multithreading support
2137 This is an implementation of the SRFI-18 threading and synchronization
2138 library. The functions and variables described here are provided by
2141 (use-modules (srfi srfi-18))
2144 As a general rule, the data types and functions in this SRFI-18
2145 implementation are compatible with the types and functions in Guile's
2146 core threading code. For example, mutexes created with the SRFI-18
2147 @code{make-mutex} function can be passed to the built-in Guile
2148 function @code{lock-mutex} (@pxref{Mutexes and Condition Variables}),
2149 and mutexes created with the built-in Guile function @code{make-mutex}
2150 can be passed to the SRFI-18 function @code{mutex-lock!}. Cases in
2151 which this does not hold true are noted in the following sections.
2154 * SRFI-18 Threads:: Executing code
2155 * SRFI-18 Mutexes:: Mutual exclusion devices
2156 * SRFI-18 Condition variables:: Synchronizing of groups of threads
2157 * SRFI-18 Time:: Representation of times and durations
2158 * SRFI-18 Exceptions:: Signalling and handling errors
2161 @node SRFI-18 Threads
2162 @subsubsection SRFI-18 Threads
2164 Threads created by SRFI-18 differ in two ways from threads created by
2165 Guile's built-in thread functions. First, a thread created by SRFI-18
2166 @code{make-thread} begins in a blocked state and will not start
2167 execution until @code{thread-start!} is called on it. Second, SRFI-18
2168 threads are constructed with a top-level exception handler that
2169 captures any exceptions that are thrown on thread exit. In all other
2170 regards, SRFI-18 threads are identical to normal Guile threads.
2172 @defun current-thread
2173 Returns the thread that called this function. This is the same
2174 procedure as the same-named built-in procedure @code{current-thread}
2179 Returns @code{#t} if @var{obj} is a thread, @code{#f} otherwise. This
2180 is the same procedure as the same-named built-in procedure
2181 @code{thread?} (@pxref{Threads}).
2184 @defun make-thread thunk [name]
2185 Call @code{thunk} in a new thread and with a new dynamic state,
2186 returning the new thread and optionally assigning it the object name
2187 @var{name}, which may be any Scheme object.
2189 Note that the name @code{make-thread} conflicts with the
2190 @code{(ice-9 threads)} function @code{make-thread}. Applications
2191 wanting to use both of these functions will need to refer to them by
2195 @defun thread-name thread
2196 Returns the name assigned to @var{thread} at the time of its creation,
2197 or @code{#f} if it was not given a name.
2200 @defun thread-specific thread
2201 @defunx thread-specific-set! thread obj
2202 Get or set the ``object-specific'' property of @var{thread}. In
2203 Guile's implementation of SRFI-18, this value is stored as an object
2204 property, and will be @code{#f} if not set.
2207 @defun thread-start! thread
2208 Unblocks @var{thread} and allows it to begin execution if it has not
2212 @defun thread-yield!
2213 If one or more threads are waiting to execute, calling
2214 @code{thread-yield!} forces an immediate context switch to one of them.
2215 Otherwise, @code{thread-yield!} has no effect. @code{thread-yield!}
2216 behaves identically to the Guile built-in function @code{yield}.
2219 @defun thread-sleep! timeout
2220 The current thread waits until the point specified by the time object
2221 @var{timeout} is reached (@pxref{SRFI-18 Time}). This blocks the
2222 thread only if @var{timeout} represents a point in the future. it is
2223 an error for @var{timeout} to be @code{#f}.
2226 @defun thread-terminate! thread
2227 Causes an abnormal termination of @var{thread}. If @var{thread} is
2228 not already terminated, all mutexes owned by @var{thread} become
2229 unlocked/abandoned. If @var{thread} is the current thread,
2230 @code{thread-terminate!} does not return. Otherwise
2231 @code{thread-terminate!} returns an unspecified value; the termination
2232 of @var{thread} will occur before @code{thread-terminate!} returns.
2233 Subsequent attempts to join on @var{thread} will cause a ``terminated
2234 thread exception'' to be raised.
2236 @code{thread-terminate!} is compatible with the thread cancellation
2237 procedures in the core threads API (@pxref{Threads}) in that if a
2238 cleanup handler has been installed for the target thread, it will be
2239 called before the thread exits and its return value (or exception, if
2240 any) will be stored for later retrieval via a call to
2241 @code{thread-join!}.
2244 @defun thread-join! thread [timeout [timeout-val]]
2245 Wait for @var{thread} to terminate and return its exit value. When a
2246 time value @var{timeout} is given, it specifies a point in time where
2247 the waiting should be aborted. When the waiting is aborted,
2248 @var{timeout-val} is returned if it is specified; otherwise, a
2249 @code{join-timeout-exception} exception is raised
2250 (@pxref{SRFI-18 Exceptions}). Exceptions may also be raised if the
2251 thread was terminated by a call to @code{thread-terminate!}
2252 (@code{terminated-thread-exception} will be raised) or if the thread
2253 exited by raising an exception that was handled by the top-level
2254 exception handler (@code{uncaught-exception} will be raised; the
2255 original exception can be retrieved using
2256 @code{uncaught-exception-reason}).
2260 @node SRFI-18 Mutexes
2261 @subsubsection SRFI-18 Mutexes
2263 The behavior of Guile's built-in mutexes is parameterized via a set of
2264 flags passed to the @code{make-mutex} procedure in the core
2265 (@pxref{Mutexes and Condition Variables}). To satisfy the requirements
2266 for mutexes specified by SRFI-18, the @code{make-mutex} procedure
2267 described below sets the following flags:
2270 @code{recursive}: the mutex can be locked recursively
2272 @code{unchecked-unlock}: attempts to unlock a mutex that is already
2273 unlocked will not raise an exception
2275 @code{allow-external-unlock}: the mutex can be unlocked by any thread,
2276 not just the thread that locked it originally
2279 @defun make-mutex [name]
2280 Returns a new mutex, optionally assigning it the object name
2281 @var{name}, which may be any Scheme object. The returned mutex will be
2282 created with the configuration described above. Note that the name
2283 @code{make-mutex} conflicts with Guile core function @code{make-mutex}.
2284 Applications wanting to use both of these functions will need to refer
2285 to them by different names.
2288 @defun mutex-name mutex
2289 Returns the name assigned to @var{mutex} at the time of its creation,
2290 or @code{#f} if it was not given a name.
2293 @defun mutex-specific mutex
2294 @defunx mutex-specific-set! mutex obj
2295 Get or set the ``object-specific'' property of @var{mutex}. In Guile's
2296 implementation of SRFI-18, this value is stored as an object property,
2297 and will be @code{#f} if not set.
2300 @defun mutex-state mutex
2301 Returns information about the state of @var{mutex}. Possible values
2305 thread @code{T}: the mutex is in the locked/owned state and thread T
2306 is the owner of the mutex
2308 symbol @code{not-owned}: the mutex is in the locked/not-owned state
2310 symbol @code{abandoned}: the mutex is in the unlocked/abandoned state
2312 symbol @code{not-abandoned}: the mutex is in the
2313 unlocked/not-abandoned state
2317 @defun mutex-lock! mutex [timeout [thread]]
2318 Lock @var{mutex}, optionally specifying a time object @var{timeout}
2319 after which to abort the lock attempt and a thread @var{thread} giving
2320 a new owner for @var{mutex} different than the current thread. This
2321 procedure has the same behavior as the @code{lock-mutex} procedure in
2325 @defun mutex-unlock! mutex [condition-variable [timeout]]
2326 Unlock @var{mutex}, optionally specifying a condition variable
2327 @var{condition-variable} on which to wait, either indefinitely or,
2328 optionally, until the time object @var{timeout} has passed, to be
2329 signalled. This procedure has the same behavior as the
2330 @code{unlock-mutex} procedure in the core library.
2334 @node SRFI-18 Condition variables
2335 @subsubsection SRFI-18 Condition variables
2337 SRFI-18 does not specify a ``wait'' function for condition variables.
2338 Waiting on a condition variable can be simulated using the SRFI-18
2339 @code{mutex-unlock!} function described in the previous section, or
2340 Guile's built-in @code{wait-condition-variable} procedure can be used.
2342 @defun condition-variable? obj
2343 Returns @code{#t} if @var{obj} is a condition variable, @code{#f}
2344 otherwise. This is the same procedure as the same-named built-in
2346 (@pxref{Mutexes and Condition Variables, @code{condition-variable?}}).
2349 @defun make-condition-variable [name]
2350 Returns a new condition variable, optionally assigning it the object
2351 name @var{name}, which may be any Scheme object. This procedure
2352 replaces a procedure of the same name in the core library.
2355 @defun condition-variable-name condition-variable
2356 Returns the name assigned to @var{condition-variable} at the time of its
2357 creation, or @code{#f} if it was not given a name.
2360 @defun condition-variable-specific condition-variable
2361 @defunx condition-variable-specific-set! condition-variable obj
2362 Get or set the ``object-specific'' property of
2363 @var{condition-variable}. In Guile's implementation of SRFI-18, this
2364 value is stored as an object property, and will be @code{#f} if not
2368 @defun condition-variable-signal! condition-variable
2369 @defunx condition-variable-broadcast! condition-variable
2370 Wake up one thread that is waiting for @var{condition-variable}, in
2371 the case of @code{condition-variable-signal!}, or all threads waiting
2372 for it, in the case of @code{condition-variable-broadcast!}. The
2373 behavior of these procedures is equivalent to that of the procedures
2374 @code{signal-condition-variable} and
2375 @code{broadcast-condition-variable} in the core library.
2380 @subsubsection SRFI-18 Time
2382 The SRFI-18 time functions manipulate time in two formats: a
2383 ``time object'' type that represents an absolute point in time in some
2384 implementation-specific way; and the number of seconds since some
2385 unspecified ``epoch''. In Guile's implementation, the epoch is the
2386 Unix epoch, 00:00:00 UTC, January 1, 1970.
2389 Return the current time as a time object. This procedure replaces
2390 the procedure of the same name in the core library, which returns the
2391 current time in seconds since the epoch.
2395 Returns @code{#t} if @var{obj} is a time object, @code{#f} otherwise.
2398 @defun time->seconds time
2399 @defunx seconds->time seconds
2400 Convert between time objects and numerical values representing the
2401 number of seconds since the epoch. When converting from a time object
2402 to seconds, the return value is the number of seconds between
2403 @var{time} and the epoch. When converting from seconds to a time
2404 object, the return value is a time object that represents a time
2405 @var{seconds} seconds after the epoch.
2409 @node SRFI-18 Exceptions
2410 @subsubsection SRFI-18 Exceptions
2412 SRFI-18 exceptions are identical to the exceptions provided by
2413 Guile's implementation of SRFI-34. The behavior of exception
2414 handlers invoked to handle exceptions thrown from SRFI-18 functions,
2415 however, differs from the conventional behavior of SRFI-34 in that
2416 the continuation of the handler is the same as that of the call to
2417 the function. Handlers are called in a tail-recursive manner; the
2418 exceptions do not ``bubble up''.
2420 @defun current-exception-handler
2421 Returns the current exception handler.
2424 @defun with-exception-handler handler thunk
2425 Installs @var{handler} as the current exception handler and calls the
2426 procedure @var{thunk} with no arguments, returning its value as the
2427 value of the exception. @var{handler} must be a procedure that accepts
2428 a single argument. The current exception handler at the time this
2429 procedure is called will be restored after the call returns.
2433 Raise @var{obj} as an exception. This is the same procedure as the
2434 same-named procedure defined in SRFI 34.
2437 @defun join-timeout-exception? obj
2438 Returns @code{#t} if @var{obj} is an exception raised as the result of
2439 performing a timed join on a thread that does not exit within the
2440 specified timeout, @code{#f} otherwise.
2443 @defun abandoned-mutex-exception? obj
2444 Returns @code{#t} if @var{obj} is an exception raised as the result of
2445 attempting to lock a mutex that has been abandoned by its owner thread,
2446 @code{#f} otherwise.
2449 @defun terminated-thread-exception? obj
2450 Returns @code{#t} if @var{obj} is an exception raised as the result of
2451 joining on a thread that exited as the result of a call to
2452 @code{thread-terminate!}.
2455 @defun uncaught-exception? obj
2456 @defunx uncaught-exception-reason exc
2457 @code{uncaught-exception?} returns @code{#t} if @var{obj} is an
2458 exception thrown as the result of joining a thread that exited by
2459 raising an exception that was handled by the top-level exception
2460 handler installed by @code{make-thread}. When this occurs, the
2461 original exception is preserved as part of the exception thrown by
2462 @code{thread-join!} and can be accessed by calling
2463 @code{uncaught-exception-reason} on that exception. Note that
2464 because this exception-preservation mechanism is a side-effect of
2465 @code{make-thread}, joining on threads that exited as described above
2466 but were created by other means will not raise this
2467 @code{uncaught-exception} error.
2472 @subsection SRFI-19 - Time/Date Library
2477 This is an implementation of the SRFI-19 time/date library. The
2478 functions and variables described here are provided by
2481 (use-modules (srfi srfi-19))
2484 @strong{Caution}: The current code in this module incorrectly extends
2485 the Gregorian calendar leap year rule back prior to the introduction
2486 of those reforms in 1582 (or the appropriate year in various
2487 countries). The Julian calendar was used prior to 1582, and there
2488 were 10 days skipped for the reform, but the code doesn't implement
2491 This will be fixed some time. Until then calculations for 1583
2492 onwards are correct, but prior to that any day/month/year and day of
2493 the week calculations are wrong.
2496 * SRFI-19 Introduction::
2499 * SRFI-19 Time/Date conversions::
2500 * SRFI-19 Date to string::
2501 * SRFI-19 String to date::
2504 @node SRFI-19 Introduction
2505 @subsubsection SRFI-19 Introduction
2507 @cindex universal time
2511 This module implements time and date representations and calculations,
2512 in various time systems, including universal time (UTC) and atomic
2515 For those not familiar with these time systems, TAI is based on a
2516 fixed length second derived from oscillations of certain atoms. UTC
2517 differs from TAI by an integral number of seconds, which is increased
2518 or decreased at announced times to keep UTC aligned to a mean solar
2519 day (the orbit and rotation of the earth are not quite constant).
2522 So far, only increases in the TAI
2529 UTC difference have been needed. Such an increase is a ``leap
2530 second'', an extra second of TAI introduced at the end of a UTC day.
2531 When working entirely within UTC this is never seen, every day simply
2532 has 86400 seconds. But when converting from TAI to a UTC date, an
2533 extra 23:59:60 is present, where normally a day would end at 23:59:59.
2534 Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI
2537 @cindex system clock
2538 In the current implementation, the system clock is assumed to be UTC,
2539 and a table of leap seconds in the code converts to TAI. See comments
2540 in @file{srfi-19.scm} for how to update this table.
2543 @cindex modified julian day
2544 Also, for those not familiar with the terminology, a @dfn{Julian Day}
2545 is a real number which is a count of days and fraction of a day, in
2546 UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan
2547 4713 B.C. A @dfn{Modified Julian Day} is the same, but starting from
2548 1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC. That time
2549 is julian day 2400000.5.
2551 @c The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at
2552 @c noon, UTC), but this is incorrect. It looks like it might have
2553 @c arisen from the code incorrectly treating years a multiple of 100
2554 @c but not 400 prior to 1582 as non-leap years, where instead the Julian
2555 @c calendar should be used so all multiples of 4 before 1582 are leap
2560 @subsubsection SRFI-19 Time
2563 A @dfn{time} object has type, seconds and nanoseconds fields
2564 representing a point in time starting from some epoch. This is an
2565 arbitrary point in time, not just a time of day. Although times are
2566 represented in nanoseconds, the actual resolution may be lower.
2568 The following variables hold the possible time types. For instance
2569 @code{(current-time time-process)} would give the current CPU process
2573 Universal Coordinated Time (UTC).
2578 International Atomic Time (TAI).
2582 @defvar time-monotonic
2583 Monotonic time, meaning a monotonically increasing time starting from
2584 an unspecified epoch.
2586 Note that in the current implementation @code{time-monotonic} is the
2587 same as @code{time-tai}, and unfortunately is therefore affected by
2588 adjustments to the system clock. Perhaps this will change in the
2592 @defvar time-duration
2593 A duration, meaning simply a difference between two times.
2596 @defvar time-process
2597 CPU time spent in the current process, starting from when the process
2599 @cindex process time
2603 CPU time spent in the current thread. Not currently implemented.
2609 Return @code{#t} if @var{obj} is a time object, or @code{#f} if not.
2612 @defun make-time type nanoseconds seconds
2613 Create a time object with the given @var{type}, @var{seconds} and
2617 @defun time-type time
2618 @defunx time-nanosecond time
2619 @defunx time-second time
2620 @defunx set-time-type! time type
2621 @defunx set-time-nanosecond! time nsec
2622 @defunx set-time-second! time sec
2623 Get or set the type, seconds or nanoseconds fields of a time object.
2625 @code{set-time-type!} merely changes the field, it doesn't convert the
2626 time value. For conversions, see @ref{SRFI-19 Time/Date conversions}.
2629 @defun copy-time time
2630 Return a new time object, which is a copy of the given @var{time}.
2633 @defun current-time [type]
2634 Return the current time of the given @var{type}. The default
2635 @var{type} is @code{time-utc}.
2637 Note that the name @code{current-time} conflicts with the Guile core
2638 @code{current-time} function (@pxref{Time}) as well as the SRFI-18
2639 @code{current-time} function (@pxref{SRFI-18 Time}). Applications
2640 wanting to use more than one of these functions will need to refer to
2641 them by different names.
2644 @defun time-resolution [type]
2645 Return the resolution, in nanoseconds, of the given time @var{type}.
2646 The default @var{type} is @code{time-utc}.
2649 @defun time<=? t1 t2
2650 @defunx time<? t1 t2
2651 @defunx time=? t1 t2
2652 @defunx time>=? t1 t2
2653 @defunx time>? t1 t2
2654 Return @code{#t} or @code{#f} according to the respective relation
2655 between time objects @var{t1} and @var{t2}. @var{t1} and @var{t2}
2656 must be the same time type.
2659 @defun time-difference t1 t2
2660 @defunx time-difference! t1 t2
2661 Return a time object of type @code{time-duration} representing the
2662 period between @var{t1} and @var{t2}. @var{t1} and @var{t2} must be
2665 @code{time-difference} returns a new time object,
2666 @code{time-difference!} may modify @var{t1} to form its return.
2669 @defun add-duration time duration
2670 @defunx add-duration! time duration
2671 @defunx subtract-duration time duration
2672 @defunx subtract-duration! time duration
2673 Return a time object which is @var{time} with the given @var{duration}
2674 added or subtracted. @var{duration} must be a time object of type
2675 @code{time-duration}.
2677 @code{add-duration} and @code{subtract-duration} return a new time
2678 object. @code{add-duration!} and @code{subtract-duration!} may modify
2679 the given @var{time} to form their return.
2684 @subsubsection SRFI-19 Date
2687 A @dfn{date} object represents a date in the Gregorian calendar and a
2688 time of day on that date in some timezone.
2690 The fields are year, month, day, hour, minute, second, nanoseconds and
2691 timezone. A date object is immutable, its fields can be read but they
2692 cannot be modified once the object is created.
2695 Return @code{#t} if @var{obj} is a date object, or @code{#f} if not.
2698 @defun make-date nsecs seconds minutes hours date month year zone-offset
2699 Create a new date object.
2701 @c FIXME: What can we say about the ranges of the values. The
2702 @c current code looks it doesn't normalize, but expects then in their
2703 @c usual range already.
2707 @defun date-nanosecond date
2708 Nanoseconds, 0 to 999999999.
2711 @defun date-second date
2712 Seconds, 0 to 59, or 60 for a leap second. 60 is never seen when working
2713 entirely within UTC, it's only when converting to or from TAI.
2716 @defun date-minute date
2720 @defun date-hour date
2724 @defun date-day date
2725 Day of the month, 1 to 31 (or less, according to the month).
2728 @defun date-month date
2732 @defun date-year date
2733 Year, eg.@: 2003. Dates B.C.@: are negative, eg.@: @math{-46} is 46
2734 B.C. There is no year 0, year @math{-1} is followed by year 1.
2737 @defun date-zone-offset date
2738 Time zone, an integer number of seconds east of Greenwich.
2741 @defun date-year-day date
2742 Day of the year, starting from 1 for 1st January.
2745 @defun date-week-day date
2746 Day of the week, starting from 0 for Sunday.
2749 @defun date-week-number date dstartw
2750 Week of the year, ignoring a first partial week. @var{dstartw} is the
2751 day of the week which is taken to start a week, 0 for Sunday, 1 for
2754 @c FIXME: The spec doesn't say whether numbering starts at 0 or 1.
2755 @c The code looks like it's 0, if that's the correct intention.
2759 @c The SRFI text doesn't actually give the default for tz-offset, but
2760 @c the reference implementation has the local timezone and the
2761 @c conversions functions all specify that, so it should be ok to
2762 @c document it here.
2764 @defun current-date [tz-offset]
2765 Return a date object representing the current date/time, in UTC offset
2766 by @var{tz-offset}. @var{tz-offset} is seconds east of Greenwich and
2767 defaults to the local timezone.
2770 @defun current-julian-day
2772 Return the current Julian Day.
2775 @defun current-modified-julian-day
2776 @cindex modified julian day
2777 Return the current Modified Julian Day.
2781 @node SRFI-19 Time/Date conversions
2782 @subsubsection SRFI-19 Time/Date conversions
2783 @cindex time conversion
2784 @cindex date conversion
2786 @defun date->julian-day date
2787 @defunx date->modified-julian-day date
2788 @defunx date->time-monotonic date
2789 @defunx date->time-tai date
2790 @defunx date->time-utc date
2792 @defun julian-day->date jdn [tz-offset]
2793 @defunx julian-day->time-monotonic jdn
2794 @defunx julian-day->time-tai jdn
2795 @defunx julian-day->time-utc jdn
2797 @defun modified-julian-day->date jdn [tz-offset]
2798 @defunx modified-julian-day->time-monotonic jdn
2799 @defunx modified-julian-day->time-tai jdn
2800 @defunx modified-julian-day->time-utc jdn
2802 @defun time-monotonic->date time [tz-offset]
2803 @defunx time-monotonic->time-tai time
2804 @defunx time-monotonic->time-tai! time
2805 @defunx time-monotonic->time-utc time
2806 @defunx time-monotonic->time-utc! time
2808 @defun time-tai->date time [tz-offset]
2809 @defunx time-tai->julian-day time
2810 @defunx time-tai->modified-julian-day time
2811 @defunx time-tai->time-monotonic time
2812 @defunx time-tai->time-monotonic! time
2813 @defunx time-tai->time-utc time
2814 @defunx time-tai->time-utc! time
2816 @defun time-utc->date time [tz-offset]
2817 @defunx time-utc->julian-day time
2818 @defunx time-utc->modified-julian-day time
2819 @defunx time-utc->time-monotonic time
2820 @defunx time-utc->time-monotonic! time
2821 @defunx time-utc->time-tai time
2822 @defunx time-utc->time-tai! time
2824 Convert between dates, times and days of the respective types. For
2825 instance @code{time-tai->time-utc} accepts a @var{time} object of type
2826 @code{time-tai} and returns an object of type @code{time-utc}.
2828 The @code{!} variants may modify their @var{time} argument to form
2829 their return. The plain functions create a new object.
2831 For conversions to dates, @var{tz-offset} is seconds east of
2832 Greenwich. The default is the local timezone, at the given time, as
2833 provided by the system, using @code{localtime} (@pxref{Time}).
2835 On 32-bit systems, @code{localtime} is limited to a 32-bit
2836 @code{time_t}, so a default @var{tz-offset} is only available for
2837 times between Dec 1901 and Jan 2038. For prior dates an application
2838 might like to use the value in 1902, though some locations have zone
2839 changes prior to that. For future dates an application might like to
2840 assume today's rules extend indefinitely. But for correct daylight
2841 savings transitions it will be necessary to take an offset for the
2842 same day and time but a year in range and which has the same starting
2843 weekday and same leap/non-leap (to support rules like last Sunday in
2847 @node SRFI-19 Date to string
2848 @subsubsection SRFI-19 Date to string
2849 @cindex date to string
2850 @cindex string, from date
2852 @defun date->string date [format]
2853 Convert a date to a string under the control of a format.
2854 @var{format} should be a string containing @samp{~} escapes, which
2855 will be expanded as per the following conversion table. The default
2856 @var{format} is @samp{~c}, a locale-dependent date and time.
2858 Many of these conversion characters are the same as POSIX
2859 @code{strftime} (@pxref{Time}), but there are some extras and some
2862 @multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM}
2863 @item @nicode{~~} @tab literal ~
2864 @item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun}
2865 @item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday}
2866 @item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan}
2867 @item @nicode{~B} @tab locale full month, eg.@: @samp{January}
2868 @item @nicode{~c} @tab locale date and time, eg.@: @*
2869 @samp{Fri Jul 14 20:28:42-0400 2000}
2870 @item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31}
2872 @c Spec says d/m/y, reference implementation says m/d/y.
2873 @c Apparently the reference code was the intention, but would like to
2874 @c see an errata published for the spec before contradicting it here.
2876 @c @item @nicode{~D} @tab date @nicode{~d/~m/~y}
2878 @item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31}
2879 @item @nicode{~f} @tab seconds and fractional seconds,
2880 with locale decimal point, eg.@: @samp{5.2}
2881 @item @nicode{~h} @tab same as @nicode{~b}
2882 @item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23}
2883 @item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12}
2884 @item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366}
2885 @item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23}
2886 @item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12}
2887 @item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12}
2888 @item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59}
2889 @item @nicode{~n} @tab newline
2890 @item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999}
2891 @item @nicode{~p} @tab locale AM or PM
2892 @item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p}
2893 @item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC
2894 @item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @*
2895 (usual limit is 59, 60 is a leap second)
2896 @item @nicode{~t} @tab horizontal tab character
2897 @item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S}
2898 @item @nicode{~U} @tab week of year, Sunday first day of week,
2899 @samp{00} to @samp{52}
2900 @item @nicode{~V} @tab week of year, Monday first day of week,
2901 @samp{01} to @samp{53}
2902 @item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6}
2903 @item @nicode{~W} @tab week of year, Monday first day of week,
2904 @samp{00} to @samp{52}
2906 @c The spec has ~x as an apparent duplicate of ~W, and ~X as a locale
2907 @c date. The reference code has ~x as the locale date and ~X as a
2908 @c locale time. The rule is apparently that the code should be
2909 @c believed, but would like to see an errata for the spec before
2910 @c contradicting it here.
2912 @c @item @nicode{~x} @tab week of year, Monday as first day of week,
2913 @c @samp{00} to @samp{53}
2914 @c @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00}
2916 @item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99}
2917 @item @nicode{~Y} @tab year, full, eg.@: @samp{2003}
2918 @item @nicode{~z} @tab time zone, RFC-822 style
2919 @item @nicode{~Z} @tab time zone symbol (not currently implemented)
2920 @item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d}
2921 @item @nicode{~2} @tab ISO-8601 time+zone, @samp{~H:~M:~S~z}
2922 @item @nicode{~3} @tab ISO-8601 time, @samp{~H:~M:~S}
2923 @item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~H:~M:~S~z}
2924 @item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~H:~M:~S}
2928 Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently
2929 described here, since the specification and reference implementation
2932 Conversion is locale-dependent on systems that support it
2933 (@pxref{Accessing Locale Information}). @xref{Locales,
2934 @code{setlocale}}, for information on how to change the current
2938 @node SRFI-19 String to date
2939 @subsubsection SRFI-19 String to date
2940 @cindex string to date
2941 @cindex date, from string
2943 @c FIXME: Can we say what happens when an incomplete date is
2944 @c converted? I.e. fields left as 0, or what? The spec seems to be
2947 @defun string->date input template
2948 Convert an @var{input} string to a date under the control of a
2949 @var{template} string. Return a newly created date object.
2951 Literal characters in @var{template} must match characters in
2952 @var{input} and @samp{~} escapes must match the input forms described
2953 in the table below. ``Skip to'' means characters up to one of the
2954 given type are ignored, or ``no skip'' for no skipping. ``Read'' is
2955 what's then read, and ``Set'' is the field affected in the date
2958 For example @samp{~Y} skips input characters until a digit is reached,
2959 at which point it expects a year and stores that to the year field of
2962 @multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}}
2974 @tab @nicode{char-alphabetic?}
2975 @tab locale abbreviated weekday name
2979 @tab @nicode{char-alphabetic?}
2980 @tab locale full weekday name
2983 @c Note that the SRFI spec says that ~b and ~B don't set anything,
2984 @c but that looks like a mistake. The reference implementation sets
2985 @c the month field, which seems sensible and is what we describe
2989 @tab @nicode{char-alphabetic?}
2990 @tab locale abbreviated month name
2991 @tab @nicode{date-month}
2994 @tab @nicode{char-alphabetic?}
2995 @tab locale full month name
2996 @tab @nicode{date-month}
2999 @tab @nicode{char-numeric?}
3001 @tab @nicode{date-day}
3005 @tab day of month, blank padded
3006 @tab @nicode{date-day}
3009 @tab same as @samp{~b}
3012 @tab @nicode{char-numeric?}
3014 @tab @nicode{date-hour}
3018 @tab hour, blank padded
3019 @tab @nicode{date-hour}
3022 @tab @nicode{char-numeric?}
3024 @tab @nicode{date-month}
3027 @tab @nicode{char-numeric?}
3029 @tab @nicode{date-minute}
3032 @tab @nicode{char-numeric?}
3034 @tab @nicode{date-second}
3039 @tab @nicode{date-year} within 50 years
3042 @tab @nicode{char-numeric?}
3044 @tab @nicode{date-year}
3049 @tab date-zone-offset
3052 Notice that the weekday matching forms don't affect the date object
3053 returned, instead the weekday will be derived from the day, month and
3056 Conversion is locale-dependent on systems that support it
3057 (@pxref{Accessing Locale Information}). @xref{Locales,
3058 @code{setlocale}}, for information on how to change the current
3063 @subsection SRFI-23 - Error Reporting
3066 The SRFI-23 @code{error} procedure is always available.
3069 @subsection SRFI-26 - specializing parameters
3071 @cindex parameter specialize
3072 @cindex argument specialize
3073 @cindex specialize parameter
3075 This SRFI provides a syntax for conveniently specializing selected
3076 parameters of a function. It can be used with,
3079 (use-modules (srfi srfi-26))
3082 @deffn {library syntax} cut slot1 slot2 @dots{}
3083 @deffnx {library syntax} cute slot1 slot2 @dots{}
3084 Return a new procedure which will make a call (@var{slot1} @var{slot2}
3085 @dots{}) but with selected parameters specialized to given expressions.
3087 An example will illustrate the idea. The following is a
3088 specialization of @code{write}, sending output to
3089 @code{my-output-port},
3092 (cut write <> my-output-port)
3094 (lambda (obj) (write obj my-output-port))
3097 The special symbol @code{<>} indicates a slot to be filled by an
3098 argument to the new procedure. @code{my-output-port} on the other
3099 hand is an expression to be evaluated and passed, ie.@: it specializes
3100 the behaviour of @code{write}.
3104 A slot to be filled by an argument from the created procedure.
3105 Arguments are assigned to @code{<>} slots in the order they appear in
3106 the @code{cut} form, there's no way to re-arrange arguments.
3108 The first argument to @code{cut} is usually a procedure (or expression
3109 giving a procedure), but @code{<>} is allowed there too. For example,
3114 (lambda (proc) (proc 1 2 3))
3118 A slot to be filled by all remaining arguments from the new procedure.
3119 This can only occur at the end of a @code{cut} form.
3121 For example, a procedure taking a variable number of arguments like
3122 @code{max} but in addition enforcing a lower bound,
3125 (define my-lower-bound 123)
3127 (cut max my-lower-bound <...>)
3129 (lambda arglist (apply max my-lower-bound arglist))
3133 For @code{cut} the specializing expressions are evaluated each time
3134 the new procedure is called. For @code{cute} they're evaluated just
3135 once, when the new procedure is created. The name @code{cute} stands
3136 for ``@code{cut} with evaluated arguments''. In all cases the
3137 evaluations take place in an unspecified order.
3139 The following illustrates the difference between @code{cut} and
3143 (cut format <> "the time is ~s" (current-time))
3145 (lambda (port) (format port "the time is ~s" (current-time)))
3147 (cute format <> "the time is ~s" (current-time))
3149 (let ((val (current-time)))
3150 (lambda (port) (format port "the time is ~s" val))
3153 (There's no provision for a mixture of @code{cut} and @code{cute}
3154 where some expressions would be evaluated every time but others
3155 evaluated only once.)
3157 @code{cut} is really just a shorthand for the sort of @code{lambda}
3158 forms shown in the above examples. But notice @code{cut} avoids the
3159 need to name unspecialized parameters, and is more compact. Use in
3160 functional programming style or just with @code{map}, @code{for-each}
3161 or similar is typical.
3164 (map (cut * 2 <>) '(1 2 3 4))
3166 (for-each (cut write <> my-port) my-list)
3171 @subsection SRFI-27 - Sources of Random Bits
3174 This subsection is based on the
3175 @uref{http://srfi.schemers.org/srfi-27/srfi-27.html, specification of
3176 SRFI-27} written by Sebastian Egner.
3178 @c The copyright notice and license text of the SRFI-27 specification is
3179 @c reproduced below:
3181 @c Copyright (C) Sebastian Egner (2002). All Rights Reserved.
3183 @c Permission is hereby granted, free of charge, to any person obtaining a
3184 @c copy of this software and associated documentation files (the
3185 @c "Software"), to deal in the Software without restriction, including
3186 @c without limitation the rights to use, copy, modify, merge, publish,
3187 @c distribute, sublicense, and/or sell copies of the Software, and to
3188 @c permit persons to whom the Software is furnished to do so, subject to
3189 @c the following conditions:
3191 @c The above copyright notice and this permission notice shall be included
3192 @c in all copies or substantial portions of the Software.
3194 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3195 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3196 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3197 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3198 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3199 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3200 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3202 This SRFI provides access to a (pseudo) random number generator; for
3203 Guile's built-in random number facilities, which SRFI-27 is implemented
3204 upon, @xref{Random}. With SRFI-27, random numbers are obtained from a
3205 @emph{random source}, which encapsulates a random number generation
3206 algorithm and its state.
3209 * SRFI-27 Default Random Source:: Obtaining random numbers
3210 * SRFI-27 Random Sources:: Creating and manipulating random sources
3211 * SRFI-27 Random Number Generators:: Obtaining random number generators
3214 @node SRFI-27 Default Random Source
3215 @subsubsection The Default Random Source
3218 @defun random-integer n
3219 Return a random number between zero (inclusive) and @var{n} (exclusive),
3220 using the default random source. The numbers returned have a uniform
3225 Return a random number in (0,1), using the default random source. The
3226 numbers returned have a uniform distribution.
3229 @defun default-random-source
3230 A random source from which @code{random-integer} and @code{random-real}
3231 have been derived using @code{random-source-make-integers} and
3232 @code{random-source-make-reals} (@pxref{SRFI-27 Random Number Generators}
3233 for those procedures). Note that an assignment to
3234 @code{default-random-source} does not change @code{random-integer} or
3235 @code{random-real}; it is also strongly recommended not to assign a new
3239 @node SRFI-27 Random Sources
3240 @subsubsection Random Sources
3243 @defun make-random-source
3244 Create a new random source. The stream of random numbers obtained from
3245 each random source created by this procedure will be identical, unless
3246 its state is changed by one of the procedures below.
3249 @defun random-source? object
3250 Tests whether @var{object} is a random source. Random sources are a
3254 @defun random-source-randomize! source
3255 Attempt to set the state of the random source to a truly random value.
3256 The current implementation uses a seed based on the current system time.
3259 @defun random-source-pseudo-randomize! source i j
3260 Changes the state of the random source s into the initial state of the
3261 (@var{i}, @var{j})-th independent random source, where @var{i} and
3262 @var{j} are non-negative integers. This procedure provides a mechanism
3263 to obtain a large number of independent random sources (usually all
3264 derived from the same backbone generator), indexed by two integers. In
3265 contrast to @code{random-source-randomize!}, this procedure is entirely
3269 The state associated with a random state can be obtained an reinstated
3270 with the following procedures:
3272 @defun random-source-state-ref source
3273 @defunx random-source-state-set! source state
3274 Get and set the state of a random source. No assumptions should be made
3275 about the nature of the state object, besides it having an external
3276 representation (i.e.@: it can be passed to @code{write} and subsequently
3280 @node SRFI-27 Random Number Generators
3281 @subsubsection Obtaining random number generator procedures
3284 @defun random-source-make-integers source
3285 Obtains a procedure to generate random integers using the random source
3286 @var{source}. The returned procedure takes a single argument @var{n},
3287 which must be a positive integer, and returns the next uniformly
3288 distributed random integer from the interval @{0, ..., @var{n}-1@} by
3289 advancing the state of @var{source}.
3291 If an application obtains and uses several generators for the same
3292 random source @var{source}, a call to any of these generators advances
3293 the state of @var{source}. Hence, the generators do not produce the
3294 same sequence of random integers each but rather share a state. This
3295 also holds for all other types of generators derived from a fixed random
3298 While the SRFI text specifies that ``Implementations that support
3299 concurrency make sure that the state of a generator is properly
3300 advanced'', this is currently not the case in Guile's implementation of
3301 SRFI-27, as it would cause a severe performance penalty. So in
3302 multi-threaded programs, you either must perform locking on random
3303 sources shared between threads yourself, or use different random sources
3304 for multiple threads.
3307 @defun random-source-make-reals source
3308 @defunx random-source-make-reals source unit
3309 Obtains a procedure to generate random real numbers @math{0 < x < 1}
3310 using the random source @var{source}. The procedure rand is called
3313 The optional parameter @var{unit} determines the type of numbers being
3314 produced by the returned procedure and the quantization of the output.
3315 @var{unit} must be a number such that @math{0 < @var{unit} < 1}. The
3316 numbers created by the returned procedure are of the same numerical type
3317 as @var{unit} and the potential output values are spaced by at most
3318 @var{unit}. One can imagine rand to create numbers as @var{x} *
3319 @var{unit} where @var{x} is a random integer in @{1, ...,
3320 floor(1/unit)-1@}. Note, however, that this need not be the way the
3321 values are actually created and that the actual resolution of rand can
3322 be much higher than unit. In case @var{unit} is absent it defaults to a
3323 reasonably small value (related to the width of the mantissa of an
3324 efficient number format).
3328 @subsection SRFI-30 - Nested Multi-line Comments
3331 Starting from version 2.0, Guile's @code{read} supports SRFI-30/R6RS
3332 nested multi-line comments by default, @ref{Block Comments}.
3335 @subsection SRFI-31 - A special form `rec' for recursive evaluation
3337 @cindex recursive expression
3340 SRFI-31 defines a special form that can be used to create
3341 self-referential expressions more conveniently. The syntax is as
3346 <rec expression> --> (rec <variable> <expression>)
3347 <rec expression> --> (rec (<variable>+) <body>)
3351 The first syntax can be used to create self-referential expressions,
3355 guile> (define tmp (rec ones (cons 1 (delay ones))))
3358 The second syntax can be used to create anonymous recursive functions:
3361 guile> (define tmp (rec (display-n item n)
3363 (begin (display n) (display-n (- n 1))))))
3371 @subsection SRFI-34 - Exception handling for programs
3374 Guile provides an implementation of
3375 @uref{http://srfi.schemers.org/srfi-34/srfi-34.html, SRFI-34's exception
3376 handling mechanisms} as an alternative to its own built-in mechanisms
3377 (@pxref{Exceptions}). It can be made available as follows:
3380 (use-modules (srfi srfi-34))
3383 @c FIXME: Document it.
3387 @subsection SRFI-35 - Conditions
3393 @uref{http://srfi.schemers.org/srfi-35/srfi-35.html, SRFI-35} implements
3394 @dfn{conditions}, a data structure akin to records designed to convey
3395 information about exceptional conditions between parts of a program. It
3396 is normally used in conjunction with SRFI-34's @code{raise}:
3399 (raise (condition (&message
3400 (message "An error occurred"))))
3403 Users can define @dfn{condition types} containing arbitrary information.
3404 Condition types may inherit from one another. This allows the part of
3405 the program that handles (or ``catches'') conditions to get accurate
3406 information about the exceptional condition that arose.
3408 SRFI-35 conditions are made available using:
3411 (use-modules (srfi srfi-35))
3414 The procedures available to manipulate condition types are the
3417 @deffn {Scheme Procedure} make-condition-type id parent field-names
3418 Return a new condition type named @var{id}, inheriting from
3419 @var{parent}, and with the fields whose names are listed in
3420 @var{field-names}. @var{field-names} must be a list of symbols and must
3421 not contain names already used by @var{parent} or one of its supertypes.
3424 @deffn {Scheme Procedure} condition-type? obj
3425 Return true if @var{obj} is a condition type.
3428 Conditions can be created and accessed with the following procedures:
3430 @deffn {Scheme Procedure} make-condition type . field+value
3431 Return a new condition of type @var{type} with fields initialized as
3432 specified by @var{field+value}, a sequence of field names (symbols) and
3433 values as in the following example:
3436 (let ((&ct (make-condition-type 'foo &condition '(a b c))))
3437 (make-condition &ct 'a 1 'b 2 'c 3))
3440 Note that all fields of @var{type} and its supertypes must be specified.
3443 @deffn {Scheme Procedure} make-compound-condition condition1 condition2 @dots{}
3444 Return a new compound condition composed of @var{condition1}
3445 @var{condition2} @enddots{}. The returned condition has the type of
3446 each condition of condition1 condition2 @dots{} (per
3447 @code{condition-has-type?}).
3450 @deffn {Scheme Procedure} condition-has-type? c type
3451 Return true if condition @var{c} has type @var{type}.
3454 @deffn {Scheme Procedure} condition-ref c field-name
3455 Return the value of the field named @var{field-name} from condition @var{c}.
3457 If @var{c} is a compound condition and several underlying condition
3458 types contain a field named @var{field-name}, then the value of the
3459 first such field is returned, using the order in which conditions were
3460 passed to @code{make-compound-condition}.
3463 @deffn {Scheme Procedure} extract-condition c type
3464 Return a condition of condition type @var{type} with the field values
3465 specified by @var{c}.
3467 If @var{c} is a compound condition, extract the field values from the
3468 subcondition belonging to @var{type} that appeared first in the call to
3469 @code{make-compound-condition} that created the condition.
3472 Convenience macros are also available to create condition types and
3475 @deffn {library syntax} define-condition-type type supertype predicate field-spec...
3476 Define a new condition type named @var{type} that inherits from
3477 @var{supertype}. In addition, bind @var{predicate} to a type predicate
3478 that returns true when passed a condition of type @var{type} or any of
3479 its subtypes. @var{field-spec} must have the form @code{(field
3480 accessor)} where @var{field} is the name of field of @var{type} and
3481 @var{accessor} is the name of a procedure to access field @var{field} in
3482 conditions of type @var{type}.
3484 The example below defines condition type @code{&foo}, inheriting from
3485 @code{&condition} with fields @code{a}, @code{b} and @code{c}:
3488 (define-condition-type &foo &condition
3496 @deffn {library syntax} condition type-field-binding1 type-field-binding2 @dots{}
3497 Return a new condition or compound condition, initialized according to
3498 @var{type-field-binding1} @var{type-field-binding2} @enddots{}. Each
3499 @var{type-field-binding} must have the form @code{(type
3500 field-specs...)}, where @var{type} is the name of a variable bound to a
3501 condition type; each @var{field-spec} must have the form
3502 @code{(field-name value)} where @var{field-name} is a symbol denoting
3503 the field being initialized to @var{value}. As for
3504 @code{make-condition}, all fields must be specified.
3506 The following example returns a simple condition:
3509 (condition (&message (message "An error occurred")))
3512 The one below returns a compound condition:
3515 (condition (&message (message "An error occurred"))
3520 Finally, SRFI-35 defines a several standard condition types.
3523 This condition type is the root of all condition types. It has no
3528 A condition type that carries a message describing the nature of the
3529 condition to humans.
3532 @deffn {Scheme Procedure} message-condition? c
3533 Return true if @var{c} is of type @code{&message} or one of its
3537 @deffn {Scheme Procedure} condition-message c
3538 Return the message associated with message condition @var{c}.
3542 This type describes conditions serious enough that they cannot safely be
3543 ignored. It has no fields.
3546 @deffn {Scheme Procedure} serious-condition? c
3547 Return true if @var{c} is of type @code{&serious} or one of its
3552 This condition describes errors, typically caused by something that has
3553 gone wrong in the interaction of the program with the external world or
3557 @deffn {Scheme Procedure} error? c
3558 Return true if @var{c} is of type @code{&error} or one of its subtypes.
3562 @subsection SRFI-37 - args-fold
3565 This is a processor for GNU @code{getopt_long}-style program
3566 arguments. It provides an alternative, less declarative interface
3567 than @code{getopt-long} in @code{(ice-9 getopt-long)}
3568 (@pxref{getopt-long,,The (ice-9 getopt-long) Module}). Unlike
3569 @code{getopt-long}, it supports repeated options and any number of
3570 short and long names per option. Access it with:
3573 (use-modules (srfi srfi-37))
3576 @acronym{SRFI}-37 principally provides an @code{option} type and the
3577 @code{args-fold} function. To use the library, create a set of
3578 options with @code{option} and use it as a specification for invoking
3581 Here is an example of a simple argument processor for the typical
3582 @samp{--version} and @samp{--help} options, which returns a backwards
3583 list of files given on the command line:
3586 (args-fold (cdr (program-arguments))
3587 (let ((display-and-exit-proc
3589 (lambda (opt name arg loads)
3590 (display msg) (quit)))))
3591 (list (option '(#\v "version") #f #f
3592 (display-and-exit-proc "Foo version 42.0\n"))
3593 (option '(#\h "help") #f #f
3594 (display-and-exit-proc
3595 "Usage: foo scheme-file ..."))))
3596 (lambda (opt name arg loads)
3597 (error "Unrecognized option `~A'" name))
3598 (lambda (op loads) (cons op loads))
3602 @deffn {Scheme Procedure} option names required-arg? optional-arg? processor
3603 Return an object that specifies a single kind of program option.
3605 @var{names} is a list of command-line option names, and should consist of
3606 characters for traditional @code{getopt} short options and strings for
3607 @code{getopt_long}-style long options.
3609 @var{required-arg?} and @var{optional-arg?} are mutually exclusive;
3610 one or both must be @code{#f}. If @var{required-arg?}, the option
3611 must be followed by an argument on the command line, such as
3612 @samp{--opt=value} for long options, or an error will be signalled.
3613 If @var{optional-arg?}, an argument will be taken if available.
3615 @var{processor} is a procedure that takes at least 3 arguments, called
3616 when @code{args-fold} encounters the option: the containing option
3617 object, the name used on the command line, and the argument given for
3618 the option (or @code{#f} if none). The rest of the arguments are
3619 @code{args-fold} ``seeds'', and the @var{processor} should return
3623 @deffn {Scheme Procedure} option-names opt
3624 @deffnx {Scheme Procedure} option-required-arg? opt
3625 @deffnx {Scheme Procedure} option-optional-arg? opt
3626 @deffnx {Scheme Procedure} option-processor opt
3627 Return the specified field of @var{opt}, an option object, as
3628 described above for @code{option}.
3631 @deffn {Scheme Procedure} args-fold args options unrecognized-option-proc operand-proc seed @dots{}
3632 Process @var{args}, a list of program arguments such as that returned by
3633 @code{(cdr (program-arguments))}, in order against @var{options}, a list
3634 of option objects as described above. All functions called take the
3635 ``seeds'', or the last multiple-values as multiple arguments, starting
3636 with @var{seed} @dots{}, and must return the new seeds. Return the
3639 Call @code{unrecognized-option-proc}, which is like an option object's
3640 processor, for any options not found in @var{options}.
3642 Call @code{operand-proc} with any items on the command line that are
3643 not named options. This includes arguments after @samp{--}. It is
3644 called with the argument in question, as well as the seeds.
3648 @subsection SRFI-38 - External Representation for Data With Shared Structure
3651 This subsection is based on
3652 @uref{http://srfi.schemers.org/srfi-38/srfi-38.html, the specification
3653 of SRFI-38} written by Ray Dillinger.
3655 @c Copyright (C) Ray Dillinger 2003. All Rights Reserved.
3657 @c Permission is hereby granted, free of charge, to any person obtaining a
3658 @c copy of this software and associated documentation files (the
3659 @c "Software"), to deal in the Software without restriction, including
3660 @c without limitation the rights to use, copy, modify, merge, publish,
3661 @c distribute, sublicense, and/or sell copies of the Software, and to
3662 @c permit persons to whom the Software is furnished to do so, subject to
3663 @c the following conditions:
3665 @c The above copyright notice and this permission notice shall be included
3666 @c in all copies or substantial portions of the Software.
3668 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3669 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3670 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3671 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3672 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3673 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3674 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3676 This SRFI creates an alternative external representation for data
3677 written and read using @code{write-with-shared-structure} and
3678 @code{read-with-shared-structure}. It is identical to the grammar for
3679 external representation for data written and read with @code{write} and
3680 @code{read} given in section 7 of R5RS, except that the single
3684 <datum> --> <simple datum> | <compound datum>
3687 is replaced by the following five productions:
3690 <datum> --> <defining datum> | <nondefining datum> | <defined datum>
3691 <defining datum> --> #<indexnum>=<nondefining datum>
3692 <defined datum> --> #<indexnum>#
3693 <nondefining datum> --> <simple datum> | <compound datum>
3694 <indexnum> --> <digit 10>+
3697 @deffn {Scheme procedure} write-with-shared-structure obj
3698 @deffnx {Scheme procedure} write-with-shared-structure obj port
3699 @deffnx {Scheme procedure} write-with-shared-structure obj port optarg
3701 Writes an external representation of @var{obj} to the given port.
3702 Strings that appear in the written representation are enclosed in
3703 doublequotes, and within those strings backslash and doublequote
3704 characters are escaped by backslashes. Character objects are written
3705 using the @code{#\} notation.
3707 Objects which denote locations rather than values (cons cells, vectors,
3708 and non-zero-length strings in R5RS scheme; also Guile's structs,
3709 bytevectors and ports and hash-tables), if they appear at more than one
3710 point in the data being written, are preceded by @samp{#@var{N}=} the
3711 first time they are written and replaced by @samp{#@var{N}#} all
3712 subsequent times they are written, where @var{N} is a natural number
3713 used to identify that particular object. If objects which denote
3714 locations occur only once in the structure, then
3715 @code{write-with-shared-structure} must produce the same external
3716 representation for those objects as @code{write}.
3718 @code{write-with-shared-structure} terminates in finite time and
3719 produces a finite representation when writing finite data.
3721 @code{write-with-shared-structure} returns an unspecified value. The
3722 @var{port} argument may be omitted, in which case it defaults to the
3723 value returned by @code{(current-output-port)}. The @var{optarg}
3724 argument may also be omitted. If present, its effects on the output and
3725 return value are unspecified but @code{write-with-shared-structure} must
3726 still write a representation that can be read by
3727 @code{read-with-shared-structure}. Some implementations may wish to use
3728 @var{optarg} to specify formatting conventions, numeric radixes, or
3729 return values. Guile's implementation ignores @var{optarg}.
3731 For example, the code
3734 (begin (define a (cons 'val1 'val2))
3736 (write-with-shared-structure a))
3739 should produce the output @code{#1=(val1 . #1#)}. This shows a cons
3740 cell whose @code{cdr} contains itself.
3744 @deffn {Scheme procedure} read-with-shared-structure
3745 @deffnx {Scheme procedure} read-with-shared-structure port
3747 @code{read-with-shared-structure} converts the external representations
3748 of Scheme objects produced by @code{write-with-shared-structure} into
3749 Scheme objects. That is, it is a parser for the nonterminal
3750 @samp{<datum>} in the augmented external representation grammar defined
3751 above. @code{read-with-shared-structure} returns the next object
3752 parsable from the given input port, updating @var{port} to point to the
3753 first character past the end of the external representation of the
3756 If an end-of-file is encountered in the input before any characters are
3757 found that can begin an object, then an end-of-file object is returned.
3758 The port remains open, and further attempts to read it (by
3759 @code{read-with-shared-structure} or @code{read} will also return an
3760 end-of-file object. If an end of file is encountered after the
3761 beginning of an object's external representation, but the external
3762 representation is incomplete and therefore not parsable, an error is
3765 The @var{port} argument may be omitted, in which case it defaults to the
3766 value returned by @code{(current-input-port)}. It is an error to read
3772 @subsection SRFI-39 - Parameters
3775 This SRFI adds support for dynamically-scoped parameters. SRFI 39 is
3776 implemented in the Guile core; there's no module needed to get SRFI-39
3777 itself. Parameters are documented in @ref{Parameters}.
3779 This module does export one extra function: @code{with-parameters*}.
3780 This is a Guile-specific addition to the SRFI, similar to the core
3781 @code{with-fluids*} (@pxref{Fluids and Dynamic States}).
3783 @defun with-parameters* param-list value-list thunk
3784 Establish a new dynamic scope, as per @code{parameterize} above,
3785 taking parameters from @var{param-list} and corresponding values from
3786 @var{value-list}. A call @code{(@var{thunk})} is made in the new
3787 scope and the result from that @var{thunk} is the return from
3788 @code{with-parameters*}.
3792 @subsection SRFI-42 - Eager Comprehensions
3795 See @uref{http://srfi.schemers.org/srfi-42/srfi-42.html, the
3796 specification of SRFI-42}.
3799 @subsection SRFI-45 - Primitives for Expressing Iterative Lazy Algorithms
3802 This subsection is based on @uref{http://srfi.schemers.org/srfi-45/srfi-45.html, the
3803 specification of SRFI-45} written by Andr@'e van Tonder.
3805 @c Copyright (C) André van Tonder (2003). All Rights Reserved.
3807 @c Permission is hereby granted, free of charge, to any person obtaining a
3808 @c copy of this software and associated documentation files (the
3809 @c "Software"), to deal in the Software without restriction, including
3810 @c without limitation the rights to use, copy, modify, merge, publish,
3811 @c distribute, sublicense, and/or sell copies of the Software, and to
3812 @c permit persons to whom the Software is furnished to do so, subject to
3813 @c the following conditions:
3815 @c The above copyright notice and this permission notice shall be included
3816 @c in all copies or substantial portions of the Software.
3818 @c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
3819 @c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
3820 @c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
3821 @c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
3822 @c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
3823 @c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
3824 @c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3826 Lazy evaluation is traditionally simulated in Scheme using @code{delay}
3827 and @code{force}. However, these primitives are not powerful enough to
3828 express a large class of lazy algorithms that are iterative. Indeed, it
3829 is folklore in the Scheme community that typical iterative lazy
3830 algorithms written using delay and force will often require unbounded
3833 This SRFI provides set of three operations: @{@code{lazy}, @code{delay},
3834 @code{force}@}, which allow the programmer to succinctly express lazy
3835 algorithms while retaining bounded space behavior in cases that are
3836 properly tail-recursive. A general recipe for using these primitives is
3837 provided. An additional procedure @code{eager} is provided for the
3838 construction of eager promises in cases where efficiency is a concern.
3840 Although this SRFI redefines @code{delay} and @code{force}, the
3841 extension is conservative in the sense that the semantics of the subset
3842 @{@code{delay}, @code{force}@} in isolation (i.e., as long as the
3843 program does not use @code{lazy}) agrees with that in R5RS. In other
3844 words, no program that uses the R5RS definitions of delay and force will
3845 break if those definition are replaced by the SRFI-45 definitions of
3848 Guile compatibly extends SRFI-45 to support multiple values. It also
3849 adds @code{promise?} to the list of exports.
3851 @deffn {Scheme Procedure} promise? obj
3852 Return true if @var{obj} is an SRFI-45 promise, otherwise return false.
3855 @deffn {Scheme Syntax} delay expression
3856 Takes an expression and returns a promise which at some point in the
3857 future may be asked (by the @code{force} procedure) to evaluate the
3858 expression and deliver the resulting value(s).
3861 @deffn {Scheme Syntax} lazy expression
3862 Takes an expression (which must evaluate to a promise) and returns a
3863 promise which at some point in the future may be asked (by the
3864 @code{force} procedure) to evaluate the expression and deliver the
3868 @deffn {Scheme Procedure} force promise
3869 Takes a promise and returns the associated value(s) as follows: If
3870 value(s) have been computed for the promise, these value(s) are
3871 returned. Otherwise, the promise is first evaluated, then overwritten
3872 by the obtained promise or value(s), and then force is again applied
3873 (iteratively) to the promise.
3876 @deffn {Scheme Procedure} eager obj ...
3877 Takes any number of argument(s) and returns a promise. As opposed to
3878 @code{delay}, the argument(s) are evaluated eagerly. Semantically,
3879 writing @code{(eager expression)} is equivalent to writing
3882 (let ((value expression)) (delay value)).
3885 However, the former is more efficient since it does not require
3886 unnecessary creation and evaluation of thunks. For expressions that
3887 return a single value, we also have the equivalence
3890 (delay expression) = (lazy (eager expression))
3893 More generally, the following equivalence holds:
3896 (delay expression) = (lazy (call-with-values
3897 (lambda () expression)
3902 The following reduction rules may be helpful for reasoning about these
3903 primitives. However, they do not express the memoization and memory
3904 usage semantics specified above:
3907 (force (delay expression)) -> expression
3908 (force (lazy expression)) -> (force expression)
3909 (force (eager obj ...)) -> (values obj ...)
3912 @subsubheading Correct usage
3914 We now provide a general recipe for using the primitives @{@code{lazy},
3915 @code{delay}, @code{force}@} to express lazy algorithms in Scheme. The
3916 transformation is best described by way of an example: Consider the
3917 stream-filter algorithm, expressed in a hypothetical lazy language as
3920 (define (stream-filter p? s)
3925 (cons h (stream-filter p? t))
3926 (stream-filter p? t)))))
3929 This algorithm can be expressed as follows in Scheme:
3932 (define (stream-filter p? s)
3934 (if (null? (force s)) (delay '())
3935 (let ((h (car (force s)))
3936 (t (cdr (force s))))
3938 (delay (cons h (stream-filter p? t)))
3939 (stream-filter p? t))))))
3946 wrap all constructors (e.g., @code{'()}, @code{cons}) with @code{delay},
3948 apply @code{force} to arguments of deconstructors (e.g., @code{car},
3949 @code{cdr} and @code{null?}),
3951 wrap procedure bodies with @code{(lazy ...)}.
3955 @subsection SRFI-55 - Requiring Features
3958 SRFI-55 provides @code{require-extension} which is a portable
3959 mechanism to load selected SRFI modules. This is implemented in the
3960 Guile core, there's no module needed to get SRFI-55 itself.
3962 @deffn {library syntax} require-extension clause1 clause2 @dots{}
3963 Require the features of @var{clause1} @var{clause2} @dots{} , throwing
3964 an error if any are unavailable.
3966 A @var{clause} is of the form @code{(@var{identifier} arg...)}. The
3967 only @var{identifier} currently supported is @code{srfi} and the
3968 arguments are SRFI numbers. For example to get SRFI-1 and SRFI-6,
3971 (require-extension (srfi 1 6))
3974 @code{require-extension} can only be used at the top-level.
3976 A Guile-specific program can simply @code{use-modules} to load SRFIs
3977 not already in the core, @code{require-extension} is for programs
3978 designed to be portable to other Scheme implementations.
3983 @subsection SRFI-60 - Integers as Bits
3985 @cindex integers as bits
3986 @cindex bitwise logical
3988 This SRFI provides various functions for treating integers as bits and
3989 for bitwise manipulations. These functions can be obtained with,
3992 (use-modules (srfi srfi-60))
3995 Integers are treated as infinite precision twos-complement, the same
3996 as in the core logical functions (@pxref{Bitwise Operations}). And
3997 likewise bit indexes start from 0 for the least significant bit. The
3998 following functions in this SRFI are already in the Guile core,
4007 @code{integer-length},
4013 @defun bitwise-and n1 ...
4014 @defunx bitwise-ior n1 ...
4015 @defunx bitwise-xor n1 ...
4016 @defunx bitwise-not n
4017 @defunx any-bits-set? j k
4018 @defunx bit-set? index n
4019 @defunx arithmetic-shift n count
4020 @defunx bit-field n start end
4022 Aliases for @code{logand}, @code{logior}, @code{logxor},
4023 @code{lognot}, @code{logtest}, @code{logbit?}, @code{ash},
4024 @code{bit-extract} and @code{logcount} respectively.
4026 Note that the name @code{bit-count} conflicts with @code{bit-count} in
4027 the core (@pxref{Bit Vectors}).
4030 @defun bitwise-if mask n1 n0
4031 @defunx bitwise-merge mask n1 n0
4032 Return an integer with bits selected from @var{n1} and @var{n0}
4033 according to @var{mask}. Those bits where @var{mask} has 1s are taken
4034 from @var{n1}, and those where @var{mask} has 0s are taken from
4038 (bitwise-if 3 #b0101 #b1010) @result{} 9
4042 @defun log2-binary-factors n
4043 @defunx first-set-bit n
4044 Return a count of how many factors of 2 are present in @var{n}. This
4045 is also the bit index of the lowest 1 bit in @var{n}. If @var{n} is
4046 0, the return is @math{-1}.
4049 (log2-binary-factors 6) @result{} 1
4050 (log2-binary-factors -8) @result{} 3
4054 @defun copy-bit index n newbit
4055 Return @var{n} with the bit at @var{index} set according to
4056 @var{newbit}. @var{newbit} should be @code{#t} to set the bit to 1,
4057 or @code{#f} to set it to 0. Bits other than at @var{index} are
4058 unchanged in the return.
4061 (copy-bit 1 #b0101 #t) @result{} 7
4065 @defun copy-bit-field n newbits start end
4066 Return @var{n} with the bits from @var{start} (inclusive) to @var{end}
4067 (exclusive) changed to the value @var{newbits}.
4069 The least significant bit in @var{newbits} goes to @var{start}, the
4070 next to @math{@var{start}+1}, etc. Anything in @var{newbits} past the
4071 @var{end} given is ignored.
4074 (copy-bit-field #b10000 #b11 1 3) @result{} #b10110
4078 @defun rotate-bit-field n count start end
4079 Return @var{n} with the bit field from @var{start} (inclusive) to
4080 @var{end} (exclusive) rotated upwards by @var{count} bits.
4082 @var{count} can be positive or negative, and it can be more than the
4083 field width (it'll be reduced modulo the width).
4086 (rotate-bit-field #b0110 2 1 4) @result{} #b1010
4090 @defun reverse-bit-field n start end
4091 Return @var{n} with the bits from @var{start} (inclusive) to @var{end}
4092 (exclusive) reversed.
4095 (reverse-bit-field #b101001 2 4) @result{} #b100101
4099 @defun integer->list n [len]
4100 Return bits from @var{n} in the form of a list of @code{#t} for 1 and
4101 @code{#f} for 0. The least significant @var{len} bits are returned,
4102 and the first list element is the most significant of those bits. If
4103 @var{len} is not given, the default is @code{(integer-length @var{n})}
4104 (@pxref{Bitwise Operations}).
4107 (integer->list 6) @result{} (#t #t #f)
4108 (integer->list 1 4) @result{} (#f #f #f #t)
4112 @defun list->integer lst
4113 @defunx booleans->integer bool@dots{}
4114 Return an integer formed bitwise from the given @var{lst} list of
4115 booleans, or for @code{booleans->integer} from the @var{bool}
4118 Each boolean is @code{#t} for a 1 and @code{#f} for a 0. The first
4119 element becomes the most significant bit in the return.
4122 (list->integer '(#t #f #t #f)) @result{} 10
4128 @subsection SRFI-61 - A more general @code{cond} clause
4130 This SRFI extends RnRS @code{cond} to support test expressions that
4131 return multiple values, as well as arbitrary definitions of test
4132 success. SRFI 61 is implemented in the Guile core; there's no module
4133 needed to get SRFI-61 itself. Extended @code{cond} is documented in
4134 @ref{Conditionals,, Simple Conditional Evaluation}.
4137 @subsection SRFI-67 - Compare procedures
4140 See @uref{http://srfi.schemers.org/srfi-67/srfi-67.html, the
4141 specification of SRFI-67}.
4144 @subsection SRFI-69 - Basic hash tables
4147 This is a portable wrapper around Guile's built-in hash table and weak
4148 table support. @xref{Hash Tables}, for information on that built-in
4149 support. Above that, this hash-table interface provides association
4150 of equality and hash functions with tables at creation time, so
4151 variants of each function are not required, as well as a procedure
4152 that takes care of most uses for Guile hash table handles, which this
4153 SRFI does not provide as such.
4158 (use-modules (srfi srfi-69))
4162 * SRFI-69 Creating hash tables::
4163 * SRFI-69 Accessing table items::
4164 * SRFI-69 Table properties::
4165 * SRFI-69 Hash table algorithms::
4168 @node SRFI-69 Creating hash tables
4169 @subsubsection Creating hash tables
4171 @deffn {Scheme Procedure} make-hash-table [equal-proc hash-proc #:weak weakness start-size]
4172 Create and answer a new hash table with @var{equal-proc} as the
4173 equality function and @var{hash-proc} as the hashing function.
4175 By default, @var{equal-proc} is @code{equal?}. It can be any
4176 two-argument procedure, and should answer whether two keys are the
4177 same for this table's purposes.
4179 My default @var{hash-proc} assumes that @code{equal-proc} is no
4180 coarser than @code{equal?} unless it is literally @code{string-ci=?}.
4181 If provided, @var{hash-proc} should be a two-argument procedure that
4182 takes a key and the current table size, and answers a reasonably good
4183 hash integer between 0 (inclusive) and the size (exclusive).
4185 @var{weakness} should be @code{#f} or a symbol indicating how ``weak''
4190 An ordinary non-weak hash table. This is the default.
4193 When the key has no more non-weak references at GC, remove that entry.
4196 When the value has no more non-weak references at GC, remove that
4200 When either has no more non-weak references at GC, remove the
4204 As a legacy of the time when Guile couldn't grow hash tables,
4205 @var{start-size} is an optional integer argument that specifies the
4206 approximate starting size for the hash table, which will be rounded to
4207 an algorithmically-sounder number.
4210 By @dfn{coarser} than @code{equal?}, we mean that for all @var{x} and
4211 @var{y} values where @code{(@var{equal-proc} @var{x} @var{y})},
4212 @code{(equal? @var{x} @var{y})} as well. If that does not hold for
4213 your @var{equal-proc}, you must provide a @var{hash-proc}.
4215 In the case of weak tables, remember that @dfn{references} above
4216 always refers to @code{eq?}-wise references. Just because you have a
4217 reference to some string @code{"foo"} doesn't mean that an association
4218 with key @code{"foo"} in a weak-key table @emph{won't} be collected;
4219 it only counts as a reference if the two @code{"foo"}s are @code{eq?},
4220 regardless of @var{equal-proc}. As such, it is usually only sensible
4221 to use @code{eq?} and @code{hashq} as the equivalence and hash
4222 functions for a weak table. @xref{Weak References}, for more
4223 information on Guile's built-in weak table support.
4225 @deffn {Scheme Procedure} alist->hash-table alist [equal-proc hash-proc #:weak weakness start-size]
4226 As with @code{make-hash-table}, but initialize it with the
4227 associations in @var{alist}. Where keys are repeated in @var{alist},
4228 the leftmost association takes precedence.
4231 @node SRFI-69 Accessing table items
4232 @subsubsection Accessing table items
4234 @deffn {Scheme Procedure} hash-table-ref table key [default-thunk]
4235 @deffnx {Scheme Procedure} hash-table-ref/default table key default
4236 Answer the value associated with @var{key} in @var{table}. If
4237 @var{key} is not present, answer the result of invoking the thunk
4238 @var{default-thunk}, which signals an error instead by default.
4240 @code{hash-table-ref/default} is a variant that requires a third
4241 argument, @var{default}, and answers @var{default} itself instead of
4245 @deffn {Scheme Procedure} hash-table-set! table key new-value
4246 Set @var{key} to @var{new-value} in @var{table}.
4249 @deffn {Scheme Procedure} hash-table-delete! table key
4250 Remove the association of @var{key} in @var{table}, if present. If
4254 @deffn {Scheme Procedure} hash-table-exists? table key
4255 Answer whether @var{key} has an association in @var{table}.
4258 @deffn {Scheme Procedure} hash-table-update! table key modifier [default-thunk]
4259 @deffnx {Scheme Procedure} hash-table-update!/default table key modifier default
4260 Replace @var{key}'s associated value in @var{table} by invoking
4261 @var{modifier} with one argument, the old value.
4263 If @var{key} is not present, and @var{default-thunk} is provided,
4264 invoke it with no arguments to get the ``old value'' to be passed to
4265 @var{modifier} as above. If @var{default-thunk} is not provided in
4266 such a case, signal an error.
4268 @code{hash-table-update!/default} is a variant that requires the
4269 fourth argument, which is used directly as the ``old value'' rather
4270 than as a thunk to be invoked to retrieve the ``old value''.
4273 @node SRFI-69 Table properties
4274 @subsubsection Table properties
4276 @deffn {Scheme Procedure} hash-table-size table
4277 Answer the number of associations in @var{table}. This is guaranteed
4278 to run in constant time for non-weak tables.
4281 @deffn {Scheme Procedure} hash-table-keys table
4282 Answer an unordered list of the keys in @var{table}.
4285 @deffn {Scheme Procedure} hash-table-values table
4286 Answer an unordered list of the values in @var{table}.
4289 @deffn {Scheme Procedure} hash-table-walk table proc
4290 Invoke @var{proc} once for each association in @var{table}, passing
4291 the key and value as arguments.
4294 @deffn {Scheme Procedure} hash-table-fold table proc init
4295 Invoke @code{(@var{proc} @var{key} @var{value} @var{previous})} for
4296 each @var{key} and @var{value} in @var{table}, where @var{previous} is
4297 the result of the previous invocation, using @var{init} as the first
4298 @var{previous} value. Answer the final @var{proc} result.
4301 @deffn {Scheme Procedure} hash-table->alist table
4302 Answer an alist where each association in @var{table} is an
4303 association in the result.
4306 @node SRFI-69 Hash table algorithms
4307 @subsubsection Hash table algorithms
4309 Each hash table carries an @dfn{equivalence function} and a @dfn{hash
4310 function}, used to implement key lookups. Beginning users should
4311 follow the rules for consistency of the default @var{hash-proc}
4312 specified above. Advanced users can use these to implement their own
4313 equivalence and hash functions for specialized lookup semantics.
4315 @deffn {Scheme Procedure} hash-table-equivalence-function hash-table
4316 @deffnx {Scheme Procedure} hash-table-hash-function hash-table
4317 Answer the equivalence and hash function of @var{hash-table}, respectively.
4320 @deffn {Scheme Procedure} hash obj [size]
4321 @deffnx {Scheme Procedure} string-hash obj [size]
4322 @deffnx {Scheme Procedure} string-ci-hash obj [size]
4323 @deffnx {Scheme Procedure} hash-by-identity obj [size]
4324 Answer a hash value appropriate for equality predicate @code{equal?},
4325 @code{string=?}, @code{string-ci=?}, and @code{eq?}, respectively.
4328 @code{hash} is a backwards-compatible replacement for Guile's built-in
4332 @subsection SRFI-88 Keyword Objects
4334 @cindex keyword objects
4336 @uref{http://srfi.schemers.org/srfi-88/srfi-88.html, SRFI-88} provides
4337 @dfn{keyword objects}, which are equivalent to Guile's keywords
4338 (@pxref{Keywords}). SRFI-88 keywords can be entered using the
4339 @dfn{postfix keyword syntax}, which consists of an identifier followed
4340 by @code{:} (@pxref{Scheme Read, @code{postfix} keyword syntax}).
4341 SRFI-88 can be made available with:
4344 (use-modules (srfi srfi-88))
4347 Doing so installs the right reader option for keyword syntax, using
4348 @code{(read-set! keywords 'postfix)}. It also provides the procedures
4351 @deffn {Scheme Procedure} keyword? obj
4352 Return @code{#t} if @var{obj} is a keyword. This is the same procedure
4353 as the same-named built-in procedure (@pxref{Keyword Procedures,
4357 (keyword? foo:) @result{} #t
4358 (keyword? 'foo:) @result{} #t
4359 (keyword? "foo") @result{} #f
4363 @deffn {Scheme Procedure} keyword->string kw
4364 Return the name of @var{kw} as a string, i.e., without the trailing
4365 colon. The returned string may not be modified, e.g., with
4369 (keyword->string foo:) @result{} "foo"
4373 @deffn {Scheme Procedure} string->keyword str
4374 Return the keyword object whose name is @var{str}.
4377 (keyword->string (string->keyword "a b c")) @result{} "a b c"
4382 @subsection SRFI-98 Accessing environment variables.
4384 @cindex environment variables
4386 This is a portable wrapper around Guile's built-in support for
4387 interacting with the current environment, @xref{Runtime Environment}.
4389 @deffn {Scheme Procedure} get-environment-variable name
4390 Returns a string containing the value of the environment variable
4391 given by the string @code{name}, or @code{#f} if the named
4392 environment variable is not found. This is equivalent to
4393 @code{(getenv name)}.
4396 @deffn {Scheme Procedure} get-environment-variables
4397 Returns the names and values of all the environment variables as an
4398 association list in which both the keys and the values are strings.
4402 @subsection SRFI-105 Curly-infix expressions.
4405 @cindex curly-infix-and-bracket-lists
4407 Guile's built-in reader includes support for SRFI-105 curly-infix
4408 expressions. See @uref{http://srfi.schemers.org/srfi-105/srfi-105.html,
4409 the specification of SRFI-105}. Some examples:
4412 @{n <= 5@} @result{} (<= n 5)
4413 @{a + b + c@} @result{} (+ a b c)
4414 @{a * @{b + c@}@} @result{} (* a (+ b c))
4415 @{(- a) / b@} @result{} (/ (- a) b)
4416 @{-(a) / b@} @result{} (/ (- a) b) as well
4417 @{(f a b) + (g h)@} @result{} (+ (f a b) (g h))
4418 @{f(a b) + g(h)@} @result{} (+ (f a b) (g h)) as well
4419 @{f[a b] + g(h)@} @result{} (+ ($bracket-apply$ f a b) (g h))
4420 '@{a + f(b) + x@} @result{} '(+ a (f b) x)
4421 @{length(x) >= 6@} @result{} (>= (length x) 6)
4422 @{n-1 + n-2@} @result{} (+ n-1 n-2)
4423 @{n * factorial@{n - 1@}@} @result{} (* n (factorial (- n 1)))
4424 @{@{a > 0@} and @{b >= 1@}@} @result{} (and (> a 0) (>= b 1))
4425 @{f@{n - 1@}(x)@} @result{} ((f (- n 1)) x)
4426 @{a . z@} @result{} ($nfx$ a . z)
4427 @{a + b - c@} @result{} ($nfx$ a + b - c)
4430 To enable curly-infix expressions within a file, place the reader
4431 directive @code{#!curly-infix} before the first use of curly-infix
4432 notation. To globally enable curly-infix expressions in Guile's reader,
4433 set the @code{curly-infix} read option.
4435 Guile also implements the following non-standard extension to SRFI-105:
4436 if @code{curly-infix} is enabled and there is no other meaning assigned
4437 to square brackets (i.e. the @code{square-brackets} read option is
4438 turned off), then lists within square brackets are read as normal lists
4439 but with the special symbol @code{$bracket-list$} added to the front.
4440 To enable this combination of read options within a file, use the reader
4441 directive @code{#!curly-infix-and-bracket-lists}. For example:
4444 [a b] @result{} ($bracket-list$ a b)
4445 [a . b] @result{} ($bracket-list$ a . b)
4449 For more information on reader options, @xref{Scheme Read}.
4451 @c srfi-modules.texi ends here
4454 @c TeX-master: "guile.texi"