guile/doc/ref/srfi-modules.texi

@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node SRFI Support
@section SRFI Support Modules
@cindex SRFI

SRFI is an acronym for Scheme Request For Implementation.  The SRFI
documents define a lot of syntactic and procedure extensions to standard
Scheme as defined in R5RS.

Guile has support for a number of SRFIs.  This chapter gives an overview
over the available SRFIs and some usage hints.  For complete
documentation, design rationales and further examples, we advise you to
get the relevant SRFI documents from the SRFI home page
@url{http://srfi.schemers.org}.

@menu
* About SRFI Usage::            What to know about Guile's SRFI support.
* SRFI-0::                      cond-expand
* SRFI-1::                      List library.
* SRFI-2::                      and-let*.
* SRFI-4::                      Homogeneous numeric vector datatypes.
* SRFI-6::                      Basic String Ports.
* SRFI-8::                      receive.
* SRFI-9::                      define-record-type.
* SRFI-10::                     Hash-Comma Reader Extension.
* SRFI-11::                     let-values and let-values*.
* SRFI-13::                     String library.
* SRFI-14::                     Character-set library.
* SRFI-16::                     case-lambda
* SRFI-17::                     Generalized set!
* SRFI-19::                     Time/Date library.
* SRFI-26::                     Specializing parameters
* SRFI-31::                     A special form `rec' for recursive evaluation
@end menu


@node About SRFI Usage
@subsection About SRFI Usage

@c FIXME::martin: Review me!

SRFI support in Guile is currently implemented partly in the core
library, and partly as add-on modules.  That means that some SRFIs are
automatically available when the interpreter is started, whereas the
other SRFIs require you to use the appropriate support module
explicitly.

There are several reasons for this inconsistency.  First, the feature
checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
available immediately, because it must be there when the user wants to
check for the Scheme implementation, that is, before she can know that
it is safe to use @code{use-modules} to load SRFI support modules.  The
second reason is that some features defined in SRFIs had been
implemented in Guile before the developers started to add SRFI
implementations as modules (for example SRFI-6 (@pxref{SRFI-6})).  In
the future, it is possible that SRFIs in the core library might be
factored out into separate modules, requiring explicit module loading
when they are needed.  So you should be prepared to have to use
@code{use-modules} someday in the future to access SRFI-6 bindings.  If
you want, you can do that already.  We have included the module
@code{(srfi srfi-6)} in the distribution, which currently does nothing,
but ensures that you can write future-safe code.

Generally, support for a specific SRFI is made available by using
modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
number of the SRFI needed.  Another possibility is to use the command
line option @code{--use-srfi}, which will load the necessary modules
automatically (@pxref{Invoking Guile}).


@node SRFI-0
@subsection SRFI-0 - cond-expand
@cindex SRFI-0

This SRFI lets a portable Scheme program test for the presence of
certain features, and adapt itself by using different blocks of code,
or fail if the necessary features are not available.  There's no
module to load, this is in the Guile core.

A program designed only for Guile will generally not need this
mechanism, such a program can of course directly use the various
documented parts of Guile.

@deffn syntax cond-expand (feature body@dots{}) @dots{}
Expand to the @var{body} of the first clause whose @var{feature}
specification is satisfied.  It is an error if no @var{feature} is
satisfied.

Features are symbols such as @code{srfi-1}, and a feature
specification can use @code{and}, @code{or} and @code{not} forms to
test combinations.  The last clause can be an @code{else}, to be used
if no other passes.

For example, define a private version of @code{alist-cons} if SRFI-1
is not available.

@example
(cond-expand (srfi-1
              )
             (else
              (define (alist-cons key val alist)
                (cons (cons key val) alist))))
@end example

Or demand a certain set of SRFIs (list operations, string ports,
@code{receive} and string operations), failing if they're not
available.

@example
(cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13)
              ))
@end example
@end deffn

The Guile core provides features @code{guile}, @code{r5rs},
@code{srfi-0} and @code{srfi-6} initially.  Other SRFI feature symbols
are defined once their code has been loaded with @code{use-modules},
since only then are their bindings available.

The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is
a good way to load SRFIs to satisfy @code{cond-expand} when running a
portable program.

Testing the @code{guile} feature allows a program to adapt itself to
the Guile module system, but still run on other Scheme systems.  For
example the following demands SRFI-8 (@code{receive}), but also knows
how to load it with the Guile mechanism.

@example
(cond-expand (srfi-8
              )
             (guile
              (use-modules (srfi srfi-8))))
@end example

It should be noted that @code{cond-expand} is separate from the
@code{*features*} mechanism (@pxref{Feature Tracking}), feature
symbols in one are unrelated to those in the other.


@node SRFI-1
@subsection SRFI-1 - List library
@cindex SRFI-1

@c FIXME::martin: Review me!

The list library defined in SRFI-1 contains a lot of useful list
processing procedures for construction, examining, destructuring and
manipulating lists and pairs.

Since SRFI-1 also defines some procedures which are already contained
in R5RS and thus are supported by the Guile core library, some list
and pair procedures which appear in the SRFI-1 document may not appear
in this section.  So when looking for a particular list/pair
processing procedure, you should also have a look at the sections
@ref{Lists} and @ref{Pairs}.

@menu
* SRFI-1 Constructors::         Constructing new lists.
* SRFI-1 Predicates::           Testing list for specific properties.
* SRFI-1 Selectors::            Selecting elements from lists.
* SRFI-1 Length Append etc::    Length calculation and list appending.
* SRFI-1 Fold and Map::         Higher-order list processing.
* SRFI-1 Filtering and Partitioning::  Filter lists based on predicates.
* SRFI-1 Searching::            Search for elements.
* SRFI-1 Deleting::             Delete elements from lists.
* SRFI-1 Association Lists::    Handle association lists.
* SRFI-1 Set Operations::       Use lists for representing sets.
@end menu

@node SRFI-1 Constructors
@subsubsection Constructors

@c FIXME::martin: Review me!

New lists can be constructed by calling one of the following
procedures.

@deffn {Scheme Procedure} xcons d a
Like @code{cons}, but with interchanged arguments.  Useful mostly when
passed to higher-order procedures.
@end deffn

@deffn {Scheme Procedure} list-tabulate n init-proc
Return an @var{n}-element list, where each list element is produced by
applying the procedure @var{init-proc} to the corresponding list
index.  The order in which @var{init-proc} is applied to the indices
is not specified.
@end deffn

@deffn {Scheme Procedure} list-copy lst
Return a new list containing the elements of the list @var{lst}.

This function differs from the core @code{list-copy} (@pxref{List
Constructors}) in accepting improper lists too.  And if @var{lst} is
not a pair at all then it's treated as the final tail of an improper
list and simply returned.
@end deffn

@deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
Return a circular list containing the given arguments @var{elt1}
@var{elt2} @dots{}.
@end deffn

@deffn {Scheme Procedure} iota count [start step]
Return a list containing @var{count} numbers, starting from
@var{start} and adding @var{step} each time.  The default @var{start}
is 0, the default @var{step} is 1.  For example,

@example
(iota 6)        @result{} (0 1 2 3 4 5)
(iota 4 2.5 -2) @result{} (2.5 0.5 -1.5 -3.5)
@end example

This function takes its name from the corresponding primitive in the
APL language.
@end deffn


@node SRFI-1 Predicates
@subsubsection Predicates

@c FIXME::martin: Review me!

The procedures in this section test specific properties of lists.

@deffn {Scheme Procedure} proper-list? obj
Return @code{#t} if @var{obj} is a proper list, that is a finite list,
terminated with the empty list.  Otherwise, return @code{#f}.
@end deffn

@deffn {Scheme Procedure} circular-list? obj
Return @code{#t} if @var{obj} is a circular list, otherwise return
@code{#f}.
@end deffn

@deffn {Scheme Procedure} dotted-list? obj
Return @code{#t} if @var{obj} is a dotted list, return @code{#f}
otherwise.  A dotted list is a finite list which is not terminated by
the empty list, but some other value.
@end deffn

@deffn {Scheme Procedure} null-list? lst
Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
otherwise.  If something else than a proper or circular list is passed
as @var{lst}, an error is signalled.  This procedure is recommended
for checking for the end of a list in contexts where dotted lists are
not allowed.
@end deffn

@deffn {Scheme Procedure} not-pair? obj
Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
This is shorthand notation @code{(not (pair? @var{obj}))} and is
supposed to be used for end-of-list checking in contexts where dotted
lists are allowed.
@end deffn

@deffn {Scheme Procedure} list= elt= list1 @dots{}
Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
List equality is determined by testing whether all lists have the same
length and the corresponding elements are equal in the sense of the
equality predicate @var{elt=}.  If no or only one list is given,
@code{#t} is returned.
@end deffn


@node SRFI-1 Selectors
@subsubsection Selectors

@c FIXME::martin: Review me!

@deffn {Scheme Procedure} first pair
@deffnx {Scheme Procedure} second pair
@deffnx {Scheme Procedure} third pair
@deffnx {Scheme Procedure} fourth pair
@deffnx {Scheme Procedure} fifth pair
@deffnx {Scheme Procedure} sixth pair
@deffnx {Scheme Procedure} seventh pair
@deffnx {Scheme Procedure} eighth pair
@deffnx {Scheme Procedure} ninth pair
@deffnx {Scheme Procedure} tenth pair
These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
@end deffn

@deffn {Scheme Procedure} car+cdr pair
Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
@end deffn

@deffn {Scheme Procedure} take lst i
@deffnx {Scheme Procedure} take! lst i
Return a list containing the first @var{i} elements of @var{lst}.

@code{take!} may modify the structure of the argument list @var{lst}
in order to produce the result.
@end deffn

@deffn {Scheme Procedure} drop lst i
Return a list containing all but the first @var{i} elements of
@var{lst}.
@end deffn

@deffn {Scheme Procedure} take-right lst i
Return the a list containing the @var{i} last elements of @var{lst}.
@end deffn

@deffn {Scheme Procedure} drop-right lst i
@deffnx {Scheme Procedure} drop-right! lst i
Return the a list containing all but the @var{i} last elements of
@var{lst}.

@code{drop-right!} may modify the structure of the argument list
@var{lst} in order to produce the result.
@end deffn

@deffn {Scheme Procedure} split-at lst i
@deffnx {Scheme Procedure} split-at! lst i
Return two values, a list containing the first @var{i} elements of the
list @var{lst} and a list containing the remaining elements.

@code{split-at!} may modify the structure of the argument list
@var{lst} in order to produce the result.
@end deffn

@deffn {Scheme Procedure} last lst
Return the last element of the non-empty, finite list @var{lst}.
@end deffn


@node SRFI-1 Length Append etc
@subsubsection Length, Append, Concatenate, etc.

@c FIXME::martin: Review me!

@deffn {Scheme Procedure} length+ lst
Return the length of the argument list @var{lst}.  When @var{lst} is a
circular list, @code{#f} is returned.
@end deffn

@deffn {Scheme Procedure} concatenate list-of-lists
@deffnx {Scheme Procedure} concatenate! list-of-lists
Construct a list by appending all lists in @var{list-of-lists}.

@code{concatenate!} may modify the structure of the given lists in
order to produce the result.
@end deffn

@deffn {Scheme Procedure} append-reverse rev-head tail
@deffnx {Scheme Procedure} append-reverse! rev-head tail
Reverse @var{rev-head}, append @var{tail} and return the result.  This
is equivalent to @code{(append (reverse @var{rev-head}) @var{tail})},
but more efficient.

@code{append-reverse!} may modify @var{rev-head} in order to produce
the result.
@end deffn

@deffn {Scheme Procedure} zip lst1 lst2 @dots{}
Return a list as long as the shortest of the argument lists, where
each element is a list.  The first list contains the first elements of
the argument lists, the second list contains the second elements, and
so on.
@end deffn

@deffn {Scheme Procedure} unzip1 lst
@deffnx {Scheme Procedure} unzip2 lst
@deffnx {Scheme Procedure} unzip3 lst
@deffnx {Scheme Procedure} unzip4 lst
@deffnx {Scheme Procedure} unzip5 lst
@code{unzip1} takes a list of lists, and returns a list containing the
first elements of each list, @code{unzip2} returns two lists, the
first containing the first elements of each lists and the second
containing the second elements of each lists, and so on.
@end deffn

@deffn {Scheme Procedure} count pred lst1 @dots{} lstN
Return a count of the number of times @var{pred} returns true when
called on elements from the given lists.

@var{pred} is called with @var{N} parameters @code{(@var{pred}
@var{elem1} @dots{} @var{elemN})}, each element being from the
corresponding @var{lst1} @dots{} @var{lstN}.  The first call is with
the first element of each list, the second with the second element
from each, and so on.

Counting stops when the end of the shortest list is reached.  At least
one list must be non-circular.
@end deffn


@node SRFI-1 Fold and Map
@subsubsection Fold, Unfold & Map

@c FIXME::martin: Review me!

@deffn {Scheme Procedure} fold kons knil lst1 lst2 @dots{}
Fold the procedure @var{kons} across all elements of @var{lst1},
@var{lst2}, @dots{}.  Produce the result of

@code{(@var{kons} @var{en1} @var{en2} @dots{} (@var{kons} @var{e21}
@var{e22} (@var{kons} @var{e11} @var{e12} @var{knil})))},

if @var{enm} are the elements of the lists @var{lst1}, @var{lst2},
@dots{}.
@end deffn

@deffn {Scheme Procedure} fold-right kons knil lst1 lst2 @dots{}
Similar to @code{fold}, but applies @var{kons} in right-to-left order
to the list elements, that is:

@code{(@var{kons} @var{e11} @var{e12}(@var{kons} @var{e21}
@var{e22}  @dots{} (@var{kons} @var{en1} @var{en2} @var{knil})))},
@end deffn

@deffn {Scheme Procedure} pair-fold kons knil lst1 lst2 @dots{}
Like @code{fold}, but apply @var{kons} to the pairs of the list
instead of the list elements.
@end deffn

@deffn {Scheme Procedure} pair-fold-right kons knil lst1 lst2 @dots{}
Like @code{fold-right}, but apply @var{kons} to the pairs of the list
instead of the list elements.
@end deffn

@deffn {Scheme Procedure} reduce f ridentity lst
@code{reduce} is a variant of @code{fold}.  If @var{lst} is
@code{()}, @var{ridentity} is returned.  Otherwise, @code{(fold f (car
@var{lst}) (cdr @var{lst}))} is returned.
@end deffn

@deffn {Scheme Procedure} reduce-right f ridentity lst
This is the @code{fold-right} variant of @code{reduce}.
@end deffn

@deffn {Scheme Procedure} unfold p f g seed [tail-gen]
@code{unfold} is defined as follows:

@lisp
(unfold p f g seed) =
   (if (p seed) (tail-gen seed)
       (cons (f seed)
             (unfold p f g (g seed))))
@end lisp

@table @var
@item p
Determines when to stop unfolding.

@item f
Maps each seed value to the corresponding list element.

@item g
Maps each seed value to next seed valu.

@item seed
The state value for the unfold.

@item tail-gen
Creates the tail of the list; defaults to @code{(lambda (x) '())}.
@end table

@var{g} produces a series of seed values, which are mapped to list
elements by @var{f}.  These elements are put into a list in
left-to-right order, and @var{p} tells when to stop unfolding.
@end deffn

@deffn {Scheme Procedure} unfold-right p f g seed [tail]
Construct a list with the following loop.

@lisp
(let lp ((seed seed) (lis tail))
   (if (p seed) lis
       (lp (g seed)
           (cons (f seed) lis))))
@end lisp

@table @var
@item p
Determines when to stop unfolding.

@item f
Maps each seed value to the corresponding list element.

@item g
Maps each seed value to next seed valu.

@item seed
The state value for the unfold.

@item tail-gen
Creates the tail of the list; defaults to @code{(lambda (x) '())}.
@end table

@end deffn

@deffn {Scheme Procedure} map f lst1 lst2 @dots{}
Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
return a list containing the results of the procedure applications.
This procedure is extended with respect to R5RS, because the argument
lists may have different lengths.  The result list will have the same
length as the shortest argument lists.  The order in which @var{f}
will be applied to the list element(s) is not specified.
@end deffn

@deffn {Scheme Procedure} for-each f lst1 lst2 @dots{}
Apply the procedure @var{f} to each pair of corresponding elements of
the list(s) @var{lst1}, @var{lst2}, @dots{}.  The return value is not
specified.  This procedure is extended with respect to R5RS, because
the argument lists may have different lengths.  The shortest argument
list determines the number of times @var{f} is called.  @var{f} will
be applied to the list elements in left-to-right order.

@end deffn

@deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
@deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
Equivalent to

@lisp
(apply append (map f clist1 clist2 ...))
@end lisp

and

@lisp
(apply append! (map f clist1 clist2 ...))
@end lisp

Map @var{f} over the elements of the lists, just as in the @code{map}
function. However, the results of the applications are appended
together to make the final result. @code{append-map} uses
@code{append} to append the results together; @code{append-map!} uses
@code{append!}.

The dynamic order in which the various applications of @var{f} are
made is not specified.
@end deffn

@deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
Linear-update variant of @code{map} -- @code{map!} is allowed, but not
required, to alter the cons cells of @var{lst1} to construct the
result list.

The dynamic order in which the various applications of @var{f} are
made is not specified. In the n-ary case, @var{lst2}, @var{lst3},
@dots{} must have at least as many elements as @var{lst1}.
@end deffn

@deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{}
Like @code{for-each}, but applies the procedure @var{f} to the pairs
from which the argument lists are constructed, instead of the list
elements.  The return value is not specified.
@end deffn

@deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
Like @code{map}, but only results from the applications of @var{f}
which are true are saved in the result list.
@end deffn


@node SRFI-1 Filtering and Partitioning
@subsubsection Filtering and Partitioning

@c FIXME::martin: Review me!

Filtering means to collect all elements from a list which satisfy a
specific condition.  Partitioning a list means to make two groups of
list elements, one which contains the elements satisfying a condition,
and the other for the elements which don't.

The @code{filter} and @code{filter!} functions are implemented in the
Guile core, @xref{List Modification}.

@deffn {Scheme Procedure} partition pred lst
@deffnx {Scheme Procedure} partition! pred lst
Split @var{lst} into those elements which do and don't satisfy the
predicate @var{pred}.

The return is two values (@pxref{Multiple Values}), the first being a
list of all elements from @var{lst} which satisfy @var{pred}, the
second a list of those which do not.

The elements in the result lists are in the same order as in @var{lst}
but the order in which the calls @code{(@var{pred} elem)} are made on
the list elements is unspecified.

@code{partition} does not change @var{lst}, but one of the returned
lists may share a tail with it.  @code{partition!} may modify
@var{lst} to construct its return.
@end deffn

@deffn {Scheme Procedure} remove pred lst
@deffnx {Scheme Procedure} remove! pred lst
Return a list containing all elements from @var{lst} which do not
satisfy the predicate @var{pred}.  The elements in the result list
have the same order as in @var{lst}.  The order in which @var{pred} is
applied to the list elements is not specified.

@code{remove!} is allowed, but not required to modify the structure of
the input list.
@end deffn


@node SRFI-1 Searching
@subsubsection Searching

@c FIXME::martin: Review me!

The procedures for searching elements in lists either accept a
predicate or a comparison object for determining which elements are to
be searched.

@deffn {Scheme Procedure} find pred lst
Return the first element of @var{lst} which satisfies the predicate
@var{pred} and @code{#f} if no such element is found.
@end deffn

@deffn {Scheme Procedure} find-tail pred lst
Return the first pair of @var{lst} whose @sc{car} satisfies the
predicate @var{pred} and @code{#f} if no such element is found.
@end deffn

@deffn {Scheme Procedure} take-while pred lst
@deffnx {Scheme Procedure} take-while! pred lst
Return the longest initial prefix of @var{lst} whose elements all
satisfy the predicate @var{pred}.

@code{take-while!} is allowed, but not required to modify the input
list while producing the result.
@end deffn

@deffn {Scheme Procedure} drop-while pred lst
Drop the longest initial prefix of @var{lst} whose elements all
satisfy the predicate @var{pred}.
@end deffn

@deffn {Scheme Procedure} span pred lst
@deffnx {Scheme Procedure} span! pred lst
@deffnx {Scheme Procedure} break pred lst
@deffnx {Scheme Procedure} break! pred lst
@code{span} splits the list @var{lst} into the longest initial prefix
whose elements all satisfy the predicate @var{pred}, and the remaining
tail.  @code{break} inverts the sense of the predicate.

@code{span!} and @code{break!} are allowed, but not required to modify
the structure of the input list @var{lst} in order to produce the
result.

Note that the name @code{break} conflicts with the @code{break}
binding established by @code{while} (@pxref{while do}).  Applications
wanting to use @code{break} from within a @code{while} loop will need
to make a new define under a different name.
@end deffn

@deffn {Scheme Procedure} any pred lst1 lst2 @dots{}
Apply @var{pred} across the lists and return a true value if the
predicate returns true for any of the list elements(s); return
@code{#f} otherwise.  The true value returned is always the result of
the first successful application of @var{pred}.
@end deffn

@deffn {Scheme Procedure} every pred lst1 lst2 @dots{}
Apply @var{pred} across the lists and return a true value if the
predicate returns true for every of the list elements(s); return
@code{#f} otherwise.  The true value returned is always the result of
the final successful application of @var{pred}.
@end deffn

@deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{}
Return the index of the leftmost element that satisfies @var{pred}.
@end deffn

@deffn {Scheme Procedure} member x lst [=]
Return the first sublist of @var{lst} whose @sc{car} is equal to
@var{x}.  If @var{x} does no appear in @var{lst}, return @code{#f}.
Equality is determined by the equality predicate @var{=}, or
@code{equal?} if @var{=} is not given.

This function extends the core @code{member} by accepting an equality
predicate.  (@pxref{List Searching})
@end deffn


@node SRFI-1 Deleting
@subsubsection Deleting

@c FIXME::martin: Review me!

@deffn {Scheme Procedure} delete x lst [=]
@deffnx {Scheme Procedure} delete! x lst [=]
Return a list containing the elements of @var{lst} but with those
equal to @var{x} deleted.  The returned elements will be in the same
order as they were in @var{lst}.

Equality is determined by the @var{=} predicate, or @code{equal?} if
not given.  An equality call is made just once for each element, but
the order in which the calls are made on the elements is unspecified.

The equality calls are always @code{(= x elem)}, ie.@: the given @var{x}
is first.  This means for instance elements greater than 5 can be
deleted with @code{(delete 5 lst <)}.

@code{delete} does not modify @var{lst}, but the return might share a
common tail with @var{lst}.  @code{delete!} may modify the structure
of @var{lst} to construct its return.

These functions extend the core @code{delete} and @code{delete!} in
accepting an equality predicate.  (@pxref{List Modification})
@end deffn

@deffn {Scheme Procedure} delete-duplicates lst [=]
@deffnx {Scheme Procedure} delete-duplicates! lst [=]
Return a list containing the elements of @var{lst} but without
duplicates.

When elements are equal, only the first in @var{lst} is retained.
Equal elements can be anywhere in @var{lst}, they don't have to be
adjacent.  The returned list will have the retained elements in the
same order as they were in @var{lst}.

Equality is determined by the @var{=} predicate, or @code{equal?} if
not given.  Calls @code{(= x y)} are made with element @var{x} being
before @var{y} in @var{lst}.  A call is made at most once for each
combination, but the sequence of the calls across the elements is
unspecified.

@code{delete-duplicates} does not modify @var{lst}, but the return
might share a common tail with @var{lst}.  @code{delete-duplicates!}
may modify the structure of @var{lst} to construct its return.

In the worst case, this is an @math{O(N^2)} algorithm because it must
check each element against all those preceding it.  For long lists it
is more efficient to sort and then compare only adjacent elements.
@end deffn


@node SRFI-1 Association Lists
@subsubsection Association Lists

@c FIXME::martin: Review me!

Association lists are described in detail in section @ref{Association
Lists}.  The present section only documents the additional procedures
for dealing with association lists defined by SRFI-1.

@deffn {Scheme Procedure} assoc key alist [=]
Return the pair from @var{alist} which matches @var{key}.  Equality is
determined by @var{=}, which defaults to @code{equal?} if not given.
@var{alist} must be an association lists---a list of pairs.

This function extends the core @code{assoc} by accepting an equality
predicate.  (@pxref{Association Lists})
@end deffn

@deffn {Scheme Procedure} alist-cons key datum alist
Equivalent to

@lisp
(cons (cons @var{key} @var{datum}) @var{alist})
@end lisp

This procedure is used to coons a new pair onto an existing
association list.
@end deffn

@deffn {Scheme Procedure} alist-copy alist
Return a newly allocated copy of @var{alist}, that means that the
spine of the list as well as the pairs are copied.
@end deffn

@deffn {Scheme Procedure} alist-delete key alist [=]
@deffnx {Scheme Procedure} alist-delete! key alist [=]
Return a list containing the elements of @var{alist} but with those
elements whose keys are equal to @var{key} deleted.  The returned
elements will be in the same order as they were in @var{alist}.

Equality is determined by the @var{=} predicate, or @code{equal?} if
not given.  The order in which elements are tested is unspecified, but
each equality call is made @code{(= key alistkey)}, ie. the given
@var{key} parameter is first and the key from @var{alist} second.
This means for instance all associations with a key greater than 5 can
be removed with @code{(alist-delete 5 alist <)}.

@code{alist-delete} does not modify @var{alist}, but the return might
share a common tail with @var{alist}.  @code{alist-delete!} may modify
the list structure of @var{alist} to construct its return.
@end deffn


@node SRFI-1 Set Operations
@subsubsection Set Operations on Lists

@c FIXME::martin: Review me!

Lists can be used for representing sets of objects.  The procedures
documented in this section can be used for such set representations.
Man combining several sets or adding elements, they make sure that no
object is contained more than once in a given list.  Please note that
lists are not a too efficient implementation method for sets, so if
you need high performance, you should think about implementing a
custom data structure for representing sets, such as trees, bitsets,
hash tables or something similar.

All these procedures accept an equality predicate as the first
argument.  This predicate is used for testing the objects in the list
sets for sameness.

@deffn {Scheme Procedure} lset<= = list1 @dots{}
Return @code{#t} if every @var{listi} is a subset of @var{listi+1},
otherwise return @code{#f}.  Returns @code{#t} if called with less
than two arguments. @var{=} is used for testing element equality.
@end deffn

@deffn {Scheme Procedure} lset= = list1 list2 @dots{}
Return @code{#t} if all argument lists are equal. @var{=} is used for
testing element equality.
@end deffn

@deffn {Scheme Procedure} lset-adjoin = list elt1 @dots{}
@deffnx {Scheme Procedure} lset-adjoin! = list elt1 @dots{}
Add all @var{elts} to the list @var{list}, suppressing duplicates and
return the resulting list.  @code{lset-adjoin!} is allowed, but not
required to modify its first argument. @var{=} is used for testing
element equality.
@end deffn

@deffn {Scheme Procedure} lset-union = list1 @dots{}
@deffnx {Scheme Procedure} lset-union! = list1 @dots{}
Return the union of all argument list sets.  The union is the set of
all elements which appear in any of the argument sets.
@code{lset-union!} is allowed, but not required to modify its first
argument. @var{=} is used for testing element equality.
@end deffn

@deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{}
@deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{}
Return the intersection of all argument list sets.  The intersection
is the set containing all elements which appear in all argument sets.
@code{lset-intersection!} is allowed, but not required to modify its
first argument. @var{=} is used for testing element equality.
@end deffn

@deffn {Scheme Procedure} lset-difference = list1 list2 @dots{}
@deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{}
Return the difference of all argument list sets.  The difference is
the the set containing all elements of the first list which do not
appear in the other lists.  @code{lset-difference!}  is allowed, but
not required to modify its first argument. @var{=} is used for testing
element equality.
@end deffn

@deffn {Scheme Procedure} lset-xor = list1 @dots{}
@deffnx {Scheme Procedure} lset-xor! = list1 @dots{}
Return the set containing all elements which appear in the first
argument list set, but not in the second; or, more generally: which
appear in an odd number of sets.  @code{lset-xor!}  is allowed, but
not required to modify its first argument. @var{=} is used for testing
element equality.
@end deffn

@deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{}
@deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{}
Return two values, the difference and the intersection of the argument
list sets. This works like a combination of @code{lset-difference} and
@code{lset-intersection}, but is more efficient.
@code{lset-diff+intersection!}  is allowed, but not required to modify
its first argument. @var{=} is used for testing element equality.  You
have to use some means to deal with the multiple values these
procedures return (@pxref{Multiple Values}).
@end deffn


@node SRFI-2
@subsection SRFI-2 - and-let*
@cindex SRFI-2

@noindent
The following syntax can be obtained with

@lisp
(use-modules (srfi srfi-2))
@end lisp

@deffn {library syntax} and-let* (clause @dots{}) body @dots{}
A combination of @code{and} and @code{let*}.

Each @var{clause} is evaluated in turn, and if @code{#f} is obtained
then evaluation stops and @code{#f} is returned.  If all are
non-@code{#f} then @var{body} is evaluated and the last form gives the
return value.  Each @var{clause} should be one of the following,

@table @code
@item (symbol expr)
Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}.
Like @code{let*}, that binding is available to subsequent clauses.
@item (expr)
Evaluate @var{expr} and check for @code{#f}.
@item symbol
Get the value bound to @var{symbol} and check for @code{#f}.
@end table

Notice that @code{(expr)} has an ``extra'' pair of parentheses, for
instance @code{((eq? x y))}.  One way to remember this is to imagine
the @code{symbol} in @code{(symbol expr)} is omitted.

@code{and-let*} is good for calculations where a @code{#f} value means
termination, but where a non-@code{#f} value is going to be needed in
subsequent expressions.

The following illustrates this, it returns text between brackets
@samp{[...]} in a string, or @code{#f} if there are no such brackets
(ie.@: either @code{string-index} gives @code{#f}).

@example
(define (extract-brackets str)
  (and-let* ((start (string-index str #\[))
             (end   (string-index str #\] start)))
    (substring str (1+ start) end)))
@end example

The following shows plain variables and expressions tested too.
@code{diagnostic-levels} is taken to be an alist associating a
diagnostic type with a level.  @code{str} is printed only if the type
is known and its level is high enough.

@example
(define (show-diagnostic type str)
  (and-let* (want-diagnostics
             (level (assq-ref diagnostic-levels type))
             ((>= level current-diagnostic-level)))
    (display str)))
@end example

The advantage of @code{and-let*} is that an extended sequence of
expressions and tests doesn't require lots of nesting as would arise
from separate @code{and} and @code{let*}, or from @code{cond} with
@code{=>}.

@end deffn


@node SRFI-4
@subsection SRFI-4 - Homogeneous numeric vector datatypes
@cindex SRFI-4

@c FIXME::martin: Review me!

SRFI-4 defines a set of datatypes and functions for vectors whose
elements are numbers, all of the same numeric type.  Vectors for
signed and unsigned exact integers and inexact reals in several
precisions are available.  Being homogeneous means they require less
memory than normal vectors.

The functions and the read syntax in this section are made available
with

@lisp
(use-modules (srfi srfi-4))
@end lisp

Procedures similar to the vector procedures (@pxref{Vectors}) are
provided for handling these homogeneous vectors, but they are distinct
datatypes and the two cannot be inter-mixed.

Ten vector data types are provided: Unsigned and signed integer values
with 8, 16, 32 and 64 bits and floating point values with 32 and 64
bits.  The type is indicated by a tag in the function names,
@code{u8}, @code{s8}, @code{u16}, @code{s16}, @code{u32}, @code{s32},
@code{u64}, @code{s64}, @code{f32}, @code{f64}.

The external representation (ie.@: read syntax) for these vectors is
similar to normal Scheme vectors, but with an additional tag
indiciating the vector's type.  For example,

@lisp
#u16(1 2 3)
#f64(3.1415 2.71)
@end lisp

Note that the read syntax for floating-point here conflicts with
@code{#f} for false.  In Standard Scheme one can write @code{(1
#f3)} for a three element list @code{(1 #f 3)}, but with the SRFI-4
module @code{(1 #f3)} is invalid.  @code{(1 #f 3)} is almost certainly
what one should write anyway to make the intention clear, so this is
rarely a problem.

@deffn {Scheme Procedure} u8vector? obj
@deffnx {Scheme Procedure} s8vector? obj
@deffnx {Scheme Procedure} u16vector? obj
@deffnx {Scheme Procedure} s16vector? obj
@deffnx {Scheme Procedure} u32vector? obj
@deffnx {Scheme Procedure} s32vector? obj
@deffnx {Scheme Procedure} u64vector? obj
@deffnx {Scheme Procedure} s64vector? obj
@deffnx {Scheme Procedure} f32vector? obj
@deffnx {Scheme Procedure} f64vector? obj
Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
indicated type.
@end deffn

@deffn {Scheme Procedure} make-u8vector n [value]
@deffnx {Scheme Procedure} make-s8vector n [value]
@deffnx {Scheme Procedure} make-u16vector n [value]
@deffnx {Scheme Procedure} make-s16vector n [value]
@deffnx {Scheme Procedure} make-u32vector n [value]
@deffnx {Scheme Procedure} make-s32vector n [value]
@deffnx {Scheme Procedure} make-u64vector n [value]
@deffnx {Scheme Procedure} make-s64vector n [value]
@deffnx {Scheme Procedure} make-f32vector n [value]
@deffnx {Scheme Procedure} make-f64vector n [value]
Return a newly allocated homogeneous numeric vector holding @var{n}
elements of the indicated type.  If @var{value} is given, the vector
is initialized with that value, otherwise the contents are
unspecified.
@end deffn

@deffn {Scheme Procedure} u8vector value @dots{}
@deffnx {Scheme Procedure} s8vector value @dots{}
@deffnx {Scheme Procedure} u16vector value @dots{}
@deffnx {Scheme Procedure} s16vector value @dots{}
@deffnx {Scheme Procedure} u32vector value @dots{}
@deffnx {Scheme Procedure} s32vector value @dots{}
@deffnx {Scheme Procedure} u64vector value @dots{}
@deffnx {Scheme Procedure} s64vector value @dots{}
@deffnx {Scheme Procedure} f32vector value @dots{}
@deffnx {Scheme Procedure} f64vector value @dots{}
Return a newly allocated homogeneous numeric vector of the indicated
type, holding the given parameter @var{value}s.  The vector length is
the number of parameters given.
@end deffn

@deffn {Scheme Procedure} u8vector-length vec
@deffnx {Scheme Procedure} s8vector-length vec
@deffnx {Scheme Procedure} u16vector-length vec
@deffnx {Scheme Procedure} s16vector-length vec
@deffnx {Scheme Procedure} u32vector-length vec
@deffnx {Scheme Procedure} s32vector-length vec
@deffnx {Scheme Procedure} u64vector-length vec
@deffnx {Scheme Procedure} s64vector-length vec
@deffnx {Scheme Procedure} f32vector-length vec
@deffnx {Scheme Procedure} f64vector-length vec
Return the number of elements in @var{vec}.
@end deffn

@deffn {Scheme Procedure} u8vector-ref vec i
@deffnx {Scheme Procedure} s8vector-ref vec i
@deffnx {Scheme Procedure} u16vector-ref vec i
@deffnx {Scheme Procedure} s16vector-ref vec i
@deffnx {Scheme Procedure} u32vector-ref vec i
@deffnx {Scheme Procedure} s32vector-ref vec i
@deffnx {Scheme Procedure} u64vector-ref vec i
@deffnx {Scheme Procedure} s64vector-ref vec i
@deffnx {Scheme Procedure} f32vector-ref vec i
@deffnx {Scheme Procedure} f64vector-ref vec i
Return the element at index @var{i} in @var{vec}.  The first element
in @var{vec} is index 0.
@end deffn

@deffn {Scheme Procedure} u8vector-ref vec i value
@deffnx {Scheme Procedure} s8vector-ref vec i value
@deffnx {Scheme Procedure} u16vector-ref vec i value
@deffnx {Scheme Procedure} s16vector-ref vec i value
@deffnx {Scheme Procedure} u32vector-ref vec i value
@deffnx {Scheme Procedure} s32vector-ref vec i value
@deffnx {Scheme Procedure} u64vector-ref vec i value
@deffnx {Scheme Procedure} s64vector-ref vec i value
@deffnx {Scheme Procedure} f32vector-ref vec i value
@deffnx {Scheme Procedure} f64vector-ref vec i value
Set the element at index @var{i} in @var{vec} to @var{value}.  The
first element in @var{vec} is index 0.  The return value is
unspecified.
@end deffn

@deffn {Scheme Procedure} u8vector->list vec
@deffnx {Scheme Procedure} s8vector->list vec
@deffnx {Scheme Procedure} u16vector->list vec
@deffnx {Scheme Procedure} s16vector->list vec
@deffnx {Scheme Procedure} u32vector->list vec
@deffnx {Scheme Procedure} s32vector->list vec
@deffnx {Scheme Procedure} u64vector->list vec
@deffnx {Scheme Procedure} s64vector->list vec
@deffnx {Scheme Procedure} f32vector->list vec
@deffnx {Scheme Procedure} f64vector->list vec
Return a newly allocated list holding all elements of @var{vec}.
@end deffn

@deffn {Scheme Procedure} list->u8vector lst
@deffnx {Scheme Procedure} list->s8vector lst
@deffnx {Scheme Procedure} list->u16vector lst
@deffnx {Scheme Procedure} list->s16vector lst
@deffnx {Scheme Procedure} list->u32vector lst
@deffnx {Scheme Procedure} list->s32vector lst
@deffnx {Scheme Procedure} list->u64vector lst
@deffnx {Scheme Procedure} list->s64vector lst
@deffnx {Scheme Procedure} list->f32vector lst
@deffnx {Scheme Procedure} list->f64vector lst
Return a newly allocated homogeneous numeric vector of the indicated type,
initialized with the elements of the list @var{lst}.
@end deffn


@node SRFI-6
@subsection SRFI-6 - Basic String Ports
@cindex SRFI-6

SRFI-6 defines the procedures @code{open-input-string},
@code{open-output-string} and @code{get-output-string}.  These
procedures are included in the Guile core, so using this module does not
make any difference at the moment.  But it is possible that support for
SRFI-6 will be factored out of the core library in the future, so using
this module does not hurt, after all.

@node SRFI-8
@subsection SRFI-8 - receive
@cindex SRFI-8

@code{receive} is a syntax for making the handling of multiple-value
procedures easier.  It is documented in @xref{Multiple Values}.


@node SRFI-9
@subsection SRFI-9 - define-record-type
@cindex SRFI-9

This SRFI is a syntax for defining new record types and creating
predicate, constructor, and field getter and setter functions.  In
Guile this is simply an alternate interface to the core record
functionality (@pxref{Records}).  It can be used with,

@example
(use-modules (srfi srfi-9))
@end example

@deffn {library syntax} define-record-type type @* (constructor fieldname @dots{}) @* predicate @* (fieldname accessor [modifier]) @dots{}
@sp 1
Create a new record type, and make various @code{define}s for using
it.  This syntax can only occur at the top-level, not nested within
some other form.

@var{type} is bound to the record type, which is as per the return
from the core @code{make-record-type}.  @var{type} also provides the
name for the record, as per @code{record-type-name}.

@var{constructor} is bound to a function to be called as
@code{(@var{constructor} fieldval @dots{})} to create a new record of
this type.  The arguments are initial values for the fields, one
argument for each field, in the order they appear in the
@code{define-record-type} form.

The @var{fieldname}s provide the names for the record fields, as per
the core @code{record-type-fields} etc, and are referred to in the
subsequent accessor/modifier forms.

@var{predictate} is bound to a function to be called as
@code{(@var{predicate} obj)}.  It returns @code{#t} or @code{#f}
according to whether @var{obj} is a record of this type.

Each @var{accessor} is bound to a function to be called
@code{(@var{accessor} record)} to retrieve the respective field from a
@var{record}.  Similarly each @var{modifier} is bound to a function to
be called @code{(@var{modifier} record val)} to set the respective
field in a @var{record}.
@end deffn

@noindent
An example will illustrate typical usage,

@example
(define-record-type employee-type
  (make-employee name age salary)
  employee?
  (name    get-employee-name)
  (age     get-employee-age    set-employee-age)
  (salary  get-employee-salary set-employee-salary))
@end example

This creates a new employee data type, with name, age and salary
fields.  Accessor functions are created for each field, but no
modifier function for the name (the intention in this example being
that it's established only when an employee object is created).  These
can all then be used as for example,

@example
employee-type @result{} #<record-type employee-type>

(define fred (make-employee "Fred" 45 20000.00))

(employee? fred)        @result{} #t
(get-employee-age fred) @result{} 45
(set-employee-salary fred 25000.00)  ;; pay rise
@end example

The functions created by @code{define-record-type} are ordinary
top-level @code{define}s.  They can be redefined or @code{set!} as
desired, exported from a module, etc.


@node SRFI-10
@subsection SRFI-10 - Hash-Comma Reader Extension
@cindex SRFI-10

@cindex hash-comma
@cindex #,()
The module @code{(srfi srfi-10)} implements the syntax extension
@code{#,()}, also called hash-comma, which is defined in SRFI-10.

The support for SRFI-10 consists of the procedure
@code{define-reader-ctor} for defining new reader constructors and the
read syntax form

@example
#,(@var{ctor} @var{datum} ...)
@end example

where @var{ctor} must be a symbol for which a read constructor was
defined previously, using @code{define-reader-ctor}.

Example:

@lisp
(use-modules (ice-9 rdelim)) ; for read-line
(define-reader-ctor 'file open-input-file)
(define f '#,(file "/etc/passwd"))
(read-line f)
@result{}
"root:x:0:0:root:/root:/bin/bash"
@end lisp

Please note the quote before the @code{#,(file ...)} expression.  This
is necessary because ports are not self-evaluating in Guile.

@deffn {Scheme Procedure} define-reader-ctor symbol proc
Define @var{proc} as the reader constructor for hash-comma forms with a
tag @var{symbol}.  @var{proc} will be applied to the datum(s) following
the tag in the hash-comma expression after the complete form has been
read in.  The result of @var{proc} is returned by the Scheme reader.
@end deffn


@node SRFI-11
@subsection SRFI-11 - let-values
@cindex SRFI-11

@findex let-values
@findex let-values*
This module implements the binding forms for multiple values
@code{let-values} and @code{let-values*}.  These forms are similar to
@code{let} and @code{let*} (@pxref{Local Bindings}), but they support
binding of the values returned by multiple-valued expressions.

Write @code{(use-modules (srfi srfi-11))} to make the bindings
available.

@lisp
(let-values (((x y) (values 1 2))
             ((z f) (values 3 4)))
   (+ x y z f))
@result{}
10
@end lisp

@code{let-values} performs all bindings simultaneously, which means that
no expression in the binding clauses may refer to variables bound in the
same clause list.  @code{let-values*}, on the other hand, performs the
bindings sequentially, just like @code{let*} does for single-valued
expressions.


@node SRFI-13
@subsection SRFI-13 - String Library
@cindex SRFI-13

In this section, we will describe all procedures defined in SRFI-13
(string library) and implemented by the module @code{(srfi srfi-13)}.

Note that only the procedures from SRFI-13 are documented here which are
not already contained in Guile.  For procedures not documented here
please refer to the relevant chapters in the Guile Reference Manual, for
example the documentation of strings and string procedures
(@pxref{Strings}).

All of the procedures defined in SRFI-13, which are not already
included in the Guile core library, are implemented in the module
@code{(srfi srfi-13)}.  The procedures which are both in Guile and in
SRFI-13 are slightly extended in this module.  Their bindings
overwrite those in the Guile core.

The procedures which are defined in the section @emph{Low-level
procedures} of SRFI-13 for parsing optional string indices, substring
specification checking and Knuth-Morris-Pratt-Searching are not
implemented.

The procedures @code{string-contains} and @code{string-contains-ci} are
not implemented very efficiently at the moment.  This will be changed as
soon as possible.

@menu
* Loading SRFI-13::             How to load SRFI-13 support.
* SRFI-13 Predicates::          String predicates.
* SRFI-13 Constructors::        String constructing procedures.
* SRFI-13 List/String Conversion::  Conversion from/to lists.
* SRFI-13 Selection::           Selection portions of strings.
* SRFI-13 Modification::        Modify strings in-place.
* SRFI-13 Comparison::          Compare strings.
* SRFI-13 Prefixes/Suffixes::   Detect common pre-/suffixes.
* SRFI-13 Searching::           Searching for substrings.
* SRFI-13 Case Mapping::        Mapping to lower-/upper-case.
* SRFI-13 Reverse/Append::      Reverse and append strings.
* SRFI-13 Fold/Unfold/Map::     Construct/deconstruct strings.
* SRFI-13 Replicate/Rotate::    Replicate and rotate portions of strings.
* SRFI-13 Miscellaneous::       Left-over string procedures.
* SRFI-13 Filtering/Deleting::  Filter and delete characters from strings.
@end menu


@node Loading SRFI-13
@subsubsection Loading SRFI-13

When Guile is properly installed, SRFI-13 support can be loaded into a
running Guile by using the @code{(srfi srfi-13)} module.

@example
$ guile
guile> (use-modules (srfi srfi-13))
guile>
@end example

When this step causes any errors, Guile is not properly installed.

One possible reason is that Guile cannot find either the Scheme module
file @file{srfi-13.scm}, or it cannot find the shared object file
@file{libguile-srfi-srfi-13-14.so}.  Make sure that the former is in the
Guile load path and that the latter is either installed in some default
location like @file{/usr/local/lib} or that the directory it was
installed to is in your @code{LTDL_LIBRARY_PATH}.  The same applies to
@file{srfi-14.scm}.

Now you can test whether the SRFI-13 procedures are working by calling
the @code{string-concatenate} procedure.

@example
guile> (string-concatenate '("Hello" " " "World!"))
"Hello World!"
@end example

@node SRFI-13 Predicates
@subsubsection Predicates

In addition to the primitives @code{string?} and @code{string-null?},
which are already in the Guile core, the string predicates
@code{string-any} and @code{string-every} are defined by SRFI-13.

@deffn {Scheme Procedure} string-any char_pred s [start end]
Return true if @code{char_pred} is satisfied for any character in the
string @var{s}.  @var{char_pred} can be

@itemize @bullet
@item
A character, to to test for any in @var{s} equal to that.
@item
A character set (@pxref{SRFI-14}), to test for any character in
@var{s} in that character set.
@item
A predicate function, called as @code{(@var{char_pred} c)} for each
character in @var{s}, from left to right, to test for any on which
@var{char_pred} returns true.

When @var{char_pred} does return true (ie.@: non-@code{#f}), that
value is the value returned by @code{string-any}.
@end itemize

If there are no characters in @var{s} (ie.@: @var{start} equals
@var{end}) then the return is @code{#f}.

SRFI-13 specifies that when @var{char_pred} is a predicate function,
the call on the last character of @var{s} (assuming that point is
reached) is a tail call, but currently in Guile this is not the case.
@end deffn

@deffn {Scheme Procedure} string-every char_pred s [start end]
Return true if @var{char_pred} is satisifed for every character in the
string @var{s}.  @var{char_pred} can be 

@itemize @bullet
@item
A character, to to test for every character in @var{s} equal to that.
@item
A character set (@pxref{SRFI-14}), to test for every character in
@var{s} being in that character set.
@item
A predicate function, called as @code{(@var{char_pred} c)} for each
character in @var{s}, from left to right, to test that it returns true
for every character in @var{s}.

When @var{char_pred} does return true (ie.@: non-@code{#f}) for every
character, the return from the last call is the value returned by
@code{string-every}.
@end itemize

If there are no characters in @var{s} (ie.@: @var{start} equals
@var{end}) then the return is @code{#t}.

SRFI-13 specifies that when @var{char_pred} is a predicate function,
the call on the last character of @var{s} (assuming that point is
reached) is a tail call, but currently in Guile this is not the case.
@end deffn

@c ===================================================================

@node SRFI-13 Constructors
@subsubsection Constructors

SRFI-13 defines several procedures for constructing new strings.  In
addition to @code{make-string} and @code{string} (available in the Guile
core library), the procedure @code{string-tabulate} does exist.

@deffn {Scheme Procedure} string-tabulate proc len
@var{proc} is an integer->char procedure.  Construct a string
of size @var{len} by applying @var{proc} to each index to
produce the corresponding string element.  The order in which
@var{proc} is applied to the indices is not specified.
@end deffn


@c ===================================================================

@node SRFI-13 List/String Conversion
@subsubsection List/String Conversion

The procedure @code{string->list} is extended by SRFI-13, that is why it
is included in @code{(srfi srfi-13)}.  The other procedures are new.
The Guile core already contains the procedure @code{list->string} for
converting a list of characters into a string (@pxref{List/String
Conversion}).

@deffn {Scheme Procedure} string->list str [start end]
Convert the string @var{str} into a list of characters.
@end deffn

@deffn {Scheme Procedure} reverse-list->string chrs
An efficient implementation of @code{(compose string->list
reverse)}:

@smalllisp
(reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
@end smalllisp
@end deffn

@deffn {Scheme Procedure} string-join ls [delimiter grammar]
Append the string in the string list @var{ls}, using the string
@var{delim} as a delimiter between the elements of @var{ls}.
@var{grammar} is a symbol which specifies how the delimiter is
placed between the strings, and defaults to the symbol
@code{infix}.

@table @code
@item infix
Insert the separator between list elements.  An empty string
will produce an empty list.

@item string-infix
Like @code{infix}, but will raise an error if given the empty
list.

@item suffix
Insert the separator after every list element.

@item prefix
Insert the separator before each list element.
@end table
@end deffn


@c ===================================================================

@node SRFI-13 Selection
@subsubsection Selection

These procedures are called @dfn{selectors}, because they access
information about the string or select pieces of a given string.

Additional selector procedures are documented in the Strings section
(@pxref{String Selection}), like @code{string-length} or
@code{string-ref}.

@code{string-copy} is also available in core Guile, but this version
accepts additional start/end indices.

@deffn {Scheme Procedure} string-copy str [start end]
Return a freshly allocated copy of the string @var{str}.  If
given, @var{start} and @var{end} delimit the portion of
@var{str} which is copied.
@end deffn

@deffn {Scheme Procedure} substring/shared str start [end]
Like @code{substring}, but the result may share memory with the
argument @var{str}.
@end deffn

@deffn {Scheme Procedure} string-copy! target tstart s [start end]
Copy the sequence of characters from index range [@var{start},
@var{end}) in string @var{s} to string @var{target}, beginning
at index @var{tstart}.  The characters are copied left-to-right
or right-to-left as needed - the copy is guaranteed to work,
even if @var{target} and @var{s} are the same string.  It is an
error if the copy operation runs off the end of the target
string.
@end deffn

@deffn {Scheme Procedure} string-take s n
@deffnx {Scheme Procedure} string-take-right s n
Return the @var{n} first/last characters of @var{s}.
@end deffn

@deffn {Scheme Procedure} string-drop s n
@deffnx {Scheme Procedure} string-drop-right s n
Return all but the first/last @var{n} characters of @var{s}.
@end deffn

@deffn {Scheme Procedure} string-pad s len [chr start end]
@deffnx {Scheme Procedure} string-pad-right s len [chr start end]
Take that characters from @var{start} to @var{end} from the
string @var{s} and return a new string, right(left)-padded by the
character @var{chr} to length @var{len}.  If the resulting
string is longer than @var{len}, it is truncated on the right (left).
@end deffn

@deffn {Scheme Procedure} string-trim s [char_pred start end]
@deffnx {Scheme Procedure} string-trim-right s [char_pred start end]
@deffnx {Scheme Procedure} string-trim-both s [char_pred start end]
Trim @var{s} by skipping over all characters on the left/right/both
sides of the string that satisfy the parameter @var{char_pred}:

@itemize @bullet
@item
if it is the character @var{ch}, characters equal to
@var{ch} are trimmed,

@item
if it is a procedure @var{pred} characters that
satisfy @var{pred} are trimmed,

@item
if it is a character set, characters in that set are trimmed.
@end itemize

If called without a @var{char_pred} argument, all whitespace is
trimmed.
@end deffn


@c ===================================================================

@node SRFI-13 Modification
@subsubsection Modification

The procedure @code{string-fill!} is extended from R5RS because it
accepts optional start/end indices.  This bindings shadows the procedure
of the same name in the Guile core.  The second modification procedure
@code{string-set!} is documented in the Strings section (@pxref{String
Modification}).

@deffn {Scheme Procedure} string-fill! str chr [start end]
Stores @var{chr} in every element of the given @var{str} and
returns an unspecified value.
@end deffn


@c ===================================================================

@node SRFI-13 Comparison
@subsubsection Comparison

The procedures in this section are used for comparing strings in
different ways.  The comparison predicates differ from those in R5RS in
that they do not only return @code{#t} or @code{#f}, but the mismatch
index in the case of a true return value.

@code{string-hash} and @code{string-hash-ci} are for calculating hash
values for strings, useful for implementing fast lookup mechanisms.

@deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
mismatch index, depending upon whether @var{s1} is less than,
equal to, or greater than @var{s2}.  The mismatch index is the
largest index @var{i} such that for every 0 <= @var{j} <
@var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] - that is,
@var{i} is the first position that does not match.  The
character comparison is done case-insensitively.
@end deffn

@deffn {Scheme Procedure} string= s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string<> s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string< s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string> s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string<= s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string>= s1 s2 [start1 end1 start2 end2]
Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
fails.  Otherwise, the mismatch index is returned (or @var{end1} in the
case of @code{string=}.
@end deffn

@deffn {Scheme Procedure} string-ci= s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-ci<> s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-ci< s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-ci> s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-ci<= s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-ci>= s1 s2 [start1 end1 start2 end2]
Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
fails.  Otherwise, the mismatch index is returned (or @var{end1} in the
case of @code{string=}.  These are the case-insensitive variants.
@end deffn

@deffn {Scheme Procedure} string-hash s [bound start end]
@deffnx {Scheme Procedure} string-hash-ci s [bound start end]
Return a hash value of the string @var{s} in the range 0 @dots{}
@var{bound} - 1.  @code{string-hash-ci} is the case-insensitive variant.
@end deffn


@c ===================================================================

@node SRFI-13 Prefixes/Suffixes
@subsubsection Prefixes/Suffixes

Using these procedures you can determine whether a given string is a
prefix or suffix of another string or how long a common prefix/suffix
is.

@deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-suffix-length s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 end1 start2 end2]
Return the length of the longest common prefix/suffix of the two
strings. @code{string-prefix-length-ci} and
@code{string-suffix-length-ci} are the case-insensitive variants.
@end deffn

@deffn {Scheme Procedure} string-prefix? s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-prefix-ci? s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-suffix? s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-suffix-ci? s1 s2 [start1 end1 start2 end2]
Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and
@code{string-suffix-ci?} are the case-insensitive variants.
@end deffn


@c ===================================================================

@node SRFI-13 Searching
@subsubsection Searching

Use these procedures to find out whether a string contains a given
character or a given substring, or a character from a set of characters.

@deffn {Scheme Procedure} string-index s char_pred [start end]
@deffnx {Scheme Procedure} string-index-right s char_pred [start end]
Search through the string @var{s} from left to right (right to left),
returning the index of the first (last) occurrence of a character which

@itemize @bullet
@item
equals @var{char_pred}, if it is character,

@item
satisfies the predicate @var{char_pred}, if it is a
procedure,

@item
is in the set @var{char_pred}, if it is a character set.
@end itemize
@end deffn

@deffn {Scheme Procedure} string-skip s char_pred [start end]
@deffnx {Scheme Procedure} string-skip-right s char_pred [start end]
Search through the string @var{s} from left to right (right to left),
returning the index of the first (last) occurrence of a character which

@itemize @bullet
@item
does not equal @var{char_pred}, if it is character,

@item
does not satisfy the predicate @var{char_pred}, if it is
a procedure.

@item
is not in the set if @var{char_pred} is a character set.
@end itemize
@end deffn

@deffn {Scheme Procedure} string-count s char_pred [start end]
Return the count of the number of characters in the string
@var{s} which

@itemize @bullet
@item
equals @var{char_pred}, if it is character,

@item
satisfies the predicate @var{char_pred}, if it is a procedure.

@item
is in the set @var{char_pred}, if it is a character set.
@end itemize
@end deffn

@deffn {Scheme Procedure} string-contains s1 s2 [start1 end1 start2 end2]
@deffnx {Scheme Procedure} string-contains-ci s1 s2 [start1 end1 start2 end2]
Does string @var{s1} contain string @var{s2}?  Return the index
in @var{s1} where @var{s2} occurs as a substring, or false.
The optional start/end indices restrict the operation to the
indicated substrings.

@code{string-contains-ci} is the case-insensitive variant.
@end deffn


@c ===================================================================

@node SRFI-13 Case Mapping
@subsubsection Alphabetic Case Mapping

These procedures convert the alphabetic case of strings.  They are
similar to the procedures in the Guile core, but are extended to handle
optional start/end indices.

@deffn {Scheme Procedure} string-upcase s [start end]
@deffnx {Scheme Procedure} string-upcase! s [start end]
Upcase every character in @var{s}.  @code{string-upcase!} is the
side-effecting variant.
@end deffn

@deffn {Scheme Procedure} string-downcase s [start end]
@deffnx {Scheme Procedure} string-downcase! s [start end]
Downcase every character in @var{s}.  @code{string-downcase!} is the
side-effecting variant.
@end deffn

@deffn {Scheme Procedure} string-titlecase s [start end]
@deffnx {Scheme Procedure} string-titlecase! s [start end]
Upcase every first character in every word in @var{s}, downcase the
other characters.  @code{string-titlecase!} is the side-effecting
variant.
@end deffn


@c ===================================================================

@node SRFI-13 Reverse/Append
@subsubsection Reverse/Append

One appending procedure, @code{string-append} is the same in R5RS and in
SRFI-13, so it is not redefined.

@deffn {Scheme Procedure} string-reverse str [start end]
@deffnx {Scheme Procedure} string-reverse! str [start end]
Reverse the string @var{str}.  The optional arguments
@var{start} and @var{end} delimit the region of @var{str} to
operate on.

@code{string-reverse!} modifies the argument string and returns an
unspecified value.
@end deffn

@deffn {Scheme Procedure} string-append/shared ls @dots{}
Like @code{string-append}, but the result may share memory
with the argument strings.
@end deffn

@deffn {Scheme Procedure} string-concatenate ls
Append the elements of @var{ls} (which must be strings)
together into a single string.  Guaranteed to return a freshly
allocated string.
@end deffn

@deffn {Scheme Procedure} string-concatenate/shared ls
Like @code{string-concatenate}, but the result may share memory
with the strings in the list @var{ls}.
@end deffn

@deffn {Scheme Procedure} string-concatenate-reverse ls final_string end
Without optional arguments, this procedure is equivalent to

@smalllisp
(string-concatenate (reverse ls))
@end smalllisp

If the optional argument @var{final_string} is specified, it is
consed onto the beginning to @var{ls} before performing the
list-reverse and string-concatenate operations.  If @var{end}
is given, only the characters of @var{final_string} up to index
@var{end} are used.

Guaranteed to return a freshly allocated string.
@end deffn

@deffn {Scheme Procedure} string-concatenate-reverse/shared ls final_string end
Like @code{string-concatenate-reverse}, but the result may
share memory with the the strings in the @var{ls} arguments.
@end deffn


@c ===================================================================

@node SRFI-13 Fold/Unfold/Map
@subsubsection Fold/Unfold/Map

@code{string-map}, @code{string-for-each} etc. are for iterating over
the characters a string is composed of.  The fold and unfold procedures
are list iterators and constructors.

@deffn {Scheme Procedure} string-map proc s [start end]
@var{proc} is a char->char procedure, it is mapped over
@var{s}.  The order in which the procedure is applied to the
string elements is not specified.
@end deffn

@deffn {Scheme Procedure} string-map! proc s [start end]
@var{proc} is a char->char procedure, it is mapped over
@var{s}.  The order in which the procedure is applied to the
string elements is not specified.  The string @var{s} is
modified in-place, the return value is not specified.
@end deffn

@deffn {Scheme Procedure} string-fold kons knil s [start end]
@deffnx {Scheme Procedure} string-fold-right kons knil s [start end]
Fold @var{kons} over the characters of @var{s}, with @var{knil} as the
terminating element, from left to right (or right to left, for
@code{string-fold-right}).  @var{kons} must expect two arguments: The
actual character and the last result of @var{kons}' application.
@end deffn

@deffn {Scheme Procedure} string-unfold p f g seed [base make_final]
@deffnx {Scheme Procedure} string-unfold-right p f g seed [base make_final]
These are the fundamental string constructors.
@itemize @bullet
@item @var{g} is used to generate a series of @emph{seed}
values from the initial @var{seed}: @var{seed}, (@var{g}
@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
@dots{}
@item @var{p} tells us when to stop - when it returns true
when applied to one of these seed values.
@item @var{f} maps each seed value to the corresponding
character in the result string.  These chars are assembled into the
string in a left-to-right (right-to-left) order.
@item @var{base} is the optional initial/leftmost (rightmost)
 portion of the constructed string; it default to the empty string.
@item @var{make_final} is applied to the terminal seed
value (on which @var{p} returns true) to produce the final/rightmost
(leftmost) portion of the constructed string.  It defaults to
@code{(lambda (x) "")}.
@end itemize
@end deffn

@deffn {Scheme Procedure} string-for-each proc s [start end]
@var{proc} is mapped over @var{s} in left-to-right order.  The
return value is not specified.
@end deffn


@c ===================================================================

@node SRFI-13 Replicate/Rotate
@subsubsection Replicate/Rotate

These procedures are special substring procedures, which can also be
used for replicating strings.  They are a bit tricky to use, but
consider this code fragment, which replicates the input string
@code{"foo"} so often that the resulting string has a length of six.

@lisp
(xsubstring "foo" 0 6)
@result{}
"foofoo"
@end lisp

@deffn {Scheme Procedure} xsubstring s from [to start end]
This is the @emph{extended substring} procedure that implements
replicated copying of a substring of some string.

@var{s} is a string, @var{start} and @var{end} are optional
arguments that demarcate a substring of @var{s}, defaulting to
0 and the length of @var{s}.  Replicate this substring up and
down index space, in both the positive and negative directions.
@code{xsubstring} returns the substring of this string
beginning at index @var{from}, and ending at @var{to}, which
defaults to @var{from} + (@var{end} - @var{start}).
@end deffn

@deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto start end]
Exactly the same as @code{xsubstring}, but the extracted text
is written into the string @var{target} starting at index
@var{tstart}.  The operation is not defined if @code{(eq?
@var{target} @var{s})} or these arguments share storage - you
cannot copy a string on top of itself.
@end deffn


@c ===================================================================

@node SRFI-13 Miscellaneous
@subsubsection Miscellaneous

@code{string-replace} is for replacing a portion of a string with
another string and @code{string-tokenize} splits a string into a list of
strings, breaking it up at a specified character.

@deffn {Scheme Procedure} string-replace s1 s2 [start1 end1 start2 end2]
Return the string @var{s1}, but with the characters
@var{start1} @dots{} @var{end1} replaced by the characters
@var{start2} @dots{} @var{end2} from @var{s2}.

For reference, note that SRFI-13 specifies @var{start1} and @var{end1}
as mandatory, but in Guile they are optional.
@end deffn

@deffn {Scheme Procedure} string-tokenize s [token-set start end]
Split the string @var{s} into a list of substrings, where each
substring is a maximal non-empty contiguous sequence of characters
from the character set @var{token_set}, which defaults to an
equivalent of @code{char-set:graphic}.  If @var{start} or @var{end}
indices are provided, they restrict @code{string-tokenize} to
operating on the indicated substring of @var{s}.
@end deffn


@c ===================================================================

@node SRFI-13 Filtering/Deleting
@subsubsection Filtering/Deleting

@dfn{Filtering} means to remove all characters from a string which do
not match a given criteria, @dfn{deleting} means the opposite.

@deffn {Scheme Procedure} string-filter s char_pred [start end]
Filter the string @var{s}, retaining only those characters that
satisfy the @var{char_pred} argument.  If the argument is a
procedure, it is applied to each character as a predicate, if
it is a character, it is tested for equality and if it is a
character set, it is tested for membership.
@end deffn

@deffn {Scheme Procedure} string-delete s char_pred [start end]
Filter the string @var{s}, retaining only those characters that
do not satisfy the @var{char_pred} argument.  If the argument
is a procedure, it is applied to each character as a predicate,
if it is a character, it is tested for equality and if it is a
character set, it is tested for membership.
@end deffn


@node SRFI-14
@subsection SRFI-14 - Character-set Library
@cindex SRFI-14

SRFI-14 defines the data type @dfn{character set}, and also defines a
lot of procedures for handling this character type, and a few standard
character sets like whitespace, alphabetic characters and others.

All procedures from SRFI-14 (character-set library) are implemented in
the module @code{(srfi srfi-14)}, as well as the standard variables
@code{char-set:letter}, @code{char-set:digit} etc.

@menu
* Loading SRFI-14::             How to make charsets available.
* SRFI-14 Character Set Data Type::  Underlying data type for charsets.
* SRFI-14 Predicates/Comparison::  Charset predicates.
* SRFI-14 Iterating Over Character Sets::  Enumerate charset elements.
* SRFI-14 Creating Character Sets::  Making new charsets.
* SRFI-14 Querying Character Sets::  Test charsets for membership etc.
* SRFI-14 Character-Set Algebra::  Calculating new charsets.
* SRFI-14 Standard Character Sets::  Variables containing predefined charsets.
@end menu


@node Loading SRFI-14
@subsubsection Loading SRFI-14

When Guile is properly installed, SRFI-14 support can be loaded into a
running Guile by using the @code{(srfi srfi-14)} module.

@example
$ guile
guile> (use-modules (srfi srfi-14))
guile> (char-set-union (char-set #\f #\o #\o) (string->char-set "bar"))
#<charset @{#\a #\b #\f #\o #\r@}>
guile>
@end example


@node SRFI-14 Character Set Data Type
@subsubsection Character Set Data Type

The data type @dfn{charset} implements sets of characters
(@pxref{Characters}).  Because the internal representation of character
sets is not visible to the user, a lot of procedures for handling them
are provided.

Character sets can be created, extended, tested for the membership of a
characters and be compared to other character sets.

The Guile implementation of character sets deals with 8-bit characters.
In the standard variables, only the ASCII part of the character range is
really used, so that for example @dfn{Umlaute} and other accented
characters are not considered to be letters.  In the future, as Guile
may get support for international character sets, this will change, so
don't rely on these ``features''.


@c ===================================================================

@node SRFI-14 Predicates/Comparison
@subsubsection Predicates/Comparison

Use these procedures for testing whether an object is a character set,
or whether several character sets are equal or subsets of each other.
@code{char-set-hash} can be used for calculating a hash value, maybe for
usage in fast lookup procedures.

@deffn {Scheme Procedure} char-set? obj
Return @code{#t} if @var{obj} is a character set, @code{#f}
otherwise.
@end deffn

@deffn {Scheme Procedure} char-set= cs1 @dots{}
Return @code{#t} if all given character sets are equal.
@end deffn

@deffn {Scheme Procedure} char-set<= cs1 @dots{}
Return @code{#t} if every character set @var{cs}i is a subset
of character set @var{cs}i+1.
@end deffn

@deffn {Scheme Procedure} char-set-hash cs [bound]
Compute a hash value for the character set @var{cs}.  If
@var{bound} is given and not @code{#f}, it restricts the
returned value to the range 0 @dots{} @var{bound - 1}.
@end deffn


@c ===================================================================

@node SRFI-14 Iterating Over Character Sets
@subsubsection Iterating Over Character Sets

Character set cursors are a means for iterating over the members of a
character sets.  After creating a character set cursor with
@code{char-set-cursor}, a cursor can be dereferenced with
@code{char-set-ref}, advanced to the next member with
@code{char-set-cursor-next}.  Whether a cursor has passed past the last
element of the set can be checked with @code{end-of-char-set?}.

Additionally, mapping and (un-)folding procedures for character sets are
provided.

@deffn {Scheme Procedure} char-set-cursor cs
Return a cursor into the character set @var{cs}.
@end deffn

@deffn {Scheme Procedure} char-set-ref cs cursor
Return the character at the current cursor position
@var{cursor} in the character set @var{cs}.  It is an error to
pass a cursor for which @code{end-of-char-set?} returns true.
@end deffn

@deffn {Scheme Procedure} char-set-cursor-next cs cursor
Advance the character set cursor @var{cursor} to the next
character in the character set @var{cs}.  It is an error if the
cursor given satisfies @code{end-of-char-set?}.
@end deffn

@deffn {Scheme Procedure} end-of-char-set? cursor
Return @code{#t} if @var{cursor} has reached the end of a
character set, @code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} char-set-fold kons knil cs
Fold the procedure @var{kons} over the character set @var{cs},
initializing it with @var{knil}.
@end deffn

@deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
@deffnx {Scheme Procedure} char-set-unfold! p f g seed base_cs
This is a fundamental constructor for character sets.
@itemize @bullet
@item @var{g} is used to generate a series of ``seed'' values
from the initial seed: @var{seed}, (@var{g} @var{seed}),
(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
@item @var{p} tells us when to stop -- when it returns true
when applied to one of the seed values.
@item @var{f} maps each seed value to a character. These
characters are added to the base character set @var{base_cs} to
form the result; @var{base_cs} defaults to the empty set.
@end itemize

@code{char-set-unfold!} is the side-effecting variant.
@end deffn

@deffn {Scheme Procedure} char-set-for-each proc cs
Apply @var{proc} to every character in the character set
@var{cs}.  The return value is not specified.
@end deffn

@deffn {Scheme Procedure} char-set-map proc cs
Map the procedure @var{proc} over every character in @var{cs}.
@var{proc} must be a character -> character procedure.
@end deffn


@c ===================================================================

@node SRFI-14 Creating Character Sets
@subsubsection Creating Character Sets

New character sets are produced with these procedures.

@deffn {Scheme Procedure} char-set-copy cs
Return a newly allocated character set containing all
characters in @var{cs}.
@end deffn

@deffn {Scheme Procedure} char-set char1 @dots{}
Return a character set containing all given characters.
@end deffn

@deffn {Scheme Procedure} list->char-set char_list [base_cs]
@deffnx {Scheme Procedure} list->char-set! char_list base_cs
Convert the character list @var{list} to a character set.  If
the character set @var{base_cs} is given, the character in this
set are also included in the result.

@code{list->char-set!} is the side-effecting variant.
@end deffn

@deffn {Scheme Procedure} string->char-set s [base_cs]
@deffnx {Scheme Procedure} string->char-set! s base_cs
Convert the string @var{str} to a character set.  If the
character set @var{base_cs} is given, the characters in this
set are also included in the result.

@code{string->char-set!} is the side-effecting variant.
@end deffn

@deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
@deffnx {Scheme Procedure} char-set-filter! pred cs base_cs
Return a character set containing every character from @var{cs}
so that it satisfies @var{pred}.  If provided, the characters
from @var{base_cs} are added to the result.

@code{char-set-filter!} is the side-effecting variant.
@end deffn

@deffn {Scheme Procedure} ucs-range->char-set lower upper [error? base_cs]
@deffnx {Scheme Procedure} uce-range->char-set! lower upper error? base_cs
Return a character set containing all characters whose
character codes lie in the half-open range
[@var{lower},@var{upper}).

If @var{error} is a true value, an error is signalled if the
specified range contains characters which are not contained in
the implemented character range.  If @var{error} is @code{#f},
these characters are silently left out of the resulting
character set.

The characters in @var{base_cs} are added to the result, if
given.

@code{ucs-range->char-set!} is the side-effecting variant.
@end deffn

@deffn {Scheme Procedure} ->char-set x
Coerce @var{x} into a character set.  @var{x} may be a string, a
character or a character set.
@end deffn


@c ===================================================================

@node SRFI-14 Querying Character Sets
@subsubsection Querying Character Sets

Access the elements and other information of a character set with these
procedures.

@deffn {Scheme Procedure} char-set-size cs
Return the number of elements in character set @var{cs}.
@end deffn

@deffn {Scheme Procedure} char-set-count pred cs
Return the number of the elements int the character set
@var{cs} which satisfy the predicate @var{pred}.
@end deffn

@deffn {Scheme Procedure} char-set->list cs
Return a list containing the elements of the character set
@var{cs}.
@end deffn

@deffn {Scheme Procedure} char-set->string cs
Return a string containing the elements of the character set
@var{cs}.  The order in which the characters are placed in the
string is not defined.
@end deffn

@deffn {Scheme Procedure} char-set-contains? cs char
Return @code{#t} iff the character @var{ch} is contained in the
character set @var{cs}.
@end deffn

@deffn {Scheme Procedure} char-set-every pred cs
Return a true value if every character in the character set
@var{cs} satisfies the predicate @var{pred}.
@end deffn

@deffn {Scheme Procedure} char-set-any pred cs
Return a true value if any character in the character set
@var{cs} satisfies the predicate @var{pred}.
@end deffn


@c ===================================================================

@node SRFI-14 Character-Set Algebra
@subsubsection Character-Set Algebra

Character sets can be manipulated with the common set algebra operation,
such as union, complement, intersection etc.  All of these procedures
provide side-effecting variants, which modify their character set
argument(s).

@deffn {Scheme Procedure} char-set-adjoin cs char1 @dots{}
@deffnx {Scheme Procedure} char-set-adjoin! cs char1 @dots{}
Add all character arguments to the first argument, which must
be a character set.
@end deffn

@deffn {Scheme Procedure} char-set-delete cs char1 @dots{}
@deffnx {Scheme Procedure} char-set-delete! cs char1 @dots{}
Delete all character arguments from the first argument, which
must be a character set.
@end deffn

@deffn {Scheme Procedure} char-set-complement cs
@deffnx {Scheme Procedure} char-set-complement! cs
Return the complement of the character set @var{cs}.
@end deffn

@deffn {Scheme Procedure} char-set-union cs1 @dots{}
@deffnx {Scheme Procedure} char-set-union! cs1 @dots{}
Return the union of all argument character sets.
@end deffn

@deffn {Scheme Procedure} char-set-intersection cs1 @dots{}
@deffnx {Scheme Procedure} char-set-intersection! cs1 @dots{}
Return the intersection of all argument character sets.
@end deffn

@deffn {Scheme Procedure} char-set-difference cs1 @dots{}
@deffnx {Scheme Procedure} char-set-difference! cs1 @dots{}
Return the difference of all argument character sets.
@end deffn

@deffn {Scheme Procedure} char-set-xor cs1 @dots{}
@deffnx {Scheme Procedure} char-set-xor! cs1 @dots{}
Return the exclusive-or of all argument character sets.
@end deffn

@deffn {Scheme Procedure} char-set-diff+intersection cs1 @dots{}
@deffnx {Scheme Procedure} char-set-diff+intersection! cs1 @dots{}
Return the difference and the intersection of all argument
character sets.
@end deffn


@c ===================================================================

@node SRFI-14 Standard Character Sets
@subsubsection Standard Character Sets

In order to make the use of the character set data type and procedures
useful, several predefined character set variables exist.

@defvar char-set:lower-case
All lower-case characters.
@end defvar

@defvar char-set:upper-case
All upper-case characters.
@end defvar

@defvar char-set:title-case
This is empty, because ASCII has no titlecase characters.
@end defvar

@defvar char-set:letter
All letters, e.g. the union of @code{char-set:lower-case} and
@code{char-set:upper-case}.
@end defvar

@defvar char-set:digit
All digits.
@end defvar

@defvar char-set:letter+digit
The union of @code{char-set:letter} and @code{char-set:digit}.
@end defvar

@defvar char-set:graphic
All characters which would put ink on the paper.
@end defvar

@defvar char-set:printing
The union of @code{char-set:graphic} and @code{char-set:whitespace}.
@end defvar

@defvar char-set:whitespace
All whitespace characters.
@end defvar

@defvar char-set:blank
All horizontal whitespace characters, that is @code{#\space} and
@code{#\tab}.
@end defvar

@defvar char-set:iso-control
The ISO control characters with the codes 0--31 and 127.
@end defvar

@defvar char-set:punctuation
The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
@end defvar

@defvar char-set:symbol
The characters @code{$+<=>^`|~}.
@end defvar

@defvar char-set:hex-digit
The hexadecimal digits @code{0123456789abcdefABCDEF}.
@end defvar

@defvar char-set:ascii
All ASCII characters.
@end defvar

@defvar char-set:empty
The empty character set.
@end defvar

@defvar char-set:full
This character set contains all possible characters.
@end defvar

@node SRFI-16
@subsection SRFI-16 - case-lambda
@cindex SRFI-16

@c FIXME::martin: Review me!

@findex case-lambda
The syntactic form @code{case-lambda} creates procedures, just like
@code{lambda}, but has syntactic extensions for writing procedures of
varying arity easier.

The syntax of the @code{case-lambda} form is defined in the following
EBNF grammar.

@example
@group
<case-lambda>
   --> (case-lambda <case-lambda-clause>)
<case-lambda-clause>
   --> (<formals> <definition-or-command>*)
<formals>
   --> (<identifier>*)
     | (<identifier>* . <identifier>)
     | <identifier>
@end group
@end example

The value returned by a @code{case-lambda} form is a procedure which
matches the number of actual arguments against the formals in the
various clauses, in order.  @dfn{Formals} means a formal argument list
just like with @code{lambda} (@pxref{Lambda}). The first matching clause
is selected, the corresponding values from the actual parameter list are
bound to the variable names in the clauses and the body of the clause is
evaluated.  If no clause matches, an error is signalled.

The following (silly) definition creates a procedure @var{foo} which
acts differently, depending on the number of actual arguments.  If one
argument is given, the constant @code{#t} is returned, two arguments are
added and if more arguments are passed, their product is calculated.

@lisp
(define foo (case-lambda
              ((x) #t)
              ((x y) (+ x y))
              (z
                (apply * z))))
(foo 'bar)
@result{}
#t
(foo 2 4)
@result{}
6
(foo 3 3 3)
@result{}
27
(foo)
@result{}
1
@end lisp

The last expression evaluates to 1 because the last clause is matched,
@var{z} is bound to the empty list and the following multiplication,
applied to zero arguments, yields 1.


@node SRFI-17
@subsection SRFI-17 - Generalized set!
@cindex SRFI-17

This is an implementation of SRFI-17: Generalized set!

@findex getter-with-setter
It exports the Guile procedure @code{make-procedure-with-setter} under
the SRFI name @code{getter-with-setter} and exports the standard
procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr},
@code{string-ref} and @code{vector-ref} as procedures with setters, as
required by the SRFI.

SRFI-17 was heavily criticized during its discussion period but it was
finalized anyway.  One issue was its concept of globally associating
setter @dfn{properties} with (procedure) values, which is non-Schemy.
For this reason, this implementation chooses not to provide a way to set
the setter of a procedure.  In fact, @code{(set!  (setter @var{proc})
@var{setter})} signals an error.  The only way to attach a setter to a
procedure is to create a new object (a @dfn{procedure with setter}) via
the @code{getter-with-setter} procedure. This procedure is also
specified in the SRFI.  Using it avoids the described problems.


@node SRFI-19
@subsection SRFI-19 - Time/Date Library
@cindex SRFI-19

This is an implementation of the SRFI-19 time/date library.  The
functions and variables described here are provided by

@example
(use-modules (srfi srfi-19))
@end example

@menu
* SRFI-19 Introduction::        
* SRFI-19 Time::                
* SRFI-19 Date::                
* SRFI-19 Time/Date conversions::  
* SRFI-19 Date to string::      
* SRFI-19 String to date::      
@end menu

@node SRFI-19 Introduction
@subsubsection SRFI-19 Introduction

@cindex universal time
@cindex atomic time
@cindex UTC
@cindex TAI
This module implements time and date representations and calculations,
in various time systems, including universal time (UTC) and atomic
time (TAI).

For those not familiar with these time systems, TAI is based on a
fixed length second derived from oscillations of certain atoms.  UTC
differs from TAI by an integral number of seconds, which is increased
or decreased at announced times to keep UTC aligned to a mean solar
day (the orbit and rotation of the earth are not quite constant).

@cindex leap second
So far, only increases in the TAI
@tex
$\leftrightarrow$
@end tex
@ifnottex
<->
@end ifnottex
UTC difference have been needed.  Such an increase is a ``leap
second'', an extra second of TAI introduced at the end of a UTC day.
When working entirely within UTC this is never seen, every day simply
has 86400 seconds.  But when converting from TAI to a UTC date, an
extra 23:59:60 is present, where normally a day would end at 23:59:59.
Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI
seconds.

@cindex system clock
In the current implementation, the system clock is assumed to be UTC,
and a table of leap seconds in the code converts to TAI.  See comments
in @file{srfi-19.scm} for how to update this table.

@cindex julian day
@cindex modified julian day
Also, for those not familiar with the terminology, a @dfn{Julian Day}
is a real number which is a count of days and fraction of a day, in
UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan
4713 B.C.  And a @dfn{Modified Julian Day} is the same, but starting
from 1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC.

@c  The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at
@c  noon, UTC), but this is incorrect.  It looks like it might have
@c  arisen from the code incorrectly treating years a multiple of 100
@c  but not 400 prior to 1582 as leap years, where instead the Julian
@c  calendar should be used so all multiples of 4 before 1582 are leap
@c  years.


@node SRFI-19 Time
@subsubsection SRFI-19 Time
@cindex time

A @dfn{time} object has type, seconds and nanoseconds fields
representing a point in time starting from some epoch.  This is an
arbitrary point in time, not just a time of day.  Although times are
represented in nanoseconds, the actual resolution may be lower.

The following variables hold the possible time types.  For instance
@code{(current-time time-process)} would give the current CPU process
time.

@defvar time-utc
Universal Coordinated Time (UTC).
@cindex UTC
@end defvar

@defvar time-tai
International Atomic Time (TAI).
@cindex TAI
@end defvar

@defvar time-monotonic
Monotonic time, meaning a monotonically increasing time starting from
an unspecified epoch.

Note that in the current implementation @code{time-monotonic} is the
same as @code{time-tai}, and unfortunately is therefore affected by
adjustments to the system clock.  Perhaps this will change in the
future.
@end defvar

@defvar time-duration
A duration, meaning simply a difference between two times.
@end defvar

@defvar time-process
CPU time spent in the current process, starting from when the process
began.
@cindex process time
@end defvar

@defvar time-thread
CPU time spent in the current thread.  Not currently implemented.
@cindex thread time
@end defvar

@sp 1
@defun time? obj
Return @code{#t} if @var{obj} is a time object, or @code{#f} if not.
@end defun

@defun make-time type nanoseconds seconds
Create a time object with the given @var{type}, @var{seconds} and
@var{nanoseconds}.
@end defun

@defun time-type time
@defunx time-nanosecond time
@defunx time-second time
@defunx set-time-type! time type
@defunx set-time-nanosecond! time nsec
@defunx set-time-second! time sec
Get or set the type, seconds or nanoseconds fields of a time object.

@code{set-time-type!} merely changes the field, it doesn't convert the
time value.  For conversions, see @ref{SRFI-19 Time/Date conversions}.
@end defun

@defun copy-time time
Return a new time object, which is a copy of the given @var{time}.
@end defun

@defun current-time [type]
Return the current time of the given @var{type}.  The default
@var{type} is @code{time-utc}.

Note that the name @code{current-time} conflicts with the Guile core
@code{current-time} function (@pxref{Time}).  Applications wanting to
use both will need to use a different name for one of them.
@end defun

@defun time-resolution [type]
Return the resolution, in nanoseconds, of the given time @var{type}.
The default @var{type} is @code{time-utc}.
@end defun

@defun time<=? t1 t2
@defunx time<? t1 t2
@defunx time=? t1 t2
@defunx time>=? t1 t2
@defunx time>? t1 t2
Return @code{#t} or @code{#f} according to the respective relation
between time objects @var{t1} and @var{t2}.  @var{t1} and @var{t2}
must be the same time type.
@end defun

@defun time-difference t1 t2
@defunx time-difference! t1 t2
Return a time object of type @code{time-duration} representing the
period between @var{t1} and @var{t2}.  @var{t1} and @var{t2} must be
the same time type.

@code{time-difference} returns a new time object,
@code{time-difference!} may modify @var{t1} to form its return.
@end defun

@defun add-duration time duration
@defunx add-duration! time duration
@defunx subtract-duration time duration
@defunx subtract-duration! time duration
Return a time object which is @var{time} with the given @var{duration}
added or subtracted.  @var{duration} must be a time object of type
@code{time-duration}.

@code{add-duration} and @code{subtract-duration} return a new time
object.  @code{add-duration!} and @code{subtract-duration!} may modify
the given @var{time} to form their return.
@end defun


@node SRFI-19 Date
@subsubsection SRFI-19 Date
@cindex date

A @dfn{date} object represents a date in the Gregorian calendar and a
time of day on that date in some timezone.

The fields are year, month, day, hour, minute, second, nanoseconds and
timezone.  A date object is immutable, its fields can be read but they
cannot be modified once the object is created.

@defun date? obj
Return @code{#t} if @var{obj} is a date object, or @code{#f} if not.
@end defun

@defun make-date nsecs seconds minutes hours date month year zone-offset
Create a new date object.
@c
@c  FIXME: What can we say about the ranges of the values.  The
@c  current code looks it doesn't normalize, but expects then in their
@c  usual range already.
@c
@end defun

@defun date-nanosecond date
Nanoseconds, 0 to 999999999.
@end defun

@defun date-second date
Seconds, 0 to 60.  0 to 59 is the usual range, 60 is for a leap second.
@end defun

@defun date-minute date
Minutes, 0 to 59.
@end defun

@defun date-hour date
Hour, 0 to 23.
@end defun

@defun date-day date
Day of the month, 1 to 31 (or less, according to the month).
@end defun

@defun date-month date
Month, 1 to 12.
@end defun

@defun date-year date
Year, eg.@: 2003.
@end defun

@defun date-zone-offset date
Time zone, an integer number of seconds east of Greenwich.
@end defun

@defun date-year-day date
Day of the year, starting from 1 for 1st January.
@end defun

@defun date-week-day date
Day of the week, starting from 0 for Sunday.
@end defun

@defun date-week-number date dstartw
Week of the year, ignoring a first partial week.  @var{dstartw} is the
day of the week which is taken to start a week, 0 for Sunday, 1 for
Monday, etc.
@c
@c  FIXME: The spec doesn't say whether numbering starts at 0 or 1.
@c  The code looks like it's 0, if that's the correct intention.
@c
@end defun

@c  The SRFI text doesn't actually give the default for tz-offset, but
@c  the reference implementation has the local timezone and the
@c  conversions functions all specify that, so it should be ok to
@c  document it here.
@c
@defun current-date [tz-offset]
Return a date object representing the current date/time UTC.
@var{tz-offset} is seconds east of Greenwich, and defaults to the
local timezone.
@end defun

@defun current-julian-day
@cindex julian day
Return the current Julian Day.
@end defun

@defun current-modified-julian-day
@cindex modified julian day
Return the current Modified Julian Day.
@end defun


@node SRFI-19 Time/Date conversions
@subsubsection SRFI-19 Time/Date conversions

@defun date->julian-day date
@defunx date->modified-julian-day date
@defunx date->time-monotonic date
@defunx date->time-tai date
@defunx date->time-utc date
@end defun
@defun julian-day->date jdn [tz-offset]
@defunx julian-day->time-monotonic jdn
@defunx julian-day->time-tai jdn
@defunx julian-day->time-utc jdn
@end defun
@defun modified-julian-day->date jdn [tz-offset]
@defunx modified-julian-day->time-monotonic jdn
@defunx modified-julian-day->time-tai jdn
@defunx modified-julian-day->time-utc jdn
@end defun
@defun time-monotonic->date time [tz-offset]
@defunx time-monotonic->time-tai time
@defunx time-monotonic->time-tai! time
@defunx time-monotonic->time-utc time
@defunx time-monotonic->time-utc! time
@end defun
@defun time-tai->date time [tz-offset]
@defunx time-tai->julian-day time
@defunx time-tai->modified-julian-day time
@defunx time-tai->time-monotonic time
@defunx time-tai->time-monotonic! time
@defunx time-tai->time-utc time
@defunx time-tai->time-utc! time
@end defun
@defun time-utc->date time [tz-offset]
@defunx time-utc->julian-day time
@defunx time-utc->modified-julian-day time
@defunx time-utc->time-monotonic time
@defunx time-utc->time-monotonic! time
@defunx time-utc->time-tai time
@defunx time-utc->time-tai! time
@sp 1
Convert between dates, times and days of the respective types.  For
instance @code{time-tai->time-utc} accepts a @var{time} object of type
@code{time-tai} and returns an object of type @code{time-utc}.

For conversions to dates, @var{tz-offset} is seconds east of
Greenwich.  The default is the local timezone.

The @code{!} variants may modify their @var{time} argument to form
their return.  The plain functions create a new object.
@end defun

@node SRFI-19 Date to string
@subsubsection SRFI-19 Date to string
@cindex date to string

@defun date->string date [format]
Convert a date to a string under the control of a format.
@var{format} should be a string containing @samp{~} escapes, which
will be expanded as per the following conversion table.  The default
@var{format} is @samp{~c}, a locale-dependent date and time.

Many of these conversion characters are the same as POSIX
@code{strftime} (@pxref{Time}), but there are some extras and some
variations.

@multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM}
@item @nicode{~~} @tab literal ~
@item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun}
@item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday}
@item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan}
@item @nicode{~B} @tab locale full month, eg.@: @samp{January}
@item @nicode{~c} @tab locale date and time, eg.@: @*
@samp{Fri Jul 14 20:28:42-0400 2000}
@item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31}

@c  Spec says d/m/y, reference implementation says m/d/y.
@c  Apparently the reference code was the intention, but would like to
@c  see an errata published for the spec before contradicting it here.
@c
@c  @item @nicode{~D} @tab date @nicode{~d/~m/~y}

@item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31}
@item @nicode{~f} @tab seconds and fractional seconds,
with locale decimal point, eg.@: @samp{5.2}
@item @nicode{~h} @tab same as @nicode{~b}
@item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23}
@item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12}
@item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366}
@item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23}
@item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12}
@item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12}
@item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59}
@item @nicode{~n} @tab newline
@item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999}
@item @nicode{~p} @tab locale AM or PM
@item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p}
@item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC
@item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @*
(usual limit is 59, 60 is a leap second)
@item @nicode{~t} @tab horizontal tab character
@item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S}
@item @nicode{~U} @tab week of year, Sunday first day of week,
@samp{00} to @samp{52}
@item @nicode{~V} @tab week of year, Monday first day of week,
@samp{01} to @samp{53}
@item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6}
@item @nicode{~W} @tab week of year, Monday first day of week,
@samp{00} to @samp{52}

@c  The spec has ~x as an apparent duplicate of ~W, and ~X as a locale
@c  date.  The reference code has ~x as the locale date and ~X as a
@c  locale time.  The rule is apparently that the code should be
@c  believed, but would like to see an errata for the spec before
@c  contradicting it here.
@c
@c  @item @nicode{~x} @tab week of year, Monday as first day of week,
@c  @samp{00} to @samp{53}
@c  @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00}

@item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99}
@item @nicode{~Y} @tab year, full, eg.@: @samp{2003}
@item @nicode{~z} @tab time zone, RFC-822 style
@item @nicode{~Z} @tab time zone symbol (not currently implemented)
@item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d}
@item @nicode{~2} @tab ISO-8601 time+zone, @samp{~k:~M:~S~z}
@item @nicode{~3} @tab ISO-8601 time, @samp{~k:~M:~S}
@item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~k:~M:~S~z}
@item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~k:~M:~S}
@end multitable
@end defun

Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently
described here, since the specification and reference implementation
differ.

Currently Guile doesn't implement any localizations for the above, all
outputs are in English, and the @samp{~c} conversion is POSIX
@code{ctime} style @samp{~a ~b ~d ~H:~M:~S~z ~Y}.  This may change in
the future.


@node SRFI-19 String to date
@subsubsection SRFI-19 String to date
@cindex string to date

@c  FIXME: Can we say what happens when an incomplete date is
@c  converted?  Ie. fields left as 0, or what?  The spec seems to be
@c  silent on this.

@defun string->date input template
Convert an @var{input} string to a date under the control of a
@var{template} string.  Return a newly created date object.

Literal characters in @var{template} must match characters in
@var{input} and @samp{~} escapes must match the input forms described
in the table below.  ``Skip to'' means characters up to one of the
given type are ignored, or ``no skip'' for no skipping.  ``Read'' is
what's then read, and ``Set'' is the field affected in the date
object.

For example @samp{~Y} skips input characters until a digit is reached,
at which point it expects a year and stores that to the year field of
the date.

@multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}}
@item
@tab Skip to
@tab Read
@tab Set

@item @nicode{~~}
@tab no skip
@tab literal ~
@tab nothing

@item @nicode{~a}
@tab @nicode{char-alphabetic?}
@tab locale abbreviated weekday name
@tab nothing

@item @nicode{~A}
@tab @nicode{char-alphabetic?}
@tab locale full weekday name
@tab nothing

@c  Note that the SRFI spec says that ~b and ~B don't set anything,
@c  but that looks like a mistake.  The reference implementation sets
@c  the month field, which seems sensible and is what we describe
@c  here.

@item @nicode{~b}
@tab @nicode{char-alphabetic?}
@tab locale abbreviated month name
@tab @nicode{date-month}

@item @nicode{~B}
@tab @nicode{char-alphabetic?}
@tab locale full month name
@tab @nicode{date-month}

@item @nicode{~d}
@tab @nicode{char-numeric?}
@tab day of month
@tab @nicode{date-day}

@item @nicode{~e}
@tab no skip
@tab day of month, blank padded
@tab @nicode{date-day}

@item @nicode{~h}
@tab same as @samp{~b}

@item @nicode{~H}
@tab @nicode{char-numeric?}
@tab hour
@tab @nicode{date-hour}

@item @nicode{~k}
@tab no skip
@tab hour, blank padded
@tab @nicode{date-hour}

@item @nicode{~m}
@tab @nicode{char-numeric?}
@tab month
@tab @nicode{date-month}

@item @nicode{~M}
@tab @nicode{char-numeric?}
@tab minute
@tab @nicode{date-minute}

@item @nicode{~S}
@tab @nicode{char-numeric?}
@tab second
@tab @nicode{date-second}

@item @nicode{~y}
@tab no skip
@tab 2-digit year
@tab @nicode{date-year} within 50 years

@item @nicode{~Y}
@tab @nicode{char-numeric?}
@tab year
@tab @nicode{date-year}

@item @nicode{~z}
@tab no skip
@tab time zone
@tab date-zone-offset
@end multitable

Notice that the weekday matching forms don't affect the date object
returned, instead the weekday will be derived from the day, month and
year.

Currently Guile doesn't implement any localizations for the above,
month and weekday names are always expected in English.  This may
change in the future.
@end defun


@node SRFI-26
@subsection SRFI-26 - specializing parameters
@cindex SRFI-26

This SRFI provides a syntax for conveniently specializing selected
parameters of a function.  It can be used with,

@example
(use-modules (srfi srfi-26))
@end example

@deffn {library syntax} cut slot @dots{}
@deffnx {library syntax} cute slot @dots{}
Return a new procedure which will make a call (@var{slot} @dots{}) but
with selected parameters specialized to given expressions.

An example will illustrate the idea.  The following is a
specialization of @code{write}, sending output to
@code{my-output-port},

@example
(cut write <> my-output-port)
@result{}
(lambda (obj) (write obj my-output-port))
@end example

The special symbol @code{<>} indicates a slot to be filled by an
argument to the new procedure.  @code{my-output-port} on the other
hand is an expression to be evaluated and passed, ie.@: it specializes
the behaviour of @code{write}.

@table @nicode
@item <>
A slot to be filled by an argument from the created procedure.
Arguments are assigned to @code{<>} slots in the order they appear in
the @code{cut} form, there's no way to re-arrange arguments.

The first argument to @code{cut} is usually a procedure (or expression
giving a procedure), but @code{<>} is allowed there too.  For example,

@example
(cut <> 1 2 3)
@result{}
(lambda (proc) (proc 1 2 3))
@end example

@item <...>
A slot to be filled by all remaining arguments from the new procedure.
This can only occur at the end of a @code{cut} form.

For example, a procedure taking a variable number of arguments like
@code{max} but in addition enforcing a lower bound,

@example
(define my-lower-bound 123)

(cut max my-lower-bound <...>)
@result{}
(lambda arglist (apply max my-lower-bound arglist))
@end example
@end table

For @code{cut} the specializing expressions are evaluated each time
the new procedure is called.  For @code{cute} they're evaluated just
once, when the new procedure is created.  The name @code{cute} stands
for ``@code{cut} with evaluated arguments''.  In all cases the
evaluations take place in an unspecified order.

The following illustrates the difference between @code{cut} and
@code{cute},

@example
(cut format <> "the time is ~s" (current-time))
@result{}
(lambda (port) (format port "the time is ~s" (current-time)))

(cute format <> "the time is ~s" (current-time))
@result{}
(let ((val (current-time)))
  (lambda (port) (format port "the time is ~s" val))
@end example

(There's no provision for a mixture of @code{cut} and @code{cute}
where some expressions would be evaluated every time but others
evaluated only once.)

@code{cut} is really just a shorthand for the sort of @code{lambda}
forms shown in the above examples.  But notice @code{cut} avoids the
need to name unspecialized parameters, and is more compact.  Use in
functional programming style or just with @code{map}, @code{for-each}
or similar is typical.

@example
(map (cut * 2 <>) '(1 2 3 4))         

(for-each (cut write <> my-port) my-list)  
@end example
@end deffn

@node SRFI-31
@subsection SRFI-31 - A special form `rec' for recursive evaluation
@cindex SRFI-31
@findex rec

SRFI-31 defines a special form that can be used to create
self-referential expressions more conveniently.  The syntax is as
follows:

@example
@group
<rec expression> --> (rec <variable> <expression>)
<rec expression> --> (rec (<variable>+) <body>)
@end group
@end example

The first syntax can be used to create self-referential expressions,
for example:

@lisp
  guile> (define tmp (rec ones (cons 1 (delay ones))))
@end lisp

The second syntax can be used to create anonymous recursive functions:

@lisp
  guile> (define tmp (rec (display-n item n)
                       (if (positive? n)
                           (begin (display n) (display-n (- n 1))))))
  guile> (tmp 42 3)
  424242
  guile>
@end lisp

@c srfi-modules.texi ends here

@c Local Variables:
@c TeX-master: "guile.texi"
@c End: