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 http://srfi.schemers.org.

About SRFI Usage
================

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 cond-expand (see 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 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 (see 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 use-modules someday in the future to access SRFI-6 bindings.  If you want, you can do that already.  We have included the module (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 (srfi srfi-NUMBER), where NUMBER is the number of the SRFI needed.  Another possibility is to use the command line option --use-srfi, which will load the necessary modules automatically (see Invoking Guile).

SRFI-0 - cond-expand
====================

SRFI-0 defines a means for checking whether a Scheme implementation has support for a specified feature.  The syntactic form cond-expand, which implements this means, has the following syntax.

     <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>

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:

  * If it is a symbol, it is satisfied if the feature identifier is supported.

  * If it is an and form, all requirements must be satisfied.  If no requirements are given, it is satisfied, too.

  * If it is an or form, at least one of the requirements must be satisfied.  If no requirements are given, it is not satisfied.

  * If it is a not form, the feature requirement must not be satisfied.

  * If the feature requirement is the keyword else and it is the last clause, it is satisfied if no prior clause matched.

If no clause is satisfied, an error is signalled.

Since cond-expand is needed to tell what a Scheme implementation provides, it must be accessible without using any implementation-dependent operations, such as use-modules in Guile.  Thus, it is not necessary to use any module to get access to this form.

Currently, the feature identifiers guile, r5rs and 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:

     (cond-expand
       (guile
         (use-modules (srfi srfi-8)))
       (srfi-8
         #t))
       ;; otherwise fail.

The other possibility is to use the --use-srfi command line option when invoking Guile (see 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 cond-expand.

So, if you invoke Guile like this:

     $ guile --use-srfi=8

the following snippet will expand to 'hooray.

     (cond-expand (srfi-8 'hooray))

SRFI-1 - List library
=====================

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 Lists and Pairs.

Constructors
------------

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

 -- Scheme Procedure: xcons d a
     Like cons, but with interchanged arguments.  Useful mostly when passed to higher-order procedures.

 -- Scheme Procedure: list-tabulate n init-proc
     Return an N-element list, where each list element is produced by applying the procedure INIT-PROC to the corresponding list index.  The order in which INIT-PROC is applied to the indices is not specified.

 -- Scheme Procedure: circular-list elt1 elt2 ...
     Return a circular list containing the given arguments ELT1 ELT2 ....

 -- Scheme Procedure: iota count [start step]
     Return a list containing COUNT elements, where each element is calculated as follows:

     START + (COUNT - 1) * STEP

     START defaults to 0 and STEP defaults to 1.

Predicates
----------

The procedures in this section test specific properties of lists.

 -- Scheme Procedure: proper-list? obj
     Return #t if OBJ is a proper list, that is a finite list, terminated with the empty list.  Otherwise, return #f.

 -- Scheme Procedure: circular-list? obj
     Return #t if OBJ is a circular list, otherwise return #f.

 -- Scheme Procedure: dotted-list? obj
     Return #t if OBJ is a dotted list, return #f otherwise.  A dotted list is a finite list which is not terminated by the empty list, but some other value.

 -- Scheme Procedure: null-list? lst
     Return #t if LST is the empty list (), #f otherwise.  If something else than a proper or circular list is passed as 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.

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

 -- Scheme Procedure: list= elt= list1 ...
     Return #t if all argument lists are equal, #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 ELT=.  If no or only one list is given, #t is returned.

Selectors
---------

 -- Scheme Procedure: first pair
 -- Scheme Procedure: second pair
 -- Scheme Procedure: third pair
 -- Scheme Procedure: fourth pair
 -- Scheme Procedure: fifth pair
 -- Scheme Procedure: sixth pair
 -- Scheme Procedure: seventh pair
 -- Scheme Procedure: eighth pair
 -- Scheme Procedure: ninth pair
 -- Scheme Procedure: tenth pair
     These are synonyms for car, cadr, caddr, ....

 -- Scheme Procedure: car+cdr pair
     Return two values, the CAR and the CDR of PAIR.

 -- Scheme Procedure: take lst i
 -- Scheme Procedure: take! lst i
     Return a list containing the first I elements of LST.

     take! may modify the structure of the argument list LST in order to produce the result.

 -- Scheme Procedure: drop lst i
     Return a list containing all but the first I elements of LST.

 -- Scheme Procedure: take-right lst i
     Return the a list containing the I last elements of LST.

 -- Scheme Procedure: drop-right lst i
 -- Scheme Procedure: drop-right! lst i
     Return the a list containing all but the I last elements of LST.

     drop-right! may modify the structure of the argument list LST in order to produce the result.

 -- Scheme Procedure: split-at lst i
 -- Scheme Procedure: split-at! lst i
     Return two values, a list containing the first I elements of the list LST and a list containing the remaining elements.

     split-at! may modify the structure of the argument list LST in order to produce the result.

 -- Scheme Procedure: last lst
     Return the last element of the non-empty, finite list LST.

Length, Append, Concatenate, etc.
---------------------------------

 -- Scheme Procedure: length+ lst
     Return the length of the argument list LST.  When LST is a circular list, #f is returned.

 -- Scheme Procedure: concatenate list-of-lists
 -- Scheme Procedure: concatenate! list-of-lists
     Construct a list by appending all lists in LIST-OF-LISTS.

     concatenate! may modify the structure of the given lists in order to produce the result.

 -- Scheme Procedure: append-reverse rev-head tail
 -- Scheme Procedure: append-reverse! rev-head tail
     Reverse REV-HEAD, append TAIL and return the result.  This is equivalent to (append (reverse REV-HEAD) TAIL), but more efficient.

     append-reverse! may modify REV-HEAD in order to produce the result.

 -- Scheme Procedure: zip lst1 lst2 ...
     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.

 -- Scheme Procedure: unzip1 lst
 -- Scheme Procedure: unzip2 lst
 -- Scheme Procedure: unzip3 lst
 -- Scheme Procedure: unzip4 lst
 -- Scheme Procedure: unzip5 lst
     unzip1 takes a list of lists, and returns a list containing the first elements of each list, 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.

 -- Scheme Procedure: count pred lst1 ... lstN
     Return a count of the number of times PRED returns true when called on elements from the given lists.

     PRED is called with N parameters (PRED ELEM1 ... ELEMN), each element being from the corresponding LST1 ... 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.

Fold, Unfold & Map
------------------

 -- Scheme Procedure: fold kons knil lst1 lst2 ...
     Fold the procedure KONS across all elements of LST1, LST2, ....  Produce the result of

     (KONS EN1 EN2 ... (KONS E21 E22 (KONS E11 E12 KNIL))),

     if ENM are the elements of the lists LST1, LST2, ....

 -- Scheme Procedure: fold-right kons knil lst1 lst2 ...
     Similar to fold, but applies KONS in right-to-left order to the list elements, that is:

     (KONS E11 E12(KONS E21 E22  ... (KONS EN1 EN2 KNIL))),

 -- Scheme Procedure: pair-fold kons knil lst1 lst2 ...
     Like fold, but apply KONS to the pairs of the list instead of the list elements.

 -- Scheme Procedure: pair-fold-right kons knil lst1 lst2 ...
     Like fold-right, but apply KONS to the pairs of the list instead of the list elements.

 -- Scheme Procedure: reduce f ridentity lst
     reduce is a variant of fold.  If LST is (), RIDENTITY is returned.  Otherwise, (fold f (car LST) (cdr LST)) is returned.

 -- Scheme Procedure: reduce-right f ridentity lst
     This is the fold-right variant of reduce.

 -- Scheme Procedure: unfold p f g seed [tail-gen]
     unfold is defined as follows:

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

     p
          Determines when to stop unfolding.

     f
          Maps each seed value to the corresponding list element.

     g
          Maps each seed value to next seed valu.

     seed
          The state value for the unfold.

     tail-gen
          Creates the tail of the list; defaults to (lambda (x) '()).

     G produces a series of seed values, which are mapped to list elements by F.  These elements are put into a list in left-to-right order, and P tells when to stop unfolding.

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

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

     p
          Determines when to stop unfolding.

     f
          Maps each seed value to the corresponding list element.

     g
          Maps each seed value to next seed valu.

     seed
          The state value for the unfold.

     tail-gen
          Creates the tail of the list; defaults to (lambda (x) '()).

 -- Scheme Procedure: map f lst1 lst2 ...
     Map the procedure over the list(s) LST1, LST2, ... 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 F will be applied to the list element(s) is not specified.

 -- Scheme Procedure: for-each f lst1 lst2 ...
     Apply the procedure F to each pair of corresponding elements of the list(s) LST1, LST2, ....  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 F is called.  F will be applied to the list elements in left-to-right order.

 -- Scheme Procedure: append-map f lst1 lst2 ...
 -- Scheme Procedure: append-map! f lst1 lst2 ...
     Equivalent to

          (apply append (map f clist1 clist2 ...))

     and

          (apply append! (map f clist1 clist2 ...))

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

     The dynamic order in which the various applications of F are made is not specified.

 -- Scheme Procedure: map! f lst1 lst2 ...
     Linear-update variant of map -- map! is allowed, but not required, to alter the cons cells of LST1 to construct the result list.

     The dynamic order in which the various applications of F are made is not specified. In the n-ary case, LST2, LST3, ... must have at least as many elements as LST1.

 -- Scheme Procedure: pair-for-each f lst1 lst2 ...
     Like for-each, but applies the procedure F to the pairs from which the argument lists are constructed, instead of the list elements.  The return value is not specified.

 -- Scheme Procedure: filter-map f lst1 lst2 ...
     Like map, but only results from the applications of F which are true are saved in the result list.

Filtering and Partitioning
--------------------------

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.

 -- Scheme Procedure: filter pred lst
 -- Scheme Procedure: filter! pred lst
     Return a list containing all elements from LST which satisfy the predicate PRED.  The elements in the result list have the same order as in LST.  The order in which PRED is applied to the list elements is not specified.

     filter! is allowed, but not required to modify the structure of

 -- Scheme Procedure: partition pred lst
 -- Scheme Procedure: partition! pred lst
     Return two lists, one containing all elements from LST which satisfy the predicate 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 LST.  The order in which PRED is applied to the list elements is not specified.

     partition! is allowed, but not required to modify the structure of the input list.

 -- Scheme Procedure: remove pred lst
 -- Scheme Procedure: remove! pred lst
     Return a list containing all elements from LST which do not satisfy the predicate PRED.  The elements in the result list have the same order as in LST.  The order in which PRED is applied to the list elements is not specified.

     remove! is allowed, but not required to modify the structure of the input list.

Searching
---------

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

 -- Scheme Procedure: find pred lst
     Return the first element of LST which satisfies the predicate PRED and #f if no such element is found.

 -- Scheme Procedure: find-tail pred lst
     Return the first pair of LST whose CAR satisfies the predicate PRED and #f if no such element is found.

 -- Scheme Procedure: take-while pred lst
 -- Scheme Procedure: take-while! pred lst
     Return the longest initial prefix of LST whose elements all satisfy the predicate PRED.

     take-while! is allowed, but not required to modify the input list while producing the result.

 -- Scheme Procedure: drop-while pred lst
     Drop the longest initial prefix of LST whose elements all satisfy the predicate PRED.

 -- Scheme Procedure: span pred lst
 -- Scheme Procedure: span! pred lst
 -- Scheme Procedure: break pred lst
 -- Scheme Procedure: break! pred lst
     span splits the list LST into the longest initial prefix whose elements all satisfy the predicate PRED, and the remaining tail.  break inverts the sense of the predicate.

     span! and break! are allowed, but not required to modify the structure of the input list LST in order to produce the result.

 -- Scheme Procedure: any pred lst1 lst2 ...
     Apply PRED across the lists and return a true value if the predicate returns true for any of the list elements(s); return #f otherwise.  The true value returned is always the result of the first successful application of PRED.

 -- Scheme Procedure: every pred lst1 lst2 ...
     Apply PRED across the lists and return a true value if the predicate returns true for every of the list elements(s); return #f otherwise.  The true value returned is always the result of the final successful application of PRED.

 -- Scheme Procedure: list-index pred lst1 lst2 ...
     Return the index of the leftmost element that satisfies PRED.

 -- Scheme Procedure: member x lst [=]
     Return the first sublist of LST whose CAR is equal to X.  If X does no appear in LST, return #f. Equality is determined by the equality predicate =, or equal? if = is not given.

Deleting
--------

 -- Scheme Procedure: delete x lst [=]
 -- Scheme Procedure: delete! x lst [=]
     Return a list containing the elements of LST but with those equal to X deleted.  The returned elements will be in the same order as they were in LST.

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

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

     delete does not modify LST, but the return might share a common tail with LST.  delete! may modify the structure of LST to construct its return.

 -- Scheme Procedure: delete-duplicates lst [=]
 -- Scheme Procedure: delete-duplicates! lst [=]
     Return a list containing the elements of LST but without duplicates.

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

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

     delete-duplicates does not modify LST, but the return might share a common tail with LST.  delete-duplicates! may modify the structure of LST to construct its return.

     In the worst case, this is an 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.

Association Lists
-----------------

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

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

 -- Scheme Procedure: alist-cons key datum alist
     Equivalent to

          (cons (cons KEY DATUM) ALIST)

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

 -- Scheme Procedure: alist-copy alist
     Return a newly allocated copy of ALIST, that means that the spine of the list as well as the pairs are copied.

 -- Scheme Procedure: alist-delete key alist [=]
 -- Scheme Procedure: alist-delete! key alist [=]
     Return a list containing the pairs of ALIST, but without the pairs whose CARS are equal to KEY.  Equality is determined by =, which defaults to equal? if not given.

     alist-delete! is allowed, but not required to modify the structure of the list ALIST in order to produce the result.

Set Operations on Lists
-----------------------

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.

 -- Scheme Procedure: lset<= = list1 ...
     Return #t if every LISTI is a subset of LISTI+1, otherwise return #f.  Returns #t if called with less than two arguments. = is used for testing element equality.

 -- Scheme Procedure: lset= = list1 list2 ...
     Return #t if all argument lists are equal. = is used for testing element equality.

 -- Scheme Procedure: lset-adjoin = list elt1 ...
 -- Scheme Procedure: lset-adjoin! = list elt1 ...
     Add all ELTS to the list LIST, suppressing duplicates and return the resulting list.  lset-adjoin! is allowed, but not required to modify its first argument. = is used for testing element equality.

 -- Scheme Procedure: lset-union = list1 ...
 -- Scheme Procedure: lset-union! = list1 ...
     Return the union of all argument list sets.  The union is the set of all elements which appear in any of the argument sets. lset-union! is allowed, but not required to modify its first argument. = is used for testing element equality.

 -- Scheme Procedure: lset-intersection = list1 list2 ...
 -- Scheme Procedure: lset-intersection! = list1 list2 ...
     Return the intersection of all argument list sets.  The intersection is the set containing all elements which appear in all argument sets. lset-intersection! is allowed, but not required to modify its first argument. = is used for testing element equality.

 -- Scheme Procedure: lset-difference = list1 list2 ...
 -- Scheme Procedure: lset-difference! = list1 list2 ...
     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.  lset-difference!  is allowed, but not required to modify its first argument. = is used for testing element equality.

 -- Scheme Procedure: lset-xor = list1 ...
 -- Scheme Procedure: lset-xor! = list1 ...
     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.  lset-xor!  is allowed, but not required to modify its first argument. = is used for testing element equality.

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

SRFI-2 - and-let*
=================

The following syntax can be obtained with

     (use-modules (srfi srfi-2))

 -- library syntax: and-let* (clause ...) body ...
     A combination of and and let*.

     Each CLAUSE is evaluated in turn, and if #f is obtained then evaluation stops and #f is returned.  If all are non-#f then BODY is evaluated and the last form gives the return value.  Each CLAUSE should be one of the following,

     (symbol expr)
          Evaluate EXPR, check for #f, and bind it to SYMBOL. Like let*, that binding is available to subsequent clauses.

     (expr)
          Evaluate EXPR and check for #f.

     symbol
          Get the value bound to SYMBOL and check for #f.

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

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

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

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

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

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

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

SRFI-4 - Homogeneous numeric vector datatypes.
==============================================

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 (see 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 (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 u8, s8, u16, s16, u32, s32, u64, s64, f32, f64, respectively, are used for denoting the various types.

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.

     #u16(1 2 3)

denotes a homogeneous numeric vector of three elements, which are the values 1, 2 and 3, represented as 16-bit unsigned integers. Correspondingly,

     #f64(3.1415 2.71)

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 #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

     '(1 #f3)

and hope that it will be parsed as a three-element list with the elements 1, #f and 3.  In normal use, this should be no problem, because people tend to terminate tokens sensibly when writing Scheme expressions.

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 TAG by any of the datatype indicators u8, s8, u16, s16, u32, s32, u64, s64, f32 and f64.

For example, you can use the procedures u8vector?, make-s8vector, u16vector, u32vector-length, s64vector-ref, f32vector-set! or f64vector->list.

 -- Scheme Procedure: TAGvector? obj
     Return #t if OBJ is a homogeneous numeric vector of type TAG.

 -- Scheme Procedure: make-TAGvector n [value]
     Create a newly allocated homogeneous numeric vector of type TAG, which can hold N elements.  If VALUE is given, the vector is initialized with the value, otherwise, the contents of the returned vector is not specified.

 -- Scheme Procedure: TAGvector value1 ...
     Create a newly allocated homogeneous numeric vector of type TAG. The returned vector is as long as the number of arguments given, and is initialized with the argument values.

 -- Scheme Procedure: TAGvector-length TAGvec
     Return the number of elements in TAGVEC.

 -- Scheme Procedure: TAGvector-ref TAGvec i
     Return the element at index I in TAGVEC.

 -- Scheme Procedure: TAGvector-ref TAGvec i value
     Set the element at index I in TAGVEC to VALUE.  The return value is not specified.

 -- Scheme Procedure: TAGvector->list TAGvec
     Return a newly allocated list holding all elements of TAGVEC.

 -- Scheme Procedure: list->TAGvector lst
     Return a newly allocated homogeneous numeric vector of type TAG, initialized with the elements of the list LST.

SRFI-6 - Basic String Ports
===========================

SRFI-6 defines the procedures open-input-string, open-output-string and 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.

SRFI-8 - receive
================

receive is a syntax for making the handling of multiple-value procedures easier.  It is documented in see Multiple Values.

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 (see 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:

     <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>

Usage 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

SRFI-10 - Hash-Comma Reader Extension
=====================================

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

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

     #,(CTOR DATUM ...)

where CTOR must be a symbol for which a read constructor was defined previously, using define-reader-ctor.

Example:

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

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

 -- Scheme Procedure: define-reader-ctor symbol proc
     Define PROC as the reader constructor for hash-comma forms with a tag SYMBOL.  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 PROC is returned by the Scheme reader.

SRFI-11 - let-values
====================

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

Write (use-modules (srfi srfi-11)) to make the bindings available.

     (let-values (((x y) (values 1 2))
                  ((z f) (values 3 4)))
        (+ x y z f))
     =>
     10

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.  let-values*, on the other hand, performs the bindings sequentially, just like let* does for single-valued expressions.

SRFI-13 - String Library
========================

In this section, we will describe all procedures defined in SRFI-13 (string library) and implemented by the module (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 (see Strings).

All of the procedures defined in SRFI-13, which are not already included in the Guile core library, are implemented in the module (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 Low-level procedures of SRFI-13 for parsing optional string indices, substring specification checking and Knuth-Morris-Pratt-Searching are not implemented.

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

Loading SRFI-13
---------------

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

     $ guile
     guile> (use-modules (srfi srfi-13))
     guile>

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

One possible reason is that Guile cannot find either the Scheme module file srfi-13.scm, or it cannot find the shared object 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 /usr/local/lib or that the directory it was installed to is in your LTDL_LIBRARY_PATH.  The same applies to srfi-14.scm.

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

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

Predicates
----------

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

 -- Scheme Procedure: string-any pred s [start end]
     Check if the predicate PRED is true for any character in the string S, proceeding from left (index START) to right (index END).  If string-any returns true, the returned true value is the one produced by the first successful application of PRED.

 -- Scheme Procedure: string-every pred s [start end]
     Check if the predicate PRED is true for every character in the string S, proceeding from left (index START) to right (index END).  If string-every returns true, the returned true value is the one produced by the final application of PRED to the last character of S.

Constructors
------------

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

 -- Scheme Procedure: string-tabulate proc len
     PROC is an integer->char procedure.  Construct a string of size LEN by applying PROC to each index to produce the corresponding string element.  The order in which PROC is applied to the indices is not specified.

List/String Conversion
----------------------

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

 -- Scheme Procedure: string->list str [start end]
     Convert the string STR into a list of characters.

 -- Scheme Procedure: reverse-list->string chrs
     An efficient implementation of (compose string->list reverse):

          (reverse-list->string '(#\a #\B #\c)) => "cBa"

 -- Scheme Procedure: string-join ls [delimiter grammar]
     Append the string in the string list LS, using the string DELIM as a delimiter between the elements of LS. GRAMMAR is a symbol which specifies how the delimiter is placed between the strings, and defaults to the symbol infix.

     infix
          Insert the separator between list elements.  An empty string will produce an empty list.

     string-infix
          Like infix, but will raise an error if given the empty list.

     suffix
          Insert the separator after every list element.

     prefix
          Insert the separator before each list element.

Selection
---------

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

Additional selector procedures are documented in the Strings section (see String Selection), like string-length or string-ref.

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

 -- Scheme Procedure: string-copy str [start end]
     Return a freshly allocated copy of the string STR.  If given, START and END delimit the portion of STR which is copied.

 -- Scheme Procedure: substring/shared str start [end]
     Like substring, but the result may share memory with the argument STR.

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

 -- Scheme Procedure: string-take s n
 -- Scheme Procedure: string-take-right s n
     Return the N first/last characters of S.

 -- Scheme Procedure: string-drop s n
 -- Scheme Procedure: string-drop-right s n
     Return all but the first/last N characters of S.

 -- Scheme Procedure: string-pad s len [chr start end]
 -- Scheme Procedure: string-pad-right s len [chr start end]
     Take that characters from START to END from the string S and return a new string, right(left)-padded by the character CHR to length LEN.  If the resulting string is longer than LEN, it is truncated on the right (left).

 -- Scheme Procedure: string-trim s [char_pred start end]
 -- Scheme Procedure: string-trim-right s [char_pred start end]
 -- Scheme Procedure: string-trim-both s [char_pred start end]
     Trim S by skipping over all characters on the left/right/both sides of the string that satisfy the parameter CHAR_PRED:

       * if it is the character CH, characters equal to CH are trimmed,

       * if it is a procedure PRED characters that satisfy PRED are trimmed,

       * if it is a character set, characters in that set are trimmed.

     If called without a CHAR_PRED argument, all whitespace is trimmed.

Modification
------------

The procedure 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 string-set! is documented in the Strings section (see String Modification).

 -- Scheme Procedure: string-fill! str chr [start end]
     Stores CHR in every element of the given STR and returns an unspecified value.

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 #t or #f, but the mismatch index in the case of a true return value.

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

 -- Scheme Procedure: string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
 -- Scheme Procedure: string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
     Apply PROC_LT, PROC_EQ, PROC_GT to the mismatch index, depending upon whether S1 is less than, equal to, or greater than S2.  The mismatch index is the largest index I such that for every 0 <= J < I, S1[J] = S2[J] - that is, I is the first position that does not match.  The character comparison is done case-insensitively.

 -- Scheme Procedure: string= s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string<> s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string< s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string> s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string<= s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string>= s1 s2 [start1 end1 start2 end2]
     Compare S1 and S2 and return #f if the predicate fails.  Otherwise, the mismatch index is returned (or END1 in the case of string=.

 -- Scheme Procedure: string-ci= s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string-ci<> s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string-ci< s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string-ci> s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string-ci<= s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string-ci>= s1 s2 [start1 end1 start2 end2]
     Compare S1 and S2 and return #f if the predicate fails.  Otherwise, the mismatch index is returned (or END1 in the case of string=.  These are the case-insensitive variants.

 -- Scheme Procedure: string-hash s [bound start end]
 -- Scheme Procedure: string-hash-ci s [bound start end]
     Return a hash value of the string S in the range 0 ... BOUND - 1.  string-hash-ci is the case-insensitive variant.

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.

 -- Scheme Procedure: string-prefix-length s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string-prefix-length-ci s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string-suffix-length s1 s2 [start1 end1 start2 end2]
 -- 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. string-prefix-length-ci and string-suffix-length-ci are the case-insensitive variants.

 -- Scheme Procedure: string-prefix? s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string-prefix-ci? s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string-suffix? s1 s2 [start1 end1 start2 end2]
 -- Scheme Procedure: string-suffix-ci? s1 s2 [start1 end1 start2 end2]
     Is S1 a prefix/suffix of S2. string-prefix-ci? and string-suffix-ci? are the case-insensitive variants.

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.

 -- Scheme Procedure: string-index s char_pred [start end]
 -- Scheme Procedure: string-index-right s char_pred [start end]
     Search through the string S from left to right (right to left), returning the index of the first (last) occurrence of a character which

       * equals CHAR_PRED, if it is character,

       * satisfies the predicate CHAR_PRED, if it is a procedure,

       * is in the set CHAR_PRED, if it is a character set.

 -- Scheme Procedure: string-skip s char_pred [start end]
 -- Scheme Procedure: string-skip-right s char_pred [start end]
     Search through the string S from left to right (right to left), returning the index of the first (last) occurrence of a character which

       * does not equal CHAR_PRED, if it is character,

       * does not satisfy the predicate CHAR_PRED, if it is a procedure.

       * is not in the set if CHAR_PRED is a character set.

 -- Scheme Procedure: string-count s char_pred [start end]
     Return the count of the number of characters in the string S which

       * equals CHAR_PRED, if it is character,

       * satisfies the predicate CHAR_PRED, if it is a procedure.

       * is in the set CHAR_PRED, if it is a character set.

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

     string-contains-ci is the case-insensitive variant.

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.

 -- Scheme Procedure: string-upcase s [start end]
 -- Scheme Procedure: string-upcase! s [start end]
     Upcase every character in S.  string-upcase! is the side-effecting variant.

 -- Scheme Procedure: string-downcase s [start end]
 -- Scheme Procedure: string-downcase! s [start end]
     Downcase every character in S.  string-downcase! is the side-effecting variant.

 -- Scheme Procedure: string-titlecase s [start end]
 -- Scheme Procedure: string-titlecase! s [start end]
     Upcase every first character in every word in S, downcase the other characters.  string-titlecase! is the side-effecting variant.

Reverse/Append
--------------

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

 -- Scheme Procedure: string-reverse str [start end]
 -- Scheme Procedure: string-reverse! str [start end]
     Reverse the string STR.  The optional arguments START and END delimit the region of STR to operate on.

     string-reverse! modifies the argument string and returns an unspecified value.

 -- Scheme Procedure: string-append/shared ls ...
     Like string-append, but the result may share memory with the argument strings.

 -- Scheme Procedure: string-concatenate ls
     Append the elements of LS (which must be strings) together into a single string.  Guaranteed to return a freshly allocated string.

 -- Scheme Procedure: string-concatenate/shared ls
     Like string-concatenate, but the result may share memory with the strings in the list LS.

 -- Scheme Procedure: string-concatenate-reverse ls final_string end
     Without optional arguments, this procedure is equivalent to

          (string-concatenate (reverse ls))

     If the optional argument FINAL_STRING is specified, it is consed onto the beginning to LS before performing the list-reverse and string-concatenate operations.  If END is given, only the characters of FINAL_STRING up to index END are used.

     Guaranteed to return a freshly allocated string.

 -- Scheme Procedure: string-concatenate-reverse/shared ls final_string end
     Like string-concatenate-reverse, but the result may share memory with the the strings in the LS arguments.

Fold/Unfold/Map
---------------

string-map, 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.

 -- Scheme Procedure: string-map proc s [start end]
     PROC is a char->char procedure, it is mapped over S.  The order in which the procedure is applied to the string elements is not specified.

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

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

 -- Scheme Procedure: string-unfold p f g seed [base make_final]
 -- Scheme Procedure: string-unfold-right p f g seed [base make_final]
     These are the fundamental string constructors.

       * G is used to generate a series of seed values from the initial SEED: SEED, (G SEED), (G^2 SEED), (G^3 SEED), ...

       * P tells us when to stop - when it returns true when applied to one of these seed values.

       * 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.

       * BASE is the optional initial/leftmost (rightmost) portion of the constructed string; it default to the empty string.

       * MAKE_FINAL is applied to the terminal seed value (on which P returns true) to produce the final/rightmost (leftmost) portion of the constructed string.  It defaults to (lambda (x) "").

 -- Scheme Procedure: string-for-each proc s [start end]
     PROC is mapped over S in left-to-right order.  The return value is not specified.

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 "foo" so often that the resulting string has a length of six.

     (xsubstring "foo" 0 6)
     =>
     "foofoo"

 -- Scheme Procedure: xsubstring s from [to start end]
     This is the extended substring procedure that implements replicated copying of a substring of some string.

     S is a string, START and END are optional arguments that demarcate a substring of S, defaulting to 0 and the length of S.  Replicate this substring up and down index space, in both the positive and negative directions. xsubstring returns the substring of this string beginning at index FROM, and ending at TO, which defaults to FROM + (END - START).

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

Miscellaneous
-------------

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

 -- Scheme Procedure: string-replace s1 s2 [start1 end1 start2 end2]
     Return the string S1, but with the characters START1 ... END1 replaced by the characters START2 ... END2 from S2.

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

Filtering/Deleting
------------------

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

 -- Scheme Procedure: string-filter s char_pred [start end]
     Filter the string S, retaining only those characters that satisfy the 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.

 -- Scheme Procedure: string-delete s char_pred [start end]
     Filter the string S, retaining only those characters that do not satisfy the 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.

SRFI-14 - Character-set Library
===============================

SRFI-14 defines the data type 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 (srfi srfi-14), as well as the standard variables char-set:letter, char-set:digit etc.

Loading SRFI-14
---------------

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

     $ 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>

Character Set Data Type
-----------------------

The data type charset implements sets of characters (see 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 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''.

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. char-set-hash can be used for calculating a hash value, maybe for usage in fast lookup procedures.

 -- Scheme Procedure: char-set? obj
     Return #t if OBJ is a character set, #f otherwise.

 -- Scheme Procedure: char-set= cs1 ...
     Return #t if all given character sets are equal.

 -- Scheme Procedure: char-set<= cs1 ...
     Return #t if every character set CSi is a subset of character set CSi+1.

 -- Scheme Procedure: char-set-hash cs [bound]
     Compute a hash value for the character set CS.  If BOUND is given and not #f, it restricts the returned value to the range 0 ... BOUND - 1.

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 char-set-cursor, a cursor can be dereferenced with char-set-ref, advanced to the next member with char-set-cursor-next.  Whether a cursor has passed past the last element of the set can be checked with end-of-char-set?.

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

 -- Scheme Procedure: char-set-cursor cs
     Return a cursor into the character set CS.

 -- Scheme Procedure: char-set-ref cs cursor
     Return the character at the current cursor position CURSOR in the character set CS.  It is an error to pass a cursor for which end-of-char-set? returns true.

 -- Scheme Procedure: char-set-cursor-next cs cursor
     Advance the character set cursor CURSOR to the next character in the character set CS.  It is an error if the cursor given satisfies end-of-char-set?.

 -- Scheme Procedure: end-of-char-set? cursor
     Return #t if CURSOR has reached the end of a character set, #f otherwise.

 -- Scheme Procedure: char-set-fold kons knil cs
     Fold the procedure KONS over the character set CS, initializing it with KNIL.

 -- Scheme Procedure: char-set-unfold p f g seed [base_cs]
 -- Scheme Procedure: char-set-unfold! p f g seed base_cs
     This is a fundamental constructor for character sets.

       * G is used to generate a series of ``seed'' values from the initial seed: SEED, (G SEED), (G^2 SEED), (G^3 SEED), ...

       * P tells us when to stop -- when it returns true when applied to one of the seed values.

       * F maps each seed value to a character. These characters are added to the base character set BASE_CS to form the result; BASE_CS defaults to the empty set.

     char-set-unfold! is the side-effecting variant.

 -- Scheme Procedure: char-set-for-each proc cs
     Apply PROC to every character in the character set CS.  The return value is not specified.

 -- Scheme Procedure: char-set-map proc cs
     Map the procedure PROC over every character in CS. PROC must be a character -> character procedure.

Creating Character Sets
-----------------------

New character sets are produced with these procedures.

 -- Scheme Procedure: char-set-copy cs
     Return a newly allocated character set containing all characters in CS.

 -- Scheme Procedure: char-set char1 ...
     Return a character set containing all given characters.

 -- Scheme Procedure: list->char-set char_list [base_cs]
 -- Scheme Procedure: list->char-set! char_list base_cs
     Convert the character list LIST to a character set.  If the character set BASE_CS is given, the character in this set are also included in the result.

     list->char-set! is the side-effecting variant.

 -- Scheme Procedure: string->char-set s [base_cs]
 -- Scheme Procedure: string->char-set! s base_cs
     Convert the string STR to a character set.  If the character set BASE_CS is given, the characters in this set are also included in the result.

     string->char-set! is the side-effecting variant.

 -- Scheme Procedure: char-set-filter pred cs [base_cs]
 -- Scheme Procedure: char-set-filter! pred cs base_cs
     Return a character set containing every character from CS so that it satisfies PRED.  If provided, the characters from BASE_CS are added to the result.

     char-set-filter! is the side-effecting variant.

 -- Scheme Procedure: ucs-range->char-set lower upper [error? base_cs]
 -- 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 [LOWER,UPPER).

     If 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 ERROR is #f, these characters are silently left out of the resulting character set.

     The characters in BASE_CS are added to the result, if given.

     ucs-range->char-set! is the side-effecting variant.

 -- Scheme Procedure: ->char-set x
     Coerce X into a character set.  X may be a string, a character or a character set.

Querying Character Sets
-----------------------

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

 -- Scheme Procedure: char-set-size cs
     Return the number of elements in character set CS.

 -- Scheme Procedure: char-set-count pred cs
     Return the number of the elements int the character set CS which satisfy the predicate PRED.

 -- Scheme Procedure: char-set->list cs
     Return a list containing the elements of the character set CS.

 -- Scheme Procedure: char-set->string cs
     Return a string containing the elements of the character set CS.  The order in which the characters are placed in the string is not defined.

 -- Scheme Procedure: char-set-contains? cs char
     Return #t iff the character CH is contained in the character set CS.

 -- Scheme Procedure: char-set-every pred cs
     Return a true value if every character in the character set CS satisfies the predicate PRED.

 -- Scheme Procedure: char-set-any pred cs
     Return a true value if any character in the character set CS satisfies the predicate PRED.

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).

 -- Scheme Procedure: char-set-adjoin cs char1 ...
 -- Scheme Procedure: char-set-adjoin! cs char1 ...
     Add all character arguments to the first argument, which must be a character set.

 -- Scheme Procedure: char-set-delete cs char1 ...
 -- Scheme Procedure: char-set-delete! cs char1 ...
     Delete all character arguments from the first argument, which must be a character set.

 -- Scheme Procedure: char-set-complement cs
 -- Scheme Procedure: char-set-complement! cs
     Return the complement of the character set CS.

 -- Scheme Procedure: char-set-union cs1 ...
 -- Scheme Procedure: char-set-union! cs1 ...
     Return the union of all argument character sets.

 -- Scheme Procedure: char-set-intersection cs1 ...
 -- Scheme Procedure: char-set-intersection! cs1 ...
     Return the intersection of all argument character sets.

 -- Scheme Procedure: char-set-difference cs1 ...
 -- Scheme Procedure: char-set-difference! cs1 ...
     Return the difference of all argument character sets.

 -- Scheme Procedure: char-set-xor cs1 ...
 -- Scheme Procedure: char-set-xor! cs1 ...
     Return the exclusive-or of all argument character sets.

 -- Scheme Procedure: char-set-diff+intersection cs1 ...
 -- Scheme Procedure: char-set-diff+intersection! cs1 ...
     Return the difference and the intersection of all argument character sets.

Standard Character Sets
-----------------------

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

 -- Variable: char-set:lower-case
     All lower-case characters.

 -- Variable: char-set:upper-case
     All upper-case characters.

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

 -- Variable: char-set:letter
     All letters, e.g. the union of char-set:lower-case and char-set:upper-case.

 -- Variable: char-set:digit
     All digits.

 -- Variable: char-set:letter+digit
     The union of char-set:letter and char-set:digit.

 -- Variable: char-set:graphic
     All characters which would put ink on the paper.

 -- Variable: char-set:printing
     The union of char-set:graphic and char-set:whitespace.

 -- Variable: char-set:whitespace
     All whitespace characters.

 -- Variable: char-set:blank
     All horizontal whitespace characters, that is #\space and #\tab.

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

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

 -- Variable: char-set:symbol
     The characters $+<=>^`|~.

 -- Variable: char-set:hex-digit
     The hexadecimal digits 0123456789abcdefABCDEF.

 -- Variable: char-set:ascii
     All ASCII characters.

 -- Variable: char-set:empty
     The empty character set.

 -- Variable: char-set:full
     This character set contains all possible characters.

SRFI-16 - case-lambda
=====================

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

The syntax of the case-lambda form is defined in the following EBNF grammar.

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

The value returned by a case-lambda form is a procedure which matches the number of actual arguments against the formals in the various clauses, in order.  Formals means a formal argument list just like with lambda (see 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 FOO which acts differently, depending on the number of actual arguments.  If one argument is given, the constant #t is returned, two arguments are added and if more arguments are passed, their product is calculated.

     (define foo (case-lambda
                   ((x) #t)
                   ((x y) (+ x y))
                   (z
                     (apply * z))))
     (foo 'bar)
     =>
     #t
     (foo 2 4)
     =>
     6
     (foo 3 3 3)
     =>
     27
     (foo)
     =>
     1

The last expression evaluates to 1 because the last clause is matched, Z is bound to the empty list and the following multiplication, applied to zero arguments, yields 1.

SRFI-17 - Generalized set!
==========================

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

It exports the Guile procedure make-procedure-with-setter under the SRFI name getter-with-setter and exports the standard procedures car, cdr, ..., cdddr, string-ref and 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 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, (set!  (setter PROC) SETTER) signals an error.  The only way to attach a setter to a procedure is to create a new object (a procedure with setter) via the getter-with-setter procedure. This procedure is also specified in the SRFI.  Using it avoids the described problems.

SRFI-19 - Time/Date Library
===========================

This is an implementation of SRFI-19: Time/Date Library

It depends on SRFIs: 6 (see SRFI-6), 8 (see SRFI-8), 9 (see SRFI-9).

This section documents constants and procedure signatures.

SRFI-19 Constants
-----------------

All these are bound to their symbol names:

                time-duration
                time-monotonic
                time-process
                time-tai
                time-thread
                time-utc

SRFI-19 Current time and clock resolution
-----------------------------------------

                (current-date . tz-offset)
                (current-julian-day)
                (current-modified-julian-day)
                (current-time . clock-type)
                (time-resolution . clock-type)

SRFI-19 Time object and accessors
---------------------------------

                (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)

SRFI-19 Time comparison procedures
----------------------------------

Args are all time values.

                (time<=? t1 t2)
                (time<? t1 t2)
                (time=? t1 t2)
                (time>=? t1 t2)
                (time>? t1 t2)

SRFI-19 Time arithmetic procedures
----------------------------------

The foo! variants modify in place.  Time difference is expressed in time-duration values.

                (time-difference t1 t2)
                (time-difference! t1 t2)
                (add-duration time duration)
                (add-duration! time duration)
                (subtract-duration time duration)
                (subtract-duration! time duration)

SRFI-19 Date object and accessors
---------------------------------

                (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)

SRFI-19 Time/Date/Julian Day/Modified Julian Day converters
-----------------------------------------------------------

                (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)

SRFI-19 Date to string/string to date converters
------------------------------------------------

                (date->string date . format-string)
                (string->date input-string template-string)