@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007,
+@c 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@node Simple Data Types
@section Simple Generic Data Types
* Character Sets:: Sets of characters.
* Strings:: Sequences of characters.
* Bytevectors:: Sequences of bytes.
-* Regular Expressions:: Pattern matching and substitution.
* Symbols:: Symbols.
* Keywords:: Self-quoting, customizable display keywords.
* Other Types:: "Functionality-centric" data types.
#t
@end lisp
-In test condition contexts like @code{if} and @code{cond} (@pxref{if
-cond case}), where a group of subexpressions will be evaluated only if a
-@var{condition} expression evaluates to ``true'', ``true'' means any
-value at all except @code{#f}.
+In test condition contexts like @code{if} and @code{cond}
+(@pxref{Conditionals}), where a group of subexpressions will be
+evaluated only if a @var{condition} expression evaluates to ``true'',
+``true'' means any value at all except @code{#f}.
@lisp
(if #t "yes" "no")
form. Conversion between these two representations is automatic and
completely invisible to the Scheme level programmer.
-The infinities @samp{+inf.0} and @samp{-inf.0} are considered to be
-inexact integers. They are explained in detail in the next section,
-together with reals and rationals.
-
C has a host of different integer types, and Guile offers a host of
functions to convert between them and the @code{SCM} representation.
For example, a C @code{int} can be handled with @code{scm_to_int} and
@deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x)
@deftypefnx {C Function} size_t scm_to_size_t (SCM x)
@deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x)
+@deftypefnx {C Function} scm_t_ptrdiff scm_to_ptrdiff_t (SCM x)
@deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x)
@deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x)
@deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x)
@deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x)
@deftypefnx {C Function} SCM scm_from_size_t (size_t x)
@deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x)
+@deftypefnx {C Function} SCM scm_from_ptrdiff_t (scm_t_ptrdiff x)
@deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x)
@deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x)
@deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x)
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 @m{\sqrt2, the square root of 2}, and
+are not rational, for example @m{\sqrt{2}, 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
-by storing the numerator and denominator as two exact integers.
-Inexact rationals are stored as floating point numbers using the C
-type @code{double}.
+cannot represent precise finite irrational numbers. Exact rationals are
+represented by storing the numerator and denominator as two exact
+integers. Inexact rationals are stored as floating point numbers using
+the C type @code{double}.
Exact rationals are written as a fraction of integers. There must be
no whitespace around the slash:
4.0
@end lisp
-The limited precision of Guile's encoding means that any ``real'' number
-in Guile can be written in a rational form, by multiplying and then dividing
-by sufficient powers of 10 (or in fact, 2). For example,
-@samp{-0.00000142857931198} is the same as @minus{}142857931198 divided by
-100000000000000000. In Guile's current incarnation, therefore, the
-@code{rational?} and @code{real?} predicates are equivalent.
-
-
-Dividing by an exact zero leads to a error message, as one might
-expect. However, dividing by an inexact zero does not produce an
-error. Instead, the result of the division is either plus or minus
-infinity, depending on the sign of the divided number.
+The limited precision of Guile's encoding means that any finite ``real''
+number in Guile can be written in a rational form, by multiplying and
+then dividing by sufficient powers of 10 (or in fact, 2). For example,
+@samp{-0.00000142857931198} is the same as @minus{}142857931198 divided
+by 100000000000000000. In Guile's current incarnation, therefore, the
+@code{rational?} and @code{real?} predicates are equivalent for finite
+numbers.
-The infinities are written @samp{+inf.0} and @samp{-inf.0},
-respectively. This syntax is also recognized by @code{read} as an
-extension to the usual Scheme syntax.
-Dividing zero by zero yields something that is not a number at all:
-@samp{+nan.0}. This is the special `not a number' value.
+Dividing by an exact zero leads to a error message, as one might expect.
+However, dividing by an inexact zero does not produce an error.
+Instead, the result of the division is either plus or minus infinity,
+depending on the sign of the divided number and the sign of the zero
+divisor (some platforms support signed zeroes @samp{-0.0} and
+@samp{+0.0}; @samp{0.0} is the same as @samp{+0.0}).
+
+Dividing zero by an inexact zero yields a @acronym{NaN} (`not a number')
+value, although they are actually considered numbers by Scheme.
+Attempts to compare a @acronym{NaN} value with any number (including
+itself) using @code{=}, @code{<}, @code{>}, @code{<=} or @code{>=}
+always returns @code{#f}. Although a @acronym{NaN} value is not
+@code{=} to itself, it is both @code{eqv?} and @code{equal?} to itself
+and other @acronym{NaN} values. However, the preferred way to test for
+them is by using @code{nan?}.
+
+The real @acronym{NaN} values and infinities are written @samp{+nan.0},
+@samp{+inf.0} and @samp{-inf.0}. This syntax is also recognized by
+@code{read} as an extension to the usual Scheme syntax. These special
+values are considered by Scheme to be inexact real numbers but not
+rational. Note that non-real complex numbers may also contain
+infinities or @acronym{NaN} values in their real or imaginary parts. To
+test a real number to see if it is infinite, a @acronym{NaN} value, or
+neither, use @code{inf?}, @code{nan?}, or @code{finite?}, respectively.
+Every real number in Scheme belongs to precisely one of those three
+classes.
On platforms that follow @acronym{IEEE} 754 for their floating point
arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
They behave in arithmetic operations like @acronym{IEEE} 754 describes
it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
-The infinities are inexact integers and are considered to be both even
-and odd. While @samp{+nan.0} is not @code{=} to itself, it is
-@code{eqv?} to itself.
-
-To test for the special values, use the functions @code{inf?} and
-@code{nan?}.
-
@deffn {Scheme Procedure} real? obj
@deffnx {C Function} scm_real_p (obj)
Return @code{#t} if @var{obj} is a real number, else @code{#f}. Note
@deffnx {C Function} scm_rational_p (x)
Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise.
Note that the set of integer values forms a subset of the set of
-rational numbers, i. e. the predicate will also be fulfilled if
+rational numbers, i.e.@: the predicate will also be fulfilled if
@var{x} is an integer number.
-
-Since Guile can not represent irrational numbers, every number
-satisfying @code{real?} also satisfies @code{rational?} in Guile.
@end deffn
@deffn {Scheme Procedure} rationalize x eps
@deffn {Scheme Procedure} inf? x
@deffnx {C Function} scm_inf_p (x)
-Return @code{#t} if @var{x} is either @samp{+inf.0} or @samp{-inf.0},
-@code{#f} otherwise.
+Return @code{#t} if the real number @var{x} is @samp{+inf.0} or
+@samp{-inf.0}. Otherwise return @code{#f}.
@end deffn
@deffn {Scheme Procedure} nan? x
@deffnx {C Function} scm_nan_p (x)
-Return @code{#t} if @var{x} is @samp{+nan.0}, @code{#f} otherwise.
+Return @code{#t} if the real number @var{x} is @samp{+nan.0}, or
+@code{#f} otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} finite? x
+@deffnx {C Function} scm_finite_p (x)
+Return @code{#t} if the real number @var{x} is neither infinite nor a
+NaN, @code{#f} otherwise.
@end deffn
@deffn {Scheme Procedure} nan
@deffnx {C Function} scm_nan ()
-Return NaN.
+Return @samp{+nan.0}, a @acronym{NaN} value.
@end deffn
@deffn {Scheme Procedure} inf
@deffnx {C Function} scm_inf ()
-Return Inf.
+Return @samp{+inf.0}, positive infinity.
@end deffn
@deffn {Scheme Procedure} numerator x
-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
-precision as single inexact rational numbers. Guile can not represent
-exact complex numbers with non-zero imaginary parts.
+Guile represents a complex number as a pair of inexact reals, so the
+real and imaginary parts of a complex number have the same properties of
+inexactness and limited precision as single inexact real numbers.
+
+Note that each part of a complex number may contain any inexact real
+value, including the special values @samp{+nan.0}, @samp{+inf.0} and
+@samp{-inf.0}, as well as either of the signed zeroes @samp{0.0} or
+@samp{-0.0}.
+
@deffn {Scheme Procedure} complex? z
@deffnx {C Function} scm_complex_p (z)
-Return @code{#t} if @var{x} is a complex number, @code{#f}
+Return @code{#t} if @var{z} is a complex number, @code{#f}
otherwise. Note that the sets of real, rational and integer
-values form subsets of the set of complex numbers, i. e. the
-predicate will also be fulfilled if @var{x} is a real,
+values form subsets of the set of complex numbers, i.e.@: the
+predicate will also be fulfilled if @var{z} is a real,
rational or integer number.
@end deffn
@rnindex exact->inexact
@rnindex inexact->exact
-R5RS requires that a calculation involving inexact numbers always
-produces an inexact result. To meet this requirement, Guile
-distinguishes between an exact integer value such as @samp{5} and the
-corresponding inexact real value which, to the limited precision
+R5RS requires that, with few exceptions, a calculation involving inexact
+numbers always produces an inexact result. To meet this requirement,
+Guile distinguishes between an exact integer value such as @samp{5} and
+the corresponding inexact integer value which, to the limited precision
available, has no fractional part, and is printed as @samp{5.0}. Guile
will only convert the latter value to the former when forced to do so by
an invocation of the @code{inexact->exact} procedure.
+The only exception to the above requirement is when the values of the
+inexact numbers do not affect the result. For example @code{(expt n 0)}
+is @samp{1} for any value of @code{n}, therefore @code{(expt 5.0 0)} is
+permitted to return an exact @samp{1}.
+
@deffn {Scheme Procedure} exact? z
@deffnx {C Function} scm_exact_p (z)
Return @code{#t} if the number @var{z} is exact, @code{#f}
@end deffn
+@deftypefn {C Function} int scm_is_exact (SCM z)
+Return a @code{1} if the number @var{z} is exact, and @code{0}
+otherwise. This is equivalent to @code{scm_is_true (scm_exact_p (z))}.
+
+An alternate approch to testing the exactness of a number is to
+use @code{scm_is_signed_integer} or @code{scm_is_unsigned_integer}.
+@end deftypefn
+
@deffn {Scheme Procedure} inexact? z
@deffnx {C Function} scm_inexact_p (z)
Return @code{#t} if the number @var{z} is inexact, @code{#f}
else.
@end deffn
+@deftypefn {C Function} int scm_is_inexact (SCM z)
+Return a @code{1} if the number @var{z} is inexact, and @code{0}
+otherwise. This is equivalent to @code{scm_is_true (scm_inexact_p (z))}.
+@end deftypefn
+
@deffn {Scheme Procedure} inexact->exact z
@deffnx {C Function} scm_inexact_to_exact (z)
Return an exact number that is numerically closest to @var{z}, when
(remainder 13 4) @result{} 1
(remainder -13 4) @result{} -1
@end lisp
+
+See also @code{truncate-quotient}, @code{truncate-remainder} and
+related operations in @ref{Arithmetic}.
@end deffn
@c begin (texi-doc-string "guile" "modulo")
(modulo 13 -4) @result{} -3
(modulo -13 -4) @result{} -1
@end lisp
+
+See also @code{floor-quotient}, @code{floor-remainder} and
+related operations in @ref{Arithmetic}.
@end deffn
@c begin (texi-doc-string "guile" "gcd")
@end lisp
@end deffn
+@deftypefn {Scheme Procedure} {} exact-integer-sqrt @var{k}
+@deftypefnx {C Function} void scm_exact_integer_sqrt (SCM @var{k}, SCM *@var{s}, SCM *@var{r})
+Return two exact non-negative integers @var{s} and @var{r}
+such that @math{@var{k} = @var{s}^2 + @var{r}} and
+@math{@var{s}^2 <= @var{k} < (@var{s} + 1)^2}.
+An error is raised if @var{k} is not an exact non-negative integer.
+
+@lisp
+(exact-integer-sqrt 10) @result{} 3 and 1
+@end lisp
+@end deftypefn
+
@node Comparison
@subsubsection Comparison Predicates
@rnindex zero?
expressed by the given @var{string}. @var{radix} must be an
exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
is a default radix that may be overridden by an explicit radix
-prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
+prefix in @var{string} (e.g.@: "#o177"). If @var{radix} is not
supplied, then the default radix is 10. If string is not a
syntactically valid notation for a number, then
@code{string->number} returns @code{#f}.
Return a complex number constructed of the given @var{real-part} and @var{imaginary-part} parts.
@end deffn
-@deffn {Scheme Procedure} make-polar x y
-@deffnx {C Function} scm_make_polar (x, y)
+@deffn {Scheme Procedure} make-polar mag ang
+@deffnx {C Function} scm_make_polar (mag, ang)
@cindex polar form
-Return the complex number @var{x} * e^(i * @var{y}).
+Return the complex number @var{mag} * e^(i * @var{ang}).
@end deffn
@c begin (texi-doc-string "guile" "real-part")
@rnindex ceiling
@rnindex truncate
@rnindex round
+@rnindex euclidean/
+@rnindex euclidean-quotient
+@rnindex euclidean-remainder
+@rnindex floor/
+@rnindex floor-quotient
+@rnindex floor-remainder
+@rnindex ceiling/
+@rnindex ceiling-quotient
+@rnindex ceiling-remainder
+@rnindex truncate/
+@rnindex truncate-quotient
+@rnindex truncate-remainder
+@rnindex centered/
+@rnindex centered-quotient
+@rnindex centered-remainder
+@rnindex round/
+@rnindex round-quotient
+@rnindex round-remainder
The C arithmetic functions below always takes two arguments, while the
Scheme functions can take an arbitrary number. When you need to
invoke them with just one argument, for example to compute the
-equivalent od @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
+equivalent of @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
one: @code{scm_difference (x, SCM_UNDEFINED)}.
@c begin (texi-doc-string "guile" "+")
values.
@end deftypefn
+@deftypefn {Scheme Procedure} {} euclidean/ @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} euclidean-quotient @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} euclidean-remainder @var{x} @var{y}
+@deftypefnx {C Function} void scm_euclidean_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
+@deftypefnx {C Function} SCM scm_euclidean_quotient (SCM @var{x}, SCM @var{y})
+@deftypefnx {C Function} SCM scm_euclidean_remainder (SCM @var{x}, SCM @var{y})
+These procedures accept two real numbers @var{x} and @var{y}, where the
+divisor @var{y} must be non-zero. @code{euclidean-quotient} returns the
+integer @var{q} and @code{euclidean-remainder} returns the real number
+@var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
+@math{0 <= @var{r} < |@var{y}|}. @code{euclidean/} returns both @var{q} and
+@var{r}, and is more efficient than computing each separately. Note
+that when @math{@var{y} > 0}, @code{euclidean-quotient} returns
+@math{floor(@var{x}/@var{y})}, otherwise it returns
+@math{ceiling(@var{x}/@var{y})}.
+
+Note that these operators are equivalent to the R6RS operators
+@code{div}, @code{mod}, and @code{div-and-mod}.
+
+@lisp
+(euclidean-quotient 123 10) @result{} 12
+(euclidean-remainder 123 10) @result{} 3
+(euclidean/ 123 10) @result{} 12 and 3
+(euclidean/ 123 -10) @result{} -12 and 3
+(euclidean/ -123 10) @result{} -13 and 7
+(euclidean/ -123 -10) @result{} 13 and 7
+(euclidean/ -123.2 -63.5) @result{} 2.0 and 3.8
+(euclidean/ 16/3 -10/7) @result{} -3 and 22/21
+@end lisp
+@end deftypefn
+
+@deftypefn {Scheme Procedure} {} floor/ @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} floor-quotient @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} floor-remainder @var{x} @var{y}
+@deftypefnx {C Function} void scm_floor_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
+@deftypefnx {C Function} SCM scm_floor_quotient (@var{x}, @var{y})
+@deftypefnx {C Function} SCM scm_floor_remainder (@var{x}, @var{y})
+These procedures accept two real numbers @var{x} and @var{y}, where the
+divisor @var{y} must be non-zero. @code{floor-quotient} returns the
+integer @var{q} and @code{floor-remainder} returns the real number
+@var{r} such that @math{@var{q} = floor(@var{x}/@var{y})} and
+@math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{floor/} returns
+both @var{q} and @var{r}, and is more efficient than computing each
+separately. Note that @var{r}, if non-zero, will have the same sign
+as @var{y}.
+
+When @var{x} and @var{y} are integers, @code{floor-remainder} is
+equivalent to the R5RS integer-only operator @code{modulo}.
+
+@lisp
+(floor-quotient 123 10) @result{} 12
+(floor-remainder 123 10) @result{} 3
+(floor/ 123 10) @result{} 12 and 3
+(floor/ 123 -10) @result{} -13 and -7
+(floor/ -123 10) @result{} -13 and 7
+(floor/ -123 -10) @result{} 12 and -3
+(floor/ -123.2 -63.5) @result{} 1.0 and -59.7
+(floor/ 16/3 -10/7) @result{} -4 and -8/21
+@end lisp
+@end deftypefn
+
+@deftypefn {Scheme Procedure} {} ceiling/ @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} ceiling-quotient @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} ceiling-remainder @var{x} @var{y}
+@deftypefnx {C Function} void scm_ceiling_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
+@deftypefnx {C Function} SCM scm_ceiling_quotient (@var{x}, @var{y})
+@deftypefnx {C Function} SCM scm_ceiling_remainder (@var{x}, @var{y})
+These procedures accept two real numbers @var{x} and @var{y}, where the
+divisor @var{y} must be non-zero. @code{ceiling-quotient} returns the
+integer @var{q} and @code{ceiling-remainder} returns the real number
+@var{r} such that @math{@var{q} = ceiling(@var{x}/@var{y})} and
+@math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{ceiling/} returns
+both @var{q} and @var{r}, and is more efficient than computing each
+separately. Note that @var{r}, if non-zero, will have the opposite sign
+of @var{y}.
+
+@lisp
+(ceiling-quotient 123 10) @result{} 13
+(ceiling-remainder 123 10) @result{} -7
+(ceiling/ 123 10) @result{} 13 and -7
+(ceiling/ 123 -10) @result{} -12 and 3
+(ceiling/ -123 10) @result{} -12 and -3
+(ceiling/ -123 -10) @result{} 13 and 7
+(ceiling/ -123.2 -63.5) @result{} 2.0 and 3.8
+(ceiling/ 16/3 -10/7) @result{} -3 and 22/21
+@end lisp
+@end deftypefn
+
+@deftypefn {Scheme Procedure} {} truncate/ @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} truncate-quotient @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} truncate-remainder @var{x} @var{y}
+@deftypefnx {C Function} void scm_truncate_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
+@deftypefnx {C Function} SCM scm_truncate_quotient (@var{x}, @var{y})
+@deftypefnx {C Function} SCM scm_truncate_remainder (@var{x}, @var{y})
+These procedures accept two real numbers @var{x} and @var{y}, where the
+divisor @var{y} must be non-zero. @code{truncate-quotient} returns the
+integer @var{q} and @code{truncate-remainder} returns the real number
+@var{r} such that @var{q} is @math{@var{x}/@var{y}} rounded toward zero,
+and @math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{truncate/} returns
+both @var{q} and @var{r}, and is more efficient than computing each
+separately. Note that @var{r}, if non-zero, will have the same sign
+as @var{x}.
+
+When @var{x} and @var{y} are integers, these operators are
+equivalent to the R5RS integer-only operators @code{quotient} and
+@code{remainder}.
+
+@lisp
+(truncate-quotient 123 10) @result{} 12
+(truncate-remainder 123 10) @result{} 3
+(truncate/ 123 10) @result{} 12 and 3
+(truncate/ 123 -10) @result{} -12 and 3
+(truncate/ -123 10) @result{} -12 and -3
+(truncate/ -123 -10) @result{} 12 and -3
+(truncate/ -123.2 -63.5) @result{} 1.0 and -59.7
+(truncate/ 16/3 -10/7) @result{} -3 and 22/21
+@end lisp
+@end deftypefn
+
+@deftypefn {Scheme Procedure} {} centered/ @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} centered-quotient @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} centered-remainder @var{x} @var{y}
+@deftypefnx {C Function} void scm_centered_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
+@deftypefnx {C Function} SCM scm_centered_quotient (SCM @var{x}, SCM @var{y})
+@deftypefnx {C Function} SCM scm_centered_remainder (SCM @var{x}, SCM @var{y})
+These procedures accept two real numbers @var{x} and @var{y}, where the
+divisor @var{y} must be non-zero. @code{centered-quotient} returns the
+integer @var{q} and @code{centered-remainder} returns the real number
+@var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
+@math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}. @code{centered/}
+returns both @var{q} and @var{r}, and is more efficient than computing
+each separately.
+
+Note that @code{centered-quotient} returns @math{@var{x}/@var{y}}
+rounded to the nearest integer. When @math{@var{x}/@var{y}} lies
+exactly half-way between two integers, the tie is broken according to
+the sign of @var{y}. If @math{@var{y} > 0}, ties are rounded toward
+positive infinity, otherwise they are rounded toward negative infinity.
+This is a consequence of the requirement that
+@math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}.
+
+Note that these operators are equivalent to the R6RS operators
+@code{div0}, @code{mod0}, and @code{div0-and-mod0}.
+
+@lisp
+(centered-quotient 123 10) @result{} 12
+(centered-remainder 123 10) @result{} 3
+(centered/ 123 10) @result{} 12 and 3
+(centered/ 123 -10) @result{} -12 and 3
+(centered/ -123 10) @result{} -12 and -3
+(centered/ -123 -10) @result{} 12 and -3
+(centered/ 125 10) @result{} 13 and -5
+(centered/ 127 10) @result{} 13 and -3
+(centered/ 135 10) @result{} 14 and -5
+(centered/ -123.2 -63.5) @result{} 2.0 and 3.8
+(centered/ 16/3 -10/7) @result{} -4 and -8/21
+@end lisp
+@end deftypefn
+
+@deftypefn {Scheme Procedure} {} round/ @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} round-quotient @var{x} @var{y}
+@deftypefnx {Scheme Procedure} {} round-remainder @var{x} @var{y}
+@deftypefnx {C Function} void scm_round_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
+@deftypefnx {C Function} SCM scm_round_quotient (@var{x}, @var{y})
+@deftypefnx {C Function} SCM scm_round_remainder (@var{x}, @var{y})
+These procedures accept two real numbers @var{x} and @var{y}, where the
+divisor @var{y} must be non-zero. @code{round-quotient} returns the
+integer @var{q} and @code{round-remainder} returns the real number
+@var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
+@var{q} is @math{@var{x}/@var{y}} rounded to the nearest integer,
+with ties going to the nearest even integer. @code{round/}
+returns both @var{q} and @var{r}, and is more efficient than computing
+each separately.
+
+Note that @code{round/} and @code{centered/} are almost equivalent, but
+their behavior differs when @math{@var{x}/@var{y}} lies exactly half-way
+between two integers. In this case, @code{round/} chooses the nearest
+even integer, whereas @code{centered/} chooses in such a way to satisfy
+the constraint @math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}, which
+is stronger than the corresponding constraint for @code{round/},
+@math{-|@var{y}/2| <= @var{r} <= |@var{y}/2|}. In particular,
+when @var{x} and @var{y} are integers, the number of possible remainders
+returned by @code{centered/} is @math{|@var{y}|}, whereas the number of
+possible remainders returned by @code{round/} is @math{|@var{y}|+1} when
+@var{y} is even.
+
+@lisp
+(round-quotient 123 10) @result{} 12
+(round-remainder 123 10) @result{} 3
+(round/ 123 10) @result{} 12 and 3
+(round/ 123 -10) @result{} -12 and 3
+(round/ -123 10) @result{} -12 and -3
+(round/ -123 -10) @result{} 12 and -3
+(round/ 125 10) @result{} 12 and 5
+(round/ 127 10) @result{} 13 and -3
+(round/ 135 10) @result{} 14 and -5
+(round/ -123.2 -63.5) @result{} 2.0 and 3.8
+(round/ 16/3 -10/7) @result{} -4 and -8/21
+@end lisp
+@end deftypefn
+
@node Scientific
@subsubsection Scientific Functions
@c begin (texi-doc-string "guile" "sqrt")
@deffn {Scheme Procedure} sqrt 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
+(positive and negative), the one with a positive real part is
returned, or if that's zero then a positive imaginary part. Thus,
@example
@end lisp
@end deffn
-@deffn {Scheme Procedure} ash n cnt
-@deffnx {C Function} scm_ash (n, cnt)
-Return @var{n} shifted left by @var{cnt} bits, or shifted right if
-@var{cnt} is negative. This is an ``arithmetic'' shift.
+@deffn {Scheme Procedure} ash n count
+@deffnx {C Function} scm_ash (n, count)
+Return @math{floor(n * 2^count)}.
+@var{n} and @var{count} must be exact integers.
-This is effectively a multiplication by @m{2^{cnt}, 2^@var{cnt}}, and
-when @var{cnt} is negative it's a division, rounded towards negative
-infinity. (Note that this is not the same rounding as @code{quotient}
-does.)
-
-With @var{n} viewed as an infinite precision twos complement,
-@code{ash} means a left shift introducing zero bits, or a right shift
-dropping bits.
+With @var{n} viewed as an infinite-precision twos-complement
+integer, @code{ash} means a left shift introducing zero bits
+when @var{count} is positive, or a right shift dropping bits
+when @var{count} is negative. This is an ``arithmetic'' shift.
@lisp
(number->string (ash #b1 3) 2) @result{} "1000"
@end lisp
@end deffn
+@deffn {Scheme Procedure} round-ash n count
+@deffnx {C Function} scm_round_ash (n, count)
+Return @math{round(n * 2^count)}.
+@var{n} and @var{count} must be exact integers.
+
+With @var{n} viewed as an infinite-precision twos-complement
+integer, @code{round-ash} means a left shift introducing zero
+bits when @var{count} is positive, or a right shift rounding
+to the nearest integer (with ties going to the nearest even
+integer) when @var{count} is negative. This is a rounded
+``arithmetic'' shift.
+
+@lisp
+(number->string (round-ash #b1 3) 2) @result{} \"1000\"
+(number->string (round-ash #b1010 -1) 2) @result{} \"101\"
+(number->string (round-ash #b1010 -2) 2) @result{} \"10\"
+(number->string (round-ash #b1011 -2) 2) @result{} \"11\"
+(number->string (round-ash #b1101 -2) 2) @result{} \"11\"
+(number->string (round-ash #b1110 -2) 2) @result{} \"100\"
+@end lisp
+@end deffn
+
@deffn {Scheme Procedure} logcount n
@deffnx {C Function} scm_logcount (n)
Return the number of bits in integer @var{n}. If @var{n} is
@subsubsection Random Number Generation
Pseudo-random numbers are generated from a random state object, which
-can be created with @code{seed->random-state}. The @var{state}
-parameter to the various functions below is optional, it defaults to
-the state object in the @code{*random-state*} variable.
+can be created with @code{seed->random-state} or
+@code{datum->random-state}. An external representation (i.e.@: one
+which can written with @code{write} and read with @code{read}) of a
+random state object can be obtained via
+@code{random-state->datum}. The @var{state} parameter to the
+various functions below is optional, it defaults to the state object
+in the @code{*random-state*} variable.
@deffn {Scheme Procedure} copy-random-state [state]
@deffnx {C Function} scm_copy_random_state (state)
Return a new random state using @var{seed}.
@end deffn
+@deffn {Scheme Procedure} datum->random-state datum
+@deffnx {C Function} scm_datum_to_random_state (datum)
+Return a new random state from @var{datum}, which should have been
+obtained by @code{random-state->datum}.
+@end deffn
+
+@deffn {Scheme Procedure} random-state->datum state
+@deffnx {C Function} scm_random_state_to_datum (state)
+Return a datum representation of @var{state} that may be written out and
+read back with the Scheme reader.
+@end deffn
+
+@deffn {Scheme Procedure} random-state-from-platform
+@deffnx {C Function} scm_random_state_from_platform ()
+Construct a new random state seeded from a platform-specific source of
+entropy, appropriate for use in non-security-critical applications.
+Currently @file{/dev/urandom} is tried first, or else the seed is based
+on the time, date, process ID, an address from a freshly allocated heap
+cell, an address from the local stack frame, and a high-resolution timer
+if available.
+@end deffn
+
@defvar *random-state*
The global random state used by the above functions when the
@var{state} parameter is not given.
(0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12)
@end lisp
-To use the time of day as the random seed, you can use code like this:
+To seed the random state in a sensible way for non-security-critical
+applications, do this during initialization of your program:
@lisp
-(let ((time (gettimeofday)))
- (set! *random-state*
- (seed->random-state (+ (car time)
- (cdr time)))))
+(set! *random-state* (random-state-from-platform))
@end lisp
-@noindent
-And then (depending on the time of day, of course):
-
-@lisp
-(map random (cdr (iota 19)))
-@result{}
-(0 0 1 0 2 4 5 4 5 5 9 3 10 1 8 3 14 17)
-@end lisp
-
-For security applications, such as password generation, you should use
-more bits of seed. Otherwise an open source password generator could
-be attacked by guessing the seed@dots{} but that's a subject for
-another manual.
-
@node Characters
@subsection Characters
Many of the non-printing characters, such as whitespace characters and
control characters, also have names.
-The most commonly used non-printing characters are space and
-newline. Their character names are @code{#\space} and
-@code{#\newline}. There are also names for all of the ``C0 control
-characters'' (those with code points below 32). The following table
-describes the names for each character.
+The most commonly used non-printing characters have long character
+names, described in the table below.
+
+@multitable {@code{#\backspace}} {Preferred}
+@item Character Name @tab Codepoint
+@item @code{#\nul} @tab U+0000
+@item @code{#\alarm} @tab u+0007
+@item @code{#\backspace} @tab U+0008
+@item @code{#\tab} @tab U+0009
+@item @code{#\linefeed} @tab U+000A
+@item @code{#\newline} @tab U+000A
+@item @code{#\vtab} @tab U+000B
+@item @code{#\page} @tab U+000C
+@item @code{#\return} @tab U+000D
+@item @code{#\esc} @tab U+001B
+@item @code{#\space} @tab U+0020
+@item @code{#\delete} @tab U+007F
+@end multitable
+
+There are also short names for all of the ``C0 control characters''
+(those with code points below 32). The following table lists the short
+name for each character.
@multitable @columnfractions .25 .25 .25 .25
@item 0 = @code{#\nul}
@tab 7 = @code{#\bel}
@item 8 = @code{#\bs}
@tab 9 = @code{#\ht}
- @tab 10 = @code{#\lf}
+ @tab 10 = @code{#\lf}
@tab 11 = @code{#\vt}
@item 12 = @code{#\ff}
@tab 13 = @code{#\cr}
@item 32 = @code{#\sp}
@end multitable
-The ``delete'' character (code point U+007F) may be referred to with the
-name @code{#\del}.
+The short name for the ``delete'' character (code point U+007F) is
+@code{#\del}.
-One might note that the space character has two names --
-@code{#\space} and @code{#\sp} -- as does the newline character.
-Several other non-printing characters have more than one name, for the
-sake of compatibility with previous versions.
+There are also a few alternative names left over for compatibility with
+previous versions of Guile.
@multitable {@code{#\backspace}} {Preferred}
@item Alternate @tab Standard
-@item @code{#\sp} @tab @code{#\space}
@item @code{#\nl} @tab @code{#\newline}
-@item @code{#\lf} @tab @code{#\newline}
-@item @code{#\tab} @tab @code{#\ht}
-@item @code{#\backspace} @tab @code{#\bs}
-@item @code{#\return} @tab @code{#\cr}
-@item @code{#\page} @tab @code{#\ff}
-@item @code{#\np} @tab @code{#\ff}
+@item @code{#\np} @tab @code{#\page}
@item @code{#\null} @tab @code{#\nul}
@end multitable
be written with as an octal number, such as @code{#\10} for
@code{#\bs} or @code{#\177} for @code{#\del}.
+If one prefers hex to octal, there is an additional syntax for character
+escapes: @code{#\xHHHH} -- the letter 'x' followed by a hexadecimal
+number of one to eight digits.
+
@rnindex char?
@deffn {Scheme Procedure} char? x
@deffnx {C Function} scm_char_p (x)
-Return @code{#t} iff @var{x} is a character, else @code{#f}.
+Return @code{#t} if @var{x} is a character, else @code{#f}.
@end deffn
Fundamentally, the character comparison operations below are
@rnindex char=?
@deffn {Scheme Procedure} char=? x y
-Return @code{#t} iff code point of @var{x} is equal to the code point
+Return @code{#t} if code point of @var{x} is equal to the code point
of @var{y}, else @code{#f}.
@end deffn
@rnindex char<?
@deffn {Scheme Procedure} char<? x y
-Return @code{#t} iff the code point of @var{x} is less than the code
+Return @code{#t} if the code point of @var{x} is less than the code
point of @var{y}, else @code{#f}.
@end deffn
@rnindex char<=?
@deffn {Scheme Procedure} char<=? x y
-Return @code{#t} iff the code point of @var{x} is less than or equal
+Return @code{#t} if the code point of @var{x} is less than or equal
to the code point of @var{y}, else @code{#f}.
@end deffn
@rnindex char>?
@deffn {Scheme Procedure} char>? x y
-Return @code{#t} iff the code point of @var{x} is greater than the
+Return @code{#t} if the code point of @var{x} is greater than the
code point of @var{y}, else @code{#f}.
@end deffn
@rnindex char>=?
@deffn {Scheme Procedure} char>=? x y
-Return @code{#t} iff the code point of @var{x} is greater than or
+Return @code{#t} if the code point of @var{x} is greater than or
equal to the code point of @var{y}, else @code{#f}.
@end deffn
@rnindex char-ci=?
@deffn {Scheme Procedure} char-ci=? x y
-Return @code{#t} iff the case-folded code point of @var{x} is the same
+Return @code{#t} if the case-folded code point of @var{x} is the same
as the case-folded code point of @var{y}, else @code{#f}.
@end deffn
@rnindex char-ci<?
@deffn {Scheme Procedure} char-ci<? x y
-Return @code{#t} iff the case-folded code point of @var{x} is less
+Return @code{#t} if the case-folded code point of @var{x} is less
than the case-folded code point of @var{y}, else @code{#f}.
@end deffn
@rnindex char-ci<=?
@deffn {Scheme Procedure} char-ci<=? x y
-Return @code{#t} iff the case-folded code point of @var{x} is less
+Return @code{#t} if the case-folded code point of @var{x} is less
than or equal to the case-folded code point of @var{y}, else
@code{#f}.
@end deffn
@rnindex char-ci>?
@deffn {Scheme Procedure} char-ci>? x y
-Return @code{#t} iff the case-folded code point of @var{x} is greater
+Return @code{#t} if the case-folded code point of @var{x} is greater
than the case-folded code point of @var{y}, else @code{#f}.
@end deffn
@rnindex char-ci>=?
@deffn {Scheme Procedure} char-ci>=? x y
-Return @code{#t} iff the case-folded code point of @var{x} is greater
+Return @code{#t} if the case-folded code point of @var{x} is greater
than or equal to the case-folded code point of @var{y}, else
@code{#f}.
@end deffn
@rnindex char-alphabetic?
@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}.
+Return @code{#t} if @var{chr} is alphabetic, else @code{#f}.
@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}.
+Return @code{#t} if @var{chr} is numeric, else @code{#f}.
@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}.
+Return @code{#t} if @var{chr} is whitespace, else @code{#f}.
@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}.
+Return @code{#t} if @var{chr} is uppercase, else @code{#f}.
@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}.
+Return @code{#t} if @var{chr} is lowercase, else @code{#f}.
@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
+Return @code{#t} if @var{chr} is either uppercase or lowercase, else
@code{#f}.
@end deffn
respectively).
@end deffn
+@tindex scm_t_wchar
+@deftypefn {C Function} scm_t_wchar scm_c_upcase (scm_t_wchar @var{c})
+@deftypefnx {C Function} scm_t_wchar scm_c_downcase (scm_t_wchar @var{c})
+@deftypefnx {C Function} scm_t_wchar scm_c_titlecase (scm_t_wchar @var{c})
+
+These C functions take an integer representation of a Unicode
+codepoint and return the codepoint corresponding to its uppercase,
+lowercase, and titlecase forms respectively. The type
+@code{scm_t_wchar} is a signed, 32-bit integer.
+@end deftypefn
+
@node Character Sets
@subsection Character Sets
otherwise.
@end deffn
-@deffn {Scheme Procedure} char-set= . char_sets
+@deffn {Scheme Procedure} char-set= char_set @dots{}
@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
+@deffn {Scheme Procedure} char-set<= char_set @dots{}
@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.
+Return @code{#t} if every character set @var{char_set}i is a subset
+of character set @var{char_set}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}.
+returned value to the range 0 @dots{} @var{bound} - 1.
@end deffn
@c ===================================================================
characters in @var{cs}.
@end deffn
-@deffn {Scheme Procedure} char-set . rest
-@deffnx {C Function} scm_char_set (rest)
+@deffn {Scheme Procedure} char-set chr @dots{}
+@deffnx {C Function} scm_char_set (chrs)
Return a character set containing all given characters.
@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}.
+Return @code{#t} if the character @var{ch} is contained in the
+character set @var{cs}, or @code{#f} otherwise.
@end deffn
@deffn {Scheme Procedure} char-set-every pred cs
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)
+@deffn {Scheme Procedure} char-set-adjoin cs chr @dots{}
+@deffnx {C Function} scm_char_set_adjoin (cs, chrs)
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)
+@deffn {Scheme Procedure} char-set-delete cs chr @dots{}
+@deffnx {C Function} scm_char_set_delete (cs, chrs)
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)
+@deffn {Scheme Procedure} char-set-adjoin! cs chr @dots{}
+@deffnx {C Function} scm_char_set_adjoin_x (cs, chrs)
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)
+@deffn {Scheme Procedure} char-set-delete! cs chr @dots{}
+@deffnx {C Function} scm_char_set_delete_x (cs, chrs)
Delete all character arguments from the first argument, which
must be a character set.
@end deffn
@code{char-set-complement} by computing its intersection with the set
of designated code points, @code{char-set:designated}.
-@deffn {Scheme Procedure} char-set-union . rest
-@deffnx {C Function} scm_char_set_union (rest)
+@deffn {Scheme Procedure} char-set-union cs @dots{}
+@deffnx {C Function} scm_char_set_union (char_sets)
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)
+@deffn {Scheme Procedure} char-set-intersection cs @dots{}
+@deffnx {C Function} scm_char_set_intersection (char_sets)
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)
+@deffn {Scheme Procedure} char-set-difference cs1 cs @dots{}
+@deffnx {C Function} scm_char_set_difference (cs1, char_sets)
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)
+@deffn {Scheme Procedure} char-set-xor cs @dots{}
+@deffnx {C Function} scm_char_set_xor (char_sets)
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)
+@deffn {Scheme Procedure} char-set-diff+intersection cs1 cs @dots{}
+@deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, char_sets)
Return the difference and the intersection of all argument
character sets.
@end deffn
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)
+@deffn {Scheme Procedure} char-set-union! cs1 cs @dots{}
+@deffnx {C Function} scm_char_set_union_x (cs1, char_sets)
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)
+@deffn {Scheme Procedure} char-set-intersection! cs1 cs @dots{}
+@deffnx {C Function} scm_char_set_intersection_x (cs1, char_sets)
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)
+@deffn {Scheme Procedure} char-set-difference! cs1 cs @dots{}
+@deffnx {C Function} scm_char_set_difference_x (cs1, char_sets)
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)
+@deffn {Scheme Procedure} char-set-xor! cs1 cs @dots{}
+@deffnx {C Function} scm_char_set_xor_x (cs1, char_sets)
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)
+@deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 cs @dots{}
+@deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, char_sets)
Return the difference and the intersection of all argument
character sets.
@end deffn
These character sets are locale independent and are not recomputed
upon a @code{setlocale} call. They contain characters from the whole
range of Unicode code points. For instance, @code{char-set:letter}
-contains about 94,000 characters.
+contains about 100,000 characters.
@defvr {Scheme Variable} char-set:lower-case
@defvrx {C Variable} scm_char_set_lower_case
* 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::
+* Representing Strings as Bytes:: Encoding and decoding strings.
+* Conversion to/from C::
+* String Internals:: The storage strategy for strings.
@end menu
@node String Syntax
The read syntax for strings is an arbitrarily long sequence of
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
-standard, the rest are Guile extensions, notice they follow C string
-syntax.
+Backslash is an escape character and can be used to insert the following
+special characters. @nicode{\"} and @nicode{\\} are R5RS standard, the
+next seven are R6RS standard --- notice they follow C syntax --- and the
+remaining four are Guile extensions.
@table @asis
@item @nicode{\\}
Double quote character (an unescaped @nicode{"} is otherwise the end
of the string).
-@item @nicode{\0}
-NUL character (ASCII 0).
-
@item @nicode{\a}
Bell character (ASCII 7).
@item @nicode{\v}
Vertical tab character (ASCII 11).
+@item @nicode{\b}
+Backspace character (ASCII 8).
+
+@item @nicode{\0}
+NUL character (ASCII 0).
+
+@item @nicode{\} followed by newline (ASCII 10)
+Nothing. This way if @nicode{\} is the last character in a line, the
+string will continue with the first character from the next line,
+without a line break.
+
+If the @code{hungry-eol-escapes} reader option is enabled, which is not
+the case by default, leading whitespace on the next line is discarded.
+
+@lisp
+"foo\
+ bar"
+@result{} "foo bar"
+(read-enable 'hungry-eol-escapes)
+"foo\
+ bar"
+@result{} "foobar"
+@end lisp
@item @nicode{\xHH}
Character code given by two hexadecimal digits. For example
@nicode{\x7f} for an ASCII DEL (127).
"\"Hi\", he said."
@end lisp
+The three escape sequences @code{\xHH}, @code{\uHHHH} and @code{\UHHHHHH} were
+chosen to not break compatibility with code written for previous versions of
+Guile. The R6RS specification suggests a different, incompatible syntax for hex
+escapes: @code{\xHHHH;} -- a character code followed by one to eight hexadecimal
+digits terminated with a semicolon. If this escape format is desired instead,
+it can be enabled with the reader option @code{r6rs-hex-escapes}.
+
+@lisp
+(read-enable 'r6rs-hex-escapes)
+@end lisp
+
+For more on reader options, @xref{Scheme Read}.
@node String Predicates
@subsubsection String Predicates
Return a newly allocated string of
length @var{k}. If @var{chr} is given, then all elements of
the string are initialized to @var{chr}, otherwise the contents
-of the @var{string} are unspecified.
+of the string are unspecified.
@end deffn
@deftypefn {C Function} SCM scm_c_make_string (size_t len, SCM chr)
@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{delimiter} 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}.
@item infix
Insert the separator between list elements. An empty string
will produce an empty list.
-@item string-infix
+@item strict-infix
Like @code{infix}, but will raise an error if given the empty
list.
@item suffix
Convert the string @var{str} into a list of characters.
@end deffn
-@deffn {Scheme Procedure} string-split str chr
-@deffnx {C Function} scm_string_split (str, chr)
-Split the string @var{str} into the a list of the substrings delimited
-by appearances of the character @var{chr}. Note that an empty substring
-between separator characters will result in an empty string in the
-result list.
+@deffn {Scheme Procedure} string-split str char_pred
+@deffnx {C Function} scm_string_split (str, char_pred)
+Split the string @var{str} into a list of substrings delimited
+by appearances of characters that
+
+@itemize @bullet
+@item
+equal @var{char_pred}, if it is a character,
+
+@item
+satisfy the predicate @var{char_pred}, if it is a procedure,
+
+@item
+are in the set @var{char_pred}, if it is a character set.
+@end itemize
+
+Note that an empty substring between separator characters will result in
+an empty string in the result list.
@lisp
(string-split "root:x:0:0:root:/root:/bin/bash" #\:)
@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}
+either pad with @var{chr} or truncate them to give @var{len}
characters.
@code{string-pad} pads or truncates on the left, so for example
@var{end} to @var{fill}.
@lisp
-(define y "abcdefg")
+(define y (string-copy "abcdefg"))
(substring-fill! y 1 3 #\r)
y
@result{} "arrdefg"
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 not ending
-@code{?}.
+@code{?}.
The predicates ending in @code{-ci} ignore the character case
when comparing strings. For now, case-insensitive comparison is done
i18n)} module}, for locale-dependent string comparison.
@rnindex string=?
-@deffn {Scheme Procedure} string=? [s1 [s2 . rest]]
-@deffnx {C Function} scm_i_string_equal_p (s1, s2, rest)
-Lexicographic equality predicate; return @code{#t} if the two
-strings are the same length and contain the same characters in
-the same positions, otherwise return @code{#f}.
+@deffn {Scheme Procedure} string=? s1 s2 s3 @dots{}
+Lexicographic equality predicate; return @code{#t} if all strings are
+the same length and contain the same characters in the same positions,
+otherwise return @code{#f}.
The procedure @code{string-ci=?} treats upper and lower case
letters as though they were the same character, but
@end deffn
@rnindex string<?
-@deffn {Scheme Procedure} string<? [s1 [s2 . rest]]
-@deffnx {C Function} scm_i_string_less_p (s1, s2, rest)
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically less than @var{s2}.
+@deffn {Scheme Procedure} string<? s1 s2 s3 @dots{}
+Lexicographic ordering predicate; return @code{#t} if, for every pair of
+consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
+lexicographically less than @var{str_i+1}.
@end deffn
@rnindex string<=?
-@deffn {Scheme Procedure} string<=? [s1 [s2 . rest]]
-@deffnx {C Function} scm_i_string_leq_p (s1, s2, rest)
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically less than or equal to @var{s2}.
+@deffn {Scheme Procedure} string<=? s1 s2 s3 @dots{}
+Lexicographic ordering predicate; return @code{#t} if, for every pair of
+consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
+lexicographically less than or equal to @var{str_i+1}.
@end deffn
@rnindex string>?
-@deffn {Scheme Procedure} string>? [s1 [s2 . rest]]
-@deffnx {C Function} scm_i_string_gr_p (s1, s2, rest)
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically greater than @var{s2}.
+@deffn {Scheme Procedure} string>? s1 s2 s3 @dots{}
+Lexicographic ordering predicate; return @code{#t} if, for every pair of
+consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
+lexicographically greater than @var{str_i+1}.
@end deffn
@rnindex string>=?
-@deffn {Scheme Procedure} string>=? [s1 [s2 . rest]]
-@deffnx {C Function} scm_i_string_geq_p (s1, s2, rest)
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically greater than or equal to @var{s2}.
+@deffn {Scheme Procedure} string>=? s1 s2 s3 @dots{}
+Lexicographic ordering predicate; return @code{#t} if, for every pair of
+consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
+lexicographically greater than or equal to @var{str_i+1}.
@end deffn
@rnindex string-ci=?
-@deffn {Scheme Procedure} string-ci=? [s1 [s2 . rest]]
-@deffnx {C Function} scm_i_string_ci_equal_p (s1, s2, rest)
+@deffn {Scheme Procedure} string-ci=? s1 s2 s3 @dots{}
Case-insensitive string equality predicate; return @code{#t} if
-the two strings are the same length and their component
+all strings are the same length and their component
characters match (ignoring case) at each position; otherwise
return @code{#f}.
@end deffn
@rnindex string-ci<?
-@deffn {Scheme Procedure} string-ci<? [s1 [s2 . rest]]
-@deffnx {C Function} scm_i_string_ci_less_p (s1, s2, rest)
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically less than @var{s2}
+@deffn {Scheme Procedure} string-ci<? s1 s2 s3 @dots{}
+Case insensitive lexicographic ordering predicate; return @code{#t} if,
+for every pair of consecutive string arguments @var{str_i} and
+@var{str_i+1}, @var{str_i} is lexicographically less than @var{str_i+1}
regardless of case.
@end deffn
@rnindex string<=?
-@deffn {Scheme Procedure} string-ci<=? [s1 [s2 . rest]]
-@deffnx {C Function} scm_i_string_ci_leq_p (s1, s2, rest)
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically less than or equal
-to @var{s2} regardless of case.
+@deffn {Scheme Procedure} string-ci<=? s1 s2 s3 @dots{}
+Case insensitive lexicographic ordering predicate; return @code{#t} if,
+for every pair of consecutive string arguments @var{str_i} and
+@var{str_i+1}, @var{str_i} is lexicographically less than or equal to
+@var{str_i+1} regardless of case.
@end deffn
@rnindex string-ci>?
-@deffn {Scheme Procedure} string-ci>? [s1 [s2 . rest]]
-@deffnx {C Function} scm_i_string_ci_gr_p (s1, s2, rest)
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically greater than
-@var{s2} regardless of case.
+@deffn {Scheme Procedure} string-ci>? s1 s2 s3 @dots{}
+Case insensitive lexicographic ordering predicate; return @code{#t} if,
+for every pair of consecutive string arguments @var{str_i} and
+@var{str_i+1}, @var{str_i} is lexicographically greater than
+@var{str_i+1} regardless of case.
@end deffn
@rnindex string-ci>=?
-@deffn {Scheme Procedure} string-ci>=? [s1 [s2 . rest]]
-@deffnx {C Function} scm_i_string_ci_geq_p (s1, s2, rest)
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically greater than or
-equal to @var{s2} regardless of case.
+@deffn {Scheme Procedure} string-ci>=? s1 s2 s3 @dots{}
+Case insensitive lexicographic ordering predicate; return @code{#t} if,
+for every pair of consecutive string arguments @var{str_i} and
+@var{str_i+1}, @var{str_i} is lexicographically greater than or equal to
+@var{str_i+1} regardless of case.
@end deffn
@deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
@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).
+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).
+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
+
+Because the same visual appearance of an abstract Unicode character can
+be obtained via multiple sequences of Unicode characters, even the
+case-insensitive string comparison functions described above may return
+@code{#f} when presented with strings containing different
+representations of the same character. For example, the Unicode
+character ``LATIN SMALL LETTER S WITH DOT BELOW AND DOT ABOVE'' can be
+represented with a single character (U+1E69) or by the character ``LATIN
+SMALL LETTER S'' (U+0073) followed by the combining marks ``COMBINING
+DOT BELOW'' (U+0323) and ``COMBINING DOT ABOVE'' (U+0307).
+
+For this reason, it is often desirable to ensure that the strings
+to be compared are using a mutually consistent representation for every
+character. The Unicode standard defines two methods of normalizing the
+contents of strings: Decomposition, which breaks composite characters
+into a set of constituent characters with an ordering defined by the
+Unicode Standard; and composition, which performs the converse.
+
+There are two decomposition operations. ``Canonical decomposition''
+produces character sequences that share the same visual appearance as
+the original characters, while ``compatibility decomposition'' produces
+ones whose visual appearances may differ from the originals but which
+represent the same abstract character.
+
+These operations are encapsulated in the following set of normalization
+forms:
+
+@table @dfn
+@item NFD
+Characters are decomposed to their canonical forms.
+
+@item NFKD
+Characters are decomposed to their compatibility forms.
+
+@item NFC
+Characters are decomposed to their canonical forms, then composed.
+
+@item NFKC
+Characters are decomposed to their compatibility forms, then composed.
+
+@end table
+
+The functions below put their arguments into one of the forms described
+above.
+
+@deffn {Scheme Procedure} string-normalize-nfd s
+@deffnx {C Function} scm_string_normalize_nfd (s)
+Return the @code{NFD} normalized form of @var{s}.
+@end deffn
+
+@deffn {Scheme Procedure} string-normalize-nfkd s
+@deffnx {C Function} scm_string_normalize_nfkd (s)
+Return the @code{NFKD} normalized form of @var{s}.
+@end deffn
+
+@deffn {Scheme Procedure} string-normalize-nfc s
+@deffnx {C Function} scm_string_normalize_nfc (s)
+Return the @code{NFC} normalized form of @var{s}.
+@end deffn
+
+@deffn {Scheme Procedure} string-normalize-nfkc s
+@deffnx {C Function} scm_string_normalize_nfkc (s)
+Return the @code{NFKC} normalized form of @var{s}.
@end deffn
@node String Searching
@item
is in the set @var{char_pred}, if it is a character set.
@end itemize
+
+Return @code{#f} if no match is found.
@end deffn
@deffn {Scheme Procedure} string-rindex s char_pred [start [end]]
@item
is in the set if @var{char_pred} is a character set.
@end itemize
+
+Return @code{#f} if no match is found.
@end deffn
@deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 [end1 [start2 [end2]]]]
@item
is in the set if @var{char_pred} is a character set.
@end itemize
+
+Return @code{#f} if no match is found.
@end deffn
@deffn {Scheme Procedure} string-skip s char_pred [start [end]]
These are procedures for mapping strings to their upper- or lower-case
equivalents, respectively, or for capitalizing strings.
+They use the basic case mapping rules for Unicode characters. No
+special language or context rules are considered. The resulting strings
+are guaranteed to be the same length as the input strings.
+
+@xref{Character Case Mapping, the @code{(ice-9
+i18n)} module}, for locale-dependent case conversions.
+
@deffn {Scheme Procedure} string-upcase str [start [end]]
@deffnx {C Function} scm_substring_upcase (str, start, end)
@deffnx {C Function} scm_string_upcase (str)
@end deffn
@rnindex string-append
-@deffn {Scheme Procedure} string-append . args
+@deffn {Scheme Procedure} string-append arg @dots{}
@deffnx {C Function} scm_string_append (args)
Return a newly allocated string whose characters form the
-concatenation of the given strings, @var{args}.
+concatenation of the given strings, @var{arg} @enddots{}.
@example
(let ((h "hello "))
@end example
@end deffn
-@deffn {Scheme Procedure} string-append/shared . rest
-@deffnx {C Function} scm_string_append_shared (rest)
+@deffn {Scheme Procedure} string-append/shared arg @dots{}
+@deffnx {C Function} scm_string_append_shared (args)
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.
+Append the elements (which must be strings) of @var{ls} together into a
+single string. Guaranteed to return a freshly allocated string.
@end deffn
@deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]]
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)
+@deffn {Scheme Procedure} string-filter char_pred s [start [end]]
+@deffnx {C Function} scm_string_filter (char_pred, s, start, end)
Filter the string @var{s}, retaining only those characters which
satisfy @var{char_pred}.
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)
+@deffn {Scheme Procedure} string-delete char_pred s [start [end]]
+@deffnx {C Function} scm_string_delete (char_pred, s, 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
is a character set, it is tested for membership.
@end deffn
+@node Representing Strings as Bytes
+@subsubsection Representing Strings as Bytes
+
+Out in the cold world outside of Guile, not all strings are treated in
+the same way. Out there there are only bytes, and there are many ways
+of representing a strings (sequences of characters) as binary data
+(sequences of bytes).
+
+As a user, usually you don't have to think about this very much. When
+you type on your keyboard, your system encodes your keystrokes as bytes
+according to the locale that you have configured on your computer.
+Guile uses the locale to decode those bytes back into characters --
+hopefully the same characters that you typed in.
+
+All is not so clear when dealing with a system with multiple users, such
+as a web server. Your web server might get a request from one user for
+data encoded in the ISO-8859-1 character set, and then another request
+from a different user for UTF-8 data.
+
+@cindex iconv
+@cindex character encoding
+Guile provides an @dfn{iconv} module for converting between strings and
+sequences of bytes. @xref{Bytevectors}, for more on how Guile
+represents raw byte sequences. This module gets its name from the
+common @sc{unix} command of the same name.
+
+Note that often it is sufficient to just read and write strings from
+ports instead of using these functions. To do this, specify the port
+encoding using @code{set-port-encoding!}. @xref{Ports}, for more on
+ports and character encodings.
+
+Unlike the rest of the procedures in this section, you have to load the
+@code{iconv} module before having access to these procedures:
+
+@example
+(use-modules (ice-9 iconv))
+@end example
+
+@deffn string->bytevector string encoding [conversion-strategy]
+Encode @var{string} as a sequence of bytes.
+
+The string will be encoded in the character set specified by the
+@var{encoding} string. If the string has characters that cannot be
+represented in the encoding, by default this procedure raises an
+@code{encoding-error}. Pass a @var{conversion-strategy} argument to
+specify other behaviors.
+
+The return value is a bytevector. @xref{Bytevectors}, for more on
+bytevectors. @xref{Ports}, for more on character encodings and
+conversion strategies.
+@end deffn
+
+@deffn bytevector->string bytevector encoding [conversion-strategy]
+Decode @var{bytevector} into a string.
+
+The bytes will be decoded from the character set by the @var{encoding}
+string. If the bytes do not form a valid encoding, by default this
+procedure raises an @code{decoding-error}. As with
+@code{string->bytevector}, pass the optional @var{conversion-strategy}
+argument to modify this behavior. @xref{Ports}, for more on character
+encodings and conversion strategies.
+@end deffn
+
+@deffn call-with-output-encoded-string encoding proc [conversion-strategy]
+Like @code{call-with-output-string}, but instead of returning a string,
+returns a encoding of the string according to @var{encoding}, as a
+bytevector. This procedure can be more efficient than collecting a
+string and then converting it via @code{string->bytevector}.
+@end deffn
+
@node Conversion to/from C
@subsubsection Conversion to/from C
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.
+that make up the string. For Scheme strings, character encoding is not
+an issue (most of the time), since in Scheme you usually treat strings
+as character sequences, not byte sequences.
+
+Converting to C and converting from C each have their own challenges.
+
+When converting from C to Scheme, it is important that the sequence of
+bytes in the C string be valid with respect to its encoding. ASCII
+strings, for example, can't have any bytes greater than 127. An ASCII
+byte greater than 127 is considered @emph{ill-formed} and cannot be
+converted into a Scheme character.
-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'.
+Problems can occur in the reverse operation as well. Not all character
+encodings can hold all possible Scheme characters. Some encodings, like
+ASCII for example, can only describe a small subset of all possible
+characters. So, when converting to C, one must first decide what to do
+with Scheme characters that can't be represented in the C string.
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
@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.
+Creates a new Scheme string that has the same contents as @var{str} when
+interpreted in the character encoding of the current locale.
For @code{scm_from_locale_string}, @var{str} must be null-terminated.
@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}.
+
+If the C string is ill-formed, an error will be raised.
+
+Note that these functions should @emph{not} be used to convert C string
+constants, because there is no guarantee that the current locale will
+match that of the source code. To convert C string constants, use
+@code{scm_from_latin1_string}, @code{scm_from_utf8_string} or
+@code{scm_from_utf32_string}.
@end deftypefn
@deftypefn {C Function} SCM scm_take_locale_string (char *str)
@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}.
+Returns a C string with the same contents as @var{str} in the character
+encoding of the current locale. 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
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}.
+
+If a character in @var{str} cannot be represented in the character
+encoding of the current locale, the default port conversion strategy is
+used. @xref{Ports}, for more on conversion strategies.
+
+If the conversion strategy is @code{error}, an error will be raised. If
+it is @code{substitute}, a replacement character, such as a question
+mark, will be inserted in its place. If it is @code{escape}, a hex
+escape will be inserted in its place.
@end deftypefn
@deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
stored and you probably need to try again with a larger buffer.
@end deftypefn
+For most situations, string conversion should occur using the current
+locale, such as with the functions above. But there may be cases where
+one wants to convert strings from a character encoding other than the
+locale's character encoding. For these cases, the lower-level functions
+@code{scm_to_stringn} and @code{scm_from_stringn} are provided. These
+functions should seldom be necessary if one is properly using locales.
+
+@deftp {C Type} scm_t_string_failed_conversion_handler
+This is an enumerated type that can take one of three values:
+@code{SCM_FAILED_CONVERSION_ERROR},
+@code{SCM_FAILED_CONVERSION_QUESTION_MARK}, and
+@code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE}. They are used to indicate
+a strategy for handling characters that cannot be converted to or from a
+given character encoding. @code{SCM_FAILED_CONVERSION_ERROR} indicates
+that a conversion should throw an error if some characters cannot be
+converted. @code{SCM_FAILED_CONVERSION_QUESTION_MARK} indicates that a
+conversion should replace unconvertable characters with the question
+mark character. And, @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE}
+requests that a conversion should replace an unconvertable character
+with an escape sequence.
+
+While all three strategies apply when converting Scheme strings to C,
+only @code{SCM_FAILED_CONVERSION_ERROR} and
+@code{SCM_FAILED_CONVERSION_QUESTION_MARK} can be used when converting C
+strings to Scheme.
+@end deftp
+
+@deftypefn {C Function} char *scm_to_stringn (SCM str, size_t *lenp, const char *encoding, scm_t_string_failed_conversion_handler handler)
+This function returns a newly allocated C string from the Guile string
+@var{str}. The length of the returned string in bytes will be returned in
+@var{lenp}. The character encoding of the C string is passed as the ASCII,
+null-terminated C string @var{encoding}. The @var{handler} parameter
+gives a strategy for dealing with characters that cannot be converted
+into @var{encoding}.
+
+If @var{lenp} is @code{NULL}, this function will return a null-terminated C
+string. It will throw an error if the string contains a null
+character.
+
+The Scheme interface to this function is @code{string->bytevector}, from the
+@code{ice-9 iconv} module. @xref{Representing Strings as Bytes}.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_from_stringn (const char *str, size_t len, const char *encoding, scm_t_string_failed_conversion_handler handler)
+This function returns a scheme string from the C string @var{str}. The
+length in bytes of the C string is input as @var{len}. The encoding of the C
+string is passed as the ASCII, null-terminated C string @code{encoding}.
+The @var{handler} parameters suggests a strategy for dealing with
+unconvertable characters.
+
+The Scheme interface to this function is @code{bytevector->string}.
+@xref{Representing Strings as Bytes}.
+@end deftypefn
+
+The following conversion functions are provided as a convenience for the
+most commonly used encodings.
+
+@deftypefn {C Function} SCM scm_from_latin1_string (const char *str)
+@deftypefnx {C Function} SCM scm_from_utf8_string (const char *str)
+@deftypefnx {C Function} SCM scm_from_utf32_string (const scm_t_wchar *str)
+Return a scheme string from the null-terminated C string @var{str},
+which is ISO-8859-1-, UTF-8-, or UTF-32-encoded. These functions should
+be used to convert hard-coded C string constants into Scheme strings.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_from_latin1_stringn (const char *str, size_t len)
+@deftypefnx {C Function} SCM scm_from_utf8_stringn (const char *str, size_t len)
+@deftypefnx {C Function} SCM scm_from_utf32_stringn (const scm_t_wchar *str, size_t len)
+Return a scheme string from C string @var{str}, which is ISO-8859-1-,
+UTF-8-, or UTF-32-encoded, of length @var{len}. @var{len} is the number
+of bytes pointed to by @var{str} for @code{scm_from_latin1_stringn} and
+@code{scm_from_utf8_stringn}; it is the number of elements (code points)
+in @var{str} in the case of @code{scm_from_utf32_stringn}.
+@end deftypefn
+
+@deftypefn {C function} char *scm_to_latin1_stringn (SCM str, size_t *lenp)
+@deftypefnx {C function} char *scm_to_utf8_stringn (SCM str, size_t *lenp)
+@deftypefnx {C function} scm_t_wchar *scm_to_utf32_stringn (SCM str, size_t *lenp)
+Return a newly allocated, ISO-8859-1-, UTF-8-, or UTF-32-encoded C string
+from Scheme string @var{str}. An error is thrown when @var{str}
+cannot be converted to the specified encoding. If @var{lenp} is
+@code{NULL}, the returned C string will be null terminated, and an error
+will be thrown if the C string would otherwise contain null
+characters. If @var{lenp} is not @code{NULL}, the string is not null terminated,
+and the length of the returned string is returned in @var{lenp}. The length
+returned is the number of bytes for @code{scm_to_latin1_stringn} and
+@code{scm_to_utf8_stringn}; it is the number of elements (code points)
+for @code{scm_to_utf32_stringn}.
+@end deftypefn
+
+It is not often the case, but sometimes when you are dealing with the
+implementation details of a port, you need to encode and decode strings
+according to the encoding and conversion strategy of the port. There
+are some convenience functions for that purpose as well.
+
+@deftypefn {C Function} SCM scm_from_port_string (const char *str, SCM port)
+@deftypefnx {C Function} SCM scm_from_port_stringn (const char *str, size_t len, SCM port)
+@deftypefnx {C Function} char* scm_to_port_string (SCM str, SCM port)
+@deftypefnx {C Function} char* scm_to_port_stringn (SCM str, size_t *lenp, SCM port)
+Like @code{scm_from_stringn} and friends, except they take their
+encoding and conversion strategy from a given port object.
+@end deftypefn
+
+@node String Internals
+@subsubsection String Internals
+
+Guile stores each string in memory as a contiguous array of Unicode code
+points along with an associated set of attributes. If all of the code
+points of a string have an integer range between 0 and 255 inclusive,
+the code point array is stored as one byte per code point: it is stored
+as an ISO-8859-1 (aka Latin-1) string. If any of the code points of the
+string has an integer value greater that 255, the code point array is
+stored as four bytes per code point: it is stored as a UTF-32 string.
+
+Conversion between the one-byte-per-code-point and
+four-bytes-per-code-point representations happens automatically as
+necessary.
+
+No API is provided to set the internal representation of strings;
+however, there are pair of procedures available to query it. These are
+debugging procedures. Using them in production code is discouraged,
+since the details of Guile's internal representation of strings may
+change from release to release.
+
+@deffn {Scheme Procedure} string-bytes-per-char str
+@deffnx {C Function} scm_string_bytes_per_char (str)
+Return the number of bytes used to encode a Unicode code point in string
+@var{str}. The result is one or four.
+@end deffn
+
+@deffn {Scheme Procedure} %string-dump str
+@deffnx {C Function} scm_sys_string_dump (str)
+Returns an association list containing debugging information for
+@var{str}. The association list has the following entries.
+@table @code
+
+@item string
+The string itself.
+
+@item start
+The start index of the string into its stringbuf
+
+@item length
+The length of the string
+
+@item shared
+If this string is a substring, it returns its
+parent string. Otherwise, it returns @code{#f}
+
+@item read-only
+@code{#t} if the string is read-only
+
+@item stringbuf-chars
+A new string containing this string's stringbuf's characters
+
+@item stringbuf-length
+The number of characters in this stringbuf
+
+@item stringbuf-shared
+@code{#t} if this stringbuf is shared
+
+@item stringbuf-wide
+@code{#t} if this stringbuf's characters are stored in a 32-bit buffer,
+or @code{#f} if they are stored in an 8-bit buffer
+@end table
+@end deffn
+
+
@node Bytevectors
@subsection Bytevectors
@cindex bytevector
@cindex R6RS
-A @dfn{bytevector} is a raw bit string. The @code{(rnrs bytevector)}
+A @dfn{bytevector} is a raw bit string. The @code{(rnrs bytevectors)}
module provides the programming interface specified by the
@uref{http://www.r6rs.org/, Revised^6 Report on the Algorithmic Language
Scheme (R6RS)}. It contains procedures to manipulate bytevectors and
* Bytevectors and Integer Lists:: Converting to/from an integer list.
* Bytevectors as Floats:: Interpreting bytes as real numbers.
* Bytevectors as Strings:: Interpreting bytes as Unicode strings.
-* Bytevectors as Generalized Vectors:: Guile extension to the bytevector API.
+* Bytevectors as Arrays:: Guile extension to the bytevector API.
+* Bytevectors as Uniform Vectors:: Bytevectors and SRFI-4.
@end menu
@node Bytevector Endianness
@deffnx {C Function} scm_bytevector_copy_x (source, source_start, target, target_start, len)
Copy @var{len} bytes from @var{source} into @var{target}, starting
reading from @var{source-start} (a positive index within @var{source})
-and start writing at @var{target-start}.
+and start writing at @var{target-start}. It is permitted for the
+@var{source} and @var{target} regions to overlap.
@end deffn
@deffn {Scheme Procedure} bytevector-copy bv
are described below.
@deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
-@deffnx {Scheme Procedure} bytevector-sint-ref bv index endianness size
@deffnx {C Function} scm_bytevector_uint_ref (bv, index, endianness, size)
+Return the @var{size}-byte long unsigned integer at index @var{index} in
+@var{bv}, decoded according to @var{endianness}.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-sint-ref bv index endianness size
@deffnx {C Function} scm_bytevector_sint_ref (bv, index, endianness, size)
-Return the @var{size}-byte long unsigned (resp. signed) integer at
-index @var{index} in @var{bv}, decoded according to @var{endianness}.
+Return the @var{size}-byte long signed integer at index @var{index} in
+@var{bv}, decoded according to @var{endianness}.
@end deffn
@deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
-@deffnx {Scheme Procedure} bytevector-sint-set! bv index value endianness size
@deffnx {C Function} scm_bytevector_uint_set_x (bv, index, value, endianness, size)
+Set the @var{size}-byte long unsigned integer at @var{index} to
+@var{value}, encoded according to @var{endianness}.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-sint-set! bv index value endianness size
@deffnx {C Function} scm_bytevector_sint_set_x (bv, index, value, endianness, size)
-Set the @var{size}-byte long unsigned (resp. signed) integer at
-@var{index} to @var{value}, encoded according to @var{endianness}.
+Set the @var{size}-byte long signed integer at @var{index} to
+@var{value}, encoded according to @var{endianness}.
@end deffn
The following procedures are similar to the ones above, but specialized
@end deffn
@deffn {Scheme Procedure} bytevector->uint-list bv endianness size
-@deffnx {Scheme Procedure} bytevector->sint-list bv endianness size
@deffnx {C Function} scm_bytevector_to_uint_list (bv, endianness, size)
+Return a list of unsigned integers of @var{size} bytes representing the
+contents of @var{bv}, decoded according to @var{endianness}.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector->sint-list bv endianness size
@deffnx {C Function} scm_bytevector_to_sint_list (bv, endianness, size)
-Return a list of unsigned (resp. signed) integers of @var{size} bytes
-representing the contents of @var{bv}, decoded according to
-@var{endianness}.
+Return a list of signed integers of @var{size} bytes representing the
+contents of @var{bv}, decoded according to @var{endianness}.
@end deffn
@deffn {Scheme Procedure} uint-list->bytevector lst endianness size
-@deffnx {Scheme Procedure} sint-list->bytevector lst endianness size
@deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
+Return a new bytevector containing the unsigned integers listed in
+@var{lst} and encoded on @var{size} bytes according to @var{endianness}.
+@end deffn
+
+@deffn {Scheme Procedure} sint-list->bytevector lst endianness size
@deffnx {C Function} scm_sint_list_to_bytevector (lst, endianness, size)
-Return a new bytevector containing the unsigned (resp. signed) integers
-listed in @var{lst} and encoded on @var{size} bytes according to
-@var{endianness}.
+Return a new bytevector containing the signed integers listed in
+@var{lst} and encoded on @var{size} bytes according to @var{endianness}.
@end deffn
@node Bytevectors as Floats
@cindex Unicode string encoding
Bytevector contents can also be interpreted as Unicode strings encoded
-in one of the most commonly available encoding formats@footnote{Guile
-1.8 does @emph{not} support Unicode strings. Therefore, the procedures
-described here assume that Guile strings are internally encoded
-according to the current locale. For instance, if @code{$LC_CTYPE} is
-@code{fr_FR.ISO-8859-1}, then @code{string->utf-8} @i{et al.} will
-assume that Guile strings are Latin-1-encoded.}.
+in one of the most commonly available encoding formats.
+@xref{Representing Strings as Bytes}, for a more generic interface.
@lisp
(utf8->string (u8-list->bytevector '(99 97 102 101)))
@end lisp
@deffn {Scheme Procedure} string->utf8 str
-@deffnx {Scheme Procedure} string->utf16 str
-@deffnx {Scheme Procedure} string->utf32 str
+@deffnx {Scheme Procedure} string->utf16 str [endianness]
+@deffnx {Scheme Procedure} string->utf32 str [endianness]
@deffnx {C Function} scm_string_to_utf8 (str)
-@deffnx {C Function} scm_string_to_utf16 (str)
-@deffnx {C Function} scm_string_to_utf32 (str)
+@deffnx {C Function} scm_string_to_utf16 (str, endianness)
+@deffnx {C Function} scm_string_to_utf32 (str, endianness)
Return a newly allocated bytevector that contains the UTF-8, UTF-16, or
-UTF-32 (aka. UCS-4) encoding of @var{str}.
+UTF-32 (aka. UCS-4) encoding of @var{str}. For UTF-16 and UTF-32,
+@var{endianness} should be the symbol @code{big} or @code{little}; when omitted,
+it defaults to big endian.
@end deffn
@deffn {Scheme Procedure} utf8->string utf
-@deffnx {Scheme Procedure} utf16->string utf
-@deffnx {Scheme Procedure} utf32->string utf
+@deffnx {Scheme Procedure} utf16->string utf [endianness]
+@deffnx {Scheme Procedure} utf32->string utf [endianness]
@deffnx {C Function} scm_utf8_to_string (utf)
-@deffnx {C Function} scm_utf16_to_string (utf)
-@deffnx {C Function} scm_utf32_to_string (utf)
+@deffnx {C Function} scm_utf16_to_string (utf, endianness)
+@deffnx {C Function} scm_utf32_to_string (utf, endianness)
Return a newly allocated string that contains from the UTF-8-, UTF-16-,
-or UTF-32-decoded contents of bytevector @var{utf}.
+or UTF-32-decoded contents of bytevector @var{utf}. For UTF-16 and UTF-32,
+@var{endianness} should be the symbol @code{big} or @code{little}; when omitted,
+it defaults to big endian.
@end deffn
-@node Bytevectors as Generalized Vectors
-@subsubsection Accessing Bytevectors with the Generalized Vector API
+@node Bytevectors as Arrays
+@subsubsection Accessing Bytevectors with the Array API
As an extension to the R6RS, Guile allows bytevectors to be manipulated
-with the @dfn{generalized vector} procedures (@pxref{Generalized
-Vectors}). This also allows bytevectors to be accessed using the
-generic @dfn{array} procedures (@pxref{Array Procedures}). When using
-these APIs, bytes are accessed one at a time as 8-bit unsigned integers:
+with the @dfn{array} procedures (@pxref{Arrays}). When using these
+APIs, bytes are accessed one at a time as 8-bit unsigned integers:
@example
(define bv #vu8(0 1 2 3))
-(generalized-vector? bv)
+(array? bv)
@result{} #t
-(generalized-vector-ref bv 2)
+(array-rank bv)
+@result{} 1
+
+(array-ref bv 2)
@result{} 2
-(generalized-vector-set! bv 2 77)
+;; Note the different argument order on array-set!.
+(array-set! bv 77 2)
(array-ref bv 2)
@result{} 77
@end example
-@node Regular Expressions
-@subsection Regular Expressions
-@tpindex Regular expressions
-
-@cindex regular expressions
-@cindex regex
-@cindex emacs regexp
-
-A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
-describes a whole class of strings. A full description of regular
-expressions and their syntax is beyond the scope of this manual;
-an introduction can be found in the Emacs manual (@pxref{Regexps,
-, Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
-in many general Unix reference books.
-
-If your system does not include a POSIX regular expression library,
-and you have not linked Guile with a third-party regexp library such
-as Rx, these functions will not be available. You can tell whether
-your Guile installation includes regular expression support by
-checking whether @code{(provided? 'regex)} returns true.
-
-The following regexp and string matching features are provided by the
-@code{(ice-9 regex)} module. Before using the described functions,
-you should load this module by executing @code{(use-modules (ice-9
-regex))}.
-
-@menu
-* Regexp Functions:: Functions that create and match regexps.
-* Match Structures:: Finding what was matched by a regexp.
-* Backslash Escapes:: Removing the special meaning of regexp
- meta-characters.
-@end menu
-
-
-@node Regexp Functions
-@subsubsection Regexp Functions
-
-By default, Guile supports POSIX extended regular expressions.
-That means that the characters @samp{(}, @samp{)}, @samp{+} and
-@samp{?} are special, and must be escaped if you wish to match the
-literal characters.
-
-This regular expression interface was modeled after that
-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
-the position of @var{str} at which to begin matching.
-
-@code{string-match} returns a @dfn{match structure} which
-describes what, if anything, was matched by the regular
-expression. @xref{Match Structures}. If @var{str} does not match
-@var{pattern} at all, @code{string-match} returns @code{#f}.
-@end deffn
-
-Two examples of a match follow. In the first example, the pattern
-matches the four digits in the match string. In the second, the pattern
-matches nothing.
-
-@example
-(string-match "[0-9][0-9][0-9][0-9]" "blah2002")
-@result{} #("blah2002" (4 . 8))
-
-(string-match "[A-Za-z]" "123456")
-@result{} #f
-@end example
-
-Each time @code{string-match} is called, it must compile its
-@var{pattern} argument into a regular expression structure. This
-operation is expensive, which makes @code{string-match} inefficient if
-the same regular expression is used several times (for example, in a
-loop). For better performance, you can compile a regular expression in
-advance and then match strings against the compiled regexp.
-
-@deffn {Scheme Procedure} make-regexp pat flag@dots{}
-@deffnx {C Function} scm_make_regexp (pat, flaglst)
-Compile the regular expression described by @var{pat}, and
-return the compiled regexp structure. If @var{pat} does not
-describe a legal regular expression, @code{make-regexp} throws
-a @code{regular-expression-syntax} error.
-
-The @var{flag} arguments change the behavior of the compiled
-regular expression. The following values may be supplied:
-
-@defvar regexp/icase
-Consider uppercase and lowercase letters to be the same when
-matching.
-@end defvar
-
-@defvar regexp/newline
-If a newline appears in the target string, then permit the
-@samp{^} and @samp{$} operators to match immediately after or
-immediately before the newline, respectively. Also, the
-@samp{.} and @samp{[^...]} operators will never match a newline
-character. The intent of this flag is to treat the target
-string as a buffer containing many lines of text, and the
-regular expression as a pattern that may match a single one of
-those lines.
-@end defvar
-
-@defvar regexp/basic
-Compile a basic (``obsolete'') regexp instead of the extended
-(``modern'') regexps that are the default. Basic regexps do
-not consider @samp{|}, @samp{+} or @samp{?} to be special
-characters, and require the @samp{@{...@}} and @samp{(...)}
-metacharacters to be backslash-escaped (@pxref{Backslash
-Escapes}). There are several other differences between basic
-and extended regular expressions, but these are the most
-significant.
-@end defvar
-
-@defvar regexp/extended
-Compile an extended regular expression rather than a basic
-regexp. This is the default behavior; this flag will not
-usually be needed. If a call to @code{make-regexp} includes
-both @code{regexp/basic} and @code{regexp/extended} flags, the
-one which comes last will override the earlier one.
-@end defvar
-@end deffn
-
-@deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
-@deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
-Match the compiled regular expression @var{rx} against
-@code{str}. If the optional integer @var{start} argument is
-provided, begin matching from that position in the string.
-Return a match structure describing the results of the match,
-or @code{#f} if no match could be found.
-
-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
-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
-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
-
-@lisp
-;; Regexp to match uppercase letters
-(define r (make-regexp "[A-Z]*"))
-
-;; Regexp to match letters, ignoring case
-(define ri (make-regexp "[A-Z]*" regexp/icase))
-
-;; Search for bob using regexp r
-(match:substring (regexp-exec r "bob"))
-@result{} "" ; no match
-
-;; Search for bob using regexp ri
-(match:substring (regexp-exec ri "Bob"))
-@result{} "Bob" ; matched case insensitive
-@end lisp
-
-@deffn {Scheme Procedure} regexp? obj
-@deffnx {C Function} scm_regexp_p (obj)
-Return @code{#t} if @var{obj} is a compiled regular expression,
-or @code{#f} otherwise.
-@end deffn
-
-@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 @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.
+@node Bytevectors as Uniform Vectors
+@subsubsection Accessing Bytevectors with the SRFI-4 API
-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
-(@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 (@code{match:prefix}).
-
-@item
-The symbol @samp{post}. The portion of the matched string following
-the regexp match is written (@code{match:suffix}).
-@end itemize
-
-For example, changing a match and retaining the text before and after,
-
-@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.")
-(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{}]
-@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.
-
-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. 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 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
-
-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 ")")
-
-@result{} "Date 04-29-2002 12am. (20020429)"
-@end lisp
-@end deffn
-
-
-@node Match Structures
-@subsubsection Match Structures
-
-@cindex match structures
-
-A @dfn{match structure} is the object returned by @code{string-match} and
-@code{regexp-exec}. It describes which portion of a string, if any,
-matched the given regular expression. Match structures include: a
-reference to the string that was checked for matches; the starting and
-ending positions of the regexp match; and, if the regexp included any
-parenthesized subexpressions, the starting and ending positions of each
-submatch.
-
-In each of the regexp match functions described below, the @code{match}
-argument must be a match structure returned by a previous call to
-@code{string-match} or @code{regexp-exec}. Most of these functions
-return some information about the original target string that was
-matched against a regular expression; we will call that string
-@var{target} for easy reference.
-
-@c begin (scm-doc-string "regex.scm" "regexp-match?")
-@deffn {Scheme Procedure} regexp-match? obj
-Return @code{#t} if @var{obj} is a match structure returned by a
-previous call to @code{regexp-exec}, or @code{#f} otherwise.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:substring")
-@deffn {Scheme Procedure} match:substring match [n]
-Return the portion of @var{target} matched by subexpression number
-@var{n}. Submatch 0 (the default) represents the entire regexp match.
-If the regular expression as a whole matched, but the subexpression
-number @var{n} did not match, return @code{#f}.
-@end deffn
-
-@lisp
-(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
-(match:substring s)
-@result{} "2002"
-
-;; match starting at offset 6 in the string
-(match:substring
- (string-match "[0-9][0-9][0-9][0-9]" "blah987654" 6))
-@result{} "7654"
-@end lisp
-
-@c begin (scm-doc-string "regex.scm" "match:start")
-@deffn {Scheme Procedure} match:start match [n]
-Return the starting position of submatch number @var{n}.
-@end deffn
-
-In the following example, the result is 4, since the match starts at
-character index 4:
-
-@lisp
-(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
-(match:start s)
-@result{} 4
-@end lisp
-
-@c begin (scm-doc-string "regex.scm" "match:end")
-@deffn {Scheme Procedure} match:end match [n]
-Return the ending position of submatch number @var{n}.
-@end deffn
-
-In the following example, the result is 8, since the match runs between
-characters 4 and 8 (i.e. the ``2002'').
-
-@lisp
-(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
-(match:end s)
-@result{} 8
-@end lisp
-
-@c begin (scm-doc-string "regex.scm" "match:prefix")
-@deffn {Scheme Procedure} match:prefix match
-Return the unmatched portion of @var{target} preceding the regexp match.
-
-@lisp
-(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
-(match:prefix s)
-@result{} "blah"
-@end lisp
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:suffix")
-@deffn {Scheme Procedure} match:suffix match
-Return the unmatched portion of @var{target} following the regexp match.
-@end deffn
-
-@lisp
-(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
-(match:suffix s)
-@result{} "foo"
-@end lisp
-
-@c begin (scm-doc-string "regex.scm" "match:count")
-@deffn {Scheme Procedure} match:count match
-Return the number of parenthesized subexpressions from @var{match}.
-Note that the entire regular expression match itself counts as a
-subexpression, and failed submatches are included in the count.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:string")
-@deffn {Scheme Procedure} match:string match
-Return the original @var{target} string.
-@end deffn
-
-@lisp
-(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
-(match:string s)
-@result{} "blah2002foo"
-@end lisp
-
-
-@node Backslash Escapes
-@subsubsection Backslash Escapes
-
-Sometimes you will want a regexp to match characters like @samp{*} or
-@samp{$} exactly. For example, to check whether a particular string
-represents a menu entry from an Info node, it would be useful to match
-it against a regexp like @samp{^* [^:]*::}. However, this won't work;
-because the asterisk is a metacharacter, it won't match the @samp{*} at
-the beginning of the string. In this case, we want to make the first
-asterisk un-magic.
-
-You can do this by preceding the metacharacter with a backslash
-character @samp{\}. (This is also called @dfn{quoting} the
-metacharacter, and is known as a @dfn{backslash escape}.) When Guile
-sees a backslash in a regular expression, it considers the following
-glyph to be an ordinary character, no matter what special meaning it
-would ordinarily have. Therefore, we can make the above example work by
-changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells
-the regular expression engine to match only a single asterisk in the
-target string.
-
-Since the backslash is itself a metacharacter, you may force a regexp to
-match a backslash in the target string by preceding the backslash with
-itself. For example, to find variable references in a @TeX{} program,
-you might want to find occurrences of the string @samp{\let\} followed
-by any number of alphabetic characters. The regular expression
-@samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the
-regexp each match a single backslash in the target string.
-
-@c begin (scm-doc-string "regex.scm" "regexp-quote")
-@deffn {Scheme Procedure} regexp-quote str
-Quote each special character found in @var{str} with a backslash, and
-return the resulting string.
-@end deffn
-
-@strong{Very important:} Using backslash escapes in Guile source code
-(as in Emacs Lisp or C) can be tricky, because the backslash character
-has special meaning for the Guile reader. For example, if Guile
-encounters the character sequence @samp{\n} in the middle of a string
-while processing Scheme code, it replaces those characters with a
-newline character. Similarly, the character sequence @samp{\t} is
-replaced by a horizontal tab. Several of these @dfn{escape sequences}
-are processed by the Guile reader before your code is executed.
-Unrecognized escape sequences are ignored: if the characters @samp{\*}
-appear in a string, they will be translated to the single character
-@samp{*}.
-
-This translation is obviously undesirable for regular expressions, since
-we want to be able to include backslashes in a string in order to
-escape regexp metacharacters. Therefore, to make sure that a backslash
-is preserved in a string in your Guile program, you must use @emph{two}
-consecutive backslashes:
-
-@lisp
-(define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
-@end lisp
-
-The string in this example is preprocessed by the Guile reader before
-any code is executed. The resulting argument to @code{make-regexp} is
-the string @samp{^\* [^:]*}, which is what we really want.
-
-This also means that in order to write a regular expression that matches
-a single backslash character, the regular expression string in the
-source code must include @emph{four} backslashes. Each consecutive pair
-of backslashes gets translated by the Guile reader to a single
-backslash, and the resulting double-backslash is interpreted by the
-regexp engine as matching a single backslash character. Hence:
-
-@lisp
-(define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
-@end lisp
-
-The reason for the unwieldiness of this syntax is historical. Both
-regular expression pattern matchers and Unix string processing systems
-have traditionally used backslashes with the special meanings
-described above. The POSIX regular expression specification and ANSI C
-standard both require these semantics. Attempting to abandon either
-convention would cause other kinds of compatibility problems, possibly
-more severe ones. Therefore, without extending the Scheme reader to
-support strings with different quoting conventions (an ungainly and
-confusing extension when implemented in other languages), we must adhere
-to this cumbersome escape syntax.
+Bytevectors may also be accessed with the SRFI-4 API. @xref{SRFI-4 and
+Bytevectors}, for more information.
@node Symbols
Most symbols are created by writing them literally in code. However it
is also possible to create symbols programmatically using the following
-@code{string->symbol} and @code{string-ci->symbol} procedures:
+procedures:
+
+@deffn {Scheme Procedure} symbol char@dots{}
+@rnindex symbol
+Return a newly allocated symbol made from the given character arguments.
+
+@example
+(symbol #\x #\y #\z) @result{} xyz
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} list->symbol lst
+@rnindex list->symbol
+Return a newly allocated symbol made from a list of characters.
+
+@example
+(list->symbol '(#\a #\b #\c)) @result{} abc
+@end example
+@end deffn
+
+@rnindex symbol-append
+@deffn {Scheme Procedure} symbol-append arg @dots{}
+Return a newly allocated symbol whose characters form the
+concatenation of the given symbols, @var{arg} @enddots{}.
+
+@example
+(let ((h 'hello))
+ (symbol-append h 'world))
+@result{} helloworld
+@end example
+@end deffn
@rnindex string->symbol
@deffn {Scheme Procedure} string->symbol string
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)
+@deftypefn {C Function} scm_from_latin1_symbol (const char *name)
+@deftypefnx {C Function} scm_from_utf8_symbol (const char *name)
+Construct and return a Scheme symbol whose name is specified by the
+null-terminated C string @var{name}. These are appropriate when
+the C string is hard-coded in the source code.
+@end deftypefn
+
+@deftypefn {C Function} scm_from_locale_symbol (const char *name)
+@deftypefnx {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_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
+
+Note that these functions should @emph{not} be used when @var{name} is a
+C string constant, because there is no guarantee that the current locale
+will match that of the source code. In such cases, use
+@code{scm_from_latin1_symbol} or @code{scm_from_utf8_symbol}.
+@end deftypefn
@deftypefn {C Function} SCM scm_take_locale_symbol (char *str)
@deftypefnx {C Function} SCM scm_take_locale_symboln (char *str, size_t len)
@item
a @dfn{function} value, which is used when the symbol appears in
-code in a function name position (i.e. as the first element in an
+code in a function name position (i.e.@: as the first element in an
unquoted list)
@item
case they turn out to be useful when implementing translators for other
languages, in particular Emacs Lisp.
-Specifically, Guile symbols have two extra slots. for a symbol's
-property list, and for its ``function value.'' The following procedures
+Specifically, Guile symbols have two extra slots, one for a symbol's
+property list, and one for its ``function value.'' The following procedures
are provided to access these slots.
@deffn {Scheme Procedure} symbol-fref symbol
created and entered into the table so that it can be found later.
Sometimes you might want to create a symbol that is guaranteed `fresh',
-i.e. a symbol that did not exist previously. You might also want to
+i.e.@: a symbol that did not exist previously. You might also want to
somehow guarantee that no one else will ever unintentionally stumble
across your symbol in the future. These properties of a symbol are
often needed when generating code during macro expansion. When
Otherwise, tokens of this form are read as symbols.
To enable and disable the alternative non-R5RS keyword syntax, you use
-the @code{read-set!} procedure documented in @ref{User level options
-interfaces} and @ref{Reader options}. Note that the @code{prefix} and
-@code{postfix} syntax are mutually exclusive.
+the @code{read-set!} procedure documented @ref{Scheme Read}. Note that
+the @code{prefix} and @code{postfix} syntax are mutually exclusive.
@lisp
(read-set! keywords 'prefix)
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)
+@deftypefn {C Function} SCM scm_from_locale_keyword (const char *name)
+@deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *name, 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.
+(@var{name}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln
+(@var{name}, @var{len}))}, respectively.
+
+Note that these functions should @emph{not} be used when @var{name} is a
+C string constant, because there is no guarantee that the current locale
+will match that of the source code. In such cases, use
+@code{scm_from_latin1_keyword} or @code{scm_from_utf8_keyword}.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_from_latin1_keyword (const char *name)
+@deftypefnx {C Function} SCM scm_from_utf8_keyword (const char *name)
+Equivalent to @code{scm_symbol_to_keyword (scm_from_latin1_symbol
+(@var{name}))} and @code{scm_symbol_to_keyword (scm_from_utf8_symbol
+(@var{name}))}, respectively.
@end deftypefn
@node Other Types
@subsection ``Functionality-Centric'' Data Types
-Procedures and macros are documented in their own chapter: see
-@ref{Procedures and Macros}.
+Procedures and macros are documented in their own sections: see
+@ref{Procedures} and @ref{Macros}.
Variable objects are documented as part of the description of Guile's
module system: see @ref{Variables}.
-Asyncs, dynamic roots and fluids are described in the chapter on
+Asyncs, dynamic roots and fluids are described in the section on
scheduling: see @ref{Scheduling}.
-Hooks are documented in the chapter on general utility functions: see
+Hooks are documented in the section on general utility functions: see
@ref{Hooks}.
-Ports are described in the chapter on I/O: see @ref{Input and Output}.
+Ports are described in the section on I/O: see @ref{Input and Output}.
+Regular expressions are described in their own section: see @ref{Regular
+Expressions}.
@c Local Variables:
@c TeX-master: "guile.texi"
HCoop / bpt / guile.git / blobdiff