+@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
@chapter 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
* SRFI-16:: case-lambda
* SRFI-17:: Generalized set!
* SRFI-19:: Time/Date library.
+* SRFI-26:: Specializing parameters
@end menu
@node SRFI-0
@section SRFI-0 - cond-expand
+@cindex SRFI-0
+@findex cond-expand
@c FIXME::martin: Review me!
Since @code{cond-expand} is needed to tell what a Scheme implementation
provides, it must be accessible without using any
-implementation-dependant operations, such as @code{use-modules} in
+implementation-dependent operations, such as @code{use-modules} in
Guile. Thus, it is not necessary to use any module to get access to
this form.
@node SRFI-1
@section SRFI-1 - List library
+@cindex SRFI-1
@c FIXME::martin: Review me!
* 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 elments.
+* 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.
New lists can be constructed by calling one of the following
procedures.
-@deffn procedure xcons d a
+@deffn {Scheme Procedure} xcons d a
Like @code{cons}, but with interchanged arguments. Useful mostly when
passed to higher-order procedures.
@end deffn
-@deffn procedure list-tabulate n init-proc
+@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 procedure circular-list elt1 elt2 @dots{}
+@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 procedure iota count [start step]
-Return a list containing @var{count} elements, where each element is
-calculated as follows:
+@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,
-@var{start} + (@var{count} - 1) * @var{step}
+@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
-@var{start} defaults to 0 and @var{step} defaults to 1.
+This function takes its name from the corresponding primitive in the
+APL language.
@end deffn
The procedures in this section test specific properties of lists.
-@deffn procedure proper-list? obj
+@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 procedure circular-list? obj
+@deffn {Scheme Procedure} circular-list? obj
Return @code{#t} if @var{obj} is a circular list, otherwise return
@code{#f}.
@end deffn
-@deffn procedure dotted-list? obj
+@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 procedure null-list? lst
+@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 recommented
+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 procedure not-pair? obj
+@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 procedure list= elt= list1 @dots{}
+@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
@c FIXME::martin: Review me!
-@deffn procedure first pair
-@deffnx procedure second pair
-@deffnx procedure third pair
-@deffnx procedure fourth pair
-@deffnx procedure fifth pair
-@deffnx procedure sixth pair
-@deffnx procedure seventh pair
-@deffnx procedure eighth pair
-@deffnx procedure ninth pair
-@deffnx procedure tenth pair
+@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 procedure car+cdr pair
+@deffn {Scheme Procedure} car+cdr pair
Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
@end deffn
-@deffn procedure take lst i
-@deffnx procedure take! lst i
+@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 procedure drop lst i
+@deffn {Scheme Procedure} drop lst i
Return a list containing all but the first @var{i} elements of
@var{lst}.
@end deffn
-@deffn procedure take-right lst i
+@deffn {Scheme Procedure} take-right lst i
Return the a list containing the @var{i} last elements of @var{lst}.
@end deffn
-@deffn procedure drop-right lst i
-@deffnx procedure drop-right! lst i
+@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}.
@var{lst} in order to produce the result.
@end deffn
-@deffn procedure split-at lst i
-@deffnx procedure split-at! lst i
+@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.
@var{lst} in order to produce the result.
@end deffn
-@deffn procedure last lst
+@deffn {Scheme Procedure} last lst
Return the last element of the non-empty, finite list @var{lst}.
@end deffn
@c FIXME::martin: Review me!
-@deffn procedure length+ lst
+@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 procedure concatenate list-of-lists
-@deffnx procedure concatenate! list-of-lists
+@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 procedure append-reverse rev-head tail
-@deffnx procedure append-reverse! rev-head tail
+@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.
the result.
@end deffn
-@deffn procedure zip lst1 lst2 @dots{}
+@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 procedure unzip1 lst
-@deffnx procedure unzip2 lst
-@deffnx procedure unzip3 lst
-@deffnx procedure unzip4 lst
-@deffnx procedure unzip5 lst
+@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
@subsection Fold, Unfold & Map
@c FIXME::martin: Review me!
-@deffn procedure fold kons knil lst1 lst2 @dots{}
+@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
@dots{}.
@end deffn
-@deffn procedure fold-right kons knil lst1 lst2 @dots{}
+@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:
@var{e22} @dots{} (@var{kons} @var{en1} @var{en2} @var{knil})))},
@end deffn
-@deffn procedure pair-fold kons knil lst1 lst2 @dots{}
+@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 procedure pair-fold-right kons knil lst1 lst2 @dots{}
+@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 procedure reduce f ridentity lst
-@code{reduce} is a variant of @code{reduce}. If @var{lst} is
-@code{()}, @var{ridentity} is returned. Otherwise, @code{(fold (car
+@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 procedure reduce-right f ridentity lst
-This is the @code{fold-right} variant of @var{reduce}.
+@deffn {Scheme Procedure} reduce-right f ridentity lst
+This is the @code{fold-right} variant of @code{reduce}.
@end deffn
-@deffn procedure unfold p f g seed [tail-gen]
+@deffn {Scheme Procedure} unfold p f g seed [tail-gen]
@code{unfold} is defined as follows:
@lisp
left-to-right order, and @var{p} tells when to stop unfolding.
@end deffn
-@deffn procedure unfold-right p f g seed [tail]
+@deffn {Scheme Procedure} unfold-right p f g seed [tail]
Construct a list with the following loop.
@lisp
@end deffn
-@deffn procedure map f lst1 lst2 @dots{}
+@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
will be applied to the list element(s) is not specified.
@end deffn
-@deffn procedure for-each f lst1 lst2 @dots{}
+@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 tge list elements in left-to-right order.
+be applied to the list elements in left-to-right order.
@end deffn
-@deffn procedure append-map f lst1 lst2 @dots{}
-@deffnx procedure append-map! f lst1 lst2 @dots{}
+@deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
+@deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
Equivalent to
@lisp
made is not specified.
@end deffn
-@deffn procedure map! f lst1 lst2 @dots{}
+@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.
@dots{} must have at least as many elements as @var{lst1}.
@end deffn
-@deffn procedure pair-for-each f lst1 lst2 @dots{}
+@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 procedure filter-map f lst1 lst2 @dots{}
+@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
list elements, one which contains the elements satisfying a condition,
and the other for the elements which don't.
-@deffn procedure filter pred lst
-@deffnx procedure filter! pred lst
-Return a list containing all elements from @var{lst} which 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.
+The @code{filter} and @code{filter!} functions are implemented in the
+Guile core, @xref{List Modification}.
-@code{filter!} is allowed, but not required to modify the structure of
-@end deffn
+@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}.
-@deffn procedure partition pred lst
-@deffnx procedure partition! pred lst
-Return two lists, one containing all elements from @var{lst} which
-satisfy the predicate @var{pred}, and one list containing the elements
-which do not satisfy the predicated. The elements in the result lists
-have the same order as in @var{lst}. The order in which @var{pred} is
-applied to the list elements is not specified.
+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.
-@code{partition!} is allowed, but not required to modify the structure of
-the input list.
+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 procedure remove pred lst
-@deffnx procedure remove! pred lst
+@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
predicate or a comparison object for determining which elements are to
be searched.
-@deffn procedure find pred lst
+@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 procedure find-tail pred lst
+@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 procedure take-while pred lst
-@deffnx procedure take-while! pred lst
+@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}.
list while producing the result.
@end deffn
-@deffn procedure drop-while pred lst
+@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 procedure span pred lst
-@deffnx procedure span! pred lst
-@deffnx procedure break pred lst
-@deffnx procedure break! pred lst
+@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 procedure any pred lst1 lst2 @dots{}
+@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 succesful application of @var{pred}.
+the first successful application of @var{pred}.
@end deffn
-@deffn procedure every pred lst1 lst2 @dots{}
+@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 succesful application of @var{pred}.
+the final successful application of @var{pred}.
@end deffn
-@deffn procedure list-index pred lst1 lst2 @dots{}
+@deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{}
Return the index of the leftmost element that satisfies @var{pred}.
@end deffn
-@deffn procedure member x lst [=]
+@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
@c FIXME::martin: Review me!
-The procedures for deleting elements from a list either accept a
-predicate or a comparison object for determining which elements are to
-be removed.
+@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.
-@deffn procedure delete x lst [=]
-@deffnx procedure delete! x lst [=]
-Return a list containing all elements from @var{lst}, but without the
-elements equal to @var{x}. Equality is determined by the equality
-predicate @var{=}, which defaults to @code{equal?} if not given.
+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!} is allowed, but not required to modify the structure of
-the argument list in order to produce the result.
+@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 procedure delete-duplicates lst [=]
-@deffnx procedure delete-duplicates! lst [=]
-Return a list containing all elements from @var{lst}, but without
-duplicate elements. Equality of elements is determined by the
-equality predicate @var{=}, which defaults to @code{equal?} if not
-given.
+@deffn {Scheme Procedure} delete-duplicates lst [=]
+@deffnx {Scheme Procedure} delete-duplicates! lst [=]
+Return a list containing the elements of @var{lst} but without
+duplicates.
-@code{delete-duplicates!} is allowed, but not required to modify the
-structure of the argument list in order to produce the result.
+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
Lists}. The present section only documents the additional procedures
for dealing with association lists defined by SRFI-1.
-@deffn procedure assoc key alist [=]
+@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 procedure alist-cons key datum alist
+@deffn {Scheme Procedure} alist-cons key datum alist
Equivalent to
@lisp
association list.
@end deffn
-@deffn procedure alist-copy alist
+@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 procedure alist-delete key alist [=]
-@deffnx procedure alist-delete! key alist [=]
-Return a list containing the pairs of @var{alist}, but without the
-pairs whose @sc{cars} are equal to @var{key}. Equality is determined
-by @var{=}, which defaults to @code{equal?} if not given.
+@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}.
-@code{alist-delete!} is allowed, but not required to modify the
-structure of the list @var{alist} in order to produce the result.
+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
Lists can be used for representing sets of objects. The procedures
documented in this section can be used for such set representations.
-Man combinding several sets or adding elements, they make sure that no
+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
argument. This predicate is used for testing the objects in the list
sets for sameness.
-@deffn procedure lset<= = list1 @dots{}
+@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 procedure lset= = list1 list2 @dots{}
+@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 procedure lset-adjoin = list elt1 @dots{}
-@deffnx procedure lset-adjoin! = list elt1 @dots{}
+@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 procedure lset-union = list1 @dots{}
-@deffnx procedure lset-union! = list1 @dots{}
+@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 procedure lset-intersection = list1 list2 @dots{}
-@deffnx procedure lset-intersection! = list1 list2 @dots{}
+@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 procedure lset-difference = list1 list2 @dots{}
-@deffnx procedure lset-difference! = list1 list2 @dots{}
+@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
element equality.
@end deffn
-@deffn procedure lset-xor = list1 @dots{}
-@deffnx procedure lset-xor! = list1 @dots{}
+@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
element equality.
@end deffn
-@deffn procedure lset-diff+intersection = list1 list2 @dots{}
-@deffnx procedure lset-diff+intersection! = list1 list2 @dots{}
+@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.
@node SRFI-2
@section SRFI-2 - and-let*
+@cindex SRFI-2
-@c FIXME::martin: Review me!
-
-The syntactic form @code{and-let*} combines the conditional evaluation
-form @code{and} with the binding form @var{let*}. Each argument
-expression will be evaluated sequentially, bound to a variable (if a
-variable name is given), but only as long as no expression returns
-the false value @code{#f}.
-
-Use @code{(use-modules (srfi srfi-2)} to access this syntax form.
-
-A short example will demonstrate how it works. In the first expression,
-@var{x} will get bound to 1, but the next expression (@code{#f}) is
-false, so evaluation of the form is stopped, and @code{#f} is returned.
-In the next expression, @var{x} is bound to 1, @var{y} is bound to
-@code{#t} and since no expression in the binding section was false, the
-body of the @code{and-let*} expression is evaluated, which in this case
-returns the value of @var{x}.
+@noindent
+The following syntax can be obtained with
@lisp
-(and-let* ((x 1) (y #f)) 42)
-@result{}
-#f
-(and-let* ((x 1) (y #t)) x)
-@result{}
-1
+(use-modules (srfi srfi-2))
@end lisp
+@deffn {library syntax} and-let* (clause @dots{}) body @dots{}
+A combination of @code{and} and @code{let*}.
-@node SRFI-4
-@section SRFI-4 - Homogeneous numeric vector datatypes.
+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,
-@c FIXME::martin: Review me!
+@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
-SRFI-4 defines a set of datatypes for vectors whose elements are all
-of the same numeric type. Vectors for signed and unsigned exact
-integer or inexact real numbers in several precisions are available.
+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.
-Procedures similar to the vector procedures (@pxref{Vectors}) are
-provided for handling these homogeneous vectors, but they are distinct
-datatypes.
+@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 reason for providing this set of datatypes is that with the
-limitation (all elements must have the same type), it is possible to
-implement them much more memory-efficient than normal, heterogenous
-vectors.
+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}).
-If you want to use these datatypes and the corresponding procedures,
-you have to use the module @code{(srfi srfi-4)}.
+@example
+(define (extract-brackets str)
+ (and-let* ((start (string-index str #\[))
+ (end (string-index str #\] start)))
+ (substring str (1+ start) end)))
+@end example
-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. In the following descriptions, the tags @code{u8}, @code{s8},
-@code{u16}, @code{s16}, @code{u32}, @code{s32}, @code{u64},
-@code{s64}, @code{f32}, @code{f64}, respectively, are used for
-denoting the various types.
+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.
-@menu
-* SRFI-4 - Read Syntax:: How to write homogeneous vector literals.
-* SRFI-4 - Procedures:: Available homogeneous vector procedures.
-@end menu
+@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{=>}.
-@node SRFI-4 - Read Syntax
-@subsection SRFI-4 - Read Syntax
+@end deffn
-Homogeneous numeric vectors have an external representation (read
-syntax) similar to normal Scheme vectors, but with an additional tag
-telling the vector's type.
-@lisp
-#u16(1 2 3)
-@end lisp
-
-denotes a homogeneous numeric vector of three elements, which are the
-values 1, 2 and 3, represented as 16-bit unsigned integers.
-Correspondingly,
+@node SRFI-4
+@section SRFI-4 - Homogeneous numeric vector datatypes
+@cindex SRFI-4
-@lisp
-#f64(3.1415 2.71)
-@end lisp
+@c FIXME::martin: Review me!
-denotes a vector of two elements, which are the values 3.1415 and
-2.71, represented as floating-point values of 64 bit precision.
+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.
-Please note that the read syntax for floating-point vectors conflicts
-with Standard Scheme, because there @code{#f} is defined to be the
-literal false value. That means, that with the loaded SRFI-4 module,
-it is not possible to enter some list like
+The functions and the read syntax in this section are made available
+with
@lisp
-'(1 #f3)
+(use-modules (srfi srfi-4))
@end lisp
-and hope that it will be parsed as a three-element list with the
-elements 1, @code{#f} and 3. In normal use, this should be no
-problem, because people tend to terminate tokens sensibly when writing
-Scheme expressions.
-
-@node SRFI-4 - Procedures
-@subsection SRFI-4 Procedures
-
-The procedures listed in this section are provided for all homogeneous
-numeric vector datatypes. For brevity, they are not all documented,
-but a summary of the procedures is given. In the following
-descriptions, you can replace @code{TAG} by any of the datatype
-indicators @code{u8}, @code{s8}, @code{u16}, @code{s16}, @code{u32},
-@code{s32}, @code{u64}, @code{s64}, @code{f32} and @code{f64}.
-
-For example, you can use the procedures @code{u8vector?},
-@code{make-s8vector}, @code{u16vector}, @code{u32vector-length},
-@code{s64vector-ref}, @code{f32vector-set!} or @code{f64vector->list}.
-
-@deffn primitive TAGvector? obj
-Return @code{#t} if @var{obj} is a homogeneous numeric vector of type
-@code{TAG}.
-@end deffn
-
-@deffn primitive make-TAGvector n [value]
-Create a newly allocated homogeneous numeric vector of type
-@code{TAG}, which can hold @var{n} elements. If @var{value} is given,
-the vector is initialized with the value, otherwise, the contents of
-the returned vector is not specified.
-@end deffn
-
-@deffn primitive TAGvector value1 @dots{}
-Create a newly allocated homogeneous numeric vector of type
-@code{TAG}. The returned vector is as long as the number of arguments
-given, and is initialized with the argument values.
-@end deffn
-
-@deffn primitive TAGvector-length TAGvec
-Return the number of elements in @var{TAGvec}.
-@end deffn
+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.
-@deffn primitive TAGvector-ref TAGvec i
-Return the element at index @var{i} in @var{TAGvec}.
-@end deffn
+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}.
-@deffn primitive TAGvector-ref TAGvec i value
-Set the element at index @var{i} in @var{TAGvec} to @var{value}. The
-return value is not specified.
-@end deffn
+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,
-@deffn primitive TAGvector->list TAGvec
-Return a newly allocated list holding all elements of @var{TAGvec}.
-@end deffn
+@lisp
+#u16(1 2 3)
+#f64(3.1415 2.71)
+@end lisp
-@deffn primitive list->TAGvector lst
-Return a newly allocated homogeneous numeric vector of type @code{TAG},
+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
@section 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
@node SRFI-8
@section 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
@section 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,
-This is the SRFI way for defining record types. The Guile
-implementation is a layer above Guile's normal record construction
-procedures (@pxref{Records}). The nice thing about this kind of record
-definition method is that no new names are implicitly created, all
-constructor, accessor and predicates are explicitly given. This reduces
-the risk of variable capture.
+@example
+(use-modules (srfi srfi-9))
+@end example
-The syntax of a record type definition is:
+@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
-@group
-<record type definition>
- -> (define-record-type <type name>
- (<constructor name> <field tag> ...)
- <predicate name>
- <field spec> ...)
-<field spec> -> (<field tag> <accessor name>)
- -> (<field tag> <accessor name> <modifier name>)
-<field tag> -> <identifier>
-<... name> -> <identifier>
-@end group
+(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
-Usage 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
-guile> (use-modules (srfi srfi-9))
-guile> (define-record-type :foo (make-foo x) foo?
- (x get-x) (y get-y set-y!))
-guile> (define f (make-foo 1))
-guile> f
-#<:foo x: 1 y: #f>
-guile> (get-x f)
-1
-guile> (set-y! f 2)
-2
-guile> (get-y f)
-2
-guile> f
-#<:foo x: 1 y: 2>
-guile> (foo? f)
-#t
-guile> (foo? 1)
-#f
+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
@section SRFI-10 - Hash-Comma Reader Extension
+@cindex SRFI-10
@cindex hash-comma
@cindex #,()
@end example
where @var{ctor} must be a symbol for which a read constructor was
-defined previouly, using @code{define-reader-ctor}.
+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)
Please note the quote before the @code{#,(file ...)} expression. This
is necessary because ports are not self-evaluating in Guile.
-@deffn procedure define-reader-ctor symbol proc
+@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
@node SRFI-11
@section 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
@node SRFI-13
@section 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)}.
* 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:: Modfify strings in-place.
+* 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.
which are already in the Guile core, the string predicates
@code{string-any} and @code{string-every} are defined by SRFI-13.
-@deffn primitive string-any pred s [start end]
+@deffn {Scheme Procedure} string-any pred s [start end]
Check if the predicate @var{pred} is true for any character in
the string @var{s}, proceeding from left (index @var{start}) to
right (index @var{end}). If @code{string-any} returns true,
successful application of @var{pred}.
@end deffn
-@deffn primitive string-every pred s [start end]
+@deffn {Scheme Procedure} string-every pred s [start end]
Check if the predicate @var{pred} is true for every character
in the string @var{s}, proceeding from left (index @var{start})
to right (index @var{end}). If @code{string-every} returns
addition to @code{make-string} and @code{string} (available in the Guile
core library), the procedure @code{string-tabulate} does exist.
-@deffn primitive string-tabulate proc len
+@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
converting a list of characters into a string (@pxref{List/String
Conversion}).
-@deffn primitive string->list str [start end]
+@deffn {Scheme Procedure} string->list str [start end]
Convert the string @var{str} into a list of characters.
@end deffn
-@deffn primitive reverse-list->string chrs
+@deffn {Scheme Procedure} reverse-list->string chrs
An efficient implementation of @code{(compose string->list
reverse)}:
@end smalllisp
@end deffn
-@deffn primitive string-join ls [delimiter grammar]
+@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
@code{string-copy} is also available in core Guile, but this version
accepts additional start/end indices.
-@deffn primitive string-copy str [start end]
+@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 primitive substring/shared str start [end]
+@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 primitive string-copy! target tstart s [start end]
+@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
string.
@end deffn
-@deffn primitive string-take s n
-@deffnx primitive string-take-right s n
+@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 primitive string-drop s n
-@deffnx primitive string-drop-right s n
+@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 primitive string-pad s len [chr start end]
-@deffnx primitive string-pad-right s len [chr start end]
+@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 primitive string-trim s [char_pred start end]
-@deffnx primitive string-trim-right s [char_pred start end]
-@deffnx primitive string-trim-both s [char_pred start end]
+@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}:
@code{string-set!} is documented in the Strings section (@pxref{String
Modification}).
-@deffn primitive string-fill! str chr [start end]
+@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
@code{string-hash} and @code{string-hash-ci} are for calculating hash
values for strings, useful for implementing fast lookup mechanisms.
-@deffn primitive string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
-@deffnx primitive string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
+@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
character comparison is done case-insensitively.
@end deffn
-@deffn primitive string= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string<> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string< s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string<= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string>= s1 s2 [start1 end1 start2 end2]
+@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 primitive string-ci= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci<> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci< s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci<= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci>= s1 s2 [start1 end1 start2 end2]
+@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 primitive string-hash s [bound start end]
-@deffnx primitive string-hash-ci s [bound start end]
+@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
prefix or suffix of another string or how long a common prefix/suffix
is.
-@deffn primitive string-prefix-length s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-prefix-length-ci s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix-length s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix-length-ci s1 s2 [start1 end1 start2 end2]
+@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 primitive string-prefix? s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-prefix-ci? s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix? s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix-ci? s1 s2 [start1 end1 start2 end2]
+@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
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 primitive string-index s char_pred [start end]
-@deffnx primitive string-index-right s char_pred [start end]
+@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) occurence of a character which
+returning the index of the first (last) occurrence of a character which
@itemize @bullet
@item
equals @var{char_pred}, if it is character,
@item
-satisifies the predicate @var{char_pred}, if it is a
+satisfies the predicate @var{char_pred}, if it is a
procedure,
@item
@end itemize
@end deffn
-@deffn primitive string-skip s char_pred [start end]
-@deffnx primitive string-skip-right s char_pred [start end]
+@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) occurence of a character which
+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 satisify the predicate @var{char_pred}, if it is
+does not satisfy the predicate @var{char_pred}, if it is
a procedure.
@item
@end itemize
@end deffn
-@deffn primitive string-count s char_pred [start end]
+@deffn {Scheme Procedure} string-count s char_pred [start end]
Return the count of the number of characters in the string
@var{s} which
equals @var{char_pred}, if it is character,
@item
-satisifies the predicate @var{char_pred}, if it is a procedure.
+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 primitive string-contains s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-contains-ci s1 s2 [start1 end1 start2 end2]
+@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
similar to the procedures in the Guile core, but are extended to handle
optional start/end indices.
-@deffn primitive string-upcase s [start end]
-@deffnx primitive string-upcase! s [start end]
+@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 primitive string-downcase s [start end]
-@deffnx primitive string-downcase! s [start end]
+@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 primitive string-titlecase s [start end]
-@deffnx primitive string-titlecase! s [start end]
+@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.
One appending procedure, @code{string-append} is the same in R5RS and in
SRFI-13, so it is not redefined.
-@deffn primitive string-reverse str [start end]
-@deffnx primitive string-reverse! str [start end]
+@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.
unspecified value.
@end deffn
-@deffn primitive string-append/shared ls @dots{}
+@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 primitive string-concatenate ls
+@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 primitive string-concatenate/shared ls
+@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 primitive string-concatenate-reverse ls final_string end
+@deffn {Scheme Procedure} string-concatenate-reverse ls final_string end
Without optional arguments, this procedure is equivalent to
@smalllisp
Guaranteed to return a freshly allocated string.
@end deffn
-@deffn primitive string-concatenate-reverse/shared ls final_string end
+@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
the characters a string is composed of. The fold and unfold procedures
are list iterators and constructors.
-@deffn primitive string-map proc s [start end]
+@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 primitive string-map! proc s [start end]
+@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 primitive string-fold kons knil s [start end]
-@deffnx primitive string-fold-right kons knil s [start end]
+@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 primitive string-unfold p f g seed [base make_final]
-@deffnx primitive string-unfold-right p f g seed [base make_final]
+@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}
@end itemize
@end deffn
-@deffn primitive string-for-each proc s [start end]
+@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
"foofoo"
@end lisp
-@deffn primitive xsubstring s from [to start end]
+@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.
defaults to @var{from} + (@var{end} - @var{start}).
@end deffn
-@deffn primitive string-xcopy! target tstart s sfrom [sto start end]
+@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?
another string and @code{string-tokenize} splits a string into a list of
strings, breaking it up at a specified character.
-@deffn primitive string-replace s1 s2 [start1 end1 start2 end2]
+@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 primitive string-tokenize s [token_char start end]
+@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 equal to the character @var{token_char}, or
-whitespace, if @var{token_char} is not given. If
-@var{token_char} is a character set, it is used for finding the
-token borders.
+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
@dfn{Filtering} means to remove all characters from a string which do
not match a given criteria, @dfn{deleting} means the opposite.
-@deffn primitive string-filter s char_pred [start end]
+@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
character set, it is tested for membership.
@end deffn
-@deffn primitive string-delete s char_pred [start end]
+@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,
@node SRFI-14
@section 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
* 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:: Makeing new charsets.
+* 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.
@code{char-set-hash} can be used for calculating a hash value, maybe for
usage in fast lookup procedures.
-@deffn primitive char-set? obj
+@deffn {Scheme Procedure} char-set? obj
Return @code{#t} if @var{obj} is a character set, @code{#f}
otherwise.
@end deffn
-@deffn primitive char-set= cs1 @dots{}
+@deffn {Scheme Procedure} char-set= cs1 @dots{}
Return @code{#t} if all given character sets are equal.
@end deffn
-@deffn primitive char-set<= cs1 @dots{}
+@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 primitive char-set-hash cs [bound]
+@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}.
Additionally, mapping and (un-)folding procedures for character sets are
provided.
-@deffn primitive char-set-cursor cs
+@deffn {Scheme Procedure} char-set-cursor cs
Return a cursor into the character set @var{cs}.
@end deffn
-@deffn primitive char-set-ref cs cursor
+@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 primitive char-set-cursor-next cs cursor
+@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 primitive end-of-char-set? cursor
+@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 primitive char-set-fold kons knil cs
+@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 primitive char-set-unfold p f g seed [base_cs]
-@deffnx primitive char-set-unfold! p f g seed base_cs
+@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
@code{char-set-unfold!} is the side-effecting variant.
@end deffn
-@deffn primitive char-set-for-each proc cs
+@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 primitive char-set-map proc cs
+@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
New character sets are produced with these procedures.
-@deffn primitive char-set-copy cs
+@deffn {Scheme Procedure} char-set-copy cs
Return a newly allocated character set containing all
characters in @var{cs}.
@end deffn
-@deffn primitive char-set char1 @dots{}
+@deffn {Scheme Procedure} char-set char1 @dots{}
Return a character set containing all given characters.
@end deffn
-@deffn primitive list->char-set char_list [base_cs]
-@deffnx primitive list->char-set! char_list base_cs
+@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 primitive string->char-set s [base_cs]
-@deffnx primitive string->char-set! s base_cs
+@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 primitive char-set-filter pred cs [base_cs]
-@deffnx primitive char-set-filter! pred cs base_cs
+@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 primitive ucs-range->char-set lower upper [error? base_cs]
-@deffnx primitive uce-range->char-set! lower upper error? base_cs
+@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 resultung
+these characters are silently left out of the resulting
character set.
The characters in @var{base_cs} are added to the result, if
@code{ucs-range->char-set!} is the side-effecting variant.
@end deffn
-@deffn procedure ->char-set x
+@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
Access the elements and other information of a character set with these
procedures.
-@deffn primitive char-set-size cs
+@deffn {Scheme Procedure} char-set-size cs
Return the number of elements in character set @var{cs}.
@end deffn
-@deffn primitive char-set-count pred cs
+@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 primitive char-set->list cs
+@deffn {Scheme Procedure} char-set->list cs
Return a list containing the elements of the character set
@var{cs}.
@end deffn
-@deffn primitive char-set->string cs
+@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 primitive char-set-contains? cs char
+@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 primitive char-set-every pred cs
+@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 primitive char-set-any pred cs
+@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
provide side-effecting variants, which modify their character set
argument(s).
-@deffn primitive char-set-adjoin cs char1 @dots{}
-@deffnx primitive char-set-adjoin! cs char1 @dots{}
+@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 primitive char-set-delete cs char1 @dots{}
-@deffnx primitive char-set-delete! cs char1 @dots{}
+@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 primitive char-set-complement cs
-@deffnx primitive char-set-complement! cs
+@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 primitive char-set-union cs1 @dots{}
-@deffnx primitive char-set-union! cs1 @dots{}
+@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 primitive char-set-intersection cs1 @dots{}
-@deffnx primitive char-set-intersection! cs1 @dots{}
+@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 primitive char-set-difference cs1 @dots{}
-@deffnx primitive char-set-difference! cs1 @dots{}
+@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 primitive char-set-xor cs1 @dots{}
-@deffnx primitive char-set-xor! cs1 @dots{}
+@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 primitive char-set-diff+intersection cs1 @dots{}
-@deffnx primitive char-set-diff+intersection! cs1 @dots{}
+@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
@node SRFI-16
@section 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.
@node SRFI-17
@section 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},
@node SRFI-19
@section SRFI-19 - Time/Date Library
+@cindex SRFI-19
-This is an implementation of SRFI-19: Time/Date Library
-
-It depends on SRFIs: 6 (@pxref{SRFI-6}), 8 (@pxref{SRFI-8}),
-9 (@pxref{SRFI-9}).
+This is an implementation of the SRFI-19 time/date library. The
+functions and variables described here are provided by
-This section documents constants and procedure signatures.
+@example
+(use-modules (srfi srfi-19))
+@end example
@menu
-* SRFI-19 Constants::
-* SRFI-19 Current time and clock resolution::
-* SRFI-19 Time object and accessors::
-* SRFI-19 Time comparison procedures::
-* SRFI-19 Time arithmetic procedures::
-* SRFI-19 Date object and accessors::
-* SRFI-19 Time/Date/Julian Day/Modified Julian Day converters::
-* SRFI-19 Date to string/string to date converters::
+* 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 Constants
-@subsection SRFI-19 Constants
+@node SRFI-19 Introduction
+@subsection 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
+@subsection 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
-All these are bound to their symbol names:
+@defvar time-tai
+International Atomic Time (TAI).
+@cindex TAI
+@end defvar
-@example
- time-duration
- time-monotonic
- time-process
- time-tai
- time-thread
- time-utc
-@end example
+@defvar time-monotonic
+Monotonic time, meaning a monotonically increasing time starting from
+an unspecified epoch.
-@node SRFI-19 Current time and clock resolution
-@subsection SRFI-19 Current time and clock resolution
+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
-@example
- (current-date . tz-offset)
- (current-julian-day)
- (current-modified-julian-day)
- (current-time . clock-type)
- (time-resolution . clock-type)
-@end example
+@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
-@node SRFI-19 Time object and accessors
-@subsection SRFI-19 Time object and accessors
+@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
+@subsection 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
+@subsection 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
+@subsection 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
+@subsection 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
+@section 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
- (make-time type nanosecond second)
- (time? obj)
- (time-type time)
- (time-nanosecond time)
- (time-second time)
- (set-time-type! time type)
- (set-time-nanosecond! time nsec)
- (set-time-second! time sec)
- (copy-time time)
+(use-modules (srfi srfi-26))
@end example
-@node SRFI-19 Time comparison procedures
-@subsection SRFI-19 Time comparison procedures
+@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.
-Args are all @code{time} values.
+An example will illustrate the idea. The following is a
+specialization of @code{write}, sending output to
+@code{my-output-port},
@example
- (time<=? t1 t2)
- (time<? t1 t2)
- (time=? t1 t2)
- (time>=? t1 t2)
- (time>? t1 t2)
+(cut write <> my-output-port)
+@result{}
+(lambda (obj) (write obj my-output-port))
@end example
-@node SRFI-19 Time arithmetic procedures
-@subsection SRFI-19 Time arithmetic procedures
+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}.
-The @code{foo!} variants modify in place. Time difference
-is expressed in @code{time-duration} values.
+@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
- (time-difference t1 t2)
- (time-difference! t1 t2)
- (add-duration time duration)
- (add-duration! time duration)
- (subtract-duration time duration)
- (subtract-duration! time duration)
- @end 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.
-@node SRFI-19 Date object and accessors
-@subsection SRFI-19 Date object and accessors
+For example, a procedure taking a variable number of arguments like
+@code{max} but in addition enforcing a lower bound,
@example
- (make-date nsecs seconds minutes hours
- date month year offset)
- (date? obj)
- (date-nanosecond date)
- (date-second date)
- (date-minute date)
- (date-hour date)
- (date-day date)
- (date-month date)
- (date-year date)
- (date-zone-offset date)
- (date-year-day date)
- (date-week-day date)
- (date-week-number date day-of-week-starting-week)
+(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.
-@node SRFI-19 Time/Date/Julian Day/Modified Julian Day converters
-@subsection SRFI-19 Time/Date/Julian Day/Modified Julian Day converters
+The following illustrates the difference between @code{cut} and
+@code{cute},
@example
- (date->julian-day date)
- (date->modified-julian-day date)
- (date->time-monotonic date)
- (date->time-tai date)
- (date->time-utc date)
- (julian-day->date jdn . tz-offset)
- (julian-day->time-monotonic jdn)
- (julian-day->time-tai jdn)
- (julian-day->time-utc jdn)
- (modified-julian-day->date jdn . tz-offset)
- (modified-julian-day->time-monotonic jdn)
- (modified-julian-day->time-tai jdn)
- (modified-julian-day->time-utc jdn)
- (time-monotonic->date time . tz-offset)
- (time-monotonic->time-tai time-in)
- (time-monotonic->time-tai! time-in)
- (time-monotonic->time-utc time-in)
- (time-monotonic->time-utc! time-in)
- (time-tai->date time . tz-offset)
- (time-tai->julian-day time)
- (time-tai->modified-julian-day time)
- (time-tai->time-monotonic time-in)
- (time-tai->time-monotonic! time-in)
- (time-tai->time-utc time-in)
- (time-tai->time-utc! time-in)
- (time-utc->date time . tz-offset)
- (time-utc->julian-day time)
- (time-utc->modified-julian-day time)
- (time-utc->time-monotonic time-in)
- (time-utc->time-monotonic! time-in)
- (time-utc->time-tai time-in)
- (time-utc->time-tai! time-in)
+(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
-@node SRFI-19 Date to string/string to date converters
-@subsection SRFI-19 Date to string/string to date converters
+(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
- (date->string date . format-string)
- (string->date input-string template-string)
+(map (cut * 2 <>) '(1 2 3 4))
+
+(for-each (cut write <> my-port) my-list)
@end example
+@end deffn
+
@c srfi-modules.texi ends here
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End:
HCoop / bpt / guile.git / blobdiff