diff options
Diffstat (limited to 'doc/ref/srfi-modules.texi')
-rw-r--r-- | doc/ref/srfi-modules.texi | 2399 |
1 files changed, 0 insertions, 2399 deletions
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi deleted file mode 100644 index 32de27a4b..000000000 --- a/doc/ref/srfi-modules.texi +++ /dev/null @@ -1,2399 +0,0 @@ -@page -@node SRFI Support -@chapter SRFI Support Modules - -SRFI is an acronym for Scheme Request For Implementation. The SRFI -documents define a lot of syntactic and procedure extensions to standard -Scheme as defined in R5RS. - -Guile has support for a number of SRFIs. This chapter gives an overview -over the available SRFIs and some usage hints. For complete -documentation, design rationales and further examples, we advise you to -get the relevant SRFI documents from the SRFI home page -@url{http://srfi.schemers.org}. - -@menu -* About SRFI Usage:: What to know about Guile's SRFI support. -* SRFI-0:: cond-expand -* SRFI-1:: List library. -* SRFI-2:: and-let*. -* SRFI-4:: Homogeneous numeric vector datatypes. -* SRFI-6:: Basic String Ports. -* SRFI-8:: receive. -* SRFI-9:: define-record-type. -* SRFI-10:: Hash-Comma Reader Extension. -* SRFI-11:: let-values and let-values*. -* SRFI-13:: String library. -* SRFI-14:: Character-set library. -* SRFI-16:: case-lambda -* SRFI-17:: Generalized set! -* SRFI-19:: Time/Date library. -@end menu - - -@node About SRFI Usage -@section About SRFI Usage - -@c FIXME::martin: Review me! - -SRFI support in Guile is currently implemented partly in the core -library, and partly as add-on modules. That means that some SRFIs are -automatically available when the interpreter is started, whereas the -other SRFIs require you to use the appropriate support module -explicitly. - -There are several reasons for this inconsistency. First, the feature -checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be -available immediately, because it must be there when the user wants to -check for the Scheme implementation, that is, before she can know that -it is safe to use @code{use-modules} to load SRFI support modules. The -second reason is that some features defined in SRFIs had been -implemented in Guile before the developers started to add SRFI -implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In -the future, it is possible that SRFIs in the core library might be -factored out into separate modules, requiring explicit module loading -when they are needed. So you should be prepared to have to use -@code{use-modules} someday in the future to access SRFI-6 bindings. If -you want, you can do that already. We have included the module -@code{(srfi srfi-6)} in the distribution, which currently does nothing, -but ensures that you can write future-safe code. - -Generally, support for a specific SRFI is made available by using -modules named @code{(srfi srfi-@var{number})}, where @var{number} is the -number of the SRFI needed. Another possibility is to use the command -line option @code{--use-srfi}, which will load the necessary modules -automatically (@pxref{Invoking Guile}). - - -@node SRFI-0 -@section SRFI-0 - cond-expand - -@c FIXME::martin: Review me! - -SRFI-0 defines a means for checking whether a Scheme implementation has -support for a specified feature. The syntactic form @code{cond-expand}, -which implements this means, has the following syntax. - -@example -@group -<cond-expand> - --> (cond-expand <cond-expand-clause>+) - | (cond-expand <cond-expand-clause>* (else <command-or-definition>)) -<cond-expand-clause> - --> (<feature-requirement> <command-or-definition>*) -<feature-requirement> - --> <feature-identifier> - | (and <feature-requirement>*) - | (or <feature-requirement>*) - | (not <feature-requirement>) -<feature-identifier> - --> <a symbol which is the name or alias of a SRFI> -@end group -@end example - -When evaluated, this form checks all clauses in order, until it finds -one whose feature requirement is satisfied. Then the form expands into -the commands or definitions in the clause. A requirement is tested as -follows: - -@itemize @bullet -@item -If it is a symbol, it is satisfied if the feature identifier is -supported. - -@item -If it is an @code{and} form, all requirements must be satisfied. If no -requirements are given, it is satisfied, too. - -@item -If it is an @code{or} form, at least one of the requirements must be -satisfied. If no requirements are given, it is not satisfied. - -@item -If it is a @code{not} form, the feature requirement must @emph{not} be -satisfied. - -@item -If the feature requirement is the keyword @code{else} and it is the last -clause, it is satisfied if no prior clause matched. -@end itemize - -If no clause is satisfied, an error is signalled. - -Since @code{cond-expand} is needed to tell what a Scheme implementation -provides, it must be accessible without using any -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. - -Currently, the feature identifiers @code{guile}, @code{r5rs} and -@code{srfi-0} are supported. The other SRFIs are not in that list by -default, because the SRFI modules must be explicitly used before their -exported bindings can be used. - -So if a Scheme program wishes to use SRFI-8, it has two possibilities: -First, it can check whether the running Scheme implementation is Guile, -and if it is, it can use the appropriate module: - -@lisp -(cond-expand - (guile - (use-modules (srfi srfi-8))) - (srfi-8 - #t)) - ;; otherwise fail. -@end lisp - -The other possibility is to use the @code{--use-srfi} command line -option when invoking Guile (@pxref{Invoking Guile}). When you do that, -the specified SRFI support modules will be loaded and add their feature -identifier to the list of symbols checked by @code{cond-expand}. - -So, if you invoke Guile like this: - -@example -$ guile --use-srfi=8 -@end example - -the following snippet will expand to @code{'hooray}. - -@lisp -(cond-expand (srfi-8 'hooray)) -@end lisp - - -@node SRFI-1 -@section SRFI-1 - List library - -@c FIXME::martin: Review me! - -The list library defined in SRFI-1 contains a lot of useful list -processing procedures for construction, examining, destructuring and -manipulating lists and pairs. - -Since SRFI-1 also defines some procedures which are already contained -in R5RS and thus are supported by the Guile core library, some list -and pair procedures which appear in the SRFI-1 document may not appear -in this section. So when looking for a particular list/pair -processing procedure, you should also have a look at the sections -@ref{Lists} and @ref{Pairs}. - -@menu -* SRFI-1 Constructors:: Constructing new lists. -* SRFI-1 Predicates:: Testing list for specific properties. -* SRFI-1 Selectors:: Selecting elements from lists. -* SRFI-1 Length Append etc:: Length calculation and list appending. -* SRFI-1 Fold and Map:: Higher-order list processing. -* SRFI-1 Filtering and Partitioning:: Filter lists based on predicates. -* SRFI-1 Searching:: Search for elements. -* SRFI-1 Deleting:: Delete elements from lists. -* SRFI-1 Association Lists:: Handle association lists. -* SRFI-1 Set Operations:: Use lists for representing sets. -@end menu - -@node SRFI-1 Constructors -@subsection Constructors - -@c FIXME::martin: Review me! - -New lists can be constructed by calling one of the following -procedures. - -@deffn {Scheme Procedure} xcons d a -Like @code{cons}, but with interchanged arguments. Useful mostly when -passed to higher-order procedures. -@end deffn - -@deffn {Scheme Procedure} list-tabulate n init-proc -Return an @var{n}-element list, where each list element is produced by -applying the procedure @var{init-proc} to the corresponding list -index. The order in which @var{init-proc} is applied to the indices -is not specified. -@end deffn - -@deffn {Scheme Procedure} circular-list elt1 elt2 @dots{} -Return a circular list containing the given arguments @var{elt1} -@var{elt2} @dots{}. -@end deffn - -@deffn {Scheme Procedure} iota count [start step] -Return a list containing @var{count} elements, where each element is -calculated as follows: - -@var{start} + (@var{count} - 1) * @var{step} - -@var{start} defaults to 0 and @var{step} defaults to 1. -@end deffn - - -@node SRFI-1 Predicates -@subsection Predicates - -@c FIXME::martin: Review me! - -The procedures in this section test specific properties of lists. - -@deffn {Scheme Procedure} proper-list? obj -Return @code{#t} if @var{obj} is a proper list, that is a finite list, -terminated with the empty list. Otherwise, return @code{#f}. -@end deffn - -@deffn {Scheme Procedure} circular-list? obj -Return @code{#t} if @var{obj} is a circular list, otherwise return -@code{#f}. -@end deffn - -@deffn {Scheme Procedure} dotted-list? obj -Return @code{#t} if @var{obj} is a dotted list, return @code{#f} -otherwise. A dotted list is a finite list which is not terminated by -the empty list, but some other value. -@end deffn - -@deffn {Scheme Procedure} null-list? lst -Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f} -otherwise. If something else than a proper or circular list is passed -as @var{lst}, an error is signalled. This procedure is recommended -for checking for the end of a list in contexts where dotted lists are -not allowed. -@end deffn - -@deffn {Scheme Procedure} not-pair? obj -Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise. -This is shorthand notation @code{(not (pair? @var{obj}))} and is -supposed to be used for end-of-list checking in contexts where dotted -lists are allowed. -@end deffn - -@deffn {Scheme Procedure} list= elt= list1 @dots{} -Return @code{#t} if all argument lists are equal, @code{#f} otherwise. -List equality is determined by testing whether all lists have the same -length and the corresponding elements are equal in the sense of the -equality predicate @var{elt=}. If no or only one list is given, -@code{#t} is returned. -@end deffn - - -@node SRFI-1 Selectors -@subsection Selectors - -@c FIXME::martin: Review me! - -@deffn {Scheme Procedure} first pair -@deffnx {Scheme Procedure} second pair -@deffnx {Scheme Procedure} third pair -@deffnx {Scheme Procedure} fourth pair -@deffnx {Scheme Procedure} fifth pair -@deffnx {Scheme Procedure} sixth pair -@deffnx {Scheme Procedure} seventh pair -@deffnx {Scheme Procedure} eighth pair -@deffnx {Scheme Procedure} ninth pair -@deffnx {Scheme Procedure} tenth pair -These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}. -@end deffn - -@deffn {Scheme Procedure} car+cdr pair -Return two values, the @sc{car} and the @sc{cdr} of @var{pair}. -@end deffn - -@deffn {Scheme Procedure} take lst i -@deffnx {Scheme Procedure} take! lst i -Return a list containing the first @var{i} elements of @var{lst}. - -@code{take!} may modify the structure of the argument list @var{lst} -in order to produce the result. -@end deffn - -@deffn {Scheme Procedure} drop lst i -Return a list containing all but the first @var{i} elements of -@var{lst}. -@end deffn - -@deffn {Scheme Procedure} take-right lst i -Return the a list containing the @var{i} last elements of @var{lst}. -@end deffn - -@deffn {Scheme Procedure} drop-right lst i -@deffnx {Scheme Procedure} drop-right! lst i -Return the a list containing all but the @var{i} last elements of -@var{lst}. - -@code{drop-right!} may modify the structure of the argument list -@var{lst} in order to produce the result. -@end deffn - -@deffn {Scheme Procedure} split-at lst i -@deffnx {Scheme Procedure} split-at! lst i -Return two values, a list containing the first @var{i} elements of the -list @var{lst} and a list containing the remaining elements. - -@code{split-at!} may modify the structure of the argument list -@var{lst} in order to produce the result. -@end deffn - -@deffn {Scheme Procedure} last lst -Return the last element of the non-empty, finite list @var{lst}. -@end deffn - - -@node SRFI-1 Length Append etc -@subsection Length, Append, Concatenate, etc. - -@c FIXME::martin: Review me! - -@deffn {Scheme Procedure} length+ lst -Return the length of the argument list @var{lst}. When @var{lst} is a -circular list, @code{#f} is returned. -@end deffn - -@deffn {Scheme Procedure} concatenate list-of-lists -@deffnx {Scheme Procedure} concatenate! list-of-lists -Construct a list by appending all lists in @var{list-of-lists}. - -@code{concatenate!} may modify the structure of the given lists in -order to produce the result. -@end deffn - -@deffn {Scheme Procedure} append-reverse rev-head tail -@deffnx {Scheme Procedure} append-reverse! rev-head tail -Reverse @var{rev-head}, append @var{tail} and return the result. This -is equivalent to @code{(append (reverse @var{rev-head}) @var{tail})}, -but more efficient. - -@code{append-reverse!} may modify @var{rev-head} in order to produce -the result. -@end deffn - -@deffn {Scheme Procedure} zip lst1 lst2 @dots{} -Return a list as long as the shortest of the argument lists, where -each element is a list. The first list contains the first elements of -the argument lists, the second list contains the second elements, and -so on. -@end deffn - -@deffn {Scheme Procedure} unzip1 lst -@deffnx {Scheme Procedure} unzip2 lst -@deffnx {Scheme Procedure} unzip3 lst -@deffnx {Scheme Procedure} unzip4 lst -@deffnx {Scheme Procedure} unzip5 lst -@code{unzip1} takes a list of lists, and returns a list containing the -first elements of each list, @code{unzip2} returns two lists, the -first containing the first elements of each lists and the second -containing the second elements of each lists, and so on. -@end deffn - - -@node SRFI-1 Fold and Map -@subsection Fold, Unfold & Map - -@c FIXME::martin: Review me! - -@deffn {Scheme Procedure} fold kons knil lst1 lst2 @dots{} -Fold the procedure @var{kons} across all elements of @var{lst1}, -@var{lst2}, @dots{}. Produce the result of - -@code{(@var{kons} @var{en1} @var{en2} @dots{} (@var{kons} @var{e21} -@var{e22} (@var{kons} @var{e11} @var{e12} @var{knil})))}, - -if @var{enm} are the elements of the lists @var{lst1}, @var{lst2}, -@dots{}. -@end deffn - -@deffn {Scheme Procedure} fold-right kons knil lst1 lst2 @dots{} -Similar to @code{fold}, but applies @var{kons} in right-to-left order -to the list elements, that is: - -@code{(@var{kons} @var{e11} @var{e12}(@var{kons} @var{e21} -@var{e22} @dots{} (@var{kons} @var{en1} @var{en2} @var{knil})))}, -@end deffn - -@deffn {Scheme Procedure} pair-fold kons knil lst1 lst2 @dots{} -Like @code{fold}, but apply @var{kons} to the pairs of the list -instead of the list elements. -@end deffn - -@deffn {Scheme Procedure} pair-fold-right kons knil lst1 lst2 @dots{} -Like @code{fold-right}, but apply @var{kons} to the pairs of the list -instead of the list elements. -@end deffn - -@deffn {Scheme Procedure} reduce f ridentity lst -@code{reduce} is a variant of @code{reduce}. If @var{lst} is -@code{()}, @var{ridentity} is returned. Otherwise, @code{(fold (car -@var{lst}) (cdr @var{lst}))} is returned. -@end deffn - -@deffn {Scheme Procedure} reduce-right f ridentity lst -This is the @code{fold-right} variant of @var{reduce}. -@end deffn - -@deffn {Scheme Procedure} unfold p f g seed [tail-gen] -@code{unfold} is defined as follows: - -@lisp -(unfold p f g seed) = - (if (p seed) (tail-gen seed) - (cons (f seed) - (unfold p f g (g seed)))) -@end lisp - -@table @var -@item p -Determines when to stop unfolding. - -@item f -Maps each seed value to the corresponding list element. - -@item g -Maps each seed value to next seed valu. - -@item seed -The state value for the unfold. - -@item tail-gen -Creates the tail of the list; defaults to @code{(lambda (x) '())}. -@end table - -@var{g} produces a series of seed values, which are mapped to list -elements by @var{f}. These elements are put into a list in -left-to-right order, and @var{p} tells when to stop unfolding. -@end deffn - -@deffn {Scheme Procedure} unfold-right p f g seed [tail] -Construct a list with the following loop. - -@lisp -(let lp ((seed seed) (lis tail)) - (if (p seed) lis - (lp (g seed) - (cons (f seed) lis)))) -@end lisp - -@table @var -@item p -Determines when to stop unfolding. - -@item f -Maps each seed value to the corresponding list element. - -@item g -Maps each seed value to next seed valu. - -@item seed -The state value for the unfold. - -@item tail-gen -Creates the tail of the list; defaults to @code{(lambda (x) '())}. -@end table - -@end deffn - -@deffn {Scheme Procedure} map f lst1 lst2 @dots{} -Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and -return a list containing the results of the procedure applications. -This procedure is extended with respect to R5RS, because the argument -lists may have different lengths. The result list will have the same -length as the shortest argument lists. The order in which @var{f} -will be applied to the list element(s) is not specified. -@end deffn - -@deffn {Scheme Procedure} for-each f lst1 lst2 @dots{} -Apply the procedure @var{f} to each pair of corresponding elements of -the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not -specified. This procedure is extended with respect to R5RS, because -the argument lists may have different lengths. The shortest argument -list determines the number of times @var{f} is called. @var{f} will -be applied to the list elements in left-to-right order. - -@end deffn - -@deffn {Scheme Procedure} append-map f lst1 lst2 @dots{} -@deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{} -Equivalent to - -@lisp -(apply append (map f clist1 clist2 ...)) -@end lisp - -and - -@lisp -(apply append! (map f clist1 clist2 ...)) -@end lisp - -Map @var{f} over the elements of the lists, just as in the @code{map} -function. However, the results of the applications are appended -together to make the final result. @code{append-map} uses -@code{append} to append the results together; @code{append-map!} uses -@code{append!}. - -The dynamic order in which the various applications of @var{f} are -made is not specified. -@end deffn - -@deffn {Scheme Procedure} map! f lst1 lst2 @dots{} -Linear-update variant of @code{map} -- @code{map!} is allowed, but not -required, to alter the cons cells of @var{lst1} to construct the -result list. - -The dynamic order in which the various applications of @var{f} are -made is not specified. In the n-ary case, @var{lst2}, @var{lst3}, -@dots{} must have at least as many elements as @var{lst1}. -@end deffn - -@deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{} -Like @code{for-each}, but applies the procedure @var{f} to the pairs -from which the argument lists are constructed, instead of the list -elements. The return value is not specified. -@end deffn - -@deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{} -Like @code{map}, but only results from the applications of @var{f} -which are true are saved in the result list. -@end deffn - - -@node SRFI-1 Filtering and Partitioning -@subsection Filtering and Partitioning - -@c FIXME::martin: Review me! - -Filtering means to collect all elements from a list which satisfy a -specific condition. Partitioning a list means to make two groups of -list elements, one which contains the elements satisfying a condition, -and the other for the elements which don't. - -@deffn {Scheme Procedure} filter pred lst -@deffnx {Scheme 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. - -@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 -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. - -@code{partition!} is allowed, but not required to modify the structure of -the input list. -@end deffn - -@deffn {Scheme Procedure} remove pred lst -@deffnx {Scheme Procedure} remove! pred lst -Return a list containing all elements from @var{lst} which do not -satisfy the predicate @var{pred}. The elements in the result list -have the same order as in @var{lst}. The order in which @var{pred} is -applied to the list elements is not specified. - -@code{remove!} is allowed, but not required to modify the structure of -the input list. -@end deffn - - -@node SRFI-1 Searching -@subsection Searching - -@c FIXME::martin: Review me! - -The procedures for searching elements in lists either accept a -predicate or a comparison object for determining which elements are to -be searched. - -@deffn {Scheme Procedure} find pred lst -Return the first element of @var{lst} which satisfies the predicate -@var{pred} and @code{#f} if no such element is found. -@end deffn - -@deffn {Scheme Procedure} find-tail pred lst -Return the first pair of @var{lst} whose @sc{car} satisfies the -predicate @var{pred} and @code{#f} if no such element is found. -@end deffn - -@deffn {Scheme Procedure} take-while pred lst -@deffnx {Scheme Procedure} take-while! pred lst -Return the longest initial prefix of @var{lst} whose elements all -satisfy the predicate @var{pred}. - -@code{take-while!} is allowed, but not required to modify the input -list while producing the result. -@end deffn - -@deffn {Scheme Procedure} drop-while pred lst -Drop the longest initial prefix of @var{lst} whose elements all -satisfy the predicate @var{pred}. -@end deffn - -@deffn {Scheme Procedure} span pred lst -@deffnx {Scheme Procedure} span! pred lst -@deffnx {Scheme Procedure} break pred lst -@deffnx {Scheme Procedure} break! pred lst -@code{span} splits the list @var{lst} into the longest initial prefix -whose elements all satisfy the predicate @var{pred}, and the remaining -tail. @code{break} inverts the sense of the predicate. - -@code{span!} and @code{break!} are allowed, but not required to modify -the structure of the input list @var{lst} in order to produce the -result. -@end deffn - -@deffn {Scheme Procedure} any pred lst1 lst2 @dots{} -Apply @var{pred} across the lists and return a true value if the -predicate returns true for any of the list elements(s); return -@code{#f} otherwise. The true value returned is always the result of -the first successful application of @var{pred}. -@end deffn - -@deffn {Scheme Procedure} every pred lst1 lst2 @dots{} -Apply @var{pred} across the lists and return a true value if the -predicate returns true for every of the list elements(s); return -@code{#f} otherwise. The true value returned is always the result of -the final successful application of @var{pred}. -@end deffn - -@deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{} -Return the index of the leftmost element that satisfies @var{pred}. -@end deffn - -@deffn {Scheme Procedure} member x lst [=] -Return the first sublist of @var{lst} whose @sc{car} is equal to -@var{x}. If @var{x} does no appear in @var{lst}, return @code{#f}. -Equality is determined by the equality predicate @var{=}, or -@code{equal?} if @var{=} is not given. -@end deffn - - -@node SRFI-1 Deleting -@subsection Deleting - -@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 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. - -@code{delete!} is allowed, but not required to modify the structure of -the argument list in order to produce the result. -@end deffn - -@deffn {Scheme Procedure} delete-duplicates lst [=] -@deffnx {Scheme 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. - -@code{delete-duplicates!} is allowed, but not required to modify the -structure of the argument list in order to produce the result. -@end deffn - - -@node SRFI-1 Association Lists -@subsection Association Lists - -@c FIXME::martin: Review me! - -Association lists are described in detail in section @ref{Association -Lists}. The present section only documents the additional procedures -for dealing with association lists defined by SRFI-1. - -@deffn {Scheme Procedure} assoc key alist [=] -Return the pair from @var{alist} which matches @var{key}. Equality is -determined by @var{=}, which defaults to @code{equal?} if not given. -@var{alist} must be an association lists---a list of pairs. -@end deffn - -@deffn {Scheme Procedure} alist-cons key datum alist -Equivalent to - -@lisp -(cons (cons @var{key} @var{datum}) @var{alist}) -@end lisp - -This procedure is used to coons a new pair onto an existing -association list. -@end deffn - -@deffn {Scheme Procedure} alist-copy alist -Return a newly allocated copy of @var{alist}, that means that the -spine of the list as well as the pairs are copied. -@end deffn - -@deffn {Scheme Procedure} alist-delete key alist [=] -@deffnx {Scheme Procedure} alist-delete! key alist [=] -Return a list containing the 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. - -@code{alist-delete!} is allowed, but not required to modify the -structure of the list @var{alist} in order to produce the result. -@end deffn - - -@node SRFI-1 Set Operations -@subsection Set Operations on Lists - -@c FIXME::martin: Review me! - -Lists can be used for representing sets of objects. The procedures -documented in this section can be used for such set representations. -Man combining several sets or adding elements, they make sure that no -object is contained more than once in a given list. Please note that -lists are not a too efficient implementation method for sets, so if -you need high performance, you should think about implementing a -custom data structure for representing sets, such as trees, bitsets, -hash tables or something similar. - -All these procedures accept an equality predicate as the first -argument. This predicate is used for testing the objects in the list -sets for sameness. - -@deffn {Scheme Procedure} lset<= = list1 @dots{} -Return @code{#t} if every @var{listi} is a subset of @var{listi+1}, -otherwise return @code{#f}. Returns @code{#t} if called with less -than two arguments. @var{=} is used for testing element equality. -@end deffn - -@deffn {Scheme Procedure} lset= = list1 list2 @dots{} -Return @code{#t} if all argument lists are equal. @var{=} is used for -testing element equality. -@end deffn - -@deffn {Scheme Procedure} lset-adjoin = list elt1 @dots{} -@deffnx {Scheme Procedure} lset-adjoin! = list elt1 @dots{} -Add all @var{elts} to the list @var{list}, suppressing duplicates and -return the resulting list. @code{lset-adjoin!} is allowed, but not -required to modify its first argument. @var{=} is used for testing -element equality. -@end deffn - -@deffn {Scheme Procedure} lset-union = list1 @dots{} -@deffnx {Scheme Procedure} lset-union! = list1 @dots{} -Return the union of all argument list sets. The union is the set of -all elements which appear in any of the argument sets. -@code{lset-union!} is allowed, but not required to modify its first -argument. @var{=} is used for testing element equality. -@end deffn - -@deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{} -@deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{} -Return the intersection of all argument list sets. The intersection -is the set containing all elements which appear in all argument sets. -@code{lset-intersection!} is allowed, but not required to modify its -first argument. @var{=} is used for testing element equality. -@end deffn - -@deffn {Scheme Procedure} lset-difference = list1 list2 @dots{} -@deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{} -Return the difference of all argument list sets. The difference is -the the set containing all elements of the first list which do not -appear in the other lists. @code{lset-difference!} is allowed, but -not required to modify its first argument. @var{=} is used for testing -element equality. -@end deffn - -@deffn {Scheme Procedure} lset-xor = list1 @dots{} -@deffnx {Scheme Procedure} lset-xor! = list1 @dots{} -Return the set containing all elements which appear in the first -argument list set, but not in the second; or, more generally: which -appear in an odd number of sets. @code{lset-xor!} is allowed, but -not required to modify its first argument. @var{=} is used for testing -element equality. -@end deffn - -@deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{} -@deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{} -Return two values, the difference and the intersection of the argument -list sets. This works like a combination of @code{lset-difference} and -@code{lset-intersection}, but is more efficient. -@code{lset-diff+intersection!} is allowed, but not required to modify -its first argument. @var{=} is used for testing element equality. You -have to use some means to deal with the multiple values these -procedures return (@pxref{Multiple Values}). -@end deffn - - -@node SRFI-2 -@section SRFI-2 - and-let* - -@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}. - -@lisp -(and-let* ((x 1) (y #f)) 42) -@result{} -#f -(and-let* ((x 1) (y #t)) x) -@result{} -1 -@end lisp - - -@node SRFI-4 -@section SRFI-4 - Homogeneous numeric vector datatypes. - -@c FIXME::martin: Review me! - -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. - -Procedures similar to the vector procedures (@pxref{Vectors}) are -provided for handling these homogeneous vectors, but they are distinct -datatypes. - -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. - -If you want to use these datatypes and the corresponding procedures, -you have to use the module @code{(srfi srfi-4)}. - -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. - -@menu -* SRFI-4 - Read Syntax:: How to write homogeneous vector literals. -* SRFI-4 - Procedures:: Available homogeneous vector procedures. -@end menu - - -@node SRFI-4 - Read Syntax -@subsection SRFI-4 - Read Syntax - -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, - -@lisp -#f64(3.1415 2.71) -@end lisp - -denotes a vector of two elements, which are the values 3.1415 and -2.71, represented as floating-point values of 64 bit precision. - -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 - -@lisp -'(1 #f3) -@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 {Scheme Procedure} TAGvector? obj -Return @code{#t} if @var{obj} is a homogeneous numeric vector of type -@code{TAG}. -@end deffn - -@deffn {Scheme Procedure} 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 {Scheme Procedure} 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 {Scheme Procedure} TAGvector-length TAGvec -Return the number of elements in @var{TAGvec}. -@end deffn - -@deffn {Scheme Procedure} TAGvector-ref TAGvec i -Return the element at index @var{i} in @var{TAGvec}. -@end deffn - -@deffn {Scheme Procedure} 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 - -@deffn {Scheme Procedure} TAGvector->list TAGvec -Return a newly allocated list holding all elements of @var{TAGvec}. -@end deffn - -@deffn {Scheme Procedure} list->TAGvector lst -Return a newly allocated homogeneous numeric vector of type @code{TAG}, -initialized with the elements of the list @var{lst}. -@end deffn - - -@node SRFI-6 -@section SRFI-6 - Basic String Ports - -SRFI-6 defines the procedures @code{open-input-string}, -@code{open-output-string} and @code{get-output-string}. These -procedures are included in the Guile core, so using this module does not -make any difference at the moment. But it is possible that support for -SRFI-6 will be factored out of the core library in the future, so using -this module does not hurt, after all. - -@node SRFI-8 -@section SRFI-8 - receive - -@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 - -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. - -The syntax of a record type definition is: - -@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 -@end example - -Usage 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 -@end example - - -@node SRFI-10 -@section SRFI-10 - Hash-Comma Reader Extension - -@cindex hash-comma -@cindex #,() -The module @code{(srfi srfi-10)} implements the syntax extension -@code{#,()}, also called hash-comma, which is defined in SRFI-10. - -The support for SRFI-10 consists of the procedure -@code{define-reader-ctor} for defining new reader constructors and the -read syntax form - -@example -#,(@var{ctor} @var{datum} ...) -@end example - -where @var{ctor} must be a symbol for which a read constructor was -defined previously, using @code{define-reader-ctor}. - -Example: - -@lisp -(define-reader-ctor 'file open-input-file) -(define f '#,(file "/etc/passwd")) -(read-line f) -@result{} -"root:x:0:0:root:/root:/bin/bash" -@end lisp - -Please note the quote before the @code{#,(file ...)} expression. This -is necessary because ports are not self-evaluating in Guile. - -@deffn {Scheme Procedure} define-reader-ctor symbol proc -Define @var{proc} as the reader constructor for hash-comma forms with a -tag @var{symbol}. @var{proc} will be applied to the datum(s) following -the tag in the hash-comma expression after the complete form has been -read in. The result of @var{proc} is returned by the Scheme reader. -@end deffn - - -@node SRFI-11 -@section SRFI-11 - let-values - -This module implements the binding forms for multiple values -@code{let-values} and @code{let-values*}. These forms are similar to -@code{let} and @code{let*} (@pxref{Local Bindings}), but they support -binding of the values returned by multiple-valued expressions. - -Write @code{(use-modules (srfi srfi-11))} to make the bindings -available. - -@lisp -(let-values (((x y) (values 1 2)) - ((z f) (values 3 4))) - (+ x y z f)) -@result{} -10 -@end lisp - -@code{let-values} performs all bindings simultaneously, which means that -no expression in the binding clauses may refer to variables bound in the -same clause list. @code{let-values*}, on the other hand, performs the -bindings sequentially, just like @code{let*} does for single-valued -expressions. - - -@node SRFI-13 -@section SRFI-13 - String Library - -In this section, we will describe all procedures defined in SRFI-13 -(string library) and implemented by the module @code{(srfi srfi-13)}. - -Note that only the procedures from SRFI-13 are documented here which are -not already contained in Guile. For procedures not documented here -please refer to the relevant chapters in the Guile Reference Manual, for -example the documentation of strings and string procedures -(@pxref{Strings}). - -All of the procedures defined in SRFI-13, which are not already -included in the Guile core library, are implemented in the module -@code{(srfi srfi-13)}. The procedures which are both in Guile and in -SRFI-13 are slightly extended in this module. Their bindings -overwrite those in the Guile core. - -The procedures which are defined in the section @emph{Low-level -procedures} of SRFI-13 for parsing optional string indices, substring -specification checking and Knuth-Morris-Pratt-Searching are not -implemented. - -The procedures @code{string-contains} and @code{string-contains-ci} are -not implemented very efficiently at the moment. This will be changed as -soon as possible. - -@menu -* Loading SRFI-13:: How to load SRFI-13 support. -* SRFI-13 Predicates:: String predicates. -* SRFI-13 Constructors:: String constructing procedures. -* SRFI-13 List/String Conversion:: Conversion from/to lists. -* SRFI-13 Selection:: Selection portions of strings. -* SRFI-13 Modification:: Modify strings in-place. -* SRFI-13 Comparison:: Compare strings. -* SRFI-13 Prefixes/Suffixes:: Detect common pre-/suffixes. -* SRFI-13 Searching:: Searching for substrings. -* SRFI-13 Case Mapping:: Mapping to lower-/upper-case. -* SRFI-13 Reverse/Append:: Reverse and append strings. -* SRFI-13 Fold/Unfold/Map:: Construct/deconstruct strings. -* SRFI-13 Replicate/Rotate:: Replicate and rotate portions of strings. -* SRFI-13 Miscellaneous:: Left-over string procedures. -* SRFI-13 Filtering/Deleting:: Filter and delete characters from strings. -@end menu - - -@node Loading SRFI-13 -@subsection Loading SRFI-13 - -When Guile is properly installed, SRFI-13 support can be loaded into a -running Guile by using the @code{(srfi srfi-13)} module. - -@example -$ guile -guile> (use-modules (srfi srfi-13)) -guile> -@end example - -When this step causes any errors, Guile is not properly installed. - -One possible reason is that Guile cannot find either the Scheme module -file @file{srfi-13.scm}, or it cannot find the shared object file -@file{libguile-srfi-srfi-13-14.so}. Make sure that the former is in the -Guile load path and that the latter is either installed in some default -location like @file{/usr/local/lib} or that the directory it was -installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to -@file{srfi-14.scm}. - -Now you can test whether the SRFI-13 procedures are working by calling -the @code{string-concatenate} procedure. - -@example -guile> (string-concatenate '("Hello" " " "World!")) -"Hello World!" -@end example - -@node SRFI-13 Predicates -@subsection Predicates - -In addition to the primitives @code{string?} and @code{string-null?}, -which are already in the Guile core, the string predicates -@code{string-any} and @code{string-every} are defined by SRFI-13. - -@deffn {Scheme Procedure} string-any 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, -the returned true value is the one produced by the first -successful application of @var{pred}. -@end deffn - -@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 -true, the returned true value is the one produced by the final -application of @var{pred} to the last character of @var{s}. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Constructors -@subsection Constructors - -SRFI-13 defines several procedures for constructing new strings. In -addition to @code{make-string} and @code{string} (available in the Guile -core library), the procedure @code{string-tabulate} does exist. - -@deffn {Scheme Procedure} string-tabulate proc len -@var{proc} is an integer->char procedure. Construct a string -of size @var{len} by applying @var{proc} to each index to -produce the corresponding string element. The order in which -@var{proc} is applied to the indices is not specified. -@end deffn - - -@c =================================================================== - -@node SRFI-13 List/String Conversion -@subsection List/String Conversion - -The procedure @code{string->list} is extended by SRFI-13, that is why it -is included in @code{(srfi srfi-13)}. The other procedures are new. -The Guile core already contains the procedure @code{list->string} for -converting a list of characters into a string (@pxref{List/String -Conversion}). - -@deffn {Scheme Procedure} string->list str [start end] -Convert the string @var{str} into a list of characters. -@end deffn - -@deffn {Scheme Procedure} reverse-list->string chrs -An efficient implementation of @code{(compose string->list -reverse)}: - -@smalllisp -(reverse-list->string '(#\a #\B #\c)) @result{} "cBa" -@end smalllisp -@end deffn - -@deffn {Scheme Procedure} string-join ls [delimiter grammar] -Append the string in the string list @var{ls}, using the string -@var{delim} as a delimiter between the elements of @var{ls}. -@var{grammar} is a symbol which specifies how the delimiter is -placed between the strings, and defaults to the symbol -@code{infix}. - -@table @code -@item infix -Insert the separator between list elements. An empty string -will produce an empty list. - -@item string-infix -Like @code{infix}, but will raise an error if given the empty -list. - -@item suffix -Insert the separator after every list element. - -@item prefix -Insert the separator before each list element. -@end table -@end deffn - - -@c =================================================================== - -@node SRFI-13 Selection -@subsection Selection - -These procedures are called @dfn{selectors}, because they access -information about the string or select pieces of a given string. - -Additional selector procedures are documented in the Strings section -(@pxref{String Selection}), like @code{string-length} or -@code{string-ref}. - -@code{string-copy} is also available in core Guile, but this version -accepts additional start/end indices. - -@deffn {Scheme Procedure} string-copy str [start end] -Return a freshly allocated copy of the string @var{str}. If -given, @var{start} and @var{end} delimit the portion of -@var{str} which is copied. -@end deffn - -@deffn {Scheme Procedure} substring/shared str start [end] -Like @code{substring}, but the result may share memory with the -argument @var{str}. -@end deffn - -@deffn {Scheme Procedure} string-copy! target tstart s [start end] -Copy the sequence of characters from index range [@var{start}, -@var{end}) in string @var{s} to string @var{target}, beginning -at index @var{tstart}. The characters are copied left-to-right -or right-to-left as needed - the copy is guaranteed to work, -even if @var{target} and @var{s} are the same string. It is an -error if the copy operation runs off the end of the target -string. -@end deffn - -@deffn {Scheme Procedure} string-take s n -@deffnx {Scheme Procedure} string-take-right s n -Return the @var{n} first/last characters of @var{s}. -@end deffn - -@deffn {Scheme Procedure} string-drop s n -@deffnx {Scheme Procedure} string-drop-right s n -Return all but the first/last @var{n} characters of @var{s}. -@end deffn - -@deffn {Scheme Procedure} string-pad s len [chr start end] -@deffnx {Scheme Procedure} string-pad-right s len [chr start end] -Take that characters from @var{start} to @var{end} from the -string @var{s} and return a new string, right(left)-padded by the -character @var{chr} to length @var{len}. If the resulting -string is longer than @var{len}, it is truncated on the right (left). -@end deffn - -@deffn {Scheme Procedure} string-trim s [char_pred start end] -@deffnx {Scheme Procedure} string-trim-right s [char_pred start end] -@deffnx {Scheme Procedure} string-trim-both s [char_pred start end] -Trim @var{s} by skipping over all characters on the left/right/both -sides of the string that satisfy the parameter @var{char_pred}: - -@itemize @bullet -@item -if it is the character @var{ch}, characters equal to -@var{ch} are trimmed, - -@item -if it is a procedure @var{pred} characters that -satisfy @var{pred} are trimmed, - -@item -if it is a character set, characters in that set are trimmed. -@end itemize - -If called without a @var{char_pred} argument, all whitespace is -trimmed. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Modification -@subsection Modification - -The procedure @code{string-fill!} is extended from R5RS because it -accepts optional start/end indices. This bindings shadows the procedure -of the same name in the Guile core. The second modification procedure -@code{string-set!} is documented in the Strings section (@pxref{String -Modification}). - -@deffn {Scheme Procedure} string-fill! str chr [start end] -Stores @var{chr} in every element of the given @var{str} and -returns an unspecified value. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Comparison -@subsection Comparison - -The procedures in this section are used for comparing strings in -different ways. The comparison predicates differ from those in R5RS in -that they do not only return @code{#t} or @code{#f}, but the mismatch -index in the case of a true return value. - -@code{string-hash} and @code{string-hash-ci} are for calculating hash -values for strings, useful for implementing fast lookup mechanisms. - -@deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2] -Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the -mismatch index, depending upon whether @var{s1} is less than, -equal to, or greater than @var{s2}. The mismatch index is the -largest index @var{i} such that for every 0 <= @var{j} < -@var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] - that is, -@var{i} is the first position that does not match. The -character comparison is done case-insensitively. -@end deffn - -@deffn {Scheme Procedure} string= s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string<> s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string< s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string> s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string<= s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string>= s1 s2 [start1 end1 start2 end2] -Compare @var{s1} and @var{s2} and return @code{#f} if the predicate -fails. Otherwise, the mismatch index is returned (or @var{end1} in the -case of @code{string=}. -@end deffn - -@deffn {Scheme Procedure} string-ci= s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-ci<> s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-ci< s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-ci> s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-ci<= s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-ci>= s1 s2 [start1 end1 start2 end2] -Compare @var{s1} and @var{s2} and return @code{#f} if the predicate -fails. Otherwise, the mismatch index is returned (or @var{end1} in the -case of @code{string=}. These are the case-insensitive variants. -@end deffn - -@deffn {Scheme Procedure} string-hash s [bound start end] -@deffnx {Scheme Procedure} string-hash-ci s [bound start end] -Return a hash value of the string @var{s} in the range 0 @dots{} -@var{bound} - 1. @code{string-hash-ci} is the case-insensitive variant. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Prefixes/Suffixes -@subsection Prefixes/Suffixes - -Using these procedures you can determine whether a given string is a -prefix or suffix of another string or how long a common prefix/suffix -is. - -@deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-suffix-length s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 end1 start2 end2] -Return the length of the longest common prefix/suffix of the two -strings. @code{string-prefix-length-ci} and -@code{string-suffix-length-ci} are the case-insensitive variants. -@end deffn - -@deffn {Scheme Procedure} string-prefix? s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-prefix-ci? s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-suffix? s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-suffix-ci? s1 s2 [start1 end1 start2 end2] -Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and -@code{string-suffix-ci?} are the case-insensitive variants. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Searching -@subsection Searching - -Use these procedures to find out whether a string contains a given -character or a given substring, or a character from a set of characters. - -@deffn {Scheme Procedure} string-index s char_pred [start end] -@deffnx {Scheme Procedure} string-index-right s char_pred [start end] -Search through the string @var{s} from left to right (right to left), -returning the index of the first (last) occurrence of a character which - -@itemize @bullet -@item -equals @var{char_pred}, if it is character, - -@item -satisfies the predicate @var{char_pred}, if it is a -procedure, - -@item -is in the set @var{char_pred}, if it is a character set. -@end itemize -@end deffn - -@deffn {Scheme Procedure} string-skip s char_pred [start end] -@deffnx {Scheme Procedure} string-skip-right s char_pred [start end] -Search through the string @var{s} from left to right (right to left), -returning the index of the first (last) occurrence of a character which - -@itemize @bullet -@item -does not equal @var{char_pred}, if it is character, - -@item -does not satisfy the predicate @var{char_pred}, if it is -a procedure. - -@item -is not in the set if @var{char_pred} is a character set. -@end itemize -@end deffn - -@deffn {Scheme Procedure} string-count s char_pred [start end] -Return the count of the number of characters in the string -@var{s} which - -@itemize @bullet -@item -equals @var{char_pred}, if it is character, - -@item -satisfies the predicate @var{char_pred}, if it is a procedure. - -@item -is in the set @var{char_pred}, if it is a character set. -@end itemize -@end deffn - -@deffn {Scheme Procedure} string-contains s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-contains-ci s1 s2 [start1 end1 start2 end2] -Does string @var{s1} contain string @var{s2}? Return the index -in @var{s1} where @var{s2} occurs as a substring, or false. -The optional start/end indices restrict the operation to the -indicated substrings. - -@code{string-contains-ci} is the case-insensitive variant. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Case Mapping -@subsection Alphabetic Case Mapping - -These procedures convert the alphabetic case of strings. They are -similar to the procedures in the Guile core, but are extended to handle -optional start/end indices. - -@deffn {Scheme Procedure} string-upcase s [start end] -@deffnx {Scheme Procedure} string-upcase! s [start end] -Upcase every character in @var{s}. @code{string-upcase!} is the -side-effecting variant. -@end deffn - -@deffn {Scheme Procedure} string-downcase s [start end] -@deffnx {Scheme Procedure} string-downcase! s [start end] -Downcase every character in @var{s}. @code{string-downcase!} is the -side-effecting variant. -@end deffn - -@deffn {Scheme Procedure} string-titlecase s [start end] -@deffnx {Scheme Procedure} string-titlecase! s [start end] -Upcase every first character in every word in @var{s}, downcase the -other characters. @code{string-titlecase!} is the side-effecting -variant. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Reverse/Append -@subsection Reverse/Append - -One appending procedure, @code{string-append} is the same in R5RS and in -SRFI-13, so it is not redefined. - -@deffn {Scheme Procedure} string-reverse str [start end] -@deffnx {Scheme Procedure} string-reverse! str [start end] -Reverse the string @var{str}. The optional arguments -@var{start} and @var{end} delimit the region of @var{str} to -operate on. - -@code{string-reverse!} modifies the argument string and returns an -unspecified value. -@end deffn - -@deffn {Scheme Procedure} string-append/shared ls @dots{} -Like @code{string-append}, but the result may share memory -with the argument strings. -@end deffn - -@deffn {Scheme Procedure} string-concatenate ls -Append the elements of @var{ls} (which must be strings) -together into a single string. Guaranteed to return a freshly -allocated string. -@end deffn - -@deffn {Scheme Procedure} string-concatenate/shared ls -Like @code{string-concatenate}, but the result may share memory -with the strings in the list @var{ls}. -@end deffn - -@deffn {Scheme Procedure} string-concatenate-reverse ls final_string end -Without optional arguments, this procedure is equivalent to - -@smalllisp -(string-concatenate (reverse ls)) -@end smalllisp - -If the optional argument @var{final_string} is specified, it is -consed onto the beginning to @var{ls} before performing the -list-reverse and string-concatenate operations. If @var{end} -is given, only the characters of @var{final_string} up to index -@var{end} are used. - -Guaranteed to return a freshly allocated string. -@end deffn - -@deffn {Scheme Procedure} string-concatenate-reverse/shared ls final_string end -Like @code{string-concatenate-reverse}, but the result may -share memory with the the strings in the @var{ls} arguments. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Fold/Unfold/Map -@subsection Fold/Unfold/Map - -@code{string-map}, @code{string-for-each} etc. are for iterating over -the characters a string is composed of. The fold and unfold procedures -are list iterators and constructors. - -@deffn {Scheme Procedure} string-map proc s [start end] -@var{proc} is a char->char procedure, it is mapped over -@var{s}. The order in which the procedure is applied to the -string elements is not specified. -@end deffn - -@deffn {Scheme Procedure} string-map! proc s [start end] -@var{proc} is a char->char procedure, it is mapped over -@var{s}. The order in which the procedure is applied to the -string elements is not specified. The string @var{s} is -modified in-place, the return value is not specified. -@end deffn - -@deffn {Scheme Procedure} string-fold kons knil s [start end] -@deffnx {Scheme Procedure} string-fold-right kons knil s [start end] -Fold @var{kons} over the characters of @var{s}, with @var{knil} as the -terminating element, from left to right (or right to left, for -@code{string-fold-right}). @var{kons} must expect two arguments: The -actual character and the last result of @var{kons}' application. -@end deffn - -@deffn {Scheme Procedure} string-unfold p f g seed [base make_final] -@deffnx {Scheme Procedure} string-unfold-right p f g seed [base make_final] -These are the fundamental string constructors. -@itemize @bullet -@item @var{g} is used to generate a series of @emph{seed} -values from the initial @var{seed}: @var{seed}, (@var{g} -@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), -@dots{} -@item @var{p} tells us when to stop - when it returns true -when applied to one of these seed values. -@item @var{f} maps each seed value to the corresponding -character in the result string. These chars are assembled into the -string in a left-to-right (right-to-left) order. -@item @var{base} is the optional initial/leftmost (rightmost) - portion of the constructed string; it default to the empty string. -@item @var{make_final} is applied to the terminal seed -value (on which @var{p} returns true) to produce the final/rightmost -(leftmost) portion of the constructed string. It defaults to -@code{(lambda (x) "")}. -@end itemize -@end deffn - -@deffn {Scheme Procedure} string-for-each proc s [start end] -@var{proc} is mapped over @var{s} in left-to-right order. The -return value is not specified. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Replicate/Rotate -@subsection Replicate/Rotate - -These procedures are special substring procedures, which can also be -used for replicating strings. They are a bit tricky to use, but -consider this code fragment, which replicates the input string -@code{"foo"} so often that the resulting string has a length of six. - -@lisp -(xsubstring "foo" 0 6) -@result{} -"foofoo" -@end lisp - -@deffn {Scheme Procedure} xsubstring s from [to start end] -This is the @emph{extended substring} procedure that implements -replicated copying of a substring of some string. - -@var{s} is a string, @var{start} and @var{end} are optional -arguments that demarcate a substring of @var{s}, defaulting to -0 and the length of @var{s}. Replicate this substring up and -down index space, in both the positive and negative directions. -@code{xsubstring} returns the substring of this string -beginning at index @var{from}, and ending at @var{to}, which -defaults to @var{from} + (@var{end} - @var{start}). -@end deffn - -@deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto start end] -Exactly the same as @code{xsubstring}, but the extracted text -is written into the string @var{target} starting at index -@var{tstart}. The operation is not defined if @code{(eq? -@var{target} @var{s})} or these arguments share storage - you -cannot copy a string on top of itself. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Miscellaneous -@subsection Miscellaneous - -@code{string-replace} is for replacing a portion of a string with -another string and @code{string-tokenize} splits a string into a list of -strings, breaking it up at a specified character. - -@deffn {Scheme Procedure} string-replace s1 s2 [start1 end1 start2 end2] -Return the string @var{s1}, but with the characters -@var{start1} @dots{} @var{end1} replaced by the characters -@var{start2} @dots{} @var{end2} from @var{s2}. -@end deffn - -@deffn {Scheme Procedure} string-tokenize s [token-set start end] -Split the string @var{s} into a list of substrings, where each -substring is a maximal non-empty contiguous sequence of characters -from the character set @var{token_set}, which defaults to an -equivalent of @code{char-set:graphic}. If @var{start} or @var{end} -indices are provided, they restrict @code{string-tokenize} to -operating on the indicated substring of @var{s}. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Filtering/Deleting -@subsection Filtering/Deleting - -@dfn{Filtering} means to remove all characters from a string which do -not match a given criteria, @dfn{deleting} means the opposite. - -@deffn {Scheme Procedure} string-filter s char_pred [start end] -Filter the string @var{s}, retaining only those characters that -satisfy the @var{char_pred} argument. If the argument is a -procedure, it is applied to each character as a predicate, if -it is a character, it is tested for equality and if it is a -character set, it is tested for membership. -@end deffn - -@deffn {Scheme Procedure} string-delete s char_pred [start end] -Filter the string @var{s}, retaining only those characters that -do not satisfy the @var{char_pred} argument. If the argument -is a procedure, it is applied to each character as a predicate, -if it is a character, it is tested for equality and if it is a -character set, it is tested for membership. -@end deffn - - -@node SRFI-14 -@section SRFI-14 - Character-set Library - -SRFI-14 defines the data type @dfn{character set}, and also defines a -lot of procedures for handling this character type, and a few standard -character sets like whitespace, alphabetic characters and others. - -All procedures from SRFI-14 (character-set library) are implemented in -the module @code{(srfi srfi-14)}, as well as the standard variables -@code{char-set:letter}, @code{char-set:digit} etc. - -@menu -* Loading SRFI-14:: How to make charsets available. -* SRFI-14 Character Set Data Type:: Underlying data type for charsets. -* SRFI-14 Predicates/Comparison:: Charset predicates. -* SRFI-14 Iterating Over Character Sets:: Enumerate charset elements. -* SRFI-14 Creating Character Sets:: Making new charsets. -* SRFI-14 Querying Character Sets:: Test charsets for membership etc. -* SRFI-14 Character-Set Algebra:: Calculating new charsets. -* SRFI-14 Standard Character Sets:: Variables containing predefined charsets. -@end menu - - -@node Loading SRFI-14 -@subsection Loading SRFI-14 - -When Guile is properly installed, SRFI-14 support can be loaded into a -running Guile by using the @code{(srfi srfi-14)} module. - -@example -$ guile -guile> (use-modules (srfi srfi-14)) -guile> (char-set-union (char-set #\f #\o #\o) (string->char-set "bar")) -#<charset @{#\a #\b #\f #\o #\r@}> -guile> -@end example - - -@node SRFI-14 Character Set Data Type -@subsection Character Set Data Type - -The data type @dfn{charset} implements sets of characters -(@pxref{Characters}). Because the internal representation of character -sets is not visible to the user, a lot of procedures for handling them -are provided. - -Character sets can be created, extended, tested for the membership of a -characters and be compared to other character sets. - -The Guile implementation of character sets deals with 8-bit characters. -In the standard variables, only the ASCII part of the character range is -really used, so that for example @dfn{Umlaute} and other accented -characters are not considered to be letters. In the future, as Guile -may get support for international character sets, this will change, so -don't rely on these ``features''. - - -@c =================================================================== - -@node SRFI-14 Predicates/Comparison -@subsection Predicates/Comparison - -Use these procedures for testing whether an object is a character set, -or whether several character sets are equal or subsets of each other. -@code{char-set-hash} can be used for calculating a hash value, maybe for -usage in fast lookup procedures. - -@deffn {Scheme Procedure} char-set? obj -Return @code{#t} if @var{obj} is a character set, @code{#f} -otherwise. -@end deffn - -@deffn {Scheme Procedure} char-set= cs1 @dots{} -Return @code{#t} if all given character sets are equal. -@end deffn - -@deffn {Scheme Procedure} char-set<= cs1 @dots{} -Return @code{#t} if every character set @var{cs}i is a subset -of character set @var{cs}i+1. -@end deffn - -@deffn {Scheme Procedure} char-set-hash cs [bound] -Compute a hash value for the character set @var{cs}. If -@var{bound} is given and not @code{#f}, it restricts the -returned value to the range 0 @dots{} @var{bound - 1}. -@end deffn - - -@c =================================================================== - -@node SRFI-14 Iterating Over Character Sets -@subsection Iterating Over Character Sets - -Character set cursors are a means for iterating over the members of a -character sets. After creating a character set cursor with -@code{char-set-cursor}, a cursor can be dereferenced with -@code{char-set-ref}, advanced to the next member with -@code{char-set-cursor-next}. Whether a cursor has passed past the last -element of the set can be checked with @code{end-of-char-set?}. - -Additionally, mapping and (un-)folding procedures for character sets are -provided. - -@deffn {Scheme Procedure} char-set-cursor cs -Return a cursor into the character set @var{cs}. -@end deffn - -@deffn {Scheme Procedure} char-set-ref cs cursor -Return the character at the current cursor position -@var{cursor} in the character set @var{cs}. It is an error to -pass a cursor for which @code{end-of-char-set?} returns true. -@end deffn - -@deffn {Scheme Procedure} char-set-cursor-next cs cursor -Advance the character set cursor @var{cursor} to the next -character in the character set @var{cs}. It is an error if the -cursor given satisfies @code{end-of-char-set?}. -@end deffn - -@deffn {Scheme Procedure} end-of-char-set? cursor -Return @code{#t} if @var{cursor} has reached the end of a -character set, @code{#f} otherwise. -@end deffn - -@deffn {Scheme Procedure} char-set-fold kons knil cs -Fold the procedure @var{kons} over the character set @var{cs}, -initializing it with @var{knil}. -@end deffn - -@deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs] -@deffnx {Scheme Procedure} char-set-unfold! p f g seed base_cs -This is a fundamental constructor for character sets. -@itemize @bullet -@item @var{g} is used to generate a series of ``seed'' values -from the initial seed: @var{seed}, (@var{g} @var{seed}), -(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{} -@item @var{p} tells us when to stop -- when it returns true -when applied to one of the seed values. -@item @var{f} maps each seed value to a character. These -characters are added to the base character set @var{base_cs} to -form the result; @var{base_cs} defaults to the empty set. -@end itemize - -@code{char-set-unfold!} is the side-effecting variant. -@end deffn - -@deffn {Scheme Procedure} char-set-for-each proc cs -Apply @var{proc} to every character in the character set -@var{cs}. The return value is not specified. -@end deffn - -@deffn {Scheme Procedure} char-set-map proc cs -Map the procedure @var{proc} over every character in @var{cs}. -@var{proc} must be a character -> character procedure. -@end deffn - - -@c =================================================================== - -@node SRFI-14 Creating Character Sets -@subsection Creating Character Sets - -New character sets are produced with these procedures. - -@deffn {Scheme Procedure} char-set-copy cs -Return a newly allocated character set containing all -characters in @var{cs}. -@end deffn - -@deffn {Scheme Procedure} char-set char1 @dots{} -Return a character set containing all given characters. -@end deffn - -@deffn {Scheme Procedure} list->char-set char_list [base_cs] -@deffnx {Scheme Procedure} list->char-set! char_list base_cs -Convert the character list @var{list} to a character set. If -the character set @var{base_cs} is given, the character in this -set are also included in the result. - -@code{list->char-set!} is the side-effecting variant. -@end deffn - -@deffn {Scheme Procedure} string->char-set s [base_cs] -@deffnx {Scheme Procedure} string->char-set! s base_cs -Convert the string @var{str} to a character set. If the -character set @var{base_cs} is given, the characters in this -set are also included in the result. - -@code{string->char-set!} is the side-effecting variant. -@end deffn - -@deffn {Scheme Procedure} char-set-filter pred cs [base_cs] -@deffnx {Scheme Procedure} char-set-filter! pred cs base_cs -Return a character set containing every character from @var{cs} -so that it satisfies @var{pred}. If provided, the characters -from @var{base_cs} are added to the result. - -@code{char-set-filter!} is the side-effecting variant. -@end deffn - -@deffn {Scheme Procedure} ucs-range->char-set lower upper [error? base_cs] -@deffnx {Scheme Procedure} uce-range->char-set! lower upper error? base_cs -Return a character set containing all characters whose -character codes lie in the half-open range -[@var{lower},@var{upper}). - -If @var{error} is a true value, an error is signalled if the -specified range contains characters which are not contained in -the implemented character range. If @var{error} is @code{#f}, -these characters are silently left out of the resulting -character set. - -The characters in @var{base_cs} are added to the result, if -given. - -@code{ucs-range->char-set!} is the side-effecting variant. -@end deffn - -@deffn {Scheme Procedure} ->char-set x -Coerce @var{x} into a character set. @var{x} may be a string, a -character or a character set. -@end deffn - - -@c =================================================================== - -@node SRFI-14 Querying Character Sets -@subsection Querying Character Sets - -Access the elements and other information of a character set with these -procedures. - -@deffn {Scheme Procedure} char-set-size cs -Return the number of elements in character set @var{cs}. -@end deffn - -@deffn {Scheme Procedure} char-set-count pred cs -Return the number of the elements int the character set -@var{cs} which satisfy the predicate @var{pred}. -@end deffn - -@deffn {Scheme Procedure} char-set->list cs -Return a list containing the elements of the character set -@var{cs}. -@end deffn - -@deffn {Scheme Procedure} char-set->string cs -Return a string containing the elements of the character set -@var{cs}. The order in which the characters are placed in the -string is not defined. -@end deffn - -@deffn {Scheme Procedure} char-set-contains? cs char -Return @code{#t} iff the character @var{ch} is contained in the -character set @var{cs}. -@end deffn - -@deffn {Scheme Procedure} char-set-every pred cs -Return a true value if every character in the character set -@var{cs} satisfies the predicate @var{pred}. -@end deffn - -@deffn {Scheme Procedure} char-set-any pred cs -Return a true value if any character in the character set -@var{cs} satisfies the predicate @var{pred}. -@end deffn - - -@c =================================================================== - -@node SRFI-14 Character-Set Algebra -@subsection Character-Set Algebra - -Character sets can be manipulated with the common set algebra operation, -such as union, complement, intersection etc. All of these procedures -provide side-effecting variants, which modify their character set -argument(s). - -@deffn {Scheme Procedure} char-set-adjoin cs char1 @dots{} -@deffnx {Scheme Procedure} char-set-adjoin! cs char1 @dots{} -Add all character arguments to the first argument, which must -be a character set. -@end deffn - -@deffn {Scheme Procedure} char-set-delete cs char1 @dots{} -@deffnx {Scheme Procedure} char-set-delete! cs char1 @dots{} -Delete all character arguments from the first argument, which -must be a character set. -@end deffn - -@deffn {Scheme Procedure} char-set-complement cs -@deffnx {Scheme Procedure} char-set-complement! cs -Return the complement of the character set @var{cs}. -@end deffn - -@deffn {Scheme Procedure} char-set-union cs1 @dots{} -@deffnx {Scheme Procedure} char-set-union! cs1 @dots{} -Return the union of all argument character sets. -@end deffn - -@deffn {Scheme Procedure} char-set-intersection cs1 @dots{} -@deffnx {Scheme Procedure} char-set-intersection! cs1 @dots{} -Return the intersection of all argument character sets. -@end deffn - -@deffn {Scheme Procedure} char-set-difference cs1 @dots{} -@deffnx {Scheme Procedure} char-set-difference! cs1 @dots{} -Return the difference of all argument character sets. -@end deffn - -@deffn {Scheme Procedure} char-set-xor cs1 @dots{} -@deffnx {Scheme Procedure} char-set-xor! cs1 @dots{} -Return the exclusive-or of all argument character sets. -@end deffn - -@deffn {Scheme Procedure} char-set-diff+intersection cs1 @dots{} -@deffnx {Scheme Procedure} char-set-diff+intersection! cs1 @dots{} -Return the difference and the intersection of all argument -character sets. -@end deffn - - -@c =================================================================== - -@node SRFI-14 Standard Character Sets -@subsection Standard Character Sets - -In order to make the use of the character set data type and procedures -useful, several predefined character set variables exist. - -@defvar char-set:lower-case -All lower-case characters. -@end defvar - -@defvar char-set:upper-case -All upper-case characters. -@end defvar - -@defvar char-set:title-case -This is empty, because ASCII has no titlecase characters. -@end defvar - -@defvar char-set:letter -All letters, e.g. the union of @code{char-set:lower-case} and -@code{char-set:upper-case}. -@end defvar - -@defvar char-set:digit -All digits. -@end defvar - -@defvar char-set:letter+digit -The union of @code{char-set:letter} and @code{char-set:digit}. -@end defvar - -@defvar char-set:graphic -All characters which would put ink on the paper. -@end defvar - -@defvar char-set:printing -The union of @code{char-set:graphic} and @code{char-set:whitespace}. -@end defvar - -@defvar char-set:whitespace -All whitespace characters. -@end defvar - -@defvar char-set:blank -All horizontal whitespace characters, that is @code{#\space} and -@code{#\tab}. -@end defvar - -@defvar char-set:iso-control -The ISO control characters with the codes 0--31 and 127. -@end defvar - -@defvar char-set:punctuation -The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}} -@end defvar - -@defvar char-set:symbol -The characters @code{$+<=>^`|~}. -@end defvar - -@defvar char-set:hex-digit -The hexadecimal digits @code{0123456789abcdefABCDEF}. -@end defvar - -@defvar char-set:ascii -All ASCII characters. -@end defvar - -@defvar char-set:empty -The empty character set. -@end defvar - -@defvar char-set:full -This character set contains all possible characters. -@end defvar - -@node SRFI-16 -@section SRFI-16 - case-lambda - -@c FIXME::martin: Review me! - -The syntactic form @code{case-lambda} creates procedures, just like -@code{lambda}, but has syntactic extensions for writing procedures of -varying arity easier. - -The syntax of the @code{case-lambda} form is defined in the following -EBNF grammar. - -@example -@group -<case-lambda> - --> (case-lambda <case-lambda-clause>) -<case-lambda-clause> - --> (<formals> <definition-or-command>*) -<formals> - --> (<identifier>*) - | (<identifier>* . <identifier>) - | <identifier> -@end group -@end example - -The value returned by a @code{case-lambda} form is a procedure which -matches the number of actual arguments against the formals in the -various clauses, in order. @dfn{Formals} means a formal argument list -just like with @code{lambda} (@pxref{Lambda}). The first matching clause -is selected, the corresponding values from the actual parameter list are -bound to the variable names in the clauses and the body of the clause is -evaluated. If no clause matches, an error is signalled. - -The following (silly) definition creates a procedure @var{foo} which -acts differently, depending on the number of actual arguments. If one -argument is given, the constant @code{#t} is returned, two arguments are -added and if more arguments are passed, their product is calculated. - -@lisp -(define foo (case-lambda - ((x) #t) - ((x y) (+ x y)) - (z - (apply * z)))) -(foo 'bar) -@result{} -#t -(foo 2 4) -@result{} -6 -(foo 3 3 3) -@result{} -27 -(foo) -@result{} -1 -@end lisp - -The last expression evaluates to 1 because the last clause is matched, -@var{z} is bound to the empty list and the following multiplication, -applied to zero arguments, yields 1. - - -@node SRFI-17 -@section SRFI-17 - Generalized set! - -This is an implementation of SRFI-17: Generalized set! - -It exports the Guile procedure @code{make-procedure-with-setter} under -the SRFI name @code{getter-with-setter} and exports the standard -procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr}, -@code{string-ref} and @code{vector-ref} as procedures with setters, as -required by the SRFI. - -SRFI-17 was heavily criticized during its discussion period but it was -finalized anyway. One issue was its concept of globally associating -setter @dfn{properties} with (procedure) values, which is non-Schemy. -For this reason, this implementation chooses not to provide a way to set -the setter of a procedure. In fact, @code{(set! (setter @var{proc}) -@var{setter})} signals an error. The only way to attach a setter to a -procedure is to create a new object (a @dfn{procedure with setter}) via -the @code{getter-with-setter} procedure. This procedure is also -specified in the SRFI. Using it avoids the described problems. - - -@node SRFI-19 -@section SRFI-19 - Time/Date Library - -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 section documents constants and procedure signatures. - -@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:: -@end menu - -@node SRFI-19 Constants -@subsection SRFI-19 Constants - -All these are bound to their symbol names: - -@example - time-duration - time-monotonic - time-process - time-tai - time-thread - time-utc -@end example - -@node SRFI-19 Current time and clock resolution -@subsection SRFI-19 Current time and clock resolution - -@example - (current-date . tz-offset) - (current-julian-day) - (current-modified-julian-day) - (current-time . clock-type) - (time-resolution . clock-type) -@end example - -@node SRFI-19 Time object and accessors -@subsection SRFI-19 Time object and accessors - -@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) -@end example - -@node SRFI-19 Time comparison procedures -@subsection SRFI-19 Time comparison procedures - -Args are all @code{time} values. - -@example - (time<=? t1 t2) - (time<? t1 t2) - (time=? t1 t2) - (time>=? t1 t2) - (time>? t1 t2) -@end example - -@node SRFI-19 Time arithmetic procedures -@subsection SRFI-19 Time arithmetic procedures - -The @code{foo!} variants modify in place. Time difference -is expressed in @code{time-duration} values. - -@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 - -@node SRFI-19 Date object and accessors -@subsection SRFI-19 Date object and accessors - -@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) -@end example - -@node SRFI-19 Time/Date/Julian Day/Modified Julian Day converters -@subsection SRFI-19 Time/Date/Julian Day/Modified Julian Day converters - -@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) -@end example - -@node SRFI-19 Date to string/string to date converters -@subsection SRFI-19 Date to string/string to date converters - -@example - (date->string date . format-string) - (string->date input-string template-string) -@end example - -@c srfi-modules.texi ends here |