This is guile.info, produced by makeinfo version 4.3 from guile.texi.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* Guile Reference: (guile).     The Guile reference manual.
END-INFO-DIR-ENTRY

   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation
Copyright (C) 2002 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.


File: guile.info,  Node: SRFI-1 Selectors,  Next: SRFI-1 Length Append etc,  Prev: SRFI-1 Predicates,  Up: SRFI-1

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.


File: guile.info,  Node: SRFI-1 Length Append etc,  Next: SRFI-1 Fold and Map,  Prev: SRFI-1 Selectors,  Up: SRFI-1

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.


File: guile.info,  Node: SRFI-1 Fold and Map,  Next: SRFI-1 Filtering and Partitioning,  Prev: SRFI-1 Length Append etc,  Up: SRFI-1

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 `reduce'.  If LST is `()', RIDENTITY is
     returned.  Otherwise, `(fold (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.


File: guile.info,  Node: SRFI-1 Filtering and Partitioning,  Next: SRFI-1 Searching,  Prev: SRFI-1 Fold and Map,  Up: SRFI-1

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.


File: guile.info,  Node: SRFI-1 Searching,  Next: SRFI-1 Deleting,  Prev: SRFI-1 Filtering and Partitioning,  Up: SRFI-1

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.


File: guile.info,  Node: SRFI-1 Deleting,  Next: SRFI-1 Association Lists,  Prev: SRFI-1 Searching,  Up: SRFI-1

Deleting
--------

   The procedures for deleting elements from a list either accept a
predicate or a comparison object for determining which elements are to
be removed.

 - Scheme Procedure: delete x lst [=]
 - Scheme Procedure: delete! x lst [=]
     Return a list containing all elements from LST, but without the
     elements equal to X.  Equality is determined by the equality
     predicate =, which defaults to `equal?' if not given.

     `delete!' is allowed, but not required to modify the structure of
     the argument list in order to produce the result.

 - Scheme Procedure: delete-duplicates lst [=]
 - Scheme Procedure: delete-duplicates! lst [=]
     Return a list containing all elements from LST, but without
     duplicate elements.  Equality of elements is determined by the
     equality predicate =, which defaults to `equal?' if not given.

     `delete-duplicates!' is allowed, but not required to modify the
     structure of the argument list in order to produce the result.


File: guile.info,  Node: SRFI-1 Association Lists,  Next: SRFI-1 Set Operations,  Prev: SRFI-1 Deleting,  Up: SRFI-1

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

   Association lists are described in detail in section *Note
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.


File: guile.info,  Node: SRFI-1 Set Operations,  Prev: SRFI-1 Association Lists,  Up: SRFI-1

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 (*note Multiple Values::).


File: guile.info,  Node: SRFI-2,  Next: SRFI-4,  Prev: SRFI-1,  Up: SRFI Support

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

   The syntactic form `and-let*' combines the conditional evaluation
form `and' with the binding form 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 `#f'.

   Use `(use-modules (srfi srfi-2)' to access this syntax form.

   A short example will demonstrate how it works.  In the first
expression, X will get bound to 1, but the next expression (`#f') is
false, so evaluation of the form is stopped, and `#f' is returned.  In
the next expression, X is bound to 1, Y is bound to `#t' and since no
expression in the binding section was false, the body of the `and-let*'
expression is evaluated, which in this case returns the value of X.

     (and-let* ((x 1) (y #f)) 42)
     =>
     #f
     (and-let* ((x 1) (y #t)) x)
     =>
     1


File: guile.info,  Node: SRFI-4,  Next: SRFI-6,  Prev: SRFI-2,  Up: SRFI Support

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

* Menu:

* SRFI-4 - Read Syntax::        How to write homogeneous vector literals.
* SRFI-4 - Procedures::         Available homogeneous vector procedures.


File: guile.info,  Node: SRFI-4 - Read Syntax,  Next: SRFI-4 - Procedures,  Up: SRFI-4

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.


File: guile.info,  Node: SRFI-4 - Procedures,  Prev: SRFI-4 - Read Syntax,  Up: SRFI-4

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.


File: guile.info,  Node: SRFI-6,  Next: SRFI-8,  Prev: SRFI-4,  Up: SRFI Support

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.


File: guile.info,  Node: SRFI-8,  Next: SRFI-9,  Prev: SRFI-6,  Up: SRFI Support

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

   `receive' is a syntax for making the handling of multiple-value
procedures easier.  It is documented in *Note Multiple Values::.


File: guile.info,  Node: SRFI-9,  Next: SRFI-10,  Prev: SRFI-8,  Up: SRFI Support

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 (*note 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


File: guile.info,  Node: SRFI-10,  Next: SRFI-11,  Prev: SRFI-9,  Up: SRFI Support

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:

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


File: guile.info,  Node: SRFI-11,  Next: SRFI-13,  Prev: SRFI-10,  Up: SRFI Support

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*' (*note 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.


File: guile.info,  Node: SRFI-13,  Next: SRFI-14,  Prev: SRFI-11,  Up: SRFI Support

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

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


File: guile.info,  Node: Loading SRFI-13,  Next: SRFI-13 Predicates,  Up: SRFI-13

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


File: guile.info,  Node: SRFI-13 Predicates,  Next: SRFI-13 Constructors,  Prev: Loading SRFI-13,  Up: SRFI-13

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.


File: guile.info,  Node: SRFI-13 Constructors,  Next: SRFI-13 List/String Conversion,  Prev: SRFI-13 Predicates,  Up: SRFI-13

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.


File: guile.info,  Node: SRFI-13 List/String Conversion,  Next: SRFI-13 Selection,  Prev: SRFI-13 Constructors,  Up: SRFI-13

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


File: guile.info,  Node: SRFI-13 Selection,  Next: SRFI-13 Modification,  Prev: SRFI-13 List/String Conversion,  Up: SRFI-13

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


File: guile.info,  Node: SRFI-13 Modification,  Next: SRFI-13 Comparison,  Prev: SRFI-13 Selection,  Up: SRFI-13

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 (*note String
Modification::).

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


File: guile.info,  Node: SRFI-13 Comparison,  Next: SRFI-13 Prefixes/Suffixes,  Prev: SRFI-13 Modification,  Up: SRFI-13

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.


File: guile.info,  Node: SRFI-13 Prefixes/Suffixes,  Next: SRFI-13 Searching,  Prev: SRFI-13 Comparison,  Up: SRFI-13

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.


File: guile.info,  Node: SRFI-13 Searching,  Next: SRFI-13 Case Mapping,  Prev: SRFI-13 Prefixes/Suffixes,  Up: SRFI-13

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.


File: guile.info,  Node: SRFI-13 Case Mapping,  Next: SRFI-13 Reverse/Append,  Prev: SRFI-13 Searching,  Up: SRFI-13

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.


File: guile.info,  Node: SRFI-13 Reverse/Append,  Next: SRFI-13 Fold/Unfold/Map,  Prev: SRFI-13 Case Mapping,  Up: SRFI-13

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.


File: guile.info,  Node: SRFI-13 Fold/Unfold/Map,  Next: SRFI-13 Replicate/Rotate,  Prev: SRFI-13 Reverse/Append,  Up: SRFI-13

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.


File: guile.info,  Node: SRFI-13 Replicate/Rotate,  Next: SRFI-13 Miscellaneous,  Prev: SRFI-13 Fold/Unfold/Map,  Up: SRFI-13

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.

