3 @chapter SRFI Support Modules
6 SRFI is an acronym for Scheme Request For Implementation. The SRFI
7 documents define a lot of syntactic and procedure extensions to standard
8 Scheme as defined in R5RS.
10 Guile has support for a number of SRFIs. This chapter gives an overview
11 over the available SRFIs and some usage hints. For complete
12 documentation, design rationales and further examples, we advise you to
13 get the relevant SRFI documents from the SRFI home page
14 @url{http://srfi.schemers.org}.
17 * About SRFI Usage:: What to know about Guile's SRFI support.
18 * SRFI-0:: cond-expand
19 * SRFI-1:: List library.
21 * SRFI-4:: Homogeneous numeric vector datatypes.
22 * SRFI-6:: Basic String Ports.
24 * SRFI-9:: define-record-type.
25 * SRFI-10:: Hash-Comma Reader Extension.
26 * SRFI-11:: let-values and let-values*.
27 * SRFI-13:: String library.
28 * SRFI-14:: Character-set library.
29 * SRFI-16:: case-lambda
30 * SRFI-17:: Generalized set!
31 * SRFI-19:: Time/Date library.
35 @node About SRFI Usage
36 @section About SRFI Usage
38 @c FIXME::martin: Review me!
40 SRFI support in Guile is currently implemented partly in the core
41 library, and partly as add-on modules. That means that some SRFIs are
42 automatically available when the interpreter is started, whereas the
43 other SRFIs require you to use the appropriate support module
46 There are several reasons for this inconsistency. First, the feature
47 checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
48 available immediately, because it must be there when the user wants to
49 check for the Scheme implementation, that is, before she can know that
50 it is safe to use @code{use-modules} to load SRFI support modules. The
51 second reason is that some features defined in SRFIs had been
52 implemented in Guile before the developers started to add SRFI
53 implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In
54 the future, it is possible that SRFIs in the core library might be
55 factored out into separate modules, requiring explicit module loading
56 when they are needed. So you should be prepared to have to use
57 @code{use-modules} someday in the future to access SRFI-6 bindings. If
58 you want, you can do that already. We have included the module
59 @code{(srfi srfi-6)} in the distribution, which currently does nothing,
60 but ensures that you can write future-safe code.
62 Generally, support for a specific SRFI is made available by using
63 modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
64 number of the SRFI needed. Another possibility is to use the command
65 line option @code{--use-srfi}, which will load the necessary modules
66 automatically (@pxref{Invoking Guile}).
70 @section SRFI-0 - cond-expand
74 @c FIXME::martin: Review me!
76 SRFI-0 defines a means for checking whether a Scheme implementation has
77 support for a specified feature. The syntactic form @code{cond-expand},
78 which implements this means, has the following syntax.
83 --> (cond-expand <cond-expand-clause>+)
84 | (cond-expand <cond-expand-clause>* (else <command-or-definition>))
86 --> (<feature-requirement> <command-or-definition>*)
88 --> <feature-identifier>
89 | (and <feature-requirement>*)
90 | (or <feature-requirement>*)
91 | (not <feature-requirement>)
93 --> <a symbol which is the name or alias of a SRFI>
97 When evaluated, this form checks all clauses in order, until it finds
98 one whose feature requirement is satisfied. Then the form expands into
99 the commands or definitions in the clause. A requirement is tested as
104 If it is a symbol, it is satisfied if the feature identifier is
108 If it is an @code{and} form, all requirements must be satisfied. If no
109 requirements are given, it is satisfied, too.
112 If it is an @code{or} form, at least one of the requirements must be
113 satisfied. If no requirements are given, it is not satisfied.
116 If it is a @code{not} form, the feature requirement must @emph{not} be
120 If the feature requirement is the keyword @code{else} and it is the last
121 clause, it is satisfied if no prior clause matched.
124 If no clause is satisfied, an error is signalled.
126 Since @code{cond-expand} is needed to tell what a Scheme implementation
127 provides, it must be accessible without using any
128 implementation-dependent operations, such as @code{use-modules} in
129 Guile. Thus, it is not necessary to use any module to get access to
132 Currently, the feature identifiers @code{guile}, @code{r5rs} and
133 @code{srfi-0} are supported. The other SRFIs are not in that list by
134 default, because the SRFI modules must be explicitly used before their
135 exported bindings can be used.
137 So if a Scheme program wishes to use SRFI-8, it has two possibilities:
138 First, it can check whether the running Scheme implementation is Guile,
139 and if it is, it can use the appropriate module:
144 (use-modules (srfi srfi-8)))
150 The other possibility is to use the @code{--use-srfi} command line
151 option when invoking Guile (@pxref{Invoking Guile}). When you do that,
152 the specified SRFI support modules will be loaded and add their feature
153 identifier to the list of symbols checked by @code{cond-expand}.
155 So, if you invoke Guile like this:
161 the following snippet will expand to @code{'hooray}.
164 (cond-expand (srfi-8 'hooray))
169 @section SRFI-1 - List library
172 @c FIXME::martin: Review me!
174 The list library defined in SRFI-1 contains a lot of useful list
175 processing procedures for construction, examining, destructuring and
176 manipulating lists and pairs.
178 Since SRFI-1 also defines some procedures which are already contained
179 in R5RS and thus are supported by the Guile core library, some list
180 and pair procedures which appear in the SRFI-1 document may not appear
181 in this section. So when looking for a particular list/pair
182 processing procedure, you should also have a look at the sections
183 @ref{Lists} and @ref{Pairs}.
186 * SRFI-1 Constructors:: Constructing new lists.
187 * SRFI-1 Predicates:: Testing list for specific properties.
188 * SRFI-1 Selectors:: Selecting elements from lists.
189 * SRFI-1 Length Append etc:: Length calculation and list appending.
190 * SRFI-1 Fold and Map:: Higher-order list processing.
191 * SRFI-1 Filtering and Partitioning:: Filter lists based on predicates.
192 * SRFI-1 Searching:: Search for elements.
193 * SRFI-1 Deleting:: Delete elements from lists.
194 * SRFI-1 Association Lists:: Handle association lists.
195 * SRFI-1 Set Operations:: Use lists for representing sets.
198 @node SRFI-1 Constructors
199 @subsection Constructors
201 @c FIXME::martin: Review me!
203 New lists can be constructed by calling one of the following
206 @deffn {Scheme Procedure} xcons d a
207 Like @code{cons}, but with interchanged arguments. Useful mostly when
208 passed to higher-order procedures.
211 @deffn {Scheme Procedure} list-tabulate n init-proc
212 Return an @var{n}-element list, where each list element is produced by
213 applying the procedure @var{init-proc} to the corresponding list
214 index. The order in which @var{init-proc} is applied to the indices
218 @deffn {Scheme Procedure} list-copy lst
219 Return a new list containing the elements of the list @var{lst}.
221 This function differs from the core @code{list-copy} (@pxref{List
222 Constructors}) in accepting improper lists too. And if @var{lst} is
223 not a pair at all then it's treated as the final tail of an improper
224 list and simply returned.
227 @deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
228 Return a circular list containing the given arguments @var{elt1}
232 @deffn {Scheme Procedure} iota count [start step]
233 Return a list containing @var{count} numbers, starting from
234 @var{start} and adding @var{step} each time. The default @var{start}
235 is 0, the default @var{step} is 1. For example,
238 (iota 6) @result{} (0 1 2 3 4 5)
239 (iota 4 2.5 -2) @result{} (2.5 0.5 -1.5 -3.5)
242 This function takes its name from the corresponding primitive in the
247 @node SRFI-1 Predicates
248 @subsection Predicates
250 @c FIXME::martin: Review me!
252 The procedures in this section test specific properties of lists.
254 @deffn {Scheme Procedure} proper-list? obj
255 Return @code{#t} if @var{obj} is a proper list, that is a finite list,
256 terminated with the empty list. Otherwise, return @code{#f}.
259 @deffn {Scheme Procedure} circular-list? obj
260 Return @code{#t} if @var{obj} is a circular list, otherwise return
264 @deffn {Scheme Procedure} dotted-list? obj
265 Return @code{#t} if @var{obj} is a dotted list, return @code{#f}
266 otherwise. A dotted list is a finite list which is not terminated by
267 the empty list, but some other value.
270 @deffn {Scheme Procedure} null-list? lst
271 Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
272 otherwise. If something else than a proper or circular list is passed
273 as @var{lst}, an error is signalled. This procedure is recommended
274 for checking for the end of a list in contexts where dotted lists are
278 @deffn {Scheme Procedure} not-pair? obj
279 Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
280 This is shorthand notation @code{(not (pair? @var{obj}))} and is
281 supposed to be used for end-of-list checking in contexts where dotted
285 @deffn {Scheme Procedure} list= elt= list1 @dots{}
286 Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
287 List equality is determined by testing whether all lists have the same
288 length and the corresponding elements are equal in the sense of the
289 equality predicate @var{elt=}. If no or only one list is given,
290 @code{#t} is returned.
294 @node SRFI-1 Selectors
295 @subsection Selectors
297 @c FIXME::martin: Review me!
299 @deffn {Scheme Procedure} first pair
300 @deffnx {Scheme Procedure} second pair
301 @deffnx {Scheme Procedure} third pair
302 @deffnx {Scheme Procedure} fourth pair
303 @deffnx {Scheme Procedure} fifth pair
304 @deffnx {Scheme Procedure} sixth pair
305 @deffnx {Scheme Procedure} seventh pair
306 @deffnx {Scheme Procedure} eighth pair
307 @deffnx {Scheme Procedure} ninth pair
308 @deffnx {Scheme Procedure} tenth pair
309 These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
312 @deffn {Scheme Procedure} car+cdr pair
313 Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
316 @deffn {Scheme Procedure} take lst i
317 @deffnx {Scheme Procedure} take! lst i
318 Return a list containing the first @var{i} elements of @var{lst}.
320 @code{take!} may modify the structure of the argument list @var{lst}
321 in order to produce the result.
324 @deffn {Scheme Procedure} drop lst i
325 Return a list containing all but the first @var{i} elements of
329 @deffn {Scheme Procedure} take-right lst i
330 Return the a list containing the @var{i} last elements of @var{lst}.
333 @deffn {Scheme Procedure} drop-right lst i
334 @deffnx {Scheme Procedure} drop-right! lst i
335 Return the a list containing all but the @var{i} last elements of
338 @code{drop-right!} may modify the structure of the argument list
339 @var{lst} in order to produce the result.
342 @deffn {Scheme Procedure} split-at lst i
343 @deffnx {Scheme Procedure} split-at! lst i
344 Return two values, a list containing the first @var{i} elements of the
345 list @var{lst} and a list containing the remaining elements.
347 @code{split-at!} may modify the structure of the argument list
348 @var{lst} in order to produce the result.
351 @deffn {Scheme Procedure} last lst
352 Return the last element of the non-empty, finite list @var{lst}.
356 @node SRFI-1 Length Append etc
357 @subsection Length, Append, Concatenate, etc.
359 @c FIXME::martin: Review me!
361 @deffn {Scheme Procedure} length+ lst
362 Return the length of the argument list @var{lst}. When @var{lst} is a
363 circular list, @code{#f} is returned.
366 @deffn {Scheme Procedure} concatenate list-of-lists
367 @deffnx {Scheme Procedure} concatenate! list-of-lists
368 Construct a list by appending all lists in @var{list-of-lists}.
370 @code{concatenate!} may modify the structure of the given lists in
371 order to produce the result.
374 @deffn {Scheme Procedure} append-reverse rev-head tail
375 @deffnx {Scheme Procedure} append-reverse! rev-head tail
376 Reverse @var{rev-head}, append @var{tail} and return the result. This
377 is equivalent to @code{(append (reverse @var{rev-head}) @var{tail})},
380 @code{append-reverse!} may modify @var{rev-head} in order to produce
384 @deffn {Scheme Procedure} zip lst1 lst2 @dots{}
385 Return a list as long as the shortest of the argument lists, where
386 each element is a list. The first list contains the first elements of
387 the argument lists, the second list contains the second elements, and
391 @deffn {Scheme Procedure} unzip1 lst
392 @deffnx {Scheme Procedure} unzip2 lst
393 @deffnx {Scheme Procedure} unzip3 lst
394 @deffnx {Scheme Procedure} unzip4 lst
395 @deffnx {Scheme Procedure} unzip5 lst
396 @code{unzip1} takes a list of lists, and returns a list containing the
397 first elements of each list, @code{unzip2} returns two lists, the
398 first containing the first elements of each lists and the second
399 containing the second elements of each lists, and so on.
402 @deffn {Scheme Procedure} count pred lst1 @dots{} lstN
403 Return a count of the number of times @var{pred} returns true when
404 called on elements from the given lists.
406 @var{pred} is called with @var{N} parameters @code{(@var{pred}
407 @var{elem1} @dots{} @var{elemN})}, each element being from the
408 corresponding @var{lst1} @dots{} @var{lstN}. The first call is with
409 the first element of each list, the second with the second element
410 from each, and so on.
412 Counting stops when the end of the shortest list is reached. At least
413 one list must be non-circular.
417 @node SRFI-1 Fold and Map
418 @subsection Fold, Unfold & Map
420 @c FIXME::martin: Review me!
422 @deffn {Scheme Procedure} fold kons knil lst1 lst2 @dots{}
423 Fold the procedure @var{kons} across all elements of @var{lst1},
424 @var{lst2}, @dots{}. Produce the result of
426 @code{(@var{kons} @var{en1} @var{en2} @dots{} (@var{kons} @var{e21}
427 @var{e22} (@var{kons} @var{e11} @var{e12} @var{knil})))},
429 if @var{enm} are the elements of the lists @var{lst1}, @var{lst2},
433 @deffn {Scheme Procedure} fold-right kons knil lst1 lst2 @dots{}
434 Similar to @code{fold}, but applies @var{kons} in right-to-left order
435 to the list elements, that is:
437 @code{(@var{kons} @var{e11} @var{e12}(@var{kons} @var{e21}
438 @var{e22} @dots{} (@var{kons} @var{en1} @var{en2} @var{knil})))},
441 @deffn {Scheme Procedure} pair-fold kons knil lst1 lst2 @dots{}
442 Like @code{fold}, but apply @var{kons} to the pairs of the list
443 instead of the list elements.
446 @deffn {Scheme Procedure} pair-fold-right kons knil lst1 lst2 @dots{}
447 Like @code{fold-right}, but apply @var{kons} to the pairs of the list
448 instead of the list elements.
451 @deffn {Scheme Procedure} reduce f ridentity lst
452 @code{reduce} is a variant of @code{fold}. If @var{lst} is
453 @code{()}, @var{ridentity} is returned. Otherwise, @code{(fold f (car
454 @var{lst}) (cdr @var{lst}))} is returned.
457 @deffn {Scheme Procedure} reduce-right f ridentity lst
458 This is the @code{fold-right} variant of @code{reduce}.
461 @deffn {Scheme Procedure} unfold p f g seed [tail-gen]
462 @code{unfold} is defined as follows:
465 (unfold p f g seed) =
466 (if (p seed) (tail-gen seed)
468 (unfold p f g (g seed))))
473 Determines when to stop unfolding.
476 Maps each seed value to the corresponding list element.
479 Maps each seed value to next seed valu.
482 The state value for the unfold.
485 Creates the tail of the list; defaults to @code{(lambda (x) '())}.
488 @var{g} produces a series of seed values, which are mapped to list
489 elements by @var{f}. These elements are put into a list in
490 left-to-right order, and @var{p} tells when to stop unfolding.
493 @deffn {Scheme Procedure} unfold-right p f g seed [tail]
494 Construct a list with the following loop.
497 (let lp ((seed seed) (lis tail))
500 (cons (f seed) lis))))
505 Determines when to stop unfolding.
508 Maps each seed value to the corresponding list element.
511 Maps each seed value to next seed valu.
514 The state value for the unfold.
517 Creates the tail of the list; defaults to @code{(lambda (x) '())}.
522 @deffn {Scheme Procedure} map f lst1 lst2 @dots{}
523 Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
524 return a list containing the results of the procedure applications.
525 This procedure is extended with respect to R5RS, because the argument
526 lists may have different lengths. The result list will have the same
527 length as the shortest argument lists. The order in which @var{f}
528 will be applied to the list element(s) is not specified.
531 @deffn {Scheme Procedure} for-each f lst1 lst2 @dots{}
532 Apply the procedure @var{f} to each pair of corresponding elements of
533 the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not
534 specified. This procedure is extended with respect to R5RS, because
535 the argument lists may have different lengths. The shortest argument
536 list determines the number of times @var{f} is called. @var{f} will
537 be applied to the list elements in left-to-right order.
541 @deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
542 @deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
546 (apply append (map f clist1 clist2 ...))
552 (apply append! (map f clist1 clist2 ...))
555 Map @var{f} over the elements of the lists, just as in the @code{map}
556 function. However, the results of the applications are appended
557 together to make the final result. @code{append-map} uses
558 @code{append} to append the results together; @code{append-map!} uses
561 The dynamic order in which the various applications of @var{f} are
562 made is not specified.
565 @deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
566 Linear-update variant of @code{map} -- @code{map!} is allowed, but not
567 required, to alter the cons cells of @var{lst1} to construct the
570 The dynamic order in which the various applications of @var{f} are
571 made is not specified. In the n-ary case, @var{lst2}, @var{lst3},
572 @dots{} must have at least as many elements as @var{lst1}.
575 @deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{}
576 Like @code{for-each}, but applies the procedure @var{f} to the pairs
577 from which the argument lists are constructed, instead of the list
578 elements. The return value is not specified.
581 @deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
582 Like @code{map}, but only results from the applications of @var{f}
583 which are true are saved in the result list.
587 @node SRFI-1 Filtering and Partitioning
588 @subsection Filtering and Partitioning
590 @c FIXME::martin: Review me!
592 Filtering means to collect all elements from a list which satisfy a
593 specific condition. Partitioning a list means to make two groups of
594 list elements, one which contains the elements satisfying a condition,
595 and the other for the elements which don't.
597 The @code{filter} and @code{filter!} functions are implemented in the
598 Guile core, @xref{List Modification}.
600 @deffn {Scheme Procedure} partition pred lst
601 @deffnx {Scheme Procedure} partition! pred lst
602 Split @var{lst} into those elements which do and don't satisfy the
603 predicate @var{pred}.
605 The return is two values (@pxref{Multiple Values}), the first being a
606 list of all elements from @var{lst} which satisfy @var{pred}, the
607 second a list of those which do not.
609 The elements in the result lists are in the same order as in @var{lst}
610 but the order in which the calls @code{(@var{pred} elem)} are made on
611 the list elements is unspecified.
613 @code{partition} does not change @var{lst}, but one of the returned
614 lists may share a tail with it. @code{partition!} may modify
615 @var{lst} to construct its return.
618 @deffn {Scheme Procedure} remove pred lst
619 @deffnx {Scheme Procedure} remove! pred lst
620 Return a list containing all elements from @var{lst} which do not
621 satisfy the predicate @var{pred}. The elements in the result list
622 have the same order as in @var{lst}. The order in which @var{pred} is
623 applied to the list elements is not specified.
625 @code{remove!} is allowed, but not required to modify the structure of
630 @node SRFI-1 Searching
631 @subsection Searching
633 @c FIXME::martin: Review me!
635 The procedures for searching elements in lists either accept a
636 predicate or a comparison object for determining which elements are to
639 @deffn {Scheme Procedure} find pred lst
640 Return the first element of @var{lst} which satisfies the predicate
641 @var{pred} and @code{#f} if no such element is found.
644 @deffn {Scheme Procedure} find-tail pred lst
645 Return the first pair of @var{lst} whose @sc{car} satisfies the
646 predicate @var{pred} and @code{#f} if no such element is found.
649 @deffn {Scheme Procedure} take-while pred lst
650 @deffnx {Scheme Procedure} take-while! pred lst
651 Return the longest initial prefix of @var{lst} whose elements all
652 satisfy the predicate @var{pred}.
654 @code{take-while!} is allowed, but not required to modify the input
655 list while producing the result.
658 @deffn {Scheme Procedure} drop-while pred lst
659 Drop the longest initial prefix of @var{lst} whose elements all
660 satisfy the predicate @var{pred}.
663 @deffn {Scheme Procedure} span pred lst
664 @deffnx {Scheme Procedure} span! pred lst
665 @deffnx {Scheme Procedure} break pred lst
666 @deffnx {Scheme Procedure} break! pred lst
667 @code{span} splits the list @var{lst} into the longest initial prefix
668 whose elements all satisfy the predicate @var{pred}, and the remaining
669 tail. @code{break} inverts the sense of the predicate.
671 @code{span!} and @code{break!} are allowed, but not required to modify
672 the structure of the input list @var{lst} in order to produce the
675 Note that the name @code{break} conflicts with the @code{break}
676 binding established by @code{while} (@pxref{while do}). Applications
677 wanting to use @code{break} from within a @code{while} loop will need
678 to make a new define under a different name.
681 @deffn {Scheme Procedure} any pred lst1 lst2 @dots{}
682 Apply @var{pred} across the lists and return a true value if the
683 predicate returns true for any of the list elements(s); return
684 @code{#f} otherwise. The true value returned is always the result of
685 the first successful application of @var{pred}.
688 @deffn {Scheme Procedure} every pred lst1 lst2 @dots{}
689 Apply @var{pred} across the lists and return a true value if the
690 predicate returns true for every of the list elements(s); return
691 @code{#f} otherwise. The true value returned is always the result of
692 the final successful application of @var{pred}.
695 @deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{}
696 Return the index of the leftmost element that satisfies @var{pred}.
699 @deffn {Scheme Procedure} member x lst [=]
700 Return the first sublist of @var{lst} whose @sc{car} is equal to
701 @var{x}. If @var{x} does no appear in @var{lst}, return @code{#f}.
702 Equality is determined by the equality predicate @var{=}, or
703 @code{equal?} if @var{=} is not given.
705 This function extends the core @code{member} by accepting an equality
706 predicate. (@pxref{List Searching})
710 @node SRFI-1 Deleting
713 @c FIXME::martin: Review me!
715 @deffn {Scheme Procedure} delete x lst [=]
716 @deffnx {Scheme Procedure} delete! x lst [=]
717 Return a list containing the elements of @var{lst} but with those
718 equal to @var{x} deleted. The returned elements will be in the same
719 order as they were in @var{lst}.
721 Equality is determined by the @var{=} predicate, or @code{equal?} if
722 not given. An equality call is made just once for each element, but
723 the order in which the calls are made on the elements is unspecified.
725 The equality calls are always @code{(= x elem)}, ie.@: the given @var{x}
726 is first. This means for instance elements greater than 5 can be
727 deleted with @code{(delete 5 lst <)}.
729 @code{delete} does not modify @var{lst}, but the return might share a
730 common tail with @var{lst}. @code{delete!} may modify the structure
731 of @var{lst} to construct its return.
733 These functions extend the core @code{delete} and @code{delete!} in
734 accepting an equality predicate. (@pxref{List Modification})
737 @deffn {Scheme Procedure} delete-duplicates lst [=]
738 @deffnx {Scheme Procedure} delete-duplicates! lst [=]
739 Return a list containing the elements of @var{lst} but without
742 When elements are equal, only the first in @var{lst} is retained.
743 Equal elements can be anywhere in @var{lst}, they don't have to be
744 adjacent. The returned list will have the retained elements in the
745 same order as they were in @var{lst}.
747 Equality is determined by the @var{=} predicate, or @code{equal?} if
748 not given. Calls @code{(= x y)} are made with element @var{x} being
749 before @var{y} in @var{lst}. A call is made at most once for each
750 combination, but the sequence of the calls across the elements is
753 @code{delete-duplicates} does not modify @var{lst}, but the return
754 might share a common tail with @var{lst}. @code{delete-duplicates!}
755 may modify the structure of @var{lst} to construct its return.
757 In the worst case, this is an @math{O(N^2)} algorithm because it must
758 check each element against all those preceding it. For long lists it
759 is more efficient to sort and then compare only adjacent elements.
763 @node SRFI-1 Association Lists
764 @subsection Association Lists
766 @c FIXME::martin: Review me!
768 Association lists are described in detail in section @ref{Association
769 Lists}. The present section only documents the additional procedures
770 for dealing with association lists defined by SRFI-1.
772 @deffn {Scheme Procedure} assoc key alist [=]
773 Return the pair from @var{alist} which matches @var{key}. Equality is
774 determined by @var{=}, which defaults to @code{equal?} if not given.
775 @var{alist} must be an association lists---a list of pairs.
777 This function extends the core @code{assoc} by accepting an equality
778 predicate. (@pxref{Association Lists})
781 @deffn {Scheme Procedure} alist-cons key datum alist
785 (cons (cons @var{key} @var{datum}) @var{alist})
788 This procedure is used to coons a new pair onto an existing
792 @deffn {Scheme Procedure} alist-copy alist
793 Return a newly allocated copy of @var{alist}, that means that the
794 spine of the list as well as the pairs are copied.
797 @deffn {Scheme Procedure} alist-delete key alist [=]
798 @deffnx {Scheme Procedure} alist-delete! key alist [=]
799 Return a list containing the elements of @var{alist} but with those
800 elements whose keys are equal to @var{key} deleted. The returned
801 elements will be in the same order as they were in @var{alist}.
803 Equality is determined by the @var{=} predicate, or @code{equal?} if
804 not given. The order in which elements are tested is unspecified, but
805 each equality call is made @code{(= key alistkey)}, ie. the given
806 @var{key} parameter is first and the key from @var{alist} second.
807 This means for instance all associations with a key greater than 5 can
808 be removed with @code{(alist-delete 5 alist <)}.
810 @code{alist-delete} does not modify @var{alist}, but the return might
811 share a common tail with @var{alist}. @code{alist-delete!} may modify
812 the list structure of @var{alist} to construct its return.
816 @node SRFI-1 Set Operations
817 @subsection Set Operations on Lists
819 @c FIXME::martin: Review me!
821 Lists can be used for representing sets of objects. The procedures
822 documented in this section can be used for such set representations.
823 Man combining several sets or adding elements, they make sure that no
824 object is contained more than once in a given list. Please note that
825 lists are not a too efficient implementation method for sets, so if
826 you need high performance, you should think about implementing a
827 custom data structure for representing sets, such as trees, bitsets,
828 hash tables or something similar.
830 All these procedures accept an equality predicate as the first
831 argument. This predicate is used for testing the objects in the list
834 @deffn {Scheme Procedure} lset<= = list1 @dots{}
835 Return @code{#t} if every @var{listi} is a subset of @var{listi+1},
836 otherwise return @code{#f}. Returns @code{#t} if called with less
837 than two arguments. @var{=} is used for testing element equality.
840 @deffn {Scheme Procedure} lset= = list1 list2 @dots{}
841 Return @code{#t} if all argument lists are equal. @var{=} is used for
842 testing element equality.
845 @deffn {Scheme Procedure} lset-adjoin = list elt1 @dots{}
846 @deffnx {Scheme Procedure} lset-adjoin! = list elt1 @dots{}
847 Add all @var{elts} to the list @var{list}, suppressing duplicates and
848 return the resulting list. @code{lset-adjoin!} is allowed, but not
849 required to modify its first argument. @var{=} is used for testing
853 @deffn {Scheme Procedure} lset-union = list1 @dots{}
854 @deffnx {Scheme Procedure} lset-union! = list1 @dots{}
855 Return the union of all argument list sets. The union is the set of
856 all elements which appear in any of the argument sets.
857 @code{lset-union!} is allowed, but not required to modify its first
858 argument. @var{=} is used for testing element equality.
861 @deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{}
862 @deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{}
863 Return the intersection of all argument list sets. The intersection
864 is the set containing all elements which appear in all argument sets.
865 @code{lset-intersection!} is allowed, but not required to modify its
866 first argument. @var{=} is used for testing element equality.
869 @deffn {Scheme Procedure} lset-difference = list1 list2 @dots{}
870 @deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{}
871 Return the difference of all argument list sets. The difference is
872 the the set containing all elements of the first list which do not
873 appear in the other lists. @code{lset-difference!} is allowed, but
874 not required to modify its first argument. @var{=} is used for testing
878 @deffn {Scheme Procedure} lset-xor = list1 @dots{}
879 @deffnx {Scheme Procedure} lset-xor! = list1 @dots{}
880 Return the set containing all elements which appear in the first
881 argument list set, but not in the second; or, more generally: which
882 appear in an odd number of sets. @code{lset-xor!} is allowed, but
883 not required to modify its first argument. @var{=} is used for testing
887 @deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{}
888 @deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{}
889 Return two values, the difference and the intersection of the argument
890 list sets. This works like a combination of @code{lset-difference} and
891 @code{lset-intersection}, but is more efficient.
892 @code{lset-diff+intersection!} is allowed, but not required to modify
893 its first argument. @var{=} is used for testing element equality. You
894 have to use some means to deal with the multiple values these
895 procedures return (@pxref{Multiple Values}).
900 @section SRFI-2 - and-let*
904 The following syntax can be obtained with
907 (use-modules (srfi srfi-2))
910 @deffn {library syntax} and-let* (clause @dots{}) body @dots{}
911 A combination of @code{and} and @code{let*}.
913 Each @var{clause} is evaluated in turn, and if @code{#f} is obtained
914 then evaluation stops and @code{#f} is returned. If all are
915 non-@code{#f} then @var{body} is evaluated and the last form gives the
916 return value. Each @var{clause} should be one of the following,
920 Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}.
921 Like @code{let*}, that binding is available to subsequent clauses.
923 Evaluate @var{expr} and check for @code{#f}.
925 Get the value bound to @var{symbol} and check for @code{#f}.
928 Notice that @code{(expr)} has an ``extra'' pair of parentheses, for
929 instance @code{((eq? x y))}. One way to remember this is to imagine
930 the @code{symbol} in @code{(symbol expr)} is omitted.
932 @code{and-let*} is good for calculations where a @code{#f} value means
933 termination, but where a non-@code{#f} value is going to be needed in
934 subsequent expressions.
936 The following illustrates this, it returns text between brackets
937 @samp{[...]} in a string, or @code{#f} if there are no such brackets
938 (ie.@: either @code{string-index} gives @code{#f}).
941 (define (extract-brackets str)
942 (and-let* ((start (string-index str #\[))
943 (end (string-index str #\] start)))
944 (substring str (1+ start) end)))
947 The following shows plain variables and expressions tested too.
948 @code{diagnostic-levels} is taken to be an alist associating a
949 diagnostic type with a level. @code{str} is printed only if the type
950 is known and its level is high enough.
953 (define (show-diagnostic type str)
954 (and-let* (want-diagnostics
955 (level (assq-ref diagnostic-levels type))
956 ((>= level current-diagnostic-level)))
960 The advantage of @code{and-let*} is that an extended sequence of
961 expressions and tests doesn't require lots of nesting as would arise
962 from separate @code{and} and @code{let*}, or from @code{cond} with
969 @section SRFI-4 - Homogeneous numeric vector datatypes.
972 @c FIXME::martin: Review me!
974 SRFI-4 defines a set of datatypes for vectors whose elements are all
975 of the same numeric type. Vectors for signed and unsigned exact
976 integer or inexact real numbers in several precisions are available.
978 Procedures similar to the vector procedures (@pxref{Vectors}) are
979 provided for handling these homogeneous vectors, but they are distinct
982 The reason for providing this set of datatypes is that with the
983 limitation (all elements must have the same type), it is possible to
984 implement them much more memory-efficient than normal, heterogenous
987 If you want to use these datatypes and the corresponding procedures,
988 you have to use the module @code{(srfi srfi-4)}.
990 Ten vector data types are provided: Unsigned and signed integer values
991 with 8, 16, 32 and 64 bits and floating point values with 32 and 64
992 bits. In the following descriptions, the tags @code{u8}, @code{s8},
993 @code{u16}, @code{s16}, @code{u32}, @code{s32}, @code{u64},
994 @code{s64}, @code{f32}, @code{f64}, respectively, are used for
995 denoting the various types.
998 * SRFI-4 - Read Syntax:: How to write homogeneous vector literals.
999 * SRFI-4 - Procedures:: Available homogeneous vector procedures.
1003 @node SRFI-4 - Read Syntax
1004 @subsection SRFI-4 - Read Syntax
1006 Homogeneous numeric vectors have an external representation (read
1007 syntax) similar to normal Scheme vectors, but with an additional tag
1008 telling the vector's type.
1014 denotes a homogeneous numeric vector of three elements, which are the
1015 values 1, 2 and 3, represented as 16-bit unsigned integers.
1022 denotes a vector of two elements, which are the values 3.1415 and
1023 2.71, represented as floating-point values of 64 bit precision.
1025 Please note that the read syntax for floating-point vectors conflicts
1026 with Standard Scheme, because there @code{#f} is defined to be the
1027 literal false value. That means, that with the loaded SRFI-4 module,
1028 it is not possible to enter some list like
1034 and hope that it will be parsed as a three-element list with the
1035 elements 1, @code{#f} and 3. In normal use, this should be no
1036 problem, because people tend to terminate tokens sensibly when writing
1039 @node SRFI-4 - Procedures
1040 @subsection SRFI-4 Procedures
1042 The procedures listed in this section are provided for all homogeneous
1043 numeric vector datatypes. For brevity, they are not all documented,
1044 but a summary of the procedures is given. In the following
1045 descriptions, you can replace @code{TAG} by any of the datatype
1046 indicators @code{u8}, @code{s8}, @code{u16}, @code{s16}, @code{u32},
1047 @code{s32}, @code{u64}, @code{s64}, @code{f32} and @code{f64}.
1049 For example, you can use the procedures @code{u8vector?},
1050 @code{make-s8vector}, @code{u16vector}, @code{u32vector-length},
1051 @code{s64vector-ref}, @code{f32vector-set!} or @code{f64vector->list}.
1053 @deffn {Scheme Procedure} TAGvector? obj
1054 Return @code{#t} if @var{obj} is a homogeneous numeric vector of type
1058 @deffn {Scheme Procedure} make-TAGvector n [value]
1059 Create a newly allocated homogeneous numeric vector of type
1060 @code{TAG}, which can hold @var{n} elements. If @var{value} is given,
1061 the vector is initialized with the value, otherwise, the contents of
1062 the returned vector is not specified.
1065 @deffn {Scheme Procedure} TAGvector value1 @dots{}
1066 Create a newly allocated homogeneous numeric vector of type
1067 @code{TAG}. The returned vector is as long as the number of arguments
1068 given, and is initialized with the argument values.
1071 @deffn {Scheme Procedure} TAGvector-length TAGvec
1072 Return the number of elements in @var{TAGvec}.
1075 @deffn {Scheme Procedure} TAGvector-ref TAGvec i
1076 Return the element at index @var{i} in @var{TAGvec}.
1079 @deffn {Scheme Procedure} TAGvector-ref TAGvec i value
1080 Set the element at index @var{i} in @var{TAGvec} to @var{value}. The
1081 return value is not specified.
1084 @deffn {Scheme Procedure} TAGvector->list TAGvec
1085 Return a newly allocated list holding all elements of @var{TAGvec}.
1088 @deffn {Scheme Procedure} list->TAGvector lst
1089 Return a newly allocated homogeneous numeric vector of type @code{TAG},
1090 initialized with the elements of the list @var{lst}.
1095 @section SRFI-6 - Basic String Ports
1098 SRFI-6 defines the procedures @code{open-input-string},
1099 @code{open-output-string} and @code{get-output-string}. These
1100 procedures are included in the Guile core, so using this module does not
1101 make any difference at the moment. But it is possible that support for
1102 SRFI-6 will be factored out of the core library in the future, so using
1103 this module does not hurt, after all.
1106 @section SRFI-8 - receive
1109 @code{receive} is a syntax for making the handling of multiple-value
1110 procedures easier. It is documented in @xref{Multiple Values}.
1114 @section SRFI-9 - define-record-type
1116 @findex define-record-type
1118 This is the SRFI way for defining record types. The Guile
1119 implementation is a layer above Guile's normal record construction
1120 procedures (@pxref{Records}). The nice thing about this kind of record
1121 definition method is that no new names are implicitly created, all
1122 constructor, accessor and predicates are explicitly given. This reduces
1123 the risk of variable capture.
1125 The syntax of a record type definition is:
1129 <record type definition>
1130 -> (define-record-type <type name>
1131 (<constructor name> <field tag> ...)
1134 <field spec> -> (<field tag> <accessor name>)
1135 -> (<field tag> <accessor name> <modifier name>)
1136 <field tag> -> <identifier>
1137 <... name> -> <identifier>
1144 guile> (use-modules (srfi srfi-9))
1145 guile> (define-record-type :foo (make-foo x) foo?
1146 (x get-x) (y get-y set-y!))
1147 guile> (define f (make-foo 1))
1166 @section SRFI-10 - Hash-Comma Reader Extension
1171 The module @code{(srfi srfi-10)} implements the syntax extension
1172 @code{#,()}, also called hash-comma, which is defined in SRFI-10.
1174 The support for SRFI-10 consists of the procedure
1175 @code{define-reader-ctor} for defining new reader constructors and the
1179 #,(@var{ctor} @var{datum} ...)
1182 where @var{ctor} must be a symbol for which a read constructor was
1183 defined previously, using @code{define-reader-ctor}.
1188 (use-modules (ice-9 rdelim)) ; for read-line
1189 (define-reader-ctor 'file open-input-file)
1190 (define f '#,(file "/etc/passwd"))
1193 "root:x:0:0:root:/root:/bin/bash"
1196 Please note the quote before the @code{#,(file ...)} expression. This
1197 is necessary because ports are not self-evaluating in Guile.
1199 @deffn {Scheme Procedure} define-reader-ctor symbol proc
1200 Define @var{proc} as the reader constructor for hash-comma forms with a
1201 tag @var{symbol}. @var{proc} will be applied to the datum(s) following
1202 the tag in the hash-comma expression after the complete form has been
1203 read in. The result of @var{proc} is returned by the Scheme reader.
1208 @section SRFI-11 - let-values
1213 This module implements the binding forms for multiple values
1214 @code{let-values} and @code{let-values*}. These forms are similar to
1215 @code{let} and @code{let*} (@pxref{Local Bindings}), but they support
1216 binding of the values returned by multiple-valued expressions.
1218 Write @code{(use-modules (srfi srfi-11))} to make the bindings
1222 (let-values (((x y) (values 1 2))
1223 ((z f) (values 3 4)))
1229 @code{let-values} performs all bindings simultaneously, which means that
1230 no expression in the binding clauses may refer to variables bound in the
1231 same clause list. @code{let-values*}, on the other hand, performs the
1232 bindings sequentially, just like @code{let*} does for single-valued
1237 @section SRFI-13 - String Library
1240 In this section, we will describe all procedures defined in SRFI-13
1241 (string library) and implemented by the module @code{(srfi srfi-13)}.
1243 Note that only the procedures from SRFI-13 are documented here which are
1244 not already contained in Guile. For procedures not documented here
1245 please refer to the relevant chapters in the Guile Reference Manual, for
1246 example the documentation of strings and string procedures
1249 All of the procedures defined in SRFI-13, which are not already
1250 included in the Guile core library, are implemented in the module
1251 @code{(srfi srfi-13)}. The procedures which are both in Guile and in
1252 SRFI-13 are slightly extended in this module. Their bindings
1253 overwrite those in the Guile core.
1255 The procedures which are defined in the section @emph{Low-level
1256 procedures} of SRFI-13 for parsing optional string indices, substring
1257 specification checking and Knuth-Morris-Pratt-Searching are not
1260 The procedures @code{string-contains} and @code{string-contains-ci} are
1261 not implemented very efficiently at the moment. This will be changed as
1265 * Loading SRFI-13:: How to load SRFI-13 support.
1266 * SRFI-13 Predicates:: String predicates.
1267 * SRFI-13 Constructors:: String constructing procedures.
1268 * SRFI-13 List/String Conversion:: Conversion from/to lists.
1269 * SRFI-13 Selection:: Selection portions of strings.
1270 * SRFI-13 Modification:: Modify strings in-place.
1271 * SRFI-13 Comparison:: Compare strings.
1272 * SRFI-13 Prefixes/Suffixes:: Detect common pre-/suffixes.
1273 * SRFI-13 Searching:: Searching for substrings.
1274 * SRFI-13 Case Mapping:: Mapping to lower-/upper-case.
1275 * SRFI-13 Reverse/Append:: Reverse and append strings.
1276 * SRFI-13 Fold/Unfold/Map:: Construct/deconstruct strings.
1277 * SRFI-13 Replicate/Rotate:: Replicate and rotate portions of strings.
1278 * SRFI-13 Miscellaneous:: Left-over string procedures.
1279 * SRFI-13 Filtering/Deleting:: Filter and delete characters from strings.
1283 @node Loading SRFI-13
1284 @subsection Loading SRFI-13
1286 When Guile is properly installed, SRFI-13 support can be loaded into a
1287 running Guile by using the @code{(srfi srfi-13)} module.
1291 guile> (use-modules (srfi srfi-13))
1295 When this step causes any errors, Guile is not properly installed.
1297 One possible reason is that Guile cannot find either the Scheme module
1298 file @file{srfi-13.scm}, or it cannot find the shared object file
1299 @file{libguile-srfi-srfi-13-14.so}. Make sure that the former is in the
1300 Guile load path and that the latter is either installed in some default
1301 location like @file{/usr/local/lib} or that the directory it was
1302 installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to
1305 Now you can test whether the SRFI-13 procedures are working by calling
1306 the @code{string-concatenate} procedure.
1309 guile> (string-concatenate '("Hello" " " "World!"))
1313 @node SRFI-13 Predicates
1314 @subsection Predicates
1316 In addition to the primitives @code{string?} and @code{string-null?},
1317 which are already in the Guile core, the string predicates
1318 @code{string-any} and @code{string-every} are defined by SRFI-13.
1320 @deffn {Scheme Procedure} string-any pred s [start end]
1321 Check if the predicate @var{pred} is true for any character in
1322 the string @var{s}, proceeding from left (index @var{start}) to
1323 right (index @var{end}). If @code{string-any} returns true,
1324 the returned true value is the one produced by the first
1325 successful application of @var{pred}.
1328 @deffn {Scheme Procedure} string-every pred s [start end]
1329 Check if the predicate @var{pred} is true for every character
1330 in the string @var{s}, proceeding from left (index @var{start})
1331 to right (index @var{end}). If @code{string-every} returns
1332 true, the returned true value is the one produced by the final
1333 application of @var{pred} to the last character of @var{s}.
1337 @c ===================================================================
1339 @node SRFI-13 Constructors
1340 @subsection Constructors
1342 SRFI-13 defines several procedures for constructing new strings. In
1343 addition to @code{make-string} and @code{string} (available in the Guile
1344 core library), the procedure @code{string-tabulate} does exist.
1346 @deffn {Scheme Procedure} string-tabulate proc len
1347 @var{proc} is an integer->char procedure. Construct a string
1348 of size @var{len} by applying @var{proc} to each index to
1349 produce the corresponding string element. The order in which
1350 @var{proc} is applied to the indices is not specified.
1354 @c ===================================================================
1356 @node SRFI-13 List/String Conversion
1357 @subsection List/String Conversion
1359 The procedure @code{string->list} is extended by SRFI-13, that is why it
1360 is included in @code{(srfi srfi-13)}. The other procedures are new.
1361 The Guile core already contains the procedure @code{list->string} for
1362 converting a list of characters into a string (@pxref{List/String
1365 @deffn {Scheme Procedure} string->list str [start end]
1366 Convert the string @var{str} into a list of characters.
1369 @deffn {Scheme Procedure} reverse-list->string chrs
1370 An efficient implementation of @code{(compose string->list
1374 (reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
1378 @deffn {Scheme Procedure} string-join ls [delimiter grammar]
1379 Append the string in the string list @var{ls}, using the string
1380 @var{delim} as a delimiter between the elements of @var{ls}.
1381 @var{grammar} is a symbol which specifies how the delimiter is
1382 placed between the strings, and defaults to the symbol
1387 Insert the separator between list elements. An empty string
1388 will produce an empty list.
1391 Like @code{infix}, but will raise an error if given the empty
1395 Insert the separator after every list element.
1398 Insert the separator before each list element.
1403 @c ===================================================================
1405 @node SRFI-13 Selection
1406 @subsection Selection
1408 These procedures are called @dfn{selectors}, because they access
1409 information about the string or select pieces of a given string.
1411 Additional selector procedures are documented in the Strings section
1412 (@pxref{String Selection}), like @code{string-length} or
1415 @code{string-copy} is also available in core Guile, but this version
1416 accepts additional start/end indices.
1418 @deffn {Scheme Procedure} string-copy str [start end]
1419 Return a freshly allocated copy of the string @var{str}. If
1420 given, @var{start} and @var{end} delimit the portion of
1421 @var{str} which is copied.
1424 @deffn {Scheme Procedure} substring/shared str start [end]
1425 Like @code{substring}, but the result may share memory with the
1429 @deffn {Scheme Procedure} string-copy! target tstart s [start end]
1430 Copy the sequence of characters from index range [@var{start},
1431 @var{end}) in string @var{s} to string @var{target}, beginning
1432 at index @var{tstart}. The characters are copied left-to-right
1433 or right-to-left as needed - the copy is guaranteed to work,
1434 even if @var{target} and @var{s} are the same string. It is an
1435 error if the copy operation runs off the end of the target
1439 @deffn {Scheme Procedure} string-take s n
1440 @deffnx {Scheme Procedure} string-take-right s n
1441 Return the @var{n} first/last characters of @var{s}.
1444 @deffn {Scheme Procedure} string-drop s n
1445 @deffnx {Scheme Procedure} string-drop-right s n
1446 Return all but the first/last @var{n} characters of @var{s}.
1449 @deffn {Scheme Procedure} string-pad s len [chr start end]
1450 @deffnx {Scheme Procedure} string-pad-right s len [chr start end]
1451 Take that characters from @var{start} to @var{end} from the
1452 string @var{s} and return a new string, right(left)-padded by the
1453 character @var{chr} to length @var{len}. If the resulting
1454 string is longer than @var{len}, it is truncated on the right (left).
1457 @deffn {Scheme Procedure} string-trim s [char_pred start end]
1458 @deffnx {Scheme Procedure} string-trim-right s [char_pred start end]
1459 @deffnx {Scheme Procedure} string-trim-both s [char_pred start end]
1460 Trim @var{s} by skipping over all characters on the left/right/both
1461 sides of the string that satisfy the parameter @var{char_pred}:
1465 if it is the character @var{ch}, characters equal to
1466 @var{ch} are trimmed,
1469 if it is a procedure @var{pred} characters that
1470 satisfy @var{pred} are trimmed,
1473 if it is a character set, characters in that set are trimmed.
1476 If called without a @var{char_pred} argument, all whitespace is
1481 @c ===================================================================
1483 @node SRFI-13 Modification
1484 @subsection Modification
1486 The procedure @code{string-fill!} is extended from R5RS because it
1487 accepts optional start/end indices. This bindings shadows the procedure
1488 of the same name in the Guile core. The second modification procedure
1489 @code{string-set!} is documented in the Strings section (@pxref{String
1492 @deffn {Scheme Procedure} string-fill! str chr [start end]
1493 Stores @var{chr} in every element of the given @var{str} and
1494 returns an unspecified value.
1498 @c ===================================================================
1500 @node SRFI-13 Comparison
1501 @subsection Comparison
1503 The procedures in this section are used for comparing strings in
1504 different ways. The comparison predicates differ from those in R5RS in
1505 that they do not only return @code{#t} or @code{#f}, but the mismatch
1506 index in the case of a true return value.
1508 @code{string-hash} and @code{string-hash-ci} are for calculating hash
1509 values for strings, useful for implementing fast lookup mechanisms.
1511 @deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
1512 @deffnx {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
1513 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
1514 mismatch index, depending upon whether @var{s1} is less than,
1515 equal to, or greater than @var{s2}. The mismatch index is the
1516 largest index @var{i} such that for every 0 <= @var{j} <
1517 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] - that is,
1518 @var{i} is the first position that does not match. The
1519 character comparison is done case-insensitively.
1522 @deffn {Scheme Procedure} string= s1 s2 [start1 end1 start2 end2]
1523 @deffnx {Scheme Procedure} string<> s1 s2 [start1 end1 start2 end2]
1524 @deffnx {Scheme Procedure} string< s1 s2 [start1 end1 start2 end2]
1525 @deffnx {Scheme Procedure} string> s1 s2 [start1 end1 start2 end2]
1526 @deffnx {Scheme Procedure} string<= s1 s2 [start1 end1 start2 end2]
1527 @deffnx {Scheme Procedure} string>= s1 s2 [start1 end1 start2 end2]
1528 Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
1529 fails. Otherwise, the mismatch index is returned (or @var{end1} in the
1530 case of @code{string=}.
1533 @deffn {Scheme Procedure} string-ci= s1 s2 [start1 end1 start2 end2]
1534 @deffnx {Scheme Procedure} string-ci<> s1 s2 [start1 end1 start2 end2]
1535 @deffnx {Scheme Procedure} string-ci< s1 s2 [start1 end1 start2 end2]
1536 @deffnx {Scheme Procedure} string-ci> s1 s2 [start1 end1 start2 end2]
1537 @deffnx {Scheme Procedure} string-ci<= s1 s2 [start1 end1 start2 end2]
1538 @deffnx {Scheme Procedure} string-ci>= s1 s2 [start1 end1 start2 end2]
1539 Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
1540 fails. Otherwise, the mismatch index is returned (or @var{end1} in the
1541 case of @code{string=}. These are the case-insensitive variants.
1544 @deffn {Scheme Procedure} string-hash s [bound start end]
1545 @deffnx {Scheme Procedure} string-hash-ci s [bound start end]
1546 Return a hash value of the string @var{s} in the range 0 @dots{}
1547 @var{bound} - 1. @code{string-hash-ci} is the case-insensitive variant.
1551 @c ===================================================================
1553 @node SRFI-13 Prefixes/Suffixes
1554 @subsection Prefixes/Suffixes
1556 Using these procedures you can determine whether a given string is a
1557 prefix or suffix of another string or how long a common prefix/suffix
1560 @deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 end1 start2 end2]
1561 @deffnx {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 end1 start2 end2]
1562 @deffnx {Scheme Procedure} string-suffix-length s1 s2 [start1 end1 start2 end2]
1563 @deffnx {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 end1 start2 end2]
1564 Return the length of the longest common prefix/suffix of the two
1565 strings. @code{string-prefix-length-ci} and
1566 @code{string-suffix-length-ci} are the case-insensitive variants.
1569 @deffn {Scheme Procedure} string-prefix? s1 s2 [start1 end1 start2 end2]
1570 @deffnx {Scheme Procedure} string-prefix-ci? s1 s2 [start1 end1 start2 end2]
1571 @deffnx {Scheme Procedure} string-suffix? s1 s2 [start1 end1 start2 end2]
1572 @deffnx {Scheme Procedure} string-suffix-ci? s1 s2 [start1 end1 start2 end2]
1573 Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and
1574 @code{string-suffix-ci?} are the case-insensitive variants.
1578 @c ===================================================================
1580 @node SRFI-13 Searching
1581 @subsection Searching
1583 Use these procedures to find out whether a string contains a given
1584 character or a given substring, or a character from a set of characters.
1586 @deffn {Scheme Procedure} string-index s char_pred [start end]
1587 @deffnx {Scheme Procedure} string-index-right s char_pred [start end]
1588 Search through the string @var{s} from left to right (right to left),
1589 returning the index of the first (last) occurrence of a character which
1593 equals @var{char_pred}, if it is character,
1596 satisfies the predicate @var{char_pred}, if it is a
1600 is in the set @var{char_pred}, if it is a character set.
1604 @deffn {Scheme Procedure} string-skip s char_pred [start end]
1605 @deffnx {Scheme Procedure} string-skip-right s char_pred [start end]
1606 Search through the string @var{s} from left to right (right to left),
1607 returning the index of the first (last) occurrence of a character which
1611 does not equal @var{char_pred}, if it is character,
1614 does not satisfy the predicate @var{char_pred}, if it is
1618 is not in the set if @var{char_pred} is a character set.
1622 @deffn {Scheme Procedure} string-count s char_pred [start end]
1623 Return the count of the number of characters in the string
1628 equals @var{char_pred}, if it is character,
1631 satisfies the predicate @var{char_pred}, if it is a procedure.
1634 is in the set @var{char_pred}, if it is a character set.
1638 @deffn {Scheme Procedure} string-contains s1 s2 [start1 end1 start2 end2]
1639 @deffnx {Scheme Procedure} string-contains-ci s1 s2 [start1 end1 start2 end2]
1640 Does string @var{s1} contain string @var{s2}? Return the index
1641 in @var{s1} where @var{s2} occurs as a substring, or false.
1642 The optional start/end indices restrict the operation to the
1643 indicated substrings.
1645 @code{string-contains-ci} is the case-insensitive variant.
1649 @c ===================================================================
1651 @node SRFI-13 Case Mapping
1652 @subsection Alphabetic Case Mapping
1654 These procedures convert the alphabetic case of strings. They are
1655 similar to the procedures in the Guile core, but are extended to handle
1656 optional start/end indices.
1658 @deffn {Scheme Procedure} string-upcase s [start end]
1659 @deffnx {Scheme Procedure} string-upcase! s [start end]
1660 Upcase every character in @var{s}. @code{string-upcase!} is the
1661 side-effecting variant.
1664 @deffn {Scheme Procedure} string-downcase s [start end]
1665 @deffnx {Scheme Procedure} string-downcase! s [start end]
1666 Downcase every character in @var{s}. @code{string-downcase!} is the
1667 side-effecting variant.
1670 @deffn {Scheme Procedure} string-titlecase s [start end]
1671 @deffnx {Scheme Procedure} string-titlecase! s [start end]
1672 Upcase every first character in every word in @var{s}, downcase the
1673 other characters. @code{string-titlecase!} is the side-effecting
1678 @c ===================================================================
1680 @node SRFI-13 Reverse/Append
1681 @subsection Reverse/Append
1683 One appending procedure, @code{string-append} is the same in R5RS and in
1684 SRFI-13, so it is not redefined.
1686 @deffn {Scheme Procedure} string-reverse str [start end]
1687 @deffnx {Scheme Procedure} string-reverse! str [start end]
1688 Reverse the string @var{str}. The optional arguments
1689 @var{start} and @var{end} delimit the region of @var{str} to
1692 @code{string-reverse!} modifies the argument string and returns an
1696 @deffn {Scheme Procedure} string-append/shared ls @dots{}
1697 Like @code{string-append}, but the result may share memory
1698 with the argument strings.
1701 @deffn {Scheme Procedure} string-concatenate ls
1702 Append the elements of @var{ls} (which must be strings)
1703 together into a single string. Guaranteed to return a freshly
1707 @deffn {Scheme Procedure} string-concatenate/shared ls
1708 Like @code{string-concatenate}, but the result may share memory
1709 with the strings in the list @var{ls}.
1712 @deffn {Scheme Procedure} string-concatenate-reverse ls final_string end
1713 Without optional arguments, this procedure is equivalent to
1716 (string-concatenate (reverse ls))
1719 If the optional argument @var{final_string} is specified, it is
1720 consed onto the beginning to @var{ls} before performing the
1721 list-reverse and string-concatenate operations. If @var{end}
1722 is given, only the characters of @var{final_string} up to index
1725 Guaranteed to return a freshly allocated string.
1728 @deffn {Scheme Procedure} string-concatenate-reverse/shared ls final_string end
1729 Like @code{string-concatenate-reverse}, but the result may
1730 share memory with the the strings in the @var{ls} arguments.
1734 @c ===================================================================
1736 @node SRFI-13 Fold/Unfold/Map
1737 @subsection Fold/Unfold/Map
1739 @code{string-map}, @code{string-for-each} etc. are for iterating over
1740 the characters a string is composed of. The fold and unfold procedures
1741 are list iterators and constructors.
1743 @deffn {Scheme Procedure} string-map proc s [start end]
1744 @var{proc} is a char->char procedure, it is mapped over
1745 @var{s}. The order in which the procedure is applied to the
1746 string elements is not specified.
1749 @deffn {Scheme Procedure} string-map! proc s [start end]
1750 @var{proc} is a char->char procedure, it is mapped over
1751 @var{s}. The order in which the procedure is applied to the
1752 string elements is not specified. The string @var{s} is
1753 modified in-place, the return value is not specified.
1756 @deffn {Scheme Procedure} string-fold kons knil s [start end]
1757 @deffnx {Scheme Procedure} string-fold-right kons knil s [start end]
1758 Fold @var{kons} over the characters of @var{s}, with @var{knil} as the
1759 terminating element, from left to right (or right to left, for
1760 @code{string-fold-right}). @var{kons} must expect two arguments: The
1761 actual character and the last result of @var{kons}' application.
1764 @deffn {Scheme Procedure} string-unfold p f g seed [base make_final]
1765 @deffnx {Scheme Procedure} string-unfold-right p f g seed [base make_final]
1766 These are the fundamental string constructors.
1768 @item @var{g} is used to generate a series of @emph{seed}
1769 values from the initial @var{seed}: @var{seed}, (@var{g}
1770 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
1772 @item @var{p} tells us when to stop - when it returns true
1773 when applied to one of these seed values.
1774 @item @var{f} maps each seed value to the corresponding
1775 character in the result string. These chars are assembled into the
1776 string in a left-to-right (right-to-left) order.
1777 @item @var{base} is the optional initial/leftmost (rightmost)
1778 portion of the constructed string; it default to the empty string.
1779 @item @var{make_final} is applied to the terminal seed
1780 value (on which @var{p} returns true) to produce the final/rightmost
1781 (leftmost) portion of the constructed string. It defaults to
1782 @code{(lambda (x) "")}.
1786 @deffn {Scheme Procedure} string-for-each proc s [start end]
1787 @var{proc} is mapped over @var{s} in left-to-right order. The
1788 return value is not specified.
1792 @c ===================================================================
1794 @node SRFI-13 Replicate/Rotate
1795 @subsection Replicate/Rotate
1797 These procedures are special substring procedures, which can also be
1798 used for replicating strings. They are a bit tricky to use, but
1799 consider this code fragment, which replicates the input string
1800 @code{"foo"} so often that the resulting string has a length of six.
1803 (xsubstring "foo" 0 6)
1808 @deffn {Scheme Procedure} xsubstring s from [to start end]
1809 This is the @emph{extended substring} procedure that implements
1810 replicated copying of a substring of some string.
1812 @var{s} is a string, @var{start} and @var{end} are optional
1813 arguments that demarcate a substring of @var{s}, defaulting to
1814 0 and the length of @var{s}. Replicate this substring up and
1815 down index space, in both the positive and negative directions.
1816 @code{xsubstring} returns the substring of this string
1817 beginning at index @var{from}, and ending at @var{to}, which
1818 defaults to @var{from} + (@var{end} - @var{start}).
1821 @deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto start end]
1822 Exactly the same as @code{xsubstring}, but the extracted text
1823 is written into the string @var{target} starting at index
1824 @var{tstart}. The operation is not defined if @code{(eq?
1825 @var{target} @var{s})} or these arguments share storage - you
1826 cannot copy a string on top of itself.
1830 @c ===================================================================
1832 @node SRFI-13 Miscellaneous
1833 @subsection Miscellaneous
1835 @code{string-replace} is for replacing a portion of a string with
1836 another string and @code{string-tokenize} splits a string into a list of
1837 strings, breaking it up at a specified character.
1839 @deffn {Scheme Procedure} string-replace s1 s2 [start1 end1 start2 end2]
1840 Return the string @var{s1}, but with the characters
1841 @var{start1} @dots{} @var{end1} replaced by the characters
1842 @var{start2} @dots{} @var{end2} from @var{s2}.
1844 For reference, note that SRFI-13 specifies @var{start1} and @var{end1}
1845 as mandatory, but in Guile they are optional.
1848 @deffn {Scheme Procedure} string-tokenize s [token-set start end]
1849 Split the string @var{s} into a list of substrings, where each
1850 substring is a maximal non-empty contiguous sequence of characters
1851 from the character set @var{token_set}, which defaults to an
1852 equivalent of @code{char-set:graphic}. If @var{start} or @var{end}
1853 indices are provided, they restrict @code{string-tokenize} to
1854 operating on the indicated substring of @var{s}.
1858 @c ===================================================================
1860 @node SRFI-13 Filtering/Deleting
1861 @subsection Filtering/Deleting
1863 @dfn{Filtering} means to remove all characters from a string which do
1864 not match a given criteria, @dfn{deleting} means the opposite.
1866 @deffn {Scheme Procedure} string-filter s char_pred [start end]
1867 Filter the string @var{s}, retaining only those characters that
1868 satisfy the @var{char_pred} argument. If the argument is a
1869 procedure, it is applied to each character as a predicate, if
1870 it is a character, it is tested for equality and if it is a
1871 character set, it is tested for membership.
1874 @deffn {Scheme Procedure} string-delete s char_pred [start end]
1875 Filter the string @var{s}, retaining only those characters that
1876 do not satisfy the @var{char_pred} argument. If the argument
1877 is a procedure, it is applied to each character as a predicate,
1878 if it is a character, it is tested for equality and if it is a
1879 character set, it is tested for membership.
1884 @section SRFI-14 - Character-set Library
1887 SRFI-14 defines the data type @dfn{character set}, and also defines a
1888 lot of procedures for handling this character type, and a few standard
1889 character sets like whitespace, alphabetic characters and others.
1891 All procedures from SRFI-14 (character-set library) are implemented in
1892 the module @code{(srfi srfi-14)}, as well as the standard variables
1893 @code{char-set:letter}, @code{char-set:digit} etc.
1896 * Loading SRFI-14:: How to make charsets available.
1897 * SRFI-14 Character Set Data Type:: Underlying data type for charsets.
1898 * SRFI-14 Predicates/Comparison:: Charset predicates.
1899 * SRFI-14 Iterating Over Character Sets:: Enumerate charset elements.
1900 * SRFI-14 Creating Character Sets:: Making new charsets.
1901 * SRFI-14 Querying Character Sets:: Test charsets for membership etc.
1902 * SRFI-14 Character-Set Algebra:: Calculating new charsets.
1903 * SRFI-14 Standard Character Sets:: Variables containing predefined charsets.
1907 @node Loading SRFI-14
1908 @subsection Loading SRFI-14
1910 When Guile is properly installed, SRFI-14 support can be loaded into a
1911 running Guile by using the @code{(srfi srfi-14)} module.
1915 guile> (use-modules (srfi srfi-14))
1916 guile> (char-set-union (char-set #\f #\o #\o) (string->char-set "bar"))
1917 #<charset @{#\a #\b #\f #\o #\r@}>
1922 @node SRFI-14 Character Set Data Type
1923 @subsection Character Set Data Type
1925 The data type @dfn{charset} implements sets of characters
1926 (@pxref{Characters}). Because the internal representation of character
1927 sets is not visible to the user, a lot of procedures for handling them
1930 Character sets can be created, extended, tested for the membership of a
1931 characters and be compared to other character sets.
1933 The Guile implementation of character sets deals with 8-bit characters.
1934 In the standard variables, only the ASCII part of the character range is
1935 really used, so that for example @dfn{Umlaute} and other accented
1936 characters are not considered to be letters. In the future, as Guile
1937 may get support for international character sets, this will change, so
1938 don't rely on these ``features''.
1941 @c ===================================================================
1943 @node SRFI-14 Predicates/Comparison
1944 @subsection Predicates/Comparison
1946 Use these procedures for testing whether an object is a character set,
1947 or whether several character sets are equal or subsets of each other.
1948 @code{char-set-hash} can be used for calculating a hash value, maybe for
1949 usage in fast lookup procedures.
1951 @deffn {Scheme Procedure} char-set? obj
1952 Return @code{#t} if @var{obj} is a character set, @code{#f}
1956 @deffn {Scheme Procedure} char-set= cs1 @dots{}
1957 Return @code{#t} if all given character sets are equal.
1960 @deffn {Scheme Procedure} char-set<= cs1 @dots{}
1961 Return @code{#t} if every character set @var{cs}i is a subset
1962 of character set @var{cs}i+1.
1965 @deffn {Scheme Procedure} char-set-hash cs [bound]
1966 Compute a hash value for the character set @var{cs}. If
1967 @var{bound} is given and not @code{#f}, it restricts the
1968 returned value to the range 0 @dots{} @var{bound - 1}.
1972 @c ===================================================================
1974 @node SRFI-14 Iterating Over Character Sets
1975 @subsection Iterating Over Character Sets
1977 Character set cursors are a means for iterating over the members of a
1978 character sets. After creating a character set cursor with
1979 @code{char-set-cursor}, a cursor can be dereferenced with
1980 @code{char-set-ref}, advanced to the next member with
1981 @code{char-set-cursor-next}. Whether a cursor has passed past the last
1982 element of the set can be checked with @code{end-of-char-set?}.
1984 Additionally, mapping and (un-)folding procedures for character sets are
1987 @deffn {Scheme Procedure} char-set-cursor cs
1988 Return a cursor into the character set @var{cs}.
1991 @deffn {Scheme Procedure} char-set-ref cs cursor
1992 Return the character at the current cursor position
1993 @var{cursor} in the character set @var{cs}. It is an error to
1994 pass a cursor for which @code{end-of-char-set?} returns true.
1997 @deffn {Scheme Procedure} char-set-cursor-next cs cursor
1998 Advance the character set cursor @var{cursor} to the next
1999 character in the character set @var{cs}. It is an error if the
2000 cursor given satisfies @code{end-of-char-set?}.
2003 @deffn {Scheme Procedure} end-of-char-set? cursor
2004 Return @code{#t} if @var{cursor} has reached the end of a
2005 character set, @code{#f} otherwise.
2008 @deffn {Scheme Procedure} char-set-fold kons knil cs
2009 Fold the procedure @var{kons} over the character set @var{cs},
2010 initializing it with @var{knil}.
2013 @deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
2014 @deffnx {Scheme Procedure} char-set-unfold! p f g seed base_cs
2015 This is a fundamental constructor for character sets.
2017 @item @var{g} is used to generate a series of ``seed'' values
2018 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2019 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2020 @item @var{p} tells us when to stop -- when it returns true
2021 when applied to one of the seed values.
2022 @item @var{f} maps each seed value to a character. These
2023 characters are added to the base character set @var{base_cs} to
2024 form the result; @var{base_cs} defaults to the empty set.
2027 @code{char-set-unfold!} is the side-effecting variant.
2030 @deffn {Scheme Procedure} char-set-for-each proc cs
2031 Apply @var{proc} to every character in the character set
2032 @var{cs}. The return value is not specified.
2035 @deffn {Scheme Procedure} char-set-map proc cs
2036 Map the procedure @var{proc} over every character in @var{cs}.
2037 @var{proc} must be a character -> character procedure.
2041 @c ===================================================================
2043 @node SRFI-14 Creating Character Sets
2044 @subsection Creating Character Sets
2046 New character sets are produced with these procedures.
2048 @deffn {Scheme Procedure} char-set-copy cs
2049 Return a newly allocated character set containing all
2050 characters in @var{cs}.
2053 @deffn {Scheme Procedure} char-set char1 @dots{}
2054 Return a character set containing all given characters.
2057 @deffn {Scheme Procedure} list->char-set char_list [base_cs]
2058 @deffnx {Scheme Procedure} list->char-set! char_list base_cs
2059 Convert the character list @var{list} to a character set. If
2060 the character set @var{base_cs} is given, the character in this
2061 set are also included in the result.
2063 @code{list->char-set!} is the side-effecting variant.
2066 @deffn {Scheme Procedure} string->char-set s [base_cs]
2067 @deffnx {Scheme Procedure} string->char-set! s base_cs
2068 Convert the string @var{str} to a character set. If the
2069 character set @var{base_cs} is given, the characters in this
2070 set are also included in the result.
2072 @code{string->char-set!} is the side-effecting variant.
2075 @deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
2076 @deffnx {Scheme Procedure} char-set-filter! pred cs base_cs
2077 Return a character set containing every character from @var{cs}
2078 so that it satisfies @var{pred}. If provided, the characters
2079 from @var{base_cs} are added to the result.
2081 @code{char-set-filter!} is the side-effecting variant.
2084 @deffn {Scheme Procedure} ucs-range->char-set lower upper [error? base_cs]
2085 @deffnx {Scheme Procedure} uce-range->char-set! lower upper error? base_cs
2086 Return a character set containing all characters whose
2087 character codes lie in the half-open range
2088 [@var{lower},@var{upper}).
2090 If @var{error} is a true value, an error is signalled if the
2091 specified range contains characters which are not contained in
2092 the implemented character range. If @var{error} is @code{#f},
2093 these characters are silently left out of the resulting
2096 The characters in @var{base_cs} are added to the result, if
2099 @code{ucs-range->char-set!} is the side-effecting variant.
2102 @deffn {Scheme Procedure} ->char-set x
2103 Coerce @var{x} into a character set. @var{x} may be a string, a
2104 character or a character set.
2108 @c ===================================================================
2110 @node SRFI-14 Querying Character Sets
2111 @subsection Querying Character Sets
2113 Access the elements and other information of a character set with these
2116 @deffn {Scheme Procedure} char-set-size cs
2117 Return the number of elements in character set @var{cs}.
2120 @deffn {Scheme Procedure} char-set-count pred cs
2121 Return the number of the elements int the character set
2122 @var{cs} which satisfy the predicate @var{pred}.
2125 @deffn {Scheme Procedure} char-set->list cs
2126 Return a list containing the elements of the character set
2130 @deffn {Scheme Procedure} char-set->string cs
2131 Return a string containing the elements of the character set
2132 @var{cs}. The order in which the characters are placed in the
2133 string is not defined.
2136 @deffn {Scheme Procedure} char-set-contains? cs char
2137 Return @code{#t} iff the character @var{ch} is contained in the
2138 character set @var{cs}.
2141 @deffn {Scheme Procedure} char-set-every pred cs
2142 Return a true value if every character in the character set
2143 @var{cs} satisfies the predicate @var{pred}.
2146 @deffn {Scheme Procedure} char-set-any pred cs
2147 Return a true value if any character in the character set
2148 @var{cs} satisfies the predicate @var{pred}.
2152 @c ===================================================================
2154 @node SRFI-14 Character-Set Algebra
2155 @subsection Character-Set Algebra
2157 Character sets can be manipulated with the common set algebra operation,
2158 such as union, complement, intersection etc. All of these procedures
2159 provide side-effecting variants, which modify their character set
2162 @deffn {Scheme Procedure} char-set-adjoin cs char1 @dots{}
2163 @deffnx {Scheme Procedure} char-set-adjoin! cs char1 @dots{}
2164 Add all character arguments to the first argument, which must
2168 @deffn {Scheme Procedure} char-set-delete cs char1 @dots{}
2169 @deffnx {Scheme Procedure} char-set-delete! cs char1 @dots{}
2170 Delete all character arguments from the first argument, which
2171 must be a character set.
2174 @deffn {Scheme Procedure} char-set-complement cs
2175 @deffnx {Scheme Procedure} char-set-complement! cs
2176 Return the complement of the character set @var{cs}.
2179 @deffn {Scheme Procedure} char-set-union cs1 @dots{}
2180 @deffnx {Scheme Procedure} char-set-union! cs1 @dots{}
2181 Return the union of all argument character sets.
2184 @deffn {Scheme Procedure} char-set-intersection cs1 @dots{}
2185 @deffnx {Scheme Procedure} char-set-intersection! cs1 @dots{}
2186 Return the intersection of all argument character sets.
2189 @deffn {Scheme Procedure} char-set-difference cs1 @dots{}
2190 @deffnx {Scheme Procedure} char-set-difference! cs1 @dots{}
2191 Return the difference of all argument character sets.
2194 @deffn {Scheme Procedure} char-set-xor cs1 @dots{}
2195 @deffnx {Scheme Procedure} char-set-xor! cs1 @dots{}
2196 Return the exclusive-or of all argument character sets.
2199 @deffn {Scheme Procedure} char-set-diff+intersection cs1 @dots{}
2200 @deffnx {Scheme Procedure} char-set-diff+intersection! cs1 @dots{}
2201 Return the difference and the intersection of all argument
2206 @c ===================================================================
2208 @node SRFI-14 Standard Character Sets
2209 @subsection Standard Character Sets
2211 In order to make the use of the character set data type and procedures
2212 useful, several predefined character set variables exist.
2214 @defvar char-set:lower-case
2215 All lower-case characters.
2218 @defvar char-set:upper-case
2219 All upper-case characters.
2222 @defvar char-set:title-case
2223 This is empty, because ASCII has no titlecase characters.
2226 @defvar char-set:letter
2227 All letters, e.g. the union of @code{char-set:lower-case} and
2228 @code{char-set:upper-case}.
2231 @defvar char-set:digit
2235 @defvar char-set:letter+digit
2236 The union of @code{char-set:letter} and @code{char-set:digit}.
2239 @defvar char-set:graphic
2240 All characters which would put ink on the paper.
2243 @defvar char-set:printing
2244 The union of @code{char-set:graphic} and @code{char-set:whitespace}.
2247 @defvar char-set:whitespace
2248 All whitespace characters.
2251 @defvar char-set:blank
2252 All horizontal whitespace characters, that is @code{#\space} and
2256 @defvar char-set:iso-control
2257 The ISO control characters with the codes 0--31 and 127.
2260 @defvar char-set:punctuation
2261 The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
2264 @defvar char-set:symbol
2265 The characters @code{$+<=>^`|~}.
2268 @defvar char-set:hex-digit
2269 The hexadecimal digits @code{0123456789abcdefABCDEF}.
2272 @defvar char-set:ascii
2273 All ASCII characters.
2276 @defvar char-set:empty
2277 The empty character set.
2280 @defvar char-set:full
2281 This character set contains all possible characters.
2285 @section SRFI-16 - case-lambda
2288 @c FIXME::martin: Review me!
2291 The syntactic form @code{case-lambda} creates procedures, just like
2292 @code{lambda}, but has syntactic extensions for writing procedures of
2293 varying arity easier.
2295 The syntax of the @code{case-lambda} form is defined in the following
2301 --> (case-lambda <case-lambda-clause>)
2302 <case-lambda-clause>
2303 --> (<formals> <definition-or-command>*)
2306 | (<identifier>* . <identifier>)
2311 The value returned by a @code{case-lambda} form is a procedure which
2312 matches the number of actual arguments against the formals in the
2313 various clauses, in order. @dfn{Formals} means a formal argument list
2314 just like with @code{lambda} (@pxref{Lambda}). The first matching clause
2315 is selected, the corresponding values from the actual parameter list are
2316 bound to the variable names in the clauses and the body of the clause is
2317 evaluated. If no clause matches, an error is signalled.
2319 The following (silly) definition creates a procedure @var{foo} which
2320 acts differently, depending on the number of actual arguments. If one
2321 argument is given, the constant @code{#t} is returned, two arguments are
2322 added and if more arguments are passed, their product is calculated.
2325 (define foo (case-lambda
2344 The last expression evaluates to 1 because the last clause is matched,
2345 @var{z} is bound to the empty list and the following multiplication,
2346 applied to zero arguments, yields 1.
2350 @section SRFI-17 - Generalized set!
2353 This is an implementation of SRFI-17: Generalized set!
2355 @findex getter-with-setter
2356 It exports the Guile procedure @code{make-procedure-with-setter} under
2357 the SRFI name @code{getter-with-setter} and exports the standard
2358 procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr},
2359 @code{string-ref} and @code{vector-ref} as procedures with setters, as
2360 required by the SRFI.
2362 SRFI-17 was heavily criticized during its discussion period but it was
2363 finalized anyway. One issue was its concept of globally associating
2364 setter @dfn{properties} with (procedure) values, which is non-Schemy.
2365 For this reason, this implementation chooses not to provide a way to set
2366 the setter of a procedure. In fact, @code{(set! (setter @var{proc})
2367 @var{setter})} signals an error. The only way to attach a setter to a
2368 procedure is to create a new object (a @dfn{procedure with setter}) via
2369 the @code{getter-with-setter} procedure. This procedure is also
2370 specified in the SRFI. Using it avoids the described problems.
2374 @section SRFI-19 - Time/Date Library
2377 This is an implementation of the SRFI-19 time/date library. The
2378 functions and variables described here are provided by
2381 (use-modules (srfi srfi-19))
2385 * SRFI-19 Introduction::
2388 * SRFI-19 Time/Date conversions::
2389 * SRFI-19 Date to string::
2390 * SRFI-19 String to date::
2393 @node SRFI-19 Introduction
2394 @subsection SRFI-19 Introduction
2396 @cindex universal time
2400 This module implements time and date representations and calculations,
2401 in various time systems, including universal time (UTC) and atomic
2404 For those not familiar with these time systems, TAI is based on a
2405 fixed length second derived from oscillations of certain atoms. UTC
2406 differs from TAI by an integral number of seconds, which is increased
2407 or decreased at announced times to keep UTC aligned to a mean solar
2408 day (the orbit and rotation of the earth are not quite constant).
2411 So far, only increases in the TAI
2418 UTC difference have been needed. Such an increase is a ``leap
2419 second'', an extra second of TAI introduced at the end of a UTC day.
2420 When working entirely within UTC this is never seen, every day simply
2421 has 86400 seconds. But when converting from TAI to a UTC date, an
2422 extra 23:59:60 is present, where normally a day would end at 23:59:59.
2423 Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI
2426 @cindex system clock
2427 In the current implementation, the system clock is assumed to be UTC,
2428 and a table of leap seconds in the code converts to TAI. See comments
2429 in @file{srfi-19.scm} for how to update this table.
2432 @cindex modified julian day
2433 Also, for those not familiar with the terminology, a @dfn{Julian Day}
2434 is a real number which is a count of days and fraction of a day, in
2435 UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan
2436 4713 B.C. And a @dfn{Modified Julian Day} is the same, but starting
2437 from 1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC.
2439 @c The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at
2440 @c noon, UTC), but this is incorrect. It looks like it might have
2441 @c arisen from the code incorrectly treating years a multiple of 100
2442 @c but not 400 prior to 1582 as leap years, where instead the Julian
2443 @c calendar should be used so all multiples of 4 before 1582 are leap
2448 @subsection SRFI-19 Time
2451 A @dfn{time} object has type, seconds and nanoseconds fields
2452 representing a point in time starting from some epoch. This is an
2453 arbitrary point in time, not just a time of day. Although times are
2454 represented in nanoseconds, the actual resolution may be lower.
2456 The following variables hold the possible time types. For instance
2457 @code{(current-time time-process)} would give the current CPU process
2461 Universal Coordinated Time (UTC).
2466 International Atomic Time (TAI).
2470 @defvar time-monotonic
2471 Monotonic time, meaning a monotonically increasing time starting from
2472 an unspecified epoch.
2474 Note that in the current implementation @code{time-monotonic} is the
2475 same as @code{time-tai}, and unfortunately is therefore affected by
2476 adjustments to the system clock. Perhaps this will change in the
2480 @defvar time-duration
2481 A duration, meaning simply a difference between two times.
2484 @defvar time-process
2485 CPU time spent in the current process, starting from when the process
2487 @cindex process time
2491 CPU time spent in the current thread. Not currently implemented.
2497 Return @code{#t} if @var{obj} is a time object, or @code{#f} if not.
2500 @defun make-time type nanoseconds seconds
2501 Create a time object with the given @var{type}, @var{seconds} and
2505 @defun time-type time
2506 @defunx time-nanosecond time
2507 @defunx time-second time
2508 @defunx set-time-type! time type
2509 @defunx set-time-nanosecond! time nsec
2510 @defunx set-time-second! time sec
2511 Get or set the type, seconds or nanoseconds fields of a time object.
2513 @code{set-time-type!} merely changes the field, it doesn't convert the
2514 time value. For conversions, see @ref{SRFI-19 Time/Date conversions}.
2517 @defun copy-time time
2518 Return a new time object, which is a copy of the given @var{time}.
2521 @defun current-time [type]
2522 Return the current time of the given @var{type}. The default
2523 @var{type} is @code{time-utc}.
2525 Note that the name @code{current-time} conflicts with the Guile core
2526 @code{current-time} function (@pxref{Time}). Applications wanting to
2527 use both will need to use a different name for one of them.
2530 @defun time-resolution [type]
2531 Return the resolution, in nanoseconds, of the given time @var{type}.
2532 The default @var{type} is @code{time-utc}.
2535 @defun time<=? t1 t2
2536 @defunx time<? t1 t2
2537 @defunx time=? t1 t2
2538 @defunx time>=? t1 t2
2539 @defunx time>? t1 t2
2540 Return @code{#t} or @code{#f} according to the respective relation
2541 between time objects @var{t1} and @var{t2}. @var{t1} and @var{t2}
2542 must be the same time type.
2545 @defun time-difference t1 t2
2546 @defunx time-difference! t1 t2
2547 Return a time object of type @code{time-duration} representing the
2548 period between @var{t1} and @var{t2}. @var{t1} and @var{t2} must be
2551 @code{time-difference} returns a new time object,
2552 @code{time-difference!} may modify @var{t1} to form its return.
2555 @defun add-duration time duration
2556 @defunx add-duration! time duration
2557 @defunx subtract-duration time duration
2558 @defunx subtract-duration! time duration
2559 Return a time object which is @var{time} with the given @var{duration}
2560 added or subtracted. @var{duration} must be a time object of type
2561 @code{time-duration}.
2563 @code{add-duration} and @code{subtract-duration} return a new time
2564 object. @code{add-duration!} and @code{subtract-duration!} may modify
2565 the given @var{time} to form their return.
2570 @subsection SRFI-19 Date
2573 A @dfn{date} object represents a date in the Gregorian calendar and a
2574 time of day on that date in some timezone.
2576 The fields are year, month, day, hour, minute, second, nanoseconds and
2577 timezone. A date object is immutable, its fields can be read but they
2578 cannot be modified once the object is created.
2581 Return @code{#t} if @var{obj} is a date object, or @code{#f} if not.
2584 @defun make-date nsecs seconds minutes hours date month year zone-offset
2585 Create a new date object.
2587 @c FIXME: What can we say about the ranges of the values. The
2588 @c current code looks it doesn't normalize, but expects then in their
2589 @c usual range already.
2593 @defun date-nanosecond date
2594 Nanoseconds, 0 to 999999999.
2597 @defun date-second date
2598 Seconds, 0 to 60. 0 to 59 is the usual range, 60 is for a leap second.
2601 @defun date-minute date
2605 @defun date-hour date
2609 @defun date-day date
2610 Day of the month, 1 to 31 (or less, according to the month).
2613 @defun date-month date
2617 @defun date-year date
2621 @defun date-zone-offset date
2622 Time zone, an integer number of seconds east of Greenwich.
2625 @defun date-year-day date
2626 Day of the year, starting from 1 for 1st January.
2629 @defun date-week-day date
2630 Day of the week, starting from 0 for Sunday.
2633 @defun date-week-number date dstartw
2634 Week of the year, ignoring a first partial week. @var{dstartw} is the
2635 day of the week which is taken to start a week, 0 for Sunday, 1 for
2638 @c FIXME: The spec doesn't say whether numbering starts at 0 or 1.
2639 @c The code looks like it's 0, if that's the correct intention.
2643 @c The SRFI text doesn't actually give the default for tz-offset, but
2644 @c the reference implementation has the local timezone and the
2645 @c conversions functions all specify that, so it should be ok to
2646 @c document it here.
2648 @defun current-date [tz-offset]
2649 Return a date object representing the current date/time UTC.
2650 @var{tz-offset} is seconds east of Greenwich, and defaults to the
2654 @defun current-julian-day
2656 Return the current Julian Day.
2659 @defun current-modified-julian-day
2660 @cindex modified julian day
2661 Return the current Modified Julian Day.
2665 @node SRFI-19 Time/Date conversions
2666 @subsection SRFI-19 Time/Date conversions
2668 @defun date->julian-day date
2669 @defunx date->modified-julian-day date
2670 @defunx date->time-monotonic date
2671 @defunx date->time-tai date
2672 @defunx date->time-utc date
2674 @defun julian-day->date jdn [tz-offset]
2675 @defunx julian-day->time-monotonic jdn
2676 @defunx julian-day->time-tai jdn
2677 @defunx julian-day->time-utc jdn
2679 @defun modified-julian-day->date jdn [tz-offset]
2680 @defunx modified-julian-day->time-monotonic jdn
2681 @defunx modified-julian-day->time-tai jdn
2682 @defunx modified-julian-day->time-utc jdn
2684 @defun time-monotonic->date time [tz-offset]
2685 @defunx time-monotonic->time-tai time
2686 @defunx time-monotonic->time-tai! time
2687 @defunx time-monotonic->time-utc time
2688 @defunx time-monotonic->time-utc! time
2690 @defun time-tai->date time [tz-offset]
2691 @defunx time-tai->julian-day time
2692 @defunx time-tai->modified-julian-day time
2693 @defunx time-tai->time-monotonic time
2694 @defunx time-tai->time-monotonic! time
2695 @defunx time-tai->time-utc time
2696 @defunx time-tai->time-utc! time
2698 @defun time-utc->date time [tz-offset]
2699 @defunx time-utc->julian-day time
2700 @defunx time-utc->modified-julian-day time
2701 @defunx time-utc->time-monotonic time
2702 @defunx time-utc->time-monotonic! time
2703 @defunx time-utc->time-tai time
2704 @defunx time-utc->time-tai! time
2706 Convert between dates, times and days of the respective types. For
2707 instance @code{time-tai->time-utc} accepts a @var{time} object of type
2708 @code{time-tai} and returns an object of type @code{time-utc}.
2710 For conversions to dates, @var{tz-offset} is seconds east of
2711 Greenwich. The default is the local timezone.
2713 The @code{!} variants may modify their @var{time} argument to form
2714 their return. The plain functions create a new object.
2717 @node SRFI-19 Date to string
2718 @subsection SRFI-19 Date to string
2719 @cindex date to string
2721 @defun date->string date [format]
2722 Convert a date to a string under the control of a format.
2723 @var{format} should be a string containing @samp{~} escapes, which
2724 will be expanded as per the following conversion table. The default
2725 @var{format} is @samp{~c}, a locale-dependent date and time.
2727 Many of these conversion characters are the same as POSIX
2728 @code{strftime} (@pxref{Time}), but there are some extras and some
2731 @multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM}
2732 @item @nicode{~~} @tab literal ~
2733 @item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun}
2734 @item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday}
2735 @item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan}
2736 @item @nicode{~B} @tab locale full month, eg.@: @samp{January}
2737 @item @nicode{~c} @tab locale date and time, eg.@: @*
2738 @samp{Fri Jul 14 20:28:42-0400 2000}
2739 @item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31}
2741 @c Spec says d/m/y, reference implementation says m/d/y.
2742 @c Apparently the reference code was the intention, but would like to
2743 @c see an errata published for the spec before contradicting it here.
2745 @c @item @nicode{~D} @tab date @nicode{~d/~m/~y}
2747 @item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31}
2748 @item @nicode{~f} @tab seconds and fractional seconds,
2749 with locale decimal point, eg.@: @samp{5.2}
2750 @item @nicode{~h} @tab same as @nicode{~b}
2751 @item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23}
2752 @item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12}
2753 @item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366}
2754 @item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23}
2755 @item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12}
2756 @item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12}
2757 @item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59}
2758 @item @nicode{~n} @tab newline
2759 @item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999}
2760 @item @nicode{~p} @tab locale AM or PM
2761 @item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p}
2762 @item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC
2763 @item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @*
2764 (usual limit is 59, 60 is a leap second)
2765 @item @nicode{~t} @tab horizontal tab character
2766 @item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S}
2767 @item @nicode{~U} @tab week of year, Sunday first day of week,
2768 @samp{00} to @samp{52}
2769 @item @nicode{~V} @tab week of year, Monday first day of week,
2770 @samp{01} to @samp{53}
2771 @item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6}
2772 @item @nicode{~W} @tab week of year, Monday first day of week,
2773 @samp{00} to @samp{52}
2775 @c The spec has ~x as an apparent duplicate of ~W, and ~X as a locale
2776 @c date. The reference code has ~x as the locale date and ~X as a
2777 @c locale time. The rule is apparently that the code should be
2778 @c believed, but would like to see an errata for the spec before
2779 @c contradicting it here.
2781 @c @item @nicode{~x} @tab week of year, Monday as first day of week,
2782 @c @samp{00} to @samp{53}
2783 @c @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00}
2785 @item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99}
2786 @item @nicode{~Y} @tab year, full, eg.@: @samp{2003}
2787 @item @nicode{~z} @tab time zone, RFC-822 style
2788 @item @nicode{~Z} @tab time zone symbol (not currently implemented)
2789 @item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d}
2790 @item @nicode{~2} @tab ISO-8601 time+zone, @samp{~k:~M:~S~z}
2791 @item @nicode{~3} @tab ISO-8601 time, @samp{~k:~M:~S}
2792 @item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~k:~M:~S~z}
2793 @item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~k:~M:~S}
2797 Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently
2798 described here, since the specification and reference implementation
2801 Currently Guile doesn't implement any localizations for the above, all
2802 outputs are in English, and the @samp{~c} conversion is POSIX
2803 @code{ctime} style @samp{~a ~b ~d ~H:~M:~S~z ~Y}. This may change in
2807 @node SRFI-19 String to date
2808 @subsection SRFI-19 String to date
2809 @cindex string to date
2811 @c FIXME: Can we say what happens when an incomplete date is
2812 @c converted? Ie. fields left as 0, or what? The spec seems to be
2815 @defun string->date input template
2816 Convert an @var{input} string to a date under the control of a
2817 @var{template} string. Return a newly created date object.
2819 Literal characters in @var{template} must match characters in
2820 @var{input} and @samp{~} escapes must match the input forms described
2821 in the table below. ``Skip to'' means characters up to one of the
2822 given type are ignored, or ``no skip'' for no skipping. ``Read'' is
2823 what's then read, and ``Set'' is the field affected in the date
2826 For example @samp{~Y} skips input characters until a digit is reached,
2827 at which point it expects a year and stores that to the year field of
2830 @multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}}
2842 @tab @nicode{char-alphabetic?}
2843 @tab locale abbreviated weekday name
2847 @tab @nicode{char-alphabetic?}
2848 @tab locale full weekday name
2851 @c Note that the SRFI spec says that ~b and ~B don't set anything,
2852 @c but that looks like a mistake. The reference implementation sets
2853 @c the month field, which seems sensible and is what we describe
2857 @tab @nicode{char-alphabetic?}
2858 @tab locale abbreviated month name
2859 @tab @nicode{date-month}
2862 @tab @nicode{char-alphabetic?}
2863 @tab locale full month name
2864 @tab @nicode{date-month}
2867 @tab @nicode{char-numeric?}
2869 @tab @nicode{date-day}
2873 @tab day of month, blank padded
2874 @tab @nicode{date-day}
2877 @tab same as @samp{~b}
2880 @tab @nicode{char-numeric?}
2882 @tab @nicode{date-hour}
2886 @tab hour, blank padded
2887 @tab @nicode{date-hour}
2890 @tab @nicode{char-numeric?}
2892 @tab @nicode{date-month}
2895 @tab @nicode{char-numeric?}
2897 @tab @nicode{date-minute}
2900 @tab @nicode{char-numeric?}
2902 @tab @nicode{date-second}
2907 @tab @nicode{date-year} within 50 years
2910 @tab @nicode{char-numeric?}
2912 @tab @nicode{date-year}
2917 @tab date-zone-offset
2920 Notice that the weekday matching forms don't affect the date object
2921 returned, instead the weekday will be derived from the day, month and
2924 Currently Guile doesn't implement any localizations for the above,
2925 month and weekday names are always expected in English. This may
2926 change in the future.
2930 @c srfi-modules.texi ends here
2933 @c TeX-master: "guile.texi"