@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@menu
* Booleans:: True/false values.
* Numbers:: Numerical data types.
-* Characters:: New character names.
-* Strings:: Special things about strings.
+* Characters:: Single characters.
+* Character Sets:: Sets of characters.
+* Strings:: Sequences of characters.
* Regular Expressions:: Pattern matching and substitution.
* Symbols:: Symbols.
* Keywords:: Self-quoting, customizable display keywords.
In addition to the classification into integers, rationals, reals and
complex numbers, Scheme also distinguishes between whether a number is
represented exactly or not. For example, the result of
-@m{2\sin(\pi/4),sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)} but Guile
-can neither represent @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
+@m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)}, but Guile
+can represent neither @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
Instead, it stores an inexact approximation, using the C type
@code{double}.
@deffn {Scheme Procedure} integer? x
@deffnx {C Function} scm_integer_p (x)
-Return @code{#t} if @var{x} is an exactor inexact integer number, else
+Return @code{#t} if @var{x} is an exact or inexact integer number, else
@code{#f}.
@lisp
number.
@end deftypefn
+@deftypefn {C Function} void scm_to_mpz (SCM val, mpz_t rop)
+Assign @var{val} to the multiple precision integer @var{rop}.
+@var{val} must be an exact integer, otherwise an error will be
+signalled. @var{rop} must have been initialized with @code{mpz_init}
+before this function is called. When @var{rop} is no longer needed
+the occupied space must be freed with @code{mpz_clear}.
+@xref{Initializing Integers,,, gmp, GNU MP Manual}, for details.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_from_mpz (mpz_t val)
+Return the @code{SCM} value that represents @var{val}.
+@end deftypefn
+
@node Reals and Rationals
@subsubsection Real and Rational Numbers
@tpindex Real numbers
The rational numbers are the set of all numbers that can be written as
fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
All rational numbers are also real, but there are real numbers that
-are not rational, for example the square root of 2, and pi.
+are not rational, for example @m{\sqrt2, the square root of 2}, and
+@m{\pi,pi}.
Guile can represent both exact and inexact rational numbers, but it
can not represent irrational numbers. Exact rationals are represented
Return @code{#t} if @var{x} is @samp{+nan.0}, @code{#f} otherwise.
@end deffn
+@deffn {Scheme Procedure} nan
+@deffnx {C Function} scm_nan ()
+Return NaN.
+@end deffn
+
+@deffn {Scheme Procedure} inf
+@deffnx {C Function} scm_inf ()
+Return Inf.
+@end deffn
+
@deffn {Scheme Procedure} numerator x
@deffnx {C Function} scm_numerator (x)
Return the numerator of the rational number @var{x}.
9.3-17.5i
@end lisp
+@cindex polar form
+@noindent
+Polar form can also be used, with an @samp{@@} between magnitude and
+angle,
+
+@lisp
+1@@3.141592 @result{} -1.0 (approx)
+-1@@1.57079 @result{} 0.0-1.0i (approx)
+@end lisp
+
Guile represents a complex number with a non-zero imaginary part as a
pair of inexact rationals, so the real and imaginary parts of a
complex number have the same properties of inexactness and limited
rational or integer number.
@end deffn
+@deftypefn {C Function} int scm_is_complex (SCM val)
+Equivalent to @code{scm_is_true (scm_complex_p (val))}.
+@end deftypefn
+
@node Exactness
@subsubsection Exact and Inexact Numbers
@tpindex Exact numbers
@end deffn
@c begin (texi-doc-string "guile" "gcd")
-@deffn {Scheme Procedure} gcd
+@deffn {Scheme Procedure} gcd x@dots{}
@deffnx {C Function} scm_gcd (x, y)
Return the greatest common divisor of all arguments.
If called without arguments, 0 is returned.
@end deffn
@c begin (texi-doc-string "guile" "lcm")
-@deffn {Scheme Procedure} lcm
+@deffn {Scheme Procedure} lcm x@dots{}
@deffnx {C Function} scm_lcm (x, y)
Return the least common multiple of the arguments.
If called without arguments, 1 is returned.
Scheme function can take an arbitrary number.
@end deffn
+@deffn {Scheme Procedure} modulo-expt n k m
+@deffnx {C Function} scm_modulo_expt (n, k, m)
+Return @var{n} raised to the integer exponent
+@var{k}, modulo @var{m}.
+
+@lisp
+(modulo-expt 2 3 5)
+ @result{} 3
+@end lisp
+@end deffn
@node Comparison
@subsubsection Comparison Predicates
@rnindex number->string
@rnindex string->number
+The following procedures read and write numbers according to their
+external representation as defined by R5RS (@pxref{Lexical structure,
+R5RS Lexical Structure,, r5rs, The Revised^5 Report on the Algorithmic
+Language Scheme}). @xref{The ice-9 i18n Module, the @code{(ice-9
+i18n)} module}, for locale-dependent number parsing.
+
@deffn {Scheme Procedure} number->string n [radix]
@deffnx {C Function} scm_number_to_string (n, radix)
Return a string holding the external representation of the
@code{string->number} returns @code{#f}.
@end deffn
+@deftypefn {C Function} SCM scm_c_locale_stringn_to_number (const char *string, size_t len, unsigned radix)
+As per @code{string->number} above, but taking a C string, as pointer
+and length. The string characters should be in the current locale
+encoding (@code{locale} in the name refers only to that, there's no
+locale-dependent parsing).
+@end deftypefn
+
@node Complex
@subsubsection Complex Number Operations
@deffn {Scheme Procedure} make-polar x y
@deffnx {C Function} scm_make_polar (x, y)
+@cindex polar form
Return the complex number @var{x} * e^(i * @var{y}).
@end deffn
@end deffn
@c begin (texi-doc-string "guile" "truncate")
-@deffn {Scheme Procedure} truncate
+@deffn {Scheme Procedure} truncate x
@deffnx {C Function} scm_truncate_number (x)
Round the inexact number @var{x} towards zero.
@end deffn
Round the number @var{x} towards infinity.
@end deffn
+@deftypefn {C Function} double scm_c_truncate (double x)
+@deftypefnx {C Function} double scm_c_round (double x)
+Like @code{scm_truncate_number} or @code{scm_round_number},
+respectively, but these functions take and return @code{double}
+values.
+@end deftypefn
@node Scientific
@subsubsection Scientific Functions
@rnindex sqrt
@c begin (texi-doc-string "guile" "sqrt")
@deffn {Scheme Procedure} sqrt z
-Return the square root of @var{z}.
+Return the square root of @var{z}. Of the two possible roots
+(positive and negative), the one with the a positive real part is
+returned, or if that's zero then a positive imaginary part. Thus,
+
+@example
+(sqrt 9.0) @result{} 3.0
+(sqrt -9.0) @result{} 0.0+3.0i
+(sqrt 1.0+1.0i) @result{} 1.09868411346781+0.455089860562227i
+(sqrt -1.0-1.0i) @result{} 0.455089860562227-1.09868411346781i
+@end example
@end deffn
@rnindex expt
@deffn {Scheme Procedure} logtest j k
@deffnx {C Function} scm_logtest (j, k)
-@lisp
-(logtest j k) @equiv{} (not (zero? (logand j k)))
+Test whether @var{j} and @var{k} have any 1 bits in common. This is
+equivalent to @code{(not (zero? (logand j k)))}, but without actually
+calculating the @code{logand}, just testing for non-zero.
+@lisp
(logtest #b0100 #b1011) @result{} #f
(logtest #b0100 #b0111) @result{} #t
@end lisp
@deffn {Scheme Procedure} logbit? index j
@deffnx {C Function} scm_logbit_p (index, j)
-@lisp
-(logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
+Test whether bit number @var{index} in @var{j} is set. @var{index}
+starts from 0 for the least significant bit.
+@lisp
(logbit? 0 #b1101) @result{} #t
(logbit? 1 #b1101) @result{} #f
(logbit? 2 #b1101) @result{} #t
@deffn {Scheme Procedure} logcount n
@deffnx {C Function} scm_logcount (n)
-Return the number of bits in integer @var{n}. If integer is
+Return the number of bits in integer @var{n}. If @var{n} is
positive, the 1-bits in its binary representation are counted.
If negative, the 0-bits in its two's-complement binary
-representation are counted. If 0, 0 is returned.
+representation are counted. If zero, 0 is returned.
@lisp
(logcount #b10101010)
@deffn {Scheme Procedure} integer-expt n k
@deffnx {C Function} scm_integer_expt (n, k)
-Return @var{n} raised to the non-negative integer exponent
-@var{k}.
+Return @var{n} raised to the power @var{k}. @var{k} must be an exact
+integer, @var{n} can be any number.
+
+Negative @var{k} is supported, and results in @m{1/n^|k|, 1/n^abs(k)}
+in the usual way. @math{@var{n}^0} is 1, as usual, and that includes
+@math{0^0} is 1.
@lisp
-(integer-expt 2 5)
- @result{} 32
-(integer-expt -3 3)
- @result{} -27
+(integer-expt 2 5) @result{} 32
+(integer-expt -3 3) @result{} -27
+(integer-expt 5 -3) @result{} 1/125
+(integer-expt 0 0) @result{} 1
@end lisp
@end deffn
squares is less than 1.0. Thinking of @var{vect} as coordinates in
space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
the coordinates are uniformly distributed within the unit
-@var{n}-sphere. The sum of the squares of the numbers is returned.
+@var{n}-sphere.
@c FIXME: What does this mean, particularly the n-sphere part?
@end deffn
@subsection Characters
@tpindex Characters
-@noindent
-[@strong{FIXME}: how do you specify regular (non-control) characters?]
+In Scheme, a character literal is written as @code{#\@var{name}} where
+@var{name} is the name of the character that you want. Printable
+characters have their usual single character name; for example,
+@code{#\a} is a lower case @code{a}.
Most of the ``control characters'' (those below codepoint 32) in the
@acronym{ASCII} character set, as well as the space, may be referred
-to by name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and
-so on. The following table describes the @acronym{ASCII} names for
-each character.
+to by longer names: for example, @code{#\tab}, @code{#\esc},
+@code{#\stx}, and so on. The following table describes the
+@acronym{ASCII} names for each character.
@multitable @columnfractions .25 .25 .25 .25
@item 0 = @code{#\nul}
@deffn {Scheme Procedure} char-alphabetic? chr
@deffnx {C Function} scm_char_alphabetic_p (chr)
Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
-Alphabetic means the same thing as the @code{isalpha} C library function.
@end deffn
@rnindex char-numeric?
@deffn {Scheme Procedure} char-numeric? chr
@deffnx {C Function} scm_char_numeric_p (chr)
Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
-Numeric means the same thing as the @code{isdigit} C library function.
@end deffn
@rnindex char-whitespace?
@deffn {Scheme Procedure} char-whitespace? chr
@deffnx {C Function} scm_char_whitespace_p (chr)
Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
-Whitespace means the same thing as the @code{isspace} C library function.
@end deffn
@rnindex char-upper-case?
@deffn {Scheme Procedure} char-upper-case? chr
@deffnx {C Function} scm_char_upper_case_p (chr)
Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
-Uppercase means the same thing as the @code{isupper} C library function.
@end deffn
@rnindex char-lower-case?
@deffn {Scheme Procedure} char-lower-case? chr
@deffnx {C Function} scm_char_lower_case_p (chr)
Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
-Lowercase means the same thing as the @code{islower} C library function.
@end deffn
@deffn {Scheme Procedure} char-is-both? chr
@deffnx {C Function} scm_char_is_both_p (chr)
Return @code{#t} iff @var{chr} is either uppercase or lowercase, else
-@code{#f}. Uppercase and lowercase are as defined by the
-@code{isupper} and @code{islower} C library functions.
+@code{#f}.
@end deffn
@rnindex char->integer
Return the lowercase character version of @var{chr}.
@end deffn
-@xref{Classification of Characters,,,libc,GNU C Library Reference
-Manual}, for information about the @code{is*} Standard C functions
-mentioned above.
+@node Character Sets
+@subsection Character Sets
+
+The features described in this section correspond directly to SRFI-14.
+
+The data type @dfn{charset} implements sets of characters
+(@pxref{Characters}). Because the internal representation of
+character sets is not visible to the user, a lot of procedures for
+handling them are provided.
+
+Character sets can be created, extended, tested for the membership of a
+characters and be compared to other character sets.
+
+The Guile implementation of character sets currently deals only with
+8-bit characters. In the future, when Guile gets support for
+international character sets, this will change, but the functions
+provided here will always then be able to efficiently cope with very
+large character sets.
+
+@menu
+* Character Set Predicates/Comparison::
+* Iterating Over Character Sets:: Enumerate charset elements.
+* Creating Character Sets:: Making new charsets.
+* Querying Character Sets:: Test charsets for membership etc.
+* Character-Set Algebra:: Calculating new charsets.
+* Standard Character Sets:: Variables containing predefined charsets.
+@end menu
+
+@node Character Set Predicates/Comparison
+@subsubsection Character Set Predicates/Comparison
+
+Use these procedures for testing whether an object is a character set,
+or whether several character sets are equal or subsets of each other.
+@code{char-set-hash} can be used for calculating a hash value, maybe for
+usage in fast lookup procedures.
+
+@deffn {Scheme Procedure} char-set? obj
+@deffnx {C Function} scm_char_set_p (obj)
+Return @code{#t} if @var{obj} is a character set, @code{#f}
+otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} char-set= . char_sets
+@deffnx {C Function} scm_char_set_eq (char_sets)
+Return @code{#t} if all given character sets are equal.
+@end deffn
+
+@deffn {Scheme Procedure} char-set<= . char_sets
+@deffnx {C Function} scm_char_set_leq (char_sets)
+Return @code{#t} if every character set @var{cs}i is a subset
+of character set @var{cs}i+1.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-hash cs [bound]
+@deffnx {C Function} scm_char_set_hash (cs, bound)
+Compute a hash value for the character set @var{cs}. If
+@var{bound} is given and non-zero, it restricts the
+returned value to the range 0 @dots{} @var{bound - 1}.
+@end deffn
+
+@c ===================================================================
+
+@node Iterating Over Character Sets
+@subsubsection Iterating Over Character Sets
+
+Character set cursors are a means for iterating over the members of a
+character sets. After creating a character set cursor with
+@code{char-set-cursor}, a cursor can be dereferenced with
+@code{char-set-ref}, advanced to the next member with
+@code{char-set-cursor-next}. Whether a cursor has passed past the last
+element of the set can be checked with @code{end-of-char-set?}.
+
+Additionally, mapping and (un-)folding procedures for character sets are
+provided.
+
+@deffn {Scheme Procedure} char-set-cursor cs
+@deffnx {C Function} scm_char_set_cursor (cs)
+Return a cursor into the character set @var{cs}.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-ref cs cursor
+@deffnx {C Function} scm_char_set_ref (cs, cursor)
+Return the character at the current cursor position
+@var{cursor} in the character set @var{cs}. It is an error to
+pass a cursor for which @code{end-of-char-set?} returns true.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-cursor-next cs cursor
+@deffnx {C Function} scm_char_set_cursor_next (cs, cursor)
+Advance the character set cursor @var{cursor} to the next
+character in the character set @var{cs}. It is an error if the
+cursor given satisfies @code{end-of-char-set?}.
+@end deffn
+
+@deffn {Scheme Procedure} end-of-char-set? cursor
+@deffnx {C Function} scm_end_of_char_set_p (cursor)
+Return @code{#t} if @var{cursor} has reached the end of a
+character set, @code{#f} otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-fold kons knil cs
+@deffnx {C Function} scm_char_set_fold (kons, knil, cs)
+Fold the procedure @var{kons} over the character set @var{cs},
+initializing it with @var{knil}.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
+@deffnx {C Function} scm_char_set_unfold (p, f, g, seed, base_cs)
+This is a fundamental constructor for character sets.
+@itemize @bullet
+@item @var{g} is used to generate a series of ``seed'' values
+from the initial seed: @var{seed}, (@var{g} @var{seed}),
+(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
+@item @var{p} tells us when to stop -- when it returns true
+when applied to one of the seed values.
+@item @var{f} maps each seed value to a character. These
+characters are added to the base character set @var{base_cs} to
+form the result; @var{base_cs} defaults to the empty set.
+@end itemize
+@end deffn
+
+@deffn {Scheme Procedure} char-set-unfold! p f g seed base_cs
+@deffnx {C Function} scm_char_set_unfold_x (p, f, g, seed, base_cs)
+This is a fundamental constructor for character sets.
+@itemize @bullet
+@item @var{g} is used to generate a series of ``seed'' values
+from the initial seed: @var{seed}, (@var{g} @var{seed}),
+(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
+@item @var{p} tells us when to stop -- when it returns true
+when applied to one of the seed values.
+@item @var{f} maps each seed value to a character. These
+characters are added to the base character set @var{base_cs} to
+form the result; @var{base_cs} defaults to the empty set.
+@end itemize
+@end deffn
+
+@deffn {Scheme Procedure} char-set-for-each proc cs
+@deffnx {C Function} scm_char_set_for_each (proc, cs)
+Apply @var{proc} to every character in the character set
+@var{cs}. The return value is not specified.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-map proc cs
+@deffnx {C Function} scm_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
+@subsubsection Creating Character Sets
+
+New character sets are produced with these procedures.
+
+@deffn {Scheme Procedure} char-set-copy cs
+@deffnx {C Function} scm_char_set_copy (cs)
+Return a newly allocated character set containing all
+characters in @var{cs}.
+@end deffn
+
+@deffn {Scheme Procedure} char-set . rest
+@deffnx {C Function} scm_char_set (rest)
+Return a character set containing all given characters.
+@end deffn
+
+@deffn {Scheme Procedure} list->char-set list [base_cs]
+@deffnx {C Function} scm_list_to_char_set (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.
+@end deffn
+
+@deffn {Scheme Procedure} list->char-set! list base_cs
+@deffnx {C Function} scm_list_to_char_set_x (list, base_cs)
+Convert the character list @var{list} to a character set. The
+characters are added to @var{base_cs} and @var{base_cs} is
+returned.
+@end deffn
+
+@deffn {Scheme Procedure} string->char-set str [base_cs]
+@deffnx {C Function} scm_string_to_char_set (str, 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.
+@end deffn
+
+@deffn {Scheme Procedure} string->char-set! str base_cs
+@deffnx {C Function} scm_string_to_char_set_x (str, base_cs)
+Convert the string @var{str} to a character set. The
+characters from the string are added to @var{base_cs}, and
+@var{base_cs} is returned.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
+@deffnx {C Function} scm_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.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-filter! pred cs base_cs
+@deffnx {C Function} scm_char_set_filter_x (pred, cs, base_cs)
+Return a character set containing every character from @var{cs}
+so that it satisfies @var{pred}. The characters are added to
+@var{base_cs} and @var{base_cs} is returned.
+@end deffn
+
+@deffn {Scheme Procedure} ucs-range->char-set lower upper [error [base_cs]]
+@deffnx {C Function} scm_ucs_range_to_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.
+@end deffn
+
+@deffn {Scheme Procedure} ucs-range->char-set! lower upper error base_cs
+@deffnx {C Function} scm_ucs_range_to_char_set_x (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 are added to @var{base_cs} and @var{base_cs} is
+returned.
+@end deffn
+
+@deffn {Scheme Procedure} ->char-set x
+@deffnx {C Function} scm_to_char_set (x)
+Coerces x into a char-set. @var{x} may be a string, character or char-set. A string is converted to the set of its constituent characters; a character is converted to a singleton set; a char-set is returned as-is.
+@end deffn
+
+@c ===================================================================
+
+@node Querying Character Sets
+@subsubsection Querying Character Sets
+
+Access the elements and other information of a character set with these
+procedures.
+
+@deffn {Scheme Procedure} char-set-size cs
+@deffnx {C Function} scm_char_set_size (cs)
+Return the number of elements in character set @var{cs}.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-count pred cs
+@deffnx {C Function} scm_char_set_count (pred, cs)
+Return the number of the elements int the character set
+@var{cs} which satisfy the predicate @var{pred}.
+@end deffn
+
+@deffn {Scheme Procedure} char-set->list cs
+@deffnx {C Function} scm_char_set_to_list (cs)
+Return a list containing the elements of the character set
+@var{cs}.
+@end deffn
+
+@deffn {Scheme Procedure} char-set->string cs
+@deffnx {C Function} scm_char_set_to_string (cs)
+Return a string containing the elements of the character set
+@var{cs}. The order in which the characters are placed in the
+string is not defined.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-contains? cs ch
+@deffnx {C Function} scm_char_set_contains_p (cs, ch)
+Return @code{#t} iff the character @var{ch} is contained in the
+character set @var{cs}.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-every pred cs
+@deffnx {C Function} scm_char_set_every (pred, cs)
+Return a true value if every character in the character set
+@var{cs} satisfies the predicate @var{pred}.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-any pred cs
+@deffnx {C Function} scm_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
+@subsubsection Character-Set Algebra
+
+Character sets can be manipulated with the common set algebra operation,
+such as union, complement, intersection etc. All of these procedures
+provide side-effecting variants, which modify their character set
+argument(s).
+
+@deffn {Scheme Procedure} char-set-adjoin cs . rest
+@deffnx {C Function} scm_char_set_adjoin (cs, rest)
+Add all character arguments to the first argument, which must
+be a character set.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-delete cs . rest
+@deffnx {C Function} scm_char_set_delete (cs, rest)
+Delete all character arguments from the first argument, which
+must be a character set.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-adjoin! cs . rest
+@deffnx {C Function} scm_char_set_adjoin_x (cs, rest)
+Add all character arguments to the first argument, which must
+be a character set.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-delete! cs . rest
+@deffnx {C Function} scm_char_set_delete_x (cs, rest)
+Delete all character arguments from the first argument, which
+must be a character set.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-complement cs
+@deffnx {C Function} scm_char_set_complement (cs)
+Return the complement of the character set @var{cs}.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-union . rest
+@deffnx {C Function} scm_char_set_union (rest)
+Return the union of all argument character sets.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-intersection . rest
+@deffnx {C Function} scm_char_set_intersection (rest)
+Return the intersection of all argument character sets.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-difference cs1 . rest
+@deffnx {C Function} scm_char_set_difference (cs1, rest)
+Return the difference of all argument character sets.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-xor . rest
+@deffnx {C Function} scm_char_set_xor (rest)
+Return the exclusive-or of all argument character sets.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-diff+intersection cs1 . rest
+@deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, rest)
+Return the difference and the intersection of all argument
+character sets.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-complement! cs
+@deffnx {C Function} scm_char_set_complement_x (cs)
+Return the complement of the character set @var{cs}.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-union! cs1 . rest
+@deffnx {C Function} scm_char_set_union_x (cs1, rest)
+Return the union of all argument character sets.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-intersection! cs1 . rest
+@deffnx {C Function} scm_char_set_intersection_x (cs1, rest)
+Return the intersection of all argument character sets.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-difference! cs1 . rest
+@deffnx {C Function} scm_char_set_difference_x (cs1, rest)
+Return the difference of all argument character sets.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-xor! cs1 . rest
+@deffnx {C Function} scm_char_set_xor_x (cs1, rest)
+Return the exclusive-or of all argument character sets.
+@end deffn
+
+@deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 . rest
+@deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, rest)
+Return the difference and the intersection of all argument
+character sets.
+@end deffn
+
+@c ===================================================================
+
+@node Standard Character Sets
+@subsubsection Standard Character Sets
+
+In order to make the use of the character set data type and procedures
+useful, several predefined character set variables exist.
+
+@cindex codeset
+@cindex charset
+@cindex locale
+
+Currently, the contents of these character sets are recomputed upon a
+successful @code{setlocale} call (@pxref{Locales}) in order to reflect
+the characters available in the current locale's codeset. For
+instance, @code{char-set:letter} contains 52 characters under an ASCII
+locale (e.g., the default @code{C} locale) and 117 characters under an
+ISO-8859-1 (``Latin-1'') locale.
+
+@defvr {Scheme Variable} char-set:lower-case
+@defvrx {C Variable} scm_char_set_lower_case
+All lower-case characters.
+@end defvr
+
+@defvr {Scheme Variable} char-set:upper-case
+@defvrx {C Variable} scm_char_set_upper_case
+All upper-case characters.
+@end defvr
+
+@defvr {Scheme Variable} char-set:title-case
+@defvrx {C Variable} scm_char_set_title_case
+This is empty, because ASCII has no titlecase characters.
+@end defvr
+
+@defvr {Scheme Variable} char-set:letter
+@defvrx {C Variable} scm_char_set_letter
+All letters, e.g. the union of @code{char-set:lower-case} and
+@code{char-set:upper-case}.
+@end defvr
+
+@defvr {Scheme Variable} char-set:digit
+@defvrx {C Variable} scm_char_set_digit
+All digits.
+@end defvr
+
+@defvr {Scheme Variable} char-set:letter+digit
+@defvrx {C Variable} scm_char_set_letter_and_digit
+The union of @code{char-set:letter} and @code{char-set:digit}.
+@end defvr
+
+@defvr {Scheme Variable} char-set:graphic
+@defvrx {C Variable} scm_char_set_graphic
+All characters which would put ink on the paper.
+@end defvr
+
+@defvr {Scheme Variable} char-set:printing
+@defvrx {C Variable} scm_char_set_printing
+The union of @code{char-set:graphic} and @code{char-set:whitespace}.
+@end defvr
+
+@defvr {Scheme Variable} char-set:whitespace
+@defvrx {C Variable} scm_char_set_whitespace
+All whitespace characters.
+@end defvr
+
+@defvr {Scheme Variable} char-set:blank
+@defvrx {C Variable} scm_char_set_blank
+All horizontal whitespace characters, that is @code{#\space} and
+@code{#\tab}.
+@end defvr
+
+@defvr {Scheme Variable} char-set:iso-control
+@defvrx {C Variable} scm_char_set_iso_control
+The ISO control characters with the codes 0--31 and 127.
+@end defvr
+
+@defvr {Scheme Variable} char-set:punctuation
+@defvrx {C Variable} scm_char_set_punctuation
+The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
+@end defvr
+
+@defvr {Scheme Variable} char-set:symbol
+@defvrx {C Variable} scm_char_set_symbol
+The characters @code{$+<=>^`|~}.
+@end defvr
+
+@defvr {Scheme Variable} char-set:hex-digit
+@defvrx {C Variable} scm_char_set_hex_digit
+The hexadecimal digits @code{0123456789abcdefABCDEF}.
+@end defvr
+
+@defvr {Scheme Variable} char-set:ascii
+@defvrx {C Variable} scm_char_set_ascii
+All ASCII characters.
+@end defvr
+
+@defvr {Scheme Variable} char-set:empty
+@defvrx {C Variable} scm_char_set_empty
+The empty character set.
+@end defvr
+@defvr {Scheme Variable} char-set:full
+@defvrx {C Variable} scm_char_set_full
+This character set contains all possible characters.
+@end defvr
@node Strings
@subsection Strings
Strings always carry the information about how many characters they are
composed of with them, so there is no special end-of-string character,
like in C. That means that Scheme strings can contain any character,
-even the @samp{NUL} character @samp{\0}. But note: Since most operating
-system calls dealing with strings (such as for file operations) expect
-strings to be zero-terminated, they might do unexpected things when
-called with string containing unusual characters.
+even the @samp{#\nul} character @samp{\0}.
+
+To use strings efficiently, you need to know a bit about how Guile
+implements them. In Guile, a string consists of two parts, a head and
+the actual memory where the characters are stored. When a string (or
+a substring of it) is copied, only a new head gets created, the memory
+is usually not copied. The two heads start out pointing to the same
+memory.
+
+When one of these two strings is modified, as with @code{string-set!},
+their common memory does get copied so that each string has its own
+memory and modifying one does not accidently modify the other as well.
+Thus, Guile's strings are `copy on write'; the actual copying of their
+memory is delayed until one string is written to.
+
+This implementation makes functions like @code{substring} very
+efficient in the common case that no modifications are done to the
+involved strings.
+
+If you do know that your strings are getting modified right away, you
+can use @code{substring/copy} instead of @code{substring}. This
+function performs the copy immediately at the time of creation. This
+is more efficient, especially in a multi-threaded program. Also,
+@code{substring/copy} can avoid the problem that a short substring
+holds on to the memory of a very large original string that could
+otherwise be recycled.
+
+If you want to avoid the copy altogether, so that modifications of one
+string show up in the other, you can use @code{substring/shared}. The
+strings created by this procedure are called @dfn{mutation sharing
+substrings} since the substring and the original string share
+modifications to each other.
+
+If you want to prevent modifications, use @code{substring/read-only}.
+
+Guile provides all procedures of SRFI-13 and a few more.
@menu
-* String Syntax:: Read syntax for strings.
-* String Predicates:: Testing strings for certain properties.
-* String Constructors:: Creating new string objects.
-* List/String Conversion:: Converting from/to lists of characters.
-* String Selection:: Select portions from strings.
-* String Modification:: Modify parts or whole strings.
-* String Comparison:: Lexicographic ordering predicates.
-* String Searching:: Searching in strings.
-* Alphabetic Case Mapping:: Convert the alphabetic case of strings.
-* Appending Strings:: Appending strings to form a new string.
+* String Syntax:: Read syntax for strings.
+* String Predicates:: Testing strings for certain properties.
+* String Constructors:: Creating new string objects.
+* List/String Conversion:: Converting from/to lists of characters.
+* String Selection:: Select portions from strings.
+* String Modification:: Modify parts or whole strings.
+* String Comparison:: Lexicographic ordering predicates.
+* String Searching:: Searching in strings.
+* Alphabetic Case Mapping:: Convert the alphabetic case of strings.
+* Reversing and Appending Strings:: Appending strings to form a new string.
+* Mapping Folding and Unfolding:: Iterating over strings.
+* Miscellaneous String Operations:: Replicating, insertion, parsing, ...
+* Conversion to/from C::
@end menu
@node String Syntax
@c special in a string (they're not).
The read syntax for strings is an arbitrarily long sequence of
-characters enclosed in double quotes (@nicode{"}). @footnote{Actually,
-the current implementation restricts strings to a length of
-@math{2^24}, or 16,777,216, characters. Sorry.}
+characters enclosed in double quotes (@nicode{"}).
Backslash is an escape character and can be used to insert the
following special characters. @nicode{\"} and @nicode{\\} are R5RS
Return @code{#t} if @var{obj} is a string, else @code{#f}.
@end deffn
+@deftypefn {C Function} int scm_is_string (SCM obj)
+Returns @code{1} if @var{obj} is a string, @code{0} otherwise.
+@end deftypefn
+
@deffn {Scheme Procedure} string-null? str
@deffnx {C Function} scm_string_null_p (str)
Return @code{#t} if @var{str}'s length is zero, and
@end lisp
@end deffn
+@deffn {Scheme Procedure} string-any char_pred s [start [end]]
+@deffnx {C Function} scm_string_any (char_pred, s, start, end)
+Check if @var{char_pred} is true for any character in string @var{s}.
+
+@var{char_pred} can be a character to check for any equal to that, or
+a character set (@pxref{Character Sets}) to check for any in that set,
+or a predicate procedure to call.
+
+For a procedure, calls @code{(@var{char_pred} c)} are made
+successively on the characters from @var{start} to @var{end}. If
+@var{char_pred} returns true (ie.@: non-@code{#f}), @code{string-any}
+stops and that return value is the return from @code{string-any}. The
+call on the last character (ie.@: at @math{@var{end}-1}), if that
+point is reached, is a tail call.
+
+If there are no characters in @var{s} (ie.@: @var{start} equals
+@var{end}) then the return is @code{#f}.
+@end deffn
+
+@deffn {Scheme Procedure} string-every char_pred s [start [end]]
+@deffnx {C Function} scm_string_every (char_pred, s, start, end)
+Check if @var{char_pred} is true for every character in string
+@var{s}.
+
+@var{char_pred} can be a character to check for every character equal
+to that, or a character set (@pxref{Character Sets}) to check for
+every character being in that set, or a predicate procedure to call.
+
+For a procedure, calls @code{(@var{char_pred} c)} are made
+successively on the characters from @var{start} to @var{end}. If
+@var{char_pred} returns @code{#f}, @code{string-every} stops and
+returns @code{#f}. The call on the last character (ie.@: at
+@math{@var{end}-1}), if that point is reached, is a tail call and the
+return from that call is the return from @code{string-every}.
+
+If there are no characters in @var{s} (ie.@: @var{start} equals
+@var{end}) then the return is @code{#t}.
+@end deffn
+
@node String Constructors
@subsubsection String Constructors
The string constructor procedures create new string objects, possibly
-initializing them with some specified character data.
+initializing them with some specified character data. See also
+@xref{String Selection}, for ways to create strings from existing
+strings.
@c FIXME::martin: list->string belongs into `List/String Conversion'
+@deffn {Scheme Procedure} string char@dots{}
@rnindex string
+Return a newly allocated string made from the given character
+arguments.
+
+@example
+(string #\x #\y #\z) @result{} "xyz"
+(string) @result{} ""
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} list->string lst
+@deffnx {C Function} scm_string (lst)
@rnindex list->string
-@deffn {Scheme Procedure} string . chrs
-@deffnx {Scheme Procedure} list->string chrs
-@deffnx {C Function} scm_string (chrs)
-Return a newly allocated string composed of the arguments,
-@var{chrs}.
+Return a newly allocated string made from a list of characters.
+
+@example
+(list->string '(#\a #\b #\c)) @result{} "abc"
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} reverse-list->string lst
+@deffnx {C Function} scm_reverse_list_to_string (lst)
+Return a newly allocated string made from a list of characters, in
+reverse order.
+
+@example
+(reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
+@end example
@end deffn
@rnindex make-string
of the @var{string} are unspecified.
@end deffn
+@deftypefn {C Function} SCM scm_c_make_string (size_t len, SCM chr)
+Like @code{scm_make_string}, but expects the length as a
+@code{size_t}.
+@end deftypefn
+
+@deffn {Scheme Procedure} string-tabulate proc len
+@deffnx {C Function} scm_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
+
+@deffn {Scheme Procedure} string-join ls [delimiter [grammar]]
+@deffnx {C Function} scm_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
+
@node List/String Conversion
@subsubsection List/String conversion
These procedures are useful for similar tasks.
@rnindex string->list
-@deffn {Scheme Procedure} string->list str
+@deffn {Scheme Procedure} string->list str [start [end]]
+@deffnx {C Function} scm_substring_to_list (str, start, end)
@deffnx {C Function} scm_string_to_list (str)
-Return a newly allocated list of the characters that make up
-the given string @var{str}. @code{string->list} and
-@code{list->string} are inverses as far as @samp{equal?} is
-concerned.
+Convert the string @var{str} into a list of characters.
@end deffn
@deffn {Scheme Procedure} string-split str chr
Return the number of characters in @var{string}.
@end deffn
+@deftypefn {C Function} size_t scm_c_string_length (SCM str)
+Return the number of characters in @var{str} as a @code{size_t}.
+@end deftypefn
+
@rnindex string-ref
@deffn {Scheme Procedure} string-ref str k
@deffnx {C Function} scm_string_ref (str, k)
indexing. @var{k} must be a valid index of @var{str}.
@end deffn
+@deftypefn {C Function} SCM scm_c_string_ref (SCM str, size_t k)
+Return character @var{k} of @var{str} using zero-origin
+indexing. @var{k} must be a valid index of @var{str}.
+@end deftypefn
+
@rnindex string-copy
-@deffn {Scheme Procedure} string-copy str
+@deffn {Scheme Procedure} string-copy str [start [end]]
+@deffnx {C Function} scm_substring_copy (str, start, end)
@deffnx {C Function} scm_string_copy (str)
-Return a newly allocated copy of the given @var{string}.
+Return a copy of the given string @var{str}.
+
+The returned string shares storage with @var{str} initially, but it is
+copied as soon as one of the two strings is modified.
@end deffn
@rnindex substring
@deffn {Scheme Procedure} substring str start [end]
@deffnx {C Function} scm_substring (str, start, end)
-Return a newly allocated string formed from the characters
+Return a new string formed from the characters
of @var{str} beginning with index @var{start} (inclusive) and
ending with index @var{end} (exclusive).
@var{str} must be a string, @var{start} and @var{end} must be
exact integers satisfying:
0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
+
+The returned string shares storage with @var{str} initially, but it is
+copied as soon as one of the two strings is modified.
@end deffn
-@node String Modification
-@subsubsection String Modification
+@deffn {Scheme Procedure} substring/shared str start [end]
+@deffnx {C Function} scm_substring_shared (str, start, end)
+Like @code{substring}, but the strings continue to share their storage
+even if they are modified. Thus, modifications to @var{str} show up
+in the new string, and vice versa.
+@end deffn
-These procedures are for modifying strings in-place. This means that the
-result of the operation is not a new string; instead, the original string's
-memory representation is modified.
+@deffn {Scheme Procedure} substring/copy str start [end]
+@deffnx {C Function} scm_substring_copy (str, start, end)
+Like @code{substring}, but the storage for the new string is copied
+immediately.
+@end deffn
-@rnindex string-set!
-@deffn {Scheme Procedure} string-set! str k chr
-@deffnx {C Function} scm_string_set_x (str, k, chr)
-Store @var{chr} in element @var{k} of @var{str} and return
-an unspecified value. @var{k} must be a valid index of
-@var{str}.
+@deffn {Scheme Procedure} substring/read-only str start [end]
+@deffnx {C Function} scm_substring_read_only (str, start, end)
+Like @code{substring}, but the resulting string can not be modified.
@end deffn
+@deftypefn {C Function} SCM scm_c_substring (SCM str, size_t start, size_t end)
+@deftypefnx {C Function} SCM scm_c_substring_shared (SCM str, size_t start, size_t end)
+@deftypefnx {C Function} SCM scm_c_substring_copy (SCM str, size_t start, size_t end)
+@deftypefnx {C Function} SCM scm_c_substring_read_only (SCM str, size_t start, size_t end)
+Like @code{scm_substring}, etc. but the bounds are given as a @code{size_t}.
+@end deftypefn
+
+@deffn {Scheme Procedure} string-take s n
+@deffnx {C Function} scm_string_take (s, n)
+Return the @var{n} first characters of @var{s}.
+@end deffn
+
+@deffn {Scheme Procedure} string-drop s n
+@deffnx {C Function} scm_string_drop (s, n)
+Return all but the first @var{n} characters of @var{s}.
+@end deffn
+
+@deffn {Scheme Procedure} string-take-right s n
+@deffnx {C Function} scm_string_take_right (s, n)
+Return the @var{n} last characters of @var{s}.
+@end deffn
+
+@deffn {Scheme Procedure} string-drop-right s n
+@deffnx {C Function} scm_string_drop_right (s, n)
+Return all but the last @var{n} characters of @var{s}.
+@end deffn
+
+@deffn {Scheme Procedure} string-pad s len [chr [start [end]]]
+@deffnx {Scheme Procedure} string-pad-right s len [chr [start [end]]]
+@deffnx {C Function} scm_string_pad (s, len, chr, start, end)
+@deffnx {C Function} scm_string_pad_right (s, len, chr, start, end)
+Take characters @var{start} to @var{end} from the string @var{s} and
+either pad with @var{char} or truncate them to give @var{len}
+characters.
+
+@code{string-pad} pads or truncates on the left, so for example
+
+@example
+(string-pad "x" 3) @result{} " x"
+(string-pad "abcde" 3) @result{} "cde"
+@end example
+
+@code{string-pad-right} pads or truncates on the right, so for example
+
+@example
+(string-pad-right "x" 3) @result{} "x "
+(string-pad-right "abcde" 3) @result{} "abc"
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} string-trim s [char_pred [start [end]]]
+@deffnx {Scheme Procedure} string-trim-right s [char_pred [start [end]]]
+@deffnx {Scheme Procedure} string-trim-both s [char_pred [start [end]]]
+@deffnx {C Function} scm_string_trim (s, char_pred, start, end)
+@deffnx {C Function} scm_string_trim_right (s, char_pred, start, end)
+@deffnx {C Function} scm_string_trim_both (s, char_pred, start, end)
+Trim occurrances of @var{char_pred} from the ends of @var{s}.
+
+@code{string-trim} trims @var{char_pred} characters from the left
+(start) of the string, @code{string-trim-right} trims them from the
+right (end) of the string, @code{string-trim-both} trims from both
+ends.
+
+@var{char_pred} can be a character, a character set, or a predicate
+procedure to call on each character. If @var{char_pred} is not given
+the default is whitespace as per @code{char-set:whitespace}
+(@pxref{Standard Character Sets}).
+
+@example
+(string-trim " x ") @result{} "x "
+(string-trim-right "banana" #\a) @result{} "banan"
+(string-trim-both ".,xy:;" char-set:punctuation)
+ @result{} "xy"
+(string-trim-both "xyzzy" (lambda (c)
+ (or (eqv? c #\x)
+ (eqv? c #\y))))
+ @result{} "zz"
+@end example
+@end deffn
+
+@node String Modification
+@subsubsection String Modification
+
+These procedures are for modifying strings in-place. This means that the
+result of the operation is not a new string; instead, the original string's
+memory representation is modified.
+
+@rnindex string-set!
+@deffn {Scheme Procedure} string-set! str k chr
+@deffnx {C Function} scm_string_set_x (str, k, chr)
+Store @var{chr} in element @var{k} of @var{str} and return
+an unspecified value. @var{k} must be a valid index of
+@var{str}.
+@end deffn
+
+@deftypefn {C Function} void scm_c_string_set_x (SCM str, size_t k, SCM chr)
+Like @code{scm_string_set_x}, but the index is given as a @code{size_t}.
+@end deftypefn
+
@rnindex string-fill!
-@deffn {Scheme Procedure} string-fill! str chr
+@deffn {Scheme Procedure} string-fill! str chr [start [end]]
+@deffnx {C Function} scm_substring_fill_x (str, chr, start, end)
@deffnx {C Function} scm_string_fill_x (str, chr)
-Store @var{char} in every element of the given @var{string} and
-return an unspecified value.
+Stores @var{chr} in every element of the given @var{str} and
+returns an unspecified value.
@end deffn
@deffn {Scheme Procedure} substring-fill! str start end fill
@var{str1} and @var{str2} can be the same string.
@end deffn
+@deffn {Scheme Procedure} string-copy! target tstart s [start [end]]
+@deffnx {C Function} scm_string_copy_x (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
+
@node String Comparison
@subsubsection String Comparison
The procedures in this section are similar to the character ordering
predicates (@pxref{Characters}), but are defined on character sequences.
-They all return @code{#t} on success and @code{#f} on failure. The
-predicates ending in @code{-ci} ignore the character case when comparing
-strings.
+The first set is specified in R5RS and has names that end in @code{?}.
+The second set is specified in SRFI-13 and the names have no ending
+@code{?}. The predicates ending in @code{-ci} ignore the character case
+when comparing strings. @xref{The ice-9 i18n Module, the @code{(ice-9
+i18n)} module}, for locale-dependent string comparison.
@rnindex string=?
@deffn {Scheme Procedure} string=? s1 s2
return @code{#f}.
@end deffn
-@rnindex string-ci<
+@rnindex string-ci<?
@deffn {Scheme Procedure} string-ci<? s1 s2
Case insensitive lexicographic ordering predicate; return
@code{#t} if @var{s1} is lexicographically less than @var{s2}
equal to @var{s2} regardless of case.
@end deffn
+@deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_compare (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.
+@end deffn
+
+@deffn {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_compare_ci (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
+Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
+mismatch index, depending upon whether @var{s1} is less than,
+equal to, or greater than @var{s2}. The mismatch index is the
+largest index @var{i} such that for every 0 <= @var{j} <
+@var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
+@var{i} is the first position that does not match. The
+character comparison is done case-insensitively.
+@end deffn
+
+@deffn {Scheme Procedure} string= s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_eq (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
+value otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} string<> s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_neq (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} and @var{s2} are equal, a true
+value otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} string< s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_lt (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
+true value otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} string> s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_gt (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
+true value otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} string<= s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_le (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} is greater to @var{s2}, a true
+value otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} string>= s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_ge (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} is less to @var{s2}, a true value
+otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} string-ci= s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_ci_eq (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
+value otherwise. The character comparison is done
+case-insensitively.
+@end deffn
+
+@deffn {Scheme Procedure} string-ci<> s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_ci_neq (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} and @var{s2} are equal, a true
+value otherwise. The character comparison is done
+case-insensitively.
+@end deffn
+
+@deffn {Scheme Procedure} string-ci< s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_ci_lt (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
+true value otherwise. The character comparison is done
+case-insensitively.
+@end deffn
+
+@deffn {Scheme Procedure} string-ci> s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_ci_gt (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
+true value otherwise. The character comparison is done
+case-insensitively.
+@end deffn
+
+@deffn {Scheme Procedure} string-ci<= s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_ci_le (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} is greater to @var{s2}, a true
+value otherwise. The character comparison is done
+case-insensitively.
+@end deffn
+
+@deffn {Scheme Procedure} string-ci>= s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_ci_ge (s1, s2, start1, end1, start2, end2)
+Return @code{#f} if @var{s1} is less to @var{s2}, a true value
+otherwise. The character comparison is done
+case-insensitively.
+@end deffn
+
+@deffn {Scheme Procedure} string-hash s [bound [start [end]]]
+@deffnx {C Function} scm_substring_hash (s, bound, start, end)
+Compute a hash value for @var{S}. the optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound).
+@end deffn
+
+@deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
+@deffnx {C Function} scm_substring_hash_ci (s, bound, start, end)
+Compute a hash value for @var{S}. the optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound).
+@end deffn
@node String Searching
@subsubsection String Searching
-When searching for the index of a character in a string, these
-procedures can be used.
+@deffn {Scheme Procedure} string-index s char_pred [start [end]]
+@deffnx {C Function} scm_string_index (s, char_pred, start, end)
+Search through the string @var{s} from left to right, returning
+the index of the first occurence of a character which
-@deffn {Scheme Procedure} string-index str chr [frm [to]]
-@deffnx {C Function} scm_string_index (str, chr, frm, to)
-Return the index of the first occurrence of @var{chr} in
-@var{str}. The optional integer arguments @var{frm} and
-@var{to} limit the search to a portion of the string. This
-procedure essentially implements the @code{index} or
-@code{strchr} functions from the C library.
+@itemize @bullet
+@item
+equals @var{char_pred}, if it is character,
-@lisp
-(string-index "weiner" #\e)
-@result{} 1
+@item
+satisifies the predicate @var{char_pred}, if it is a procedure,
-(string-index "weiner" #\e 2)
-@result{} 4
+@item
+is in the set @var{char_pred}, if it is a character set.
+@end itemize
+@end deffn
-(string-index "weiner" #\e 2 4)
-@result{} #f
-@end lisp
+@deffn {Scheme Procedure} string-rindex s char_pred [start [end]]
+@deffnx {C Function} scm_string_rindex (s, char_pred, start, end)
+Search through the string @var{s} from right to left, returning
+the index of the last occurence of a character which
+
+@itemize @bullet
+@item
+equals @var{char_pred}, if it is character,
+
+@item
+satisifies the predicate @var{char_pred}, if it is a procedure,
+
+@item
+is in the set if @var{char_pred} is a character set.
+@end itemize
@end deffn
-@deffn {Scheme Procedure} string-rindex str chr [frm [to]]
-@deffnx {C Function} scm_string_rindex (str, chr, frm, to)
-Like @code{string-index}, but search from the right of the
-string rather than from the left. This procedure essentially
-implements the @code{rindex} or @code{strrchr} functions from
-the C library.
+@deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_prefix_length (s1, s2, start1, end1, start2, end2)
+Return the length of the longest common prefix of the two
+strings.
+@end deffn
-@lisp
-(string-rindex "weiner" #\e)
-@result{} 4
+@deffn {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_prefix_length_ci (s1, s2, start1, end1, start2, end2)
+Return the length of the longest common prefix of the two
+strings, ignoring character case.
+@end deffn
-(string-rindex "weiner" #\e 2 4)
-@result{} #f
+@deffn {Scheme Procedure} string-suffix-length s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_suffix_length (s1, s2, start1, end1, start2, end2)
+Return the length of the longest common suffix of the two
+strings.
+@end deffn
-(string-rindex "weiner" #\e 2 5)
-@result{} 4
-@end lisp
+@deffn {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_suffix_length_ci (s1, s2, start1, end1, start2, end2)
+Return the length of the longest common suffix of the two
+strings, ignoring character case.
+@end deffn
+
+@deffn {Scheme Procedure} string-prefix? s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_prefix_p (s1, s2, start1, end1, start2, end2)
+Is @var{s1} a prefix of @var{s2}?
+@end deffn
+
+@deffn {Scheme Procedure} string-prefix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_prefix_ci_p (s1, s2, start1, end1, start2, end2)
+Is @var{s1} a prefix of @var{s2}, ignoring character case?
+@end deffn
+
+@deffn {Scheme Procedure} string-suffix? s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_suffix_p (s1, s2, start1, end1, start2, end2)
+Is @var{s1} a suffix of @var{s2}?
+@end deffn
+
+@deffn {Scheme Procedure} string-suffix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_suffix_ci_p (s1, s2, start1, end1, start2, end2)
+Is @var{s1} a suffix of @var{s2}, ignoring character case?
+@end deffn
+
+@deffn {Scheme Procedure} string-index-right s char_pred [start [end]]
+@deffnx {C Function} scm_string_index_right (s, char_pred, start, end)
+Search through the string @var{s} from right to left, returning
+the index of the last occurence of a character which
+
+@itemize @bullet
+@item
+equals @var{char_pred}, if it is character,
+
+@item
+satisifies the predicate @var{char_pred}, if it is a procedure,
+
+@item
+is in the set if @var{char_pred} is a character set.
+@end itemize
+@end deffn
+
+@deffn {Scheme Procedure} string-skip s char_pred [start [end]]
+@deffnx {C Function} scm_string_skip (s, char_pred, start, end)
+Search through the string @var{s} from left to right, returning
+the index of the first occurence of a character which
+
+@itemize @bullet
+@item
+does not equal @var{char_pred}, if it is character,
+
+@item
+does not satisify the predicate @var{char_pred}, if it is a
+procedure,
+
+@item
+is not in the set if @var{char_pred} is a character set.
+@end itemize
+@end deffn
+
+@deffn {Scheme Procedure} string-skip-right s char_pred [start [end]]
+@deffnx {C Function} scm_string_skip_right (s, char_pred, start, end)
+Search through the string @var{s} from right to left, returning
+the index of the last occurence of a character which
+
+@itemize @bullet
+@item
+does not equal @var{char_pred}, if it is character,
+
+@item
+does not satisfy the predicate @var{char_pred}, if it is a
+procedure,
+
+@item
+is not in the set if @var{char_pred} is a character set.
+@end itemize
+@end deffn
+
+@deffn {Scheme Procedure} string-count s char_pred [start [end]]
+@deffnx {C Function} scm_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 {Scheme Procedure} string-contains s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_contains (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.
+@end deffn
+
+@deffn {Scheme Procedure} string-contains-ci s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_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. Character comparison is done
+case-insensitively.
@end deffn
@node Alphabetic Case Mapping
These are procedures for mapping strings to their upper- or lower-case
equivalents, respectively, or for capitalizing strings.
-@deffn {Scheme Procedure} string-upcase str
+@deffn {Scheme Procedure} string-upcase str [start [end]]
+@deffnx {C Function} scm_substring_upcase (str, start, end)
@deffnx {C Function} scm_string_upcase (str)
-Return a freshly allocated string containing the characters of
-@var{str} in upper case.
+Upcase every character in @code{str}.
@end deffn
-@deffn {Scheme Procedure} string-upcase! str
+@deffn {Scheme Procedure} string-upcase! str [start [end]]
+@deffnx {C Function} scm_substring_upcase_x (str, start, end)
@deffnx {C Function} scm_string_upcase_x (str)
-Destructively upcase every character in @var{str} and return
-@var{str}.
+Destructively upcase every character in @code{str}.
+
@lisp
-y @result{} "arrdefg"
-(string-upcase! y) @result{} "ARRDEFG"
-y @result{} "ARRDEFG"
+(string-upcase! y)
+@result{} "ARRDEFG"
+y
+@result{} "ARRDEFG"
@end lisp
@end deffn
-@deffn {Scheme Procedure} string-downcase str
+@deffn {Scheme Procedure} string-downcase str [start [end]]
+@deffnx {C Function} scm_substring_downcase (str, start, end)
@deffnx {C Function} scm_string_downcase (str)
-Return a freshly allocation string containing the characters in
-@var{str} in lower case.
+Downcase every character in @var{str}.
@end deffn
-@deffn {Scheme Procedure} string-downcase! str
+@deffn {Scheme Procedure} string-downcase! str [start [end]]
+@deffnx {C Function} scm_substring_downcase_x (str, start, end)
@deffnx {C Function} scm_string_downcase_x (str)
-Destructively downcase every character in @var{str} and return
-@var{str}.
+Destructively downcase every character in @var{str}.
+
@lisp
-y @result{} "ARRDEFG"
-(string-downcase! y) @result{} "arrdefg"
-y @result{} "arrdefg"
+y
+@result{} "ARRDEFG"
+(string-downcase! y)
+@result{} "arrdefg"
+y
+@result{} "arrdefg"
@end lisp
@end deffn
@end lisp
@end deffn
+@deffn {Scheme Procedure} string-titlecase str [start [end]]
+@deffnx {C Function} scm_string_titlecase (str, start, end)
+Titlecase every first character in a word in @var{str}.
+@end deffn
-@node Appending Strings
-@subsubsection Appending Strings
+@deffn {Scheme Procedure} string-titlecase! str [start [end]]
+@deffnx {C Function} scm_string_titlecase_x (str, start, end)
+Destructively titlecase every first character in a word in
+@var{str}.
+@end deffn
-The procedure @code{string-append} appends several strings together to
-form a longer result string.
+@node Reversing and Appending Strings
+@subsubsection Reversing and Appending Strings
+
+@deffn {Scheme Procedure} string-reverse str [start [end]]
+@deffnx {C Function} scm_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.
+@end deffn
+
+@deffn {Scheme Procedure} string-reverse! str [start [end]]
+@deffnx {C Function} scm_string_reverse_x (str, start, end)
+Reverse the string @var{str} in-place. The optional arguments
+@var{start} and @var{end} delimit the region of @var{str} to
+operate on. The return value is unspecified.
+@end deffn
@rnindex string-append
@deffn {Scheme Procedure} string-append . args
@end example
@end deffn
+@deffn {Scheme Procedure} string-append/shared . ls
+@deffnx {C Function} scm_string_append_shared (ls)
+Like @code{string-append}, but the result may share memory
+with the argument strings.
+@end deffn
+
+@deffn {Scheme Procedure} string-concatenate ls
+@deffnx {C Function} scm_string_concatenate (ls)
+Append the elements of @var{ls} (which must be strings)
+together into a single string. Guaranteed to return a freshly
+allocated string.
+@end deffn
+
+@deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]]
+@deffnx {C Function} scm_string_concatenate_reverse (ls, final_string, end)
+Without optional arguments, this procedure is equivalent to
+
+@smalllisp
+(string-concatenate (reverse ls))
+@end smalllisp
+
+If the optional argument @var{final_string} is specified, it is
+consed onto the beginning to @var{ls} before performing the
+list-reverse and string-concatenate operations. If @var{end}
+is given, only the characters of @var{final_string} up to index
+@var{end} are used.
+
+Guaranteed to return a freshly allocated string.
+@end deffn
+
+@deffn {Scheme Procedure} string-concatenate/shared ls
+@deffnx {C Function} scm_string_concatenate_shared (ls)
+Like @code{string-concatenate}, but the result may share memory
+with the strings in the list @var{ls}.
+@end deffn
+
+@deffn {Scheme Procedure} string-concatenate-reverse/shared ls [final_string [end]]
+@deffnx {C Function} scm_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
+
+@node Mapping Folding and Unfolding
+@subsubsection Mapping, Folding, and Unfolding
+
+@deffn {Scheme Procedure} string-map proc s [start [end]]
+@deffnx {C Function} scm_string_map (proc, s, start, end)
+@var{proc} is a char->char procedure, it is mapped over
+@var{s}. The order in which the procedure is applied to the
+string elements is not specified.
+@end deffn
+
+@deffn {Scheme Procedure} string-map! proc s [start [end]]
+@deffnx {C Function} scm_string_map_x (proc, s, start, end)
+@var{proc} is a char->char procedure, it is mapped over
+@var{s}. The order in which the procedure is applied to the
+string elements is not specified. The string @var{s} is
+modified in-place, the return value is not specified.
+@end deffn
+
+@deffn {Scheme Procedure} string-for-each proc s [start [end]]
+@deffnx {C Function} scm_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
+
+@deffn {Scheme Procedure} string-for-each-index proc s [start [end]]
+@deffnx {C Function} scm_string_for_each_index (proc, s, start, end)
+Call @code{(@var{proc} i)} for each index i in @var{s}, from left to
+right.
+
+For example, to change characters to alternately upper and lower case,
+
+@example
+(define str (string-copy "studly"))
+(string-for-each-index (lambda (i)
+ (string-set! str i
+ ((if (even? i) char-upcase char-downcase)
+ (string-ref str i))))
+ str)
+str @result{} "StUdLy"
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} string-fold kons knil s [start [end]]
+@deffnx {C Function} scm_string_fold (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. @var{kons}
+must expect two arguments: The actual character and the last
+result of @var{kons}' application.
+@end deffn
+
+@deffn {Scheme Procedure} string-fold-right kons knil s [start [end]]
+@deffnx {C Function} scm_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 right to left. @var{kons}
+must expect two arguments: The actual character and the last
+result of @var{kons}' application.
+@end deffn
+
+@deffn {Scheme Procedure} string-unfold p f g seed [base [make_final]]
+@deffnx {C Function} scm_string_unfold (p, f, g, seed, base, make_final)
+@itemize @bullet
+@item @var{g} is used to generate a series of @emph{seed}
+values from the initial @var{seed}: @var{seed}, (@var{g}
+@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
+@dots{}
+@item @var{p} tells us when to stop -- when it returns true
+when applied to one of these seed values.
+@item @var{f} maps each seed value to the corresponding
+character in the result string. These chars are assembled
+into the string in a left-to-right order.
+@item @var{base} is the optional initial/leftmost 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 portion of the constructed string.
+It defaults to @code{(lambda (x) )}.
+@end itemize
+@end deffn
+
+@deffn {Scheme Procedure} string-unfold-right p f g seed [base [make_final]]
+@deffnx {C Function} scm_string_unfold_right (p, f, g, seed, base, make_final)
+@itemize @bullet
+@item @var{g} is used to generate a series of @emph{seed}
+values from the initial @var{seed}: @var{seed}, (@var{g}
+@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
+@dots{}
+@item @var{p} tells us when to stop -- when it returns true
+when applied to one of these seed values.
+@item @var{f} maps each seed value to the corresponding
+character in the result string. These chars are assembled
+into the string in a right-to-left order.
+@item @var{base} is the optional initial/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/leftmost portion of the constructed string.
+It defaults to @code{(lambda (x) )}.
+@end itemize
+@end deffn
+
+@node Miscellaneous String Operations
+@subsubsection Miscellaneous String Operations
+
+@deffn {Scheme Procedure} xsubstring s from [to [start [end]]]
+@deffnx {C Function} scm_xsubstring (s, from, to, start, end)
+This is the @emph{extended substring} procedure that implements
+replicated copying of a substring of some string.
+
+@var{s} is a string, @var{start} and @var{end} are optional
+arguments that demarcate a substring of @var{s}, defaulting to
+0 and the length of @var{s}. Replicate this substring up and
+down index space, in both the positive and negative directions.
+@code{xsubstring} returns the substring of this string
+beginning at index @var{from}, and ending at @var{to}, which
+defaults to @var{from} + (@var{end} - @var{start}).
+@end deffn
+
+@deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto [start [end]]]
+@deffnx {C Function} scm_string_xcopy_x (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
+
+@deffn {Scheme Procedure} string-replace s1 s2 [start1 [end1 [start2 [end2]]]]
+@deffnx {C Function} scm_string_replace (s1, s2, start1, end1, start2, end2)
+Return the string @var{s1}, but with the characters
+@var{start1} @dots{} @var{end1} replaced by the characters
+@var{start2} @dots{} @var{end2} from @var{s2}.
+@end deffn
+
+@deffn {Scheme Procedure} string-tokenize s [token_set [start [end]]]
+@deffnx {C Function} scm_string_tokenize (s, token_set, start, end)
+Split the string @var{s} into a list of substrings, where each
+substring is a maximal non-empty contiguous sequence of
+characters from the character set @var{token_set}, which
+defaults to @code{char-set:graphic}.
+If @var{start} or @var{end} indices are provided, they restrict
+@code{string-tokenize} to operating on the indicated substring
+of @var{s}.
+@end deffn
+
+@deffn {Scheme Procedure} string-filter s char_pred [start [end]]
+@deffnx {C Function} scm_string_filter (s, char_pred, start, end)
+Filter the string @var{s}, retaining only those characters which
+satisfy @var{char_pred}.
+
+If @var{char_pred} is a procedure, it is applied to each character as
+a predicate, if it is a character, it is tested for equality and if it
+is a character set, it is tested for membership.
+@end deffn
+
+@deffn {Scheme Procedure} string-delete s char_pred [start [end]]
+@deffnx {C Function} scm_string_delete (s, char_pred, start, end)
+Delete characters satisfying @var{char_pred} from @var{s}.
+
+If @var{char_pred} is a procedure, it is applied to each character as
+a predicate, if it is a character, it is tested for equality and if it
+is a character set, it is tested for membership.
+@end deffn
+
+@node Conversion to/from C
+@subsubsection Conversion to/from C
+
+When creating a Scheme string from a C string or when converting a
+Scheme string to a C string, the concept of character encoding becomes
+important.
+
+In C, a string is just a sequence of bytes, and the character encoding
+describes the relation between these bytes and the actual characters
+that make up the string. For Scheme strings, character encoding is
+not an issue (most of the time), since in Scheme you never get to see
+the bytes, only the characters.
+
+Well, ideally, anyway. Right now, Guile simply equates Scheme
+characters and bytes, ignoring the possibility of multi-byte encodings
+completely. This will change in the future, where Guile will use
+Unicode codepoints as its characters and UTF-8 or some other encoding
+as its internal encoding. When you exclusively use the functions
+listed in this section, you are `future-proof'.
+
+Converting a Scheme string to a C string will often allocate fresh
+memory to hold the result. You must take care that this memory is
+properly freed eventually. In many cases, this can be achieved by
+using @code{scm_dynwind_free} inside an appropriate dynwind context,
+@xref{Dynamic Wind}.
+
+@deftypefn {C Function} SCM scm_from_locale_string (const char *str)
+@deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
+Creates a new Scheme string that has the same contents as @var{str}
+when interpreted in the current locale character encoding.
+
+For @code{scm_from_locale_string}, @var{str} must be null-terminated.
+
+For @code{scm_from_locale_stringn}, @var{len} specifies the length of
+@var{str} in bytes, and @var{str} does not need to be null-terminated.
+If @var{len} is @code{(size_t)-1}, then @var{str} does need to be
+null-terminated and the real length will be found with @code{strlen}.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_take_locale_string (char *str)
+@deftypefnx {C Function} SCM scm_take_locale_stringn (char *str, size_t len)
+Like @code{scm_from_locale_string} and @code{scm_from_locale_stringn},
+respectively, but also frees @var{str} with @code{free} eventually.
+Thus, you can use this function when you would free @var{str} anyway
+immediately after creating the Scheme string. In certain cases, Guile
+can then use @var{str} directly as its internal representation.
+@end deftypefn
+
+@deftypefn {C Function} {char *} scm_to_locale_string (SCM str)
+@deftypefnx {C Function} {char *} scm_to_locale_stringn (SCM str, size_t *lenp)
+Returns a C string in the current locale encoding with the same
+contents as @var{str}. The C string must be freed with @code{free}
+eventually, maybe by using @code{scm_dynwind_free}, @xref{Dynamic
+Wind}.
+
+For @code{scm_to_locale_string}, the returned string is
+null-terminated and an error is signalled when @var{str} contains
+@code{#\nul} characters.
+
+For @code{scm_to_locale_stringn} and @var{lenp} not @code{NULL},
+@var{str} might contain @code{#\nul} characters and the length of the
+returned string in bytes is stored in @code{*@var{lenp}}. The
+returned string will not be null-terminated in this case. If
+@var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
+@code{scm_to_locale_string}.
+@end deftypefn
+
+@deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
+Puts @var{str} as a C string in the current locale encoding into the
+memory pointed to by @var{buf}. The buffer at @var{buf} has room for
+@var{max_len} bytes and @code{scm_to_local_stringbuf} will never store
+more than that. No terminating @code{'\0'} will be stored.
+
+The return value of @code{scm_to_locale_stringbuf} is the number of
+bytes that are needed for all of @var{str}, regardless of whether
+@var{buf} was large enough to hold them. Thus, when the return value
+is larger than @var{max_len}, only @var{max_len} bytes have been
+stored and you probably need to try again with a larger buffer.
+@end deftypefn
@node Regular Expressions
@subsection Regular Expressions
implemented by SCSH, the Scheme Shell. It is intended to be
upwardly compatible with SCSH regular expressions.
+Zero bytes (@code{#\nul}) cannot be used in regex patterns or input
+strings, since the underlying C functions treat that as the end of
+string. If there's a zero byte an error is thrown.
+
+Patterns and input strings are treated as being in the locale
+character set if @code{setlocale} has been called (@pxref{Locales}),
+and in a multibyte locale this includes treating multi-byte sequences
+as a single character. (Guile strings are currently merely bytes,
+though this may change in the future, @xref{Conversion to/from C}.)
+
@deffn {Scheme Procedure} string-match pattern str [start]
Compile the string @var{pattern} into a regular expression and compare
it with @var{str}. The optional numeric argument @var{start} specifies
Return a match structure describing the results of the match,
or @code{#f} if no match could be found.
-The @var{flags} arguments change the matching behavior.
-The following flags may be supplied:
+The @var{flags} argument changes the matching behavior. The following
+flag values may be supplied, use @code{logior} (@pxref{Bitwise
+Operations}) to combine them,
@defvar regexp/notbol
-Operator @samp{^} always fails (unless @code{regexp/newline}
-is used). Use this when the beginning of the string should
-not be considered the beginning of a line.
+Consider that the @var{start} offset into @var{str} is not the
+beginning of a line and should not match operator @samp{^}.
+
+If @var{rx} was created with the @code{regexp/newline} option above,
+@samp{^} will still match after a newline in @var{str}.
@end defvar
@defvar regexp/noteol
-Operator @samp{$} always fails (unless @code{regexp/newline}
-is used). Use this when the end of the string should not be
-considered the end of a line.
+Consider that the end of @var{str} is not the end of a line and should
+not match operator @samp{$}.
+
+If @var{rx} was created with the @code{regexp/newline} option above,
+@samp{$} will still match before a newline in @var{str}.
@end defvar
@end deffn
or @code{#f} otherwise.
@end deffn
-Regular expressions are commonly used to find patterns in one string and
-replace them with the contents of another string.
+@sp 1
+@deffn {Scheme Procedure} list-matches regexp str [flags]
+Return a list of match structures which are the non-overlapping
+matches of @var{regexp} in @var{str}. @var{regexp} can be either a
+pattern string or a compiled regexp. The @var{flags} argument is as
+per @code{regexp-exec} above.
+
+@example
+(map match:substring (list-matches "[a-z]+" "abc 42 def 78"))
+@result{} ("abc" "def")
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} fold-matches regexp str init proc [flags]
+Apply @var{proc} to the non-overlapping matches of @var{regexp} in
+@var{str}, to build a result. @var{regexp} can be either a pattern
+string or a compiled regexp. The @var{flags} argument is as per
+@code{regexp-exec} above.
+
+@var{proc} is called as @code{(@var{proc} match prev)} where
+@var{match} is a match structure and @var{prev} is the previous return
+from @var{proc}. For the first call @var{prev} is the given
+@var{init} parameter. @code{fold-matches} returns the final value
+from @var{proc}.
+
+For example to count matches,
+
+@example
+(fold-matches "[a-z][0-9]" "abc x1 def y2" 0
+ (lambda (match count)
+ (1+ count)))
+@result{} 2
+@end example
+@end deffn
+
+@sp 1
+Regular expressions are commonly used to find patterns in one string
+and replace them with the contents of another string. The following
+functions are convenient ways to do this.
@c begin (scm-doc-string "regex.scm" "regexp-substitute")
@deffn {Scheme Procedure} regexp-substitute port match [item@dots{}]
-Write to the output port @var{port} selected contents of the match
-structure @var{match}. Each @var{item} specifies what should be
-written, and may be one of the following arguments:
+Write to @var{port} selected parts of the match structure @var{match}.
+Or if @var{port} is @code{#f} then form a string from those parts and
+return that.
+
+Each @var{item} specifies a part to be written, and may be one of the
+following,
@itemize @bullet
@item
A string. String arguments are written out verbatim.
@item
-An integer. The submatch with that number is written.
+An integer. The submatch with that number is written
+(@code{match:substring}). Zero is the entire match.
@item
The symbol @samp{pre}. The portion of the matched string preceding
-the regexp match is written.
+the regexp match is written (@code{match:prefix}).
@item
The symbol @samp{post}. The portion of the matched string following
-the regexp match is written.
+the regexp match is written (@code{match:suffix}).
@end itemize
-The @var{port} argument may be @code{#f}, in which case nothing is
-written; instead, @code{regexp-substitute} constructs a string from the
-specified @var{item}s and returns that.
-@end deffn
+For example, changing a match and retaining the text before and after,
-The following example takes a regular expression that matches a standard
-@sc{yyyymmdd}-format date such as @code{"20020828"}. The
-@code{regexp-substitute} call returns a string computed from the
-information in the match structure, consisting of the fields and text
-from the original string reordered and reformatted.
+@example
+(regexp-substitute #f (string-match "[0-9]+" "number 25 is good")
+ 'pre "37" 'post)
+@result{} "number 37 is good"
+@end example
+
+Or matching a @sc{yyyymmdd} format date such as @samp{20020828} and
+re-ordering and hyphenating the fields.
@lisp
(define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
(define s "Date 20020429 12am.")
-(define sm (string-match date-regex s))
-(regexp-substitute #f sm 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
+(regexp-substitute #f (string-match date-regex s)
+ 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
@result{} "Date 04-29-2002 12am. (20020429)"
@end lisp
+@end deffn
+
@c begin (scm-doc-string "regex.scm" "regexp-substitute")
@deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
-Similar to @code{regexp-substitute}, but can be used to perform global
-substitutions on @var{str}. Instead of taking a match structure as an
-argument, @code{regexp-substitute/global} takes two string arguments: a
-@var{regexp} string describing a regular expression, and a @var{target}
-string which should be matched against this regular expression.
+@cindex search and replace
+Write to @var{port} selected parts of matches of @var{regexp} in
+@var{target}. If @var{port} is @code{#f} then form a string from
+those parts and return that. @var{regexp} can be a string or a
+compiled regex.
-Each @var{item} behaves as in @code{regexp-substitute}, with the
-following exceptions:
+This is similar to @code{regexp-substitute}, but allows global
+substitutions on @var{target}. Each @var{item} behaves as per
+@code{regexp-substitute}, with the following differences,
@itemize @bullet
@item
-A function may be supplied. When this function is called, it will be
-passed one argument: a match structure for a given regular expression
-match. It should return a string to be written out to @var{port}.
+A function. Called as @code{(@var{item} match)} with the match
+structure for the @var{regexp} match, it should return a string to be
+written to @var{port}.
@item
-The @samp{post} symbol causes @code{regexp-substitute/global} to recurse
-on the unmatched portion of @var{str}. This @emph{must} be supplied in
-order to perform global search-and-replace on @var{str}; if it is not
-present among the @var{item}s, then @code{regexp-substitute/global} will
-return after processing a single match.
+The symbol @samp{post}. This doesn't output anything, but instead
+causes @code{regexp-substitute/global} to recurse on the unmatched
+portion of @var{target}.
+
+This @emph{must} be supplied to perform a global search and replace on
+@var{target}; without it @code{regexp-substitute/global} returns after
+a single match and output.
@end itemize
-@end deffn
-The example above for @code{regexp-substitute} could be rewritten as
-follows to remove the @code{string-match} stage:
+For example, to collapse runs of tabs and spaces to a single hyphen
+each,
+
+@example
+(regexp-substitute/global #f "[ \t]+" "this is the text"
+ 'pre "-" 'post)
+@result{} "this-is-the-text"
+@end example
+
+Or using a function to reverse the letters in each word,
+
+@example
+(regexp-substitute/global #f "[a-z]+" "to do and not-do"
+ 'pre (lambda (m) (string-reverse (match:substring m))) 'post)
+@result{} "ot od dna ton-od"
+@end example
+
+Without the @code{post} symbol, just one regexp match is made. For
+example the following is the date example from
+@code{regexp-substitute} above, without the need for the separate
+@code{string-match} call.
@lisp
(define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
(define s "Date 20020429 12am.")
(regexp-substitute/global #f date-regex s
- 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
+ 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
+
@result{} "Date 04-29-2002 12am. (20020429)"
@end lisp
+@end deffn
@node Match Structures
@code{#f}.
@end deffn
+@deftypefn {C Function} int scm_is_symbol (SCM val)
+Equivalent to @code{scm_is_true (scm_symbol_p (val))}.
+@end deftypefn
+
Once you know that you have a symbol, you can obtain its name as a
string by calling @code{symbol->string}. Note that Guile differs by
default from R5RS on the details of @code{symbol->string} as regards
@end lisp
From C, there are lower level functions that construct a Scheme symbol
-from a null terminated C string or from a sequence of bytes whose length
-is specified explicitly.
+from a C string in the current locale encoding.
-@deffn {C Function} scm_str2symbol (const char * name)
-@deffnx {C Function} scm_mem2symbol (const char * name, size_t len)
+When you want to do more from C, you should convert between symbols
+and strings using @code{scm_symbol_to_string} and
+@code{scm_string_to_symbol} and work with the strings.
+
+@deffn {C Function} scm_from_locale_symbol (const char *name)
+@deffnx {C Function} scm_from_locale_symboln (const char *name, size_t len)
Construct and return a Scheme symbol whose name is specified by
-@var{name}. For @code{scm_str2symbol} @var{name} must be null
-terminated; For @code{scm_mem2symbol} the length of @var{name} is
+@var{name}. For @code{scm_from_locale_symbol}, @var{name} must be null
+terminated; for @code{scm_from_locale_symboln} the length of @var{name} is
specified explicitly by @var{len}.
@end deffn
+@deftypefn {C Function} SCM scm_take_locale_symbol (char *str)
+@deftypefnx {C Function} SCM scm_take_locale_symboln (char *str, size_t len)
+Like @code{scm_from_locale_symbol} and @code{scm_from_locale_symboln},
+respectively, but also frees @var{str} with @code{free} eventually.
+Thus, you can use this function when you would free @var{str} anyway
+immediately after creating the Scheme string. In certain cases, Guile
+can then use @var{str} directly as its internal representation.
+@end deftypefn
+
+
Finally, some applications, especially those that generate new Scheme
code dynamically, need to generate symbols for use in the generated
code. The @code{gensym} primitive meets this need:
@end deffn
Support for these extra slots may be removed in a future release, and it
-is probably better to avoid using them. (In release 1.6, Guile itself
-uses the property list slot sparingly, and the function slot not at
-all.) For a more modern and Schemely approach to properties, see
-@ref{Object Properties}.
+is probably better to avoid using them. For a more modern and Schemely
+approach to properties, see @ref{Object Properties}.
@node Symbol Read Syntax
* Coding With Keywords:: How to use keywords.
* Keyword Read Syntax:: Read syntax for keywords.
* Keyword Procedures:: Procedures for dealing with keywords.
-* Keyword Primitives:: The underlying primitive procedures.
@end menu
@node Why Use Keywords?
@node Keyword Read Syntax
@subsubsection Keyword Read Syntax
-Guile, by default, only recognizes the keyword syntax specified by R5RS.
-A token of the form @code{#:NAME}, where @code{NAME} has the same syntax
-as a Scheme symbol (@pxref{Symbol Read Syntax}), is the external
-representation of the keyword named @code{NAME}. Keyword objects print
-using this syntax as well, so values containing keyword objects can be
-read back into Guile. When used in an expression, keywords are
-self-quoting objects.
+Guile, by default, only recognizes a keyword syntax that is compatible
+with R5RS. A token of the form @code{#:NAME}, where @code{NAME} has the
+same syntax as a Scheme symbol (@pxref{Symbol Read Syntax}), is the
+external representation of the keyword named @code{NAME}. Keyword
+objects print using this syntax as well, so values containing keyword
+objects can be read back into Guile. When used in an expression,
+keywords are self-quoting objects.
If the @code{keyword} read option is set to @code{'prefix}, Guile also
recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
@node Keyword Procedures
@subsubsection Keyword Procedures
-The following procedures can be used for converting symbols to keywords
-and back.
-
-@deffn {Scheme Procedure} symbol->keyword sym
-Return a keyword with the same characters as in @var{sym}.
-@end deffn
-
-@deffn {Scheme Procedure} keyword->symbol kw
-Return a symbol with the same characters as in @var{kw}.
-@end deffn
-
-
-@node Keyword Primitives
-@subsubsection Keyword Primitives
-
-Internally, a keyword is implemented as something like a tagged symbol,
-where the tag identifies the keyword as being self-evaluating, and the
-symbol, known as the keyword's @dfn{dash symbol} has the same name as
-the keyword name but prefixed by a single dash. For example, the
-keyword @code{#:name} has the corresponding dash symbol @code{-name}.
-
-Most keyword objects are constructed automatically by the reader when it
-reads a token beginning with @code{#:}. However, if you need to
-construct a keyword object programmatically, you can do so by calling
-@code{make-keyword-from-dash-symbol} with the corresponding dash symbol
-(as the reader does). The dash symbol for a keyword object can be
-retrieved using the @code{keyword-dash-symbol} procedure.
-
-@deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
-@deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
-Make a keyword object from a @var{symbol} that starts with a dash.
-For example,
-
-@example
-(make-keyword-from-dash-symbol '-foo)
-@result{} #:foo
-@end example
-@end deffn
-
@deffn {Scheme Procedure} keyword? obj
@deffnx {C Function} scm_keyword_p (obj)
Return @code{#t} if the argument @var{obj} is a keyword, else
@code{#f}.
@end deffn
-@deffn {Scheme Procedure} keyword-dash-symbol keyword
-@deffnx {C Function} scm_keyword_dash_symbol (keyword)
-Return the dash symbol for @var{keyword}.
-This is the inverse of @code{make-keyword-from-dash-symbol}.
-For example,
-
-@example
-(keyword-dash-symbol #:foo)
-@result{} -foo
-@end example
+@deffn {Scheme Procedure} keyword->symbol keyword
+@deffnx {C Function} scm_keyword_to_symbol (keyword)
+Return the symbol with the same name as @var{keyword}.
@end deffn
-@deftypefn {C Function} SCM scm_c_make_keyword (char *@var{str})
-Make a keyword object from a string. For example,
+@deffn {Scheme Procedure} symbol->keyword symbol
+@deffnx {C Function} scm_symbol_to_keyword (symbol)
+Return the keyword with the same name as @var{symbol}.
+@end deffn
-@example
-scm_c_make_keyword ("foo")
-@result{} #:foo
-@end example
-@c
-@c FIXME: What can be said about the string argument? Currently it's
-@c not used after creation, but should that be documented?
+@deftypefn {C Function} int scm_is_keyword (SCM obj)
+Equivalent to @code{scm_is_true (scm_keyword_p (@var{obj}))}.
@end deftypefn
+@deftypefn {C Function} SCM scm_from_locale_keyword (const char *str)
+@deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *str, size_t len)
+Equivalent to @code{scm_symbol_to_keyword (scm_from_locale_symbol
+(@var{str}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln
+(@var{str}, @var{len}))}, respectively.
+@end deftypefn
@node Other Types
@subsection ``Functionality-Centric'' Data Types
HCoop / bpt / guile.git / blobdiff