summaryrefslogtreecommitdiff
path: root/doc/srfi-13-14.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/srfi-13-14.texi')
-rw-r--r--doc/srfi-13-14.texi1093
1 files changed, 0 insertions, 1093 deletions
diff --git a/doc/srfi-13-14.texi b/doc/srfi-13-14.texi
index 8d96b9618..e69de29bb 100644
--- a/doc/srfi-13-14.texi
+++ b/doc/srfi-13-14.texi
@@ -1,1093 +0,0 @@
-@node SRFI-13/14
-@chapter SRFI-13 and SRFI-14
-
-This chapter documents the SRFI-13/14 library, which provides the string
-utility procedures defined in SRFI-13 and the character-set procedures
-defined in SRFI-14 for Guile.
-
-@menu
-* Introduction:: What is this all about?
-* Loading SRFI-13/14:: Loading the module into a running Guile.
-* String Functions:: Available string processing procedures.
-* Character-set Procedures:: Procedures for manipulating character sets.
-@end menu
-
-
-@c ===================================================================
-
-@node Introduction
-@section Introduction
-
-The SRFI-13/14 library is a shared library which provides the procedures
-defined in SRFI-13 (string library) and the procedures defined in
-SRFI-14 (character-set library). You should also refer to the SRFI
-documents, which provide some details I will not document here.
-
-If you don't know what SRFI means, and what all the numbers are about,
-you may want to refer to the SRFI home page at
-@url{http://srfi.schemers.org}.
-
-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 (REFFIXME).
-
-The SRFI-14 procedures are documented completely.
-
-@menu
-* What can be done:: What is possible with SRFI-13/14
-* What cannot be done:: and what is not?
-@end menu
-
-
-@c ===================================================================
-
-@node What can be done
-@subsection What can be done
-
-All of the procedures defined in SRFI-13, which are not already included
-in the Guile core library, are implemented in the module @code{(srfi
-srfi-13)}. The procedures which are both in Guile and in SRFI-13, but
-which are slightly extended, have been implemented in this module, and
-the bindings overwrite those in the Guile core.
-
-All procedures from SRFI-14 (character-set library) are implemented in
-the module @code{(srfi srfi-14)}, as well as the standard variables
-@code{char-set:letter}, @code{char-set:digit} etc.
-
-
-@c ===================================================================
-
-@node What cannot be done
-@subsection What cannot be done
-
-The procedures which are defined in the section @emph{Low-level
-procedures} of SRFI-13 for parsing optional string indices, substring
-specification checking and Knuth-Morris-Pratt-Searching are not
-implemented.
-
-The procedures @code{string-contains} and @code{string-contains-ci} are
-not implemented very efficiently at the moment. This will be changed as
-soon as possible.
-
-
-@c ===================================================================
-
-@node Loading SRFI-13/14
-@section Loading SRFI-13/14
-
-When Guile is properly installed, it can be loaded into a running Guile
-by using the @code{(srfi srfi-13)} module.
-
-@example
-$ guile
-guile> (use-modules (srfi srfi-13))
-guile>
-@end example
-
-When this step causes any errors, Guile is not properly installed.
-
-One possible reason is that Guile cannot find either the Scheme module
-file @file{srfi-13.scm}, or it cannot find the shared object file
-@file{libguile-srfi-srfi-13-14.so}. Make sure that the former is in the
-Guile load path and that the latter is either installed in some default
-location like @file{/usr/local/lib} or that the directory it was
-installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to
-@file{srfi-14.scm}.
-
-Now you can test whether the SRFI-13 procedures are working by calling
-the @code{string-concatenate} procedure.
-
-@example
-guile> (string-concatenate '("Hello" " " "World!"))
-"Hello World!"
-@end example
-
-The same goes for the SRFI-14 module, of course.
-
-@example
-$ guile
-guile> (use-modules (srfi srfi-14))
-guile> (char-set-union (char-set #\f #\o #\o) (string->char-set "bar"))
-#<charset @{#\a #\b #\f #\o #\r@}>
-guile>
-@end example
-
-
-@c ===================================================================
-
-@node String Functions
-@section String Functions
-
-In this section, we will describe all procedures defined in SRFI-13
-(string library) and implemented by the module @code{(srfi srfi-13)}.
-
-Except for the procedures in the section @emph{Low-level procedures} of
-SRFI-13, all string procedures defined there are implemented completely.
-
-@menu
-* Predicates:: Testing strings.
-* SRFI-13 Constructors:: Constructing strings.
-* SRFI-13 List/String Conversion:: Converstion from/to character lists.
-* SRFI-13 Selection:: Selecting portions from strings.
-* SRFI-13 Modification:: Modifying string in--place.
-* SRFI-13 Comparison:: Comparing strings.
-* Prefixes/Suffixes:: Checking for common pre-/suffixes.
-* Searching:: Searching in strings.
-* Case Mapping:: Changing the case of strings.
-* Reverse/Append:: Append, concatenate and reverse strings.
-* Fold/Unfold/Map:: Fold/Unfold/Map over strings.
-* Replicate/Rotate:: String replication and rotation.
-* Miscellaneous:: Miscellaneous string procedures.
-* Filtering/Deleting:: Deleting characters from strings.
-@end menu
-
-
-@c ===================================================================
-
-@node Predicates
-@subsection Predicates
-
-In addition to the primitives @code{string?} and @code{string-null?},
-which are already in the Guile core, the string predicates
-@code{string-any} and @code{string-every} are defined by SRFI-13.
-
-@deffn primitive string-any pred s [start end]
-Check if the predicate @var{pred} is true for any character in
-the string @var{s}, proceeding from left (index @var{start}) to
-right (index @var{end}). If @code{string-any} returns true,
-the returned true value is the one produced by the first
-successful application of @var{pred}.
-@end deffn
-
-@deffn primitive string-every pred s [start end]
-Check if the predicate @var{pred} is true for every character
-in the string @var{s}, proceeding from left (index @var{start})
-to right (index @var{end}). If @code{string-every} returns
-true, the returned true value is the one produced by the final
-application of @var{pred} to the last character of @var{s}.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Constructors
-@subsection Constructors
-
-SRFI-13 defines several procedures for constructing new strings. In
-addition to @code{make-string} and @code{string} (available in the Guile
-core library), the procedure @code{string-tabulate} does exist.
-
-@deffn primitive string-tabulate proc len
-@var{proc} is an integer->char procedure. Construct a string
-of size @var{len} by applying @var{proc} to each index to
-produce the corresponding string element. The order in which
-@var{proc} is applied to the indices is not specified.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 List/String Conversion
-@subsection List/String Conversion
-
-The procedure @code{string->list} is extended by SRFI-13, that is why it
-is included in @code{(srfi srfi-13)}. The other procedures are new.
-The Guile core already contains the procedure @code{list->string} for
-converting a list of characters into a string (REFFIXME).
-
-@deffn primitive string->list str [start end]
-Convert the string @var{str} into a list of characters.
-@end deffn
-
-@deffn primitive reverse-list->string chrs
-An efficient implementation of @code{(compose string->list
-reverse)}:
-
-@smalllisp
-(reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
-@end smalllisp
-@end deffn
-
-@deffn primitive string-join ls [delimiter grammar]
-Append the string in the string list @var{ls}, using the string
-@var{delim} as a delimiter between the elements of @var{ls}.
-@var{grammar} is a symbol which specifies how the delimiter is
-placed between the strings, and defaults to the symbol
-@code{infix}.
-
-@table @code
-@item infix
-Insert the separator between list elements. An empty string
-will produce an empty list.
-
-@item string-infix
-Like @code{infix}, but will raise an error if given the empty
-list.
-
-@item suffix
-Insert the separator after every list element.
-
-@item prefix
-Insert the separator before each list element.
-@end table
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Selection
-@subsection Selection
-
-These procedures are called @dfn{selectors}, because they access
-information about the string or select pieces of a given string.
-
-Additional selector procedures are documented in the Strings section
-(REFFIXME), like @code{string-length} or @code{string-ref}.
-
-@code{string-copy} is also available in core Guile, but this version
-accepts additional start/end indices.
-
-@deffn primitive string-copy str [start end]
-Return a freshly allocated copy of the string @var{str}. If
-given, @var{start} and @var{end} delimit the portion of
-@var{str} which is copied.
-@end deffn
-
-@deffn primitive substring/shared str start [end]
-Like @code{substring}, but the result may share memory with the
-argument @var{str}.
-@end deffn
-
-@deffn primitive string-copy! target tstart s [start end]
-Copy the sequence of characters from index range [@var{start},
-@var{end}) in string @var{s} to string @var{target}, beginning
-at index @var{tstart}. The characters are copied left-to-right
-or right-to-left as needed -- the copy is guaranteed to work,
-even if @var{target} and @var{s} are the same string. It is an
-error if the copy operation runs off the end of the target
-string.
-@end deffn
-
-@deffn primitive string-take s n
-@deffnx primitive string-take-right s n
-Return the @var{n} first/last characters of @var{s}.
-@end deffn
-
-@deffn primitive string-drop s n
-@deffnx primitive string-drop-right s n
-Return all but the first/last @var{n} characters of @var{s}.
-@end deffn
-
-@deffn primitive string-pad s len [chr start end]
-@deffnx primitive string-pad-right s len [chr start end]
-Take that characters from @var{start} to @var{end} from the
-string @var{s} and return a new string, right(left)-padded by the
-character @var{chr} to length @var{len}. If the resulting
-string is longer than @var{len}, it is truncated on the right (left).
-@end deffn
-
-@deffn primitive string-trim s [char_pred start end]
-@deffnx primitive string-trim-right s [char_pred start end]
-@deffnx primitive string-trim-both s [char_pred start end]
-Trim @var{s} by skipping over all characters on the left/right/both
-sides of the string that satisfy the parameter @var{char_pred}:
-
-@itemize @bullet
-@item
-if it is the character @var{ch}, characters equal to
-@var{ch} are trimmed,
-
-@item
-if it is a procedure @var{pred} characters that
-satisfy @var{pred} are trimmed,
-
-@item
-if it is a character set, characters in that set are trimmed.
-@end itemize
-
-If called without a @var{char_pred} argument, all whitespace is
-trimmed.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Modification
-@subsection Modification
-
-The procedure @code{string-fill!} is extended from R5RS because it
-accepts optional start/end indices. This bindings shadows the procedure
-of the same name in the Guile core. The second modification procedure
-@code{string-set!} is documented in the Strings section (REFFIXME).
-
-@deffn primitive string-fill! str chr [start end]
-Stores @var{chr} in every element of the given @var{str} and
-returns an unspecified value.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Comparison
-@subsection Comparison
-
-The procedures in this section are used for comparing strings in
-different ways. The comparison predicates differ from those in R5RS in
-that they do not only return @code{#t} or @code{#f}, but the mismatch
-index in the case of a true return value.
-
-@code{string-hash} and @code{string-hash-ci} are for calculating hash
-values for strings, useful for implementing fast lookup mechanisms.
-
-@deffn primitive string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
-@deffnx primitive string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
-Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
-mismatch index, depending upon whether @var{s1} is less than,
-equal to, or greater than @var{s2}. The mismatch index is the
-largest index @var{i} such that for every 0 <= @var{j} <
-@var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
-@var{i} is the first position that does not match. The
-character comparison is done case-insensitively.
-@end deffn
-
-@deffn primitive string= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string<> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string< s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string<= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string>= s1 s2 [start1 end1 start2 end2]
-Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
-fails. Otherwise, the mismatch index is returned (or @var{end1} in the
-case of @code{string=}.
-@end deffn
-
-@deffn primitive string-ci= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci<> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci< s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci<= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci>= s1 s2 [start1 end1 start2 end2]
-Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
-fails. Otherwise, the mismatch index is returned (or @var{end1} in the
-case of @code{string=}. These are the case-insensitive variants.
-@end deffn
-
-@deffn primitive string-hash s [bound start end]
-@deffnx primitive string-hash-ci s [bound start end]
-Return a hash value of the string @var{s} in the range 0 @dots{}
-@var{bound} - 1. @code{string-hash-ci} is the case-insensitive variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node Prefixes/Suffixes
-@subsection Prefixes/Suffixes
-
-Using these procedures you can determine whether a given string is a
-prefix or suffix of another string or how long a common prefix/suffix
-is.
-
-@deffn primitive string-prefix-length s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-prefix-length-ci s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix-length s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix-length-ci s1 s2 [start1 end1 start2 end2]
-Return the length of the longest common prefix/suffix of the two
-strings. @code{string-prefix-length-ci} and
-@code{string-suffix-length-ci} are the case-insensitive variants.
-@end deffn
-
-@deffn primitive string-prefix? s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-prefix-ci? s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix? s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix-ci? s1 s2 [start1 end1 start2 end2]
-Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and
-@code{string-suffix-ci?} are the case-insensitive variants.
-@end deffn
-
-
-@c ===================================================================
-
-@node Searching
-@subsection Searching
-
-Use these procedures to find out whether a string contains a given
-character or a given substring, or a character from a set of characters.
-
-@deffn primitive string-index s char_pred [start end]
-@deffnx primitive string-index-right s char_pred [start end]
-Search through the string @var{s} from left to right (right to left),
-returning the index of the first (last) occurence of a character which
-
-@itemize
-@item
-equals @var{char_pred}, if it is character,
-
-@item
-satisifies the predicate @var{char_pred}, if it is a
-procedure,
-
-@item
-is in the set @var{char_pred}, if it is a character set.
-@end itemize
-@end deffn
-
-@deffn primitive string-skip s char_pred [start end]
-@deffnx primitive string-skip-right s char_pred [start end]
-Search through the string @var{s} from left to right (right to left),
-returning the index of the first (last) occurence of a character which
-
-@itemize
-@item
-does not equal @var{char_pred}, if it is character,
-
-@item
-does not satisify the predicate @var{char_pred}, if it is
-a procedure.
-
-@item
-is not in the set if @var{char_pred} is a character set.
-@end itemize
-@end deffn
-
-@deffn primitive string-count s char_pred [start end]
-Return the count of the number of characters in the string
-@var{s} which
-
-@itemize @bullet
-@item
-equals @var{char_pred}, if it is character,
-
-@item
-satisifies the predicate @var{char_pred}, if it is a procedure.
-
-@item
-is in the set @var{char_pred}, if it is a character set.
-@end itemize
-@end deffn
-
-@deffn primitive string-contains s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-contains-ci s1 s2 [start1 end1 start2 end2]
-Does string @var{s1} contain string @var{s2}? Return the index
-in @var{s1} where @var{s2} occurs as a substring, or false.
-The optional start/end indices restrict the operation to the
-indicated substrings.
-
-@code{string-contains-ci} is the case-insensitive variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node Case Mapping
-@subsection Alphabetic Case Mapping
-
-These procedures convert the alphabetic case of strings. They are
-similar to the procedures in the Guile core, but are extended to handle
-optional start/end indices.
-
-@deffn primitive string-upcase s [start end]
-@deffnx primitive string-upcase! s [start end]
-Upcase every character in @var{s}. @code{string-upcase!} is the
-side-effecting variant.
-@end deffn
-
-@deffn primitive string-downcase s [start end]
-@deffnx primitive string-downcase! s [start end]
-Downcase every character in @var{s}. @code{string-downcase!} is the
-side--effecting variant.
-@end deffn
-
-@deffn primitive string-titlecase s [start end]
-@deffnx primitive string-titlecase! s [start end]
-Upcase every first character in every word in @var{s}, downcase the
-other characters. @code{string-titlecase!} is the side--effecting
-variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node Reverse/Append
-@subsection Reverse/Append
-
-One appending procedure, @code{string-append} is the same in R5RS and in
-SRFI-13, so it is not redefined.
-
-@deffn primitive string-reverse str [start end]
-@deffnx primitive string-reverse! str [start end]
-Reverse the string @var{str}. The optional arguments
-@var{start} and @var{end} delimit the region of @var{str} to
-operate on.
-
-@code{string-reverse!} modifies the argument string and returns an
-unspecified value.
-@end deffn
-
-@deffn primitive string-append/shared ls @dots{}
-Like @code{string-append}, but the result may share memory
-with the argument strings.
-@end deffn
-
-@deffn primitive string-concatenate ls
-Append the elements of @var{ls} (which must be strings)
-together into a single string. Guaranteed to return a freshly
-allocated string.
-@end deffn
-
-@deffn primitive string-concatenate/shared ls
-Like @code{string-concatenate}, but the result may share memory
-with the strings in the list @var{ls}.
-@end deffn
-
-@deffn primitive string-concatenate-reverse ls final_string end
-Without optional arguments, this procedure is equivalent to
-
-@smalllisp
-(string-concatenate (reverse ls))
-@end smalllisp
-
-If the optional argument @var{final_string} is specified, it is
-consed onto the beginning to @var{ls} before performing the
-list-reverse and string-concatenate operations. If @var{end}
-is given, only the characters of @var{final_string} up to index
-@var{end} are used.
-
-Guaranteed to return a freshly allocated string.
-@end deffn
-
-@deffn primitive string-concatenate-reverse/shared ls final_string end
-Like @code{string-concatenate-reverse}, but the result may
-share memory with the the strings in the @var{ls} arguments.
-@end deffn
-
-
-@c ===================================================================
-
-@node Fold/Unfold/Map
-@subsection Fold/Unfold/Map
-
-@code{string-map}, @code{string-for-each} etc. are for iterating over
-the characters a string is composed of. The fold and unfold procedures
-are list iterators and constructors.
-
-@deffn primitive string-map proc s [start end]
-@var{proc} is a char->char procedure, it is mapped over
-@var{s}. The order in which the procedure is applied to the
-string elements is not specified.
-@end deffn
-
-@deffn primitive string-map! proc s [start end]
-@var{proc} is a char->char procedure, it is mapped over
-@var{s}. The order in which the procedure is applied to the
-string elements is not specified. The string @var{s} is
-modified in-place, the return value is not specified.
-@end deffn
-
-@deffn primitive string-fold kons knil s [start end]
-@deffnx primitive string-fold-right kons knil s [start end]
-Fold @var{kons} over the characters of @var{s}, with @var{knil} as the
-terminating element, from left to right (or right to left, for
-@code{string-fold-right}). @var{kons} must expect two arguments: The
-actual character and the last result of @var{kons}' application.
-@end deffn
-
-@deffn primitive string-unfold p f g seed [base make_final]
-@deffnx primitive string-unfold-right p f g seed [base make_final]
-These are the fundamental string constructors.
-@itemize
-@item @var{g} is used to generate a series of @emph{seed}
-values from the initial @var{seed}: @var{seed}, (@var{g}
-@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
-@dots{}
-@item @var{p} tells us when to stop -- when it returns true
-when applied to one of these seed values.
-@item @var{f} maps each seed value to the corresponding
-character in the result string. These chars are assembled into the
-string in a left-to-right (right-to-left) order.
-@item @var{base} is the optional initial/leftmost (rightmost)
- portion of the constructed string; it default to the empty string.
-@item @var{make_final} is applied to the terminal seed
-value (on which @var{p} returns true) to produce the final/rightmost
-(leftmost) portion of the constructed string. It defaults to
-@code{(lambda (x) "")}.
-@end itemize
-@end deffn
-
-@deffn primitive string-for-each proc s [start end]
-@var{proc} is mapped over @var{s} in left-to-right order. The
-return value is not specified.
-@end deffn
-
-
-@c ===================================================================
-
-@node Replicate/Rotate
-@subsection Replicate/Rotate
-
-These procedures are special substring procedures, which can also be
-used for replicating strings. They are a bit tricky to use, but
-consider this code fragment, which replicates the input string
-@code{"foo"} so often that the resulting string has a length of six.
-
-@lisp
-(xsubstring "foo" 0 6)
-@result{}
-"foofoo"
-@end lisp
-
-@deffn primitive xsubstring s from [to start end]
-This is the @emph{extended substring} procedure that implements
-replicated copying of a substring of some string.
-
-@var{s} is a string, @var{start} and @var{end} are optional
-arguments that demarcate a substring of @var{s}, defaulting to
-0 and the length of @var{s}. Replicate this substring up and
-down index space, in both the positive and negative directions.
-@code{xsubstring} returns the substring of this string
-beginning at index @var{from}, and ending at @var{to}, which
-defaults to @var{from} + (@var{end} - @var{start}).
-@end deffn
-
-@deffn primitive string-xcopy! target tstart s sfrom [sto start end]
-Exactly the same as @code{xsubstring}, but the extracted text
-is written into the string @var{target} starting at index
-@var{tstart}. The operation is not defined if @code{(eq?
-@var{target} @var{s})} or these arguments share storage -- you
-cannot copy a string on top of itself.
-@end deffn
-
-
-@c ===================================================================
-
-@node Miscellaneous
-@subsection Miscellaneous
-
-@code{string-replace} is for replacing a portion of a string with
-another string and @code{string-tokenize} splits a string into a list of
-strings, breaking it up at a specified character.
-
-@deffn primitive string-replace s1 s2 [start1 end1 start2 end2]
-Return the string @var{s1}, but with the characters
-@var{start1} @dots{} @var{end1} replaced by the characters
-@var{start2} @dots{} @var{end2} from @var{s2}.
-@end deffn
-
-@deffn primitive string-tokenize s [token_char start end]
-Split the string @var{s} into a list of substrings, where each
-substring is a maximal non-empty contiguous sequence of
-characters equal to the character @var{token_char}, or
-whitespace, if @var{token_char} is not given. If
-@var{token_char} is a character set, it is used for finding the
-token borders.
-@end deffn
-
-
-@c ===================================================================
-
-@node Filtering/Deleting
-@subsection Filtering/Deleting
-
-@dfn{Filtering} means to remove all characters from a string which do
-not match a given criteria, @dfn{deleting} means the opposite.
-
-@deffn primitive string-filter s char_pred [start end]
-Filter the string @var{s}, retaining only those characters that
-satisfy the @var{char_pred} argument. If the argument is a
-procedure, it is applied to each character as a predicate, if
-it is a character, it is tested for equality and if it is a
-character set, it is tested for membership.
-@end deffn
-
-@deffn primitive string-delete s char_pred [start end]
-Filter the string @var{s}, retaining only those characters that
-do not satisfy the @var{char_pred} argument. If the argument
-is a procedure, it is applied to each character as a predicate,
-if it is a character, it is tested for equality and if it is a
-character set, it is tested for membership.
-@end deffn
-
-
-@c ===================================================================
-
-@node Character-set Procedures
-@section Character-set Procedures
-
-SRFI-14 defines the data type @dfn{character set}, and also defines a
-lot of procedures for handling this character type, and a few standard
-character sets like whitespace, alphabetic characters and others.
-
-@menu
-* Character Set Data Type:: Description of the character set data type.
-* Predicates/Comparison:: Testing character sets.
-* Iterating Over Character Sets:: Iterating over the members of a set.
-* Creating Character Sets:: Creating new character sets.
-* Querying Character Sets:: Extracting information from character sets.
-* Character-Set Algebra:: Set-algebra on character sets.
-* Standard Character Sets:: Variables containg standard character sets.
-@end menu
-
-
-@c ===================================================================
-
-@node Character Set Data Type
-@subsection Character Set Data Type
-
-The data type @dfn{charset} implements sets of characters (REFFIXME).
-Because the internal representation of character sets is not visible to
-the user, a lot of procedures for handling them are provided.
-
-Character sets can be created, extended, tested for the membership of a
-characters and be compared to other character sets.
-
-The Guile implementation of character sets deals with 8-bit characters.
-In the standard variables, only the ASCII part of the character range is
-really used, so that for example @dfn{Umlaute} and other accented
-characters are not considered to be letters. In the future, as Guile
-may get support for international character sets, this will change, so
-don't rely on these ``features''.
-
-
-@c ===================================================================
-
-@node Predicates/Comparison
-@subsection Predicates/Comparison
-
-Use these procedures for testing whether an object is a character set,
-or whether several character sets are equal or subsets of each other.
-@code{char-set-hash} can be used for calculating a hash value, maybe for
-usage in fast lookup procedures.
-
-@deffn primitive char-set? obj
-Return @code{#t} if @var{obj} is a character set, @code{#f}
-otherwise.
-@end deffn
-
-@deffn primitive char-set= cs1 @dots{}
-Return @code{#t} if all given character sets are equal.
-@end deffn
-
-@deffn primitive char-set<= cs1 @dots{}
-Return @code{#t} if every character set @var{cs}i is a subset
-of character set @var{cs}i+1.
-@end deffn
-
-@deffn primitive char-set-hash cs [bound]
-Compute a hash value for the character set @var{cs}. If
-@var{bound} is given and not @code{#f}, it restricts the
-returned value to the range 0 @dots{} @var{bound - 1}.
-@end deffn
-
-
-@c ===================================================================
-
-@node Iterating Over Character Sets
-@subsection Iterating Over Character Sets
-
-Character set cursors are a means for iterating over the members of a
-character sets. After creating a character set cursor with
-@code{char-set-cursor}, a cursor can be dereferenced with
-@code{char-set-ref}, advanced to the next member with
-@code{char-set-cursor-next}. Whether a cursor has passed past the last
-element of the set can be checked with @code{end-of-char-set?}.
-
-Additionally, mapping and (un-)folding procedures for character sets are
-provided.
-
-@deffn primitive char-set-cursor cs
-Return a cursor into the character set @var{cs}.
-@end deffn
-
-@deffn primitive char-set-ref cs cursor
-Return the character at the current cursor position
-@var{cursor} in the character set @var{cs}. It is an error to
-pass a cursor for which @code{end-of-char-set?} returns true.
-@end deffn
-
-@deffn primitive char-set-cursor-next cs cursor
-Advance the character set cursor @var{cursor} to the next
-character in the character set @var{cs}. It is an error if the
-cursor given satisfies @code{end-of-char-set?}.
-@end deffn
-
-@deffn primitive end-of-char-set? cursor
-Return @code{#t} if @var{cursor} has reached the end of a
-character set, @code{#f} otherwise.
-@end deffn
-
-@deffn primitive char-set-fold kons knil cs
-Fold the procedure @var{kons} over the character set @var{cs},
-initializing it with @var{knil}.
-@end deffn
-
-@deffn primitive char-set-unfold p f g seed [base_cs]
-@deffnx primitive char-set-unfold! p f g seed base_cs
-This is a fundamental constructor for character sets.
-@itemize
-@item @var{g} is used to generate a series of ``seed'' values
-from the initial seed: @var{seed}, (@var{g} @var{seed}),
-(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
-@item @var{p} tells us when to stop -- when it returns true
-when applied to one of the seed values.
-@item @var{f} maps each seed value to a character. These
-characters are added to the base character set @var{base_cs} to
-form the result; @var{base_cs} defaults to the empty set.
-@end itemize
-
-@code{char-set-unfold!} is the side-effecting variant.
-@end deffn
-
-@deffn primitive char-set-for-each proc cs
-Apply @var{proc} to every character in the character set
-@var{cs}. The return value is not specified.
-@end deffn
-
-@deffn primitive char-set-map proc cs
-Map the procedure @var{proc} over every character in @var{cs}.
-@var{proc} must be a character -> character procedure.
-@end deffn
-
-
-@c ===================================================================
-
-@node Creating Character Sets
-@subsection Creating Character Sets
-
-New character sets are produced with these procedures.
-
-@deffn primitive char-set-copy cs
-Return a newly allocated character set containing all
-characters in @var{cs}.
-@end deffn
-
-@deffn primitive char-set char1 @dots{}
-Return a character set containing all given characters.
-@end deffn
-
-@deffn primitive list->char-set char_list [base_cs]
-@deffnx primitive list->char-set! char_list base_cs
-Convert the character list @var{list} to a character set. If
-the character set @var{base_cs} is given, the character in this
-set are also included in the result.
-
-@code{list->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn primitive string->char-set s [base_cs]
-@deffnx primitive string->char-set! s base_cs
-Convert the string @var{str} to a character set. If the
-character set @var{base_cs} is given, the characters in this
-set are also included in the result.
-
-@code{string->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn primitive char-set-filter pred cs [base_cs]
-@deffnx primitive char-set-filter! pred cs base_cs
-Return a character set containing every character from @var{cs}
-so that it satisfies @var{pred}. If provided, the characters
-from @var{base_cs} are added to the result.
-
-@code{char-set-filter!} is the side-effecting variant.
-@end deffn
-
-@deffn primitive ucs-range->char-set lower upper [error? base_cs]
-@deffnx primitive uce-range->char-set! lower upper error? base_cs
-Return a character set containing all characters whose
-character codes lie in the half-open range
-[@var{lower},@var{upper}).
-
-If @var{error} is a true value, an error is signalled if the
-specified range contains characters which are not contained in
-the implemented character range. If @var{error} is @code{#f},
-these characters are silently left out of the resultung
-character set.
-
-The characters in @var{base_cs} are added to the result, if
-given.
-
-@code{ucs-range->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn procedure ->char-set x
-Coerce @var{x} into a character set. @var{x} may be a string, a
-character or a character set.
-@end deffn
-
-
-@c ===================================================================
-
-@node Querying Character Sets
-@subsection Querying Character Sets
-
-Access the elements and other information of a character set with these
-procedures.
-
-@deffn primitive char-set-size cs
-Return the number of elements in character set @var{cs}.
-@end deffn
-
-@deffn primitive char-set-count pred cs
-Return the number of the elements int the character set
-@var{cs} which satisfy the predicate @var{pred}.
-@end deffn
-
-@deffn primitive char-set->list cs
-Return a list containing the elements of the character set
-@var{cs}.
-@end deffn
-
-@deffn primitive char-set->string cs
-Return a string containing the elements of the character set
-@var{cs}. The order in which the characters are placed in the
-string is not defined.
-@end deffn
-
-@deffn primitive char-set-contains? cs char
-Return @code{#t} iff the character @var{ch} is contained in the
-character set @var{cs}.
-@end deffn
-
-@deffn primitive char-set-every pred cs
-Return a true value if every character in the character set
-@var{cs} satisfies the predicate @var{pred}.
-@end deffn
-
-@deffn primitive char-set-any pred cs
-Return a true value if any character in the character set
-@var{cs} satisfies the predicate @var{pred}.
-@end deffn
-
-
-@c ===================================================================
-
-@node Character-Set Algebra
-@subsection Character-Set Algebra
-
-Character sets can be manipulated with the common set algebra operation,
-such as union, complement, intersection etc. All of these procedures
-provide side--effecting variants, which modify their character set
-argument(s).
-
-@deffn primitive char-set-adjoin cs char1 @dots{}
-@deffnx primitive char-set-adjoin! cs char1 @dots{}
-Add all character arguments to the first argument, which must
-be a character set.
-@end deffn
-
-@deffn primitive char-set-delete cs char1 @dots{}
-@deffnx primitive char-set-delete! cs char1 @dots{}
-Delete all character arguments from the first argument, which
-must be a character set.
-@end deffn
-
-@deffn primitive char-set-complement cs
-@deffnx primitive char-set-complement! cs
-Return the complement of the character set @var{cs}.
-@end deffn
-
-@deffn primitive char-set-union cs1 @dots{}
-@deffnx primitive char-set-union! cs1 @dots{}
-Return the union of all argument character sets.
-@end deffn
-
-@deffn primitive char-set-intersection cs1 @dots{}
-@deffnx primitive char-set-intersection! cs1 @dots{}
-Return the intersection of all argument character sets.
-@end deffn
-
-@deffn primitive char-set-difference cs1 @dots{}
-@deffnx primitive char-set-difference! cs1 @dots{}
-Return the difference of all argument character sets.
-@end deffn
-
-@deffn primitive char-set-xor cs1 @dots{}
-@deffnx primitive char-set-xor! cs1 @dots{}
-Return the exclusive--or of all argument character sets.
-@end deffn
-
-@deffn primitive char-set-diff+intersection cs1 @dots{}
-@deffnx primitive char-set-diff+intersection! cs1 @dots{}
-Return the difference and the intersection of all argument
-character sets.
-@end deffn
-
-
-@c ===================================================================
-
-@node Standard Character Sets
-@subsection Standard Character Sets
-
-In order to make the use of the character set data type and procedures
-useful, several predefined character set variables exist.
-
-@defvar char-set:lower-case
-All lower--case characters.
-@end defvar
-
-@defvar char-set:upper-case
-All upper--case characters.
-@end defvar
-
-@defvar char-set:title-case
-This is empty, because ASCII has no titlecase characters.
-@end defvar
-
-@defvar char-set:letter
-All letters, e.g. the union of @code{char-set:lower-case} and
-@code{char-set:upper-case}.
-@end defvar
-
-@defvar char-set:digit
-All digits.
-@end defvar
-
-@defvar char-set:letter+digit
-The union of @code{char-set:letter} and @code{char-set:digit}.
-@end defvar
-
-@defvar char-set:graphic
-All characters which would put ink on the paper.
-@end defvar
-
-@defvar char-set:printing
-The union of @code{char-set:graphic} and @code{char-set:whitespace}.
-@end defvar
-
-@defvar char-set:whitespace
-All whitespace characters.
-@end defvar
-
-@defvar char-set:blank
-All horizontal whitespace characters, that is @code{#\space} and
-@code{#\tab}.
-@end defvar
-
-@defvar char-set:iso-control
-The ISO control characters with the codes 0--31 and 127.
-@end defvar
-
-@defvar char-set:punctuation
-The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
-@end defvar
-
-@defvar char-set:symbol
-The characters @code{$+<=>^`|~}.
-@end defvar
-
-@defvar char-set:hex-digit
-The hexadecimal digits @code{0123456789abcdefABCDEF}.
-@end defvar
-
-@defvar char-set:ascii
-All ASCII characters.
-@end defvar
-
-@defvar char-set:empty
-The empty character set.
-@end defvar
-
-@defvar char-set:full
-This character set contains all possible characters.
-@end defvar