2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007,
4 @c 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Simple Data Types
8 @section Simple Generic Data Types
10 This chapter describes those of Guile's simple data types which are
11 primarily used for their role as items of generic data. By
12 @dfn{simple} we mean data types that are not primarily used as
13 containers to hold other data --- i.e.@: pairs, lists, vectors and so on.
14 For the documentation of such @dfn{compound} data types, see
15 @ref{Compound Data Types}.
17 @c One of the great strengths of Scheme is that there is no straightforward
18 @c distinction between ``data'' and ``functionality''. For example,
19 @c Guile's support for dynamic linking could be described:
23 @c either in a ``data-centric'' way, as the behaviour and properties of the
24 @c ``dynamically linked object'' data type, and the operations that may be
25 @c applied to instances of this type
28 @c or in a ``functionality-centric'' way, as the set of procedures that
29 @c constitute Guile's support for dynamic linking, in the context of the
33 @c The contents of this chapter are, therefore, a matter of judgment. By
34 @c @dfn{generic}, we mean to select those data types whose typical use as
35 @c @emph{data} in a wide variety of programming contexts is more important
36 @c than their use in the implementation of a particular piece of
37 @c @emph{functionality}. The last section of this chapter provides
38 @c references for all the data types that are documented not here but in a
39 @c ``functionality-centric'' way elsewhere in the manual.
42 * Booleans:: True/false values.
43 * Numbers:: Numerical data types.
44 * Characters:: Single characters.
45 * Character Sets:: Sets of characters.
46 * Strings:: Sequences of characters.
47 * Bytevectors:: Sequences of bytes.
49 * Keywords:: Self-quoting, customizable display keywords.
50 * Other Types:: "Functionality-centric" data types.
58 The two boolean values are @code{#t} for true and @code{#f} for false.
60 Boolean values are returned by predicate procedures, such as the general
61 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
62 (@pxref{Equality}) and numerical and string comparison operators like
63 @code{string=?} (@pxref{String Comparison}) and @code{<=}
73 (equal? "house" "houses")
81 In test condition contexts like @code{if} and @code{cond}
82 (@pxref{Conditionals}), where a group of subexpressions will be
83 evaluated only if a @var{condition} expression evaluates to ``true'',
84 ``true'' means any value at all except @code{#f}.
97 A result of this asymmetry is that typical Scheme source code more often
98 uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
99 represent an @code{if} or @code{cond} false value, whereas @code{#t} is
100 not necessary to represent an @code{if} or @code{cond} true value.
102 It is important to note that @code{#f} is @strong{not} equivalent to any
103 other Scheme value. In particular, @code{#f} is not the same as the
104 number 0 (like in C and C++), and not the same as the ``empty list''
105 (like in some Lisp dialects).
107 In C, the two Scheme boolean values are available as the two constants
108 @code{SCM_BOOL_T} for @code{#t} and @code{SCM_BOOL_F} for @code{#f}.
109 Care must be taken with the false value @code{SCM_BOOL_F}: it is not
110 false when used in C conditionals. In order to test for it, use
111 @code{scm_is_false} or @code{scm_is_true}.
114 @deffn {Scheme Procedure} not x
115 @deffnx {C Function} scm_not (x)
116 Return @code{#t} if @var{x} is @code{#f}, else return @code{#f}.
120 @deffn {Scheme Procedure} boolean? obj
121 @deffnx {C Function} scm_boolean_p (obj)
122 Return @code{#t} if @var{obj} is either @code{#t} or @code{#f}, else
126 @deftypevr {C Macro} SCM SCM_BOOL_T
127 The @code{SCM} representation of the Scheme object @code{#t}.
130 @deftypevr {C Macro} SCM SCM_BOOL_F
131 The @code{SCM} representation of the Scheme object @code{#f}.
134 @deftypefn {C Function} int scm_is_true (SCM obj)
135 Return @code{0} if @var{obj} is @code{#f}, else return @code{1}.
138 @deftypefn {C Function} int scm_is_false (SCM obj)
139 Return @code{1} if @var{obj} is @code{#f}, else return @code{0}.
142 @deftypefn {C Function} int scm_is_bool (SCM obj)
143 Return @code{1} if @var{obj} is either @code{#t} or @code{#f}, else
147 @deftypefn {C Function} SCM scm_from_bool (int val)
148 Return @code{#f} if @var{val} is @code{0}, else return @code{#t}.
151 @deftypefn {C Function} int scm_to_bool (SCM val)
152 Return @code{1} if @var{val} is @code{SCM_BOOL_T}, return @code{0}
153 when @var{val} is @code{SCM_BOOL_F}, else signal a `wrong type' error.
155 You should probably use @code{scm_is_true} instead of this function
156 when you just want to test a @code{SCM} value for trueness.
160 @subsection Numerical data types
163 Guile supports a rich ``tower'' of numerical types --- integer,
164 rational, real and complex --- and provides an extensive set of
165 mathematical and scientific functions for operating on numerical
166 data. This section of the manual documents those types and functions.
168 You may also find it illuminating to read R5RS's presentation of numbers
169 in Scheme, which is particularly clear and accessible: see
170 @ref{Numbers,,,r5rs,R5RS}.
173 * Numerical Tower:: Scheme's numerical "tower".
174 * Integers:: Whole numbers.
175 * Reals and Rationals:: Real and rational numbers.
176 * Complex Numbers:: Complex numbers.
177 * Exactness:: Exactness and inexactness.
178 * Number Syntax:: Read syntax for numerical data.
179 * Integer Operations:: Operations on integer values.
180 * Comparison:: Comparison predicates.
181 * Conversion:: Converting numbers to and from strings.
182 * Complex:: Complex number operations.
183 * Arithmetic:: Arithmetic functions.
184 * Scientific:: Scientific functions.
185 * Bitwise Operations:: Logical AND, OR, NOT, and so on.
186 * Random:: Random number generation.
190 @node Numerical Tower
191 @subsubsection Scheme's Numerical ``Tower''
194 Scheme's numerical ``tower'' consists of the following categories of
199 Whole numbers, positive or negative; e.g.@: --5, 0, 18.
202 The set of numbers that can be expressed as @math{@var{p}/@var{q}}
203 where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
204 pi (an irrational number) doesn't. These include integers
208 The set of numbers that describes all possible positions along a
209 one-dimensional line. This includes rationals as well as irrational
212 @item complex numbers
213 The set of numbers that describes all possible positions in a two
214 dimensional space. This includes real as well as imaginary numbers
215 (@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
216 @var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
220 It is called a tower because each category ``sits on'' the one that
221 follows it, in the sense that every integer is also a rational, every
222 rational is also real, and every real number is also a complex number
223 (but with zero imaginary part).
225 In addition to the classification into integers, rationals, reals and
226 complex numbers, Scheme also distinguishes between whether a number is
227 represented exactly or not. For example, the result of
228 @m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)}, but Guile
229 can represent neither @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
230 Instead, it stores an inexact approximation, using the C type
233 Guile can represent exact rationals of any magnitude, inexact
234 rationals that fit into a C @code{double}, and inexact complex numbers
235 with @code{double} real and imaginary parts.
237 The @code{number?} predicate may be applied to any Scheme value to
238 discover whether the value is any of the supported numerical types.
240 @deffn {Scheme Procedure} number? obj
241 @deffnx {C Function} scm_number_p (obj)
242 Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
251 (number? "hello there!")
254 (define pi 3.141592654)
259 @deftypefn {C Function} int scm_is_number (SCM obj)
260 This is equivalent to @code{scm_is_true (scm_number_p (obj))}.
263 The next few subsections document each of Guile's numerical data types
267 @subsubsection Integers
269 @tpindex Integer numbers
273 Integers are whole numbers, that is numbers with no fractional part,
274 such as 2, 83, and @minus{}3789.
276 Integers in Guile can be arbitrarily big, as shown by the following
280 (define (factorial n)
281 (let loop ((n n) (product 1))
284 (loop (- n 1) (* product n)))))
290 @result{} 2432902008176640000
293 @result{} -119622220865480194561963161495657715064383733760000000000
296 Readers whose background is in programming languages where integers are
297 limited by the need to fit into just 4 or 8 bytes of memory may find
298 this surprising, or suspect that Guile's representation of integers is
299 inefficient. In fact, Guile achieves a near optimal balance of
300 convenience and efficiency by using the host computer's native
301 representation of integers where possible, and a more general
302 representation where the required number does not fit in the native
303 form. Conversion between these two representations is automatic and
304 completely invisible to the Scheme level programmer.
306 C has a host of different integer types, and Guile offers a host of
307 functions to convert between them and the @code{SCM} representation.
308 For example, a C @code{int} can be handled with @code{scm_to_int} and
309 @code{scm_from_int}. Guile also defines a few C integer types of its
310 own, to help with differences between systems.
312 C integer types that are not covered can be handled with the generic
313 @code{scm_to_signed_integer} and @code{scm_from_signed_integer} for
314 signed types, or with @code{scm_to_unsigned_integer} and
315 @code{scm_from_unsigned_integer} for unsigned types.
317 Scheme integers can be exact and inexact. For example, a number
318 written as @code{3.0} with an explicit decimal-point is inexact, but
319 it is also an integer. The functions @code{integer?} and
320 @code{scm_is_integer} report true for such a number, but the functions
321 @code{scm_is_signed_integer} and @code{scm_is_unsigned_integer} only
322 allow exact integers and thus report false. Likewise, the conversion
323 functions like @code{scm_to_signed_integer} only accept exact
326 The motivation for this behavior is that the inexactness of a number
327 should not be lost silently. If you want to allow inexact integers,
328 you can explicitly insert a call to @code{inexact->exact} or to its C
329 equivalent @code{scm_inexact_to_exact}. (Only inexact integers will
330 be converted by this call into exact integers; inexact non-integers
331 will become exact fractions.)
333 @deffn {Scheme Procedure} integer? x
334 @deffnx {C Function} scm_integer_p (x)
335 Return @code{#t} if @var{x} is an exact or inexact integer number, else
353 @deftypefn {C Function} int scm_is_integer (SCM x)
354 This is equivalent to @code{scm_is_true (scm_integer_p (x))}.
357 @defvr {C Type} scm_t_int8
358 @defvrx {C Type} scm_t_uint8
359 @defvrx {C Type} scm_t_int16
360 @defvrx {C Type} scm_t_uint16
361 @defvrx {C Type} scm_t_int32
362 @defvrx {C Type} scm_t_uint32
363 @defvrx {C Type} scm_t_int64
364 @defvrx {C Type} scm_t_uint64
365 @defvrx {C Type} scm_t_intmax
366 @defvrx {C Type} scm_t_uintmax
367 The C types are equivalent to the corresponding ISO C types but are
368 defined on all platforms, with the exception of @code{scm_t_int64} and
369 @code{scm_t_uint64}, which are only defined when a 64-bit type is
370 available. For example, @code{scm_t_int8} is equivalent to
373 You can regard these definitions as a stop-gap measure until all
374 platforms provide these types. If you know that all the platforms
375 that you are interested in already provide these types, it is better
376 to use them directly instead of the types provided by Guile.
379 @deftypefn {C Function} int scm_is_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
380 @deftypefnx {C Function} int scm_is_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
381 Return @code{1} when @var{x} represents an exact integer that is
382 between @var{min} and @var{max}, inclusive.
384 These functions can be used to check whether a @code{SCM} value will
385 fit into a given range, such as the range of a given C integer type.
386 If you just want to convert a @code{SCM} value to a given C integer
387 type, use one of the conversion functions directly.
390 @deftypefn {C Function} scm_t_intmax scm_to_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
391 @deftypefnx {C Function} scm_t_uintmax scm_to_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
392 When @var{x} represents an exact integer that is between @var{min} and
393 @var{max} inclusive, return that integer. Else signal an error,
394 either a `wrong-type' error when @var{x} is not an exact integer, or
395 an `out-of-range' error when it doesn't fit the given range.
398 @deftypefn {C Function} SCM scm_from_signed_integer (scm_t_intmax x)
399 @deftypefnx {C Function} SCM scm_from_unsigned_integer (scm_t_uintmax x)
400 Return the @code{SCM} value that represents the integer @var{x}. This
401 function will always succeed and will always return an exact number.
404 @deftypefn {C Function} char scm_to_char (SCM x)
405 @deftypefnx {C Function} {signed char} scm_to_schar (SCM x)
406 @deftypefnx {C Function} {unsigned char} scm_to_uchar (SCM x)
407 @deftypefnx {C Function} short scm_to_short (SCM x)
408 @deftypefnx {C Function} {unsigned short} scm_to_ushort (SCM x)
409 @deftypefnx {C Function} int scm_to_int (SCM x)
410 @deftypefnx {C Function} {unsigned int} scm_to_uint (SCM x)
411 @deftypefnx {C Function} long scm_to_long (SCM x)
412 @deftypefnx {C Function} {unsigned long} scm_to_ulong (SCM x)
413 @deftypefnx {C Function} {long long} scm_to_long_long (SCM x)
414 @deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x)
415 @deftypefnx {C Function} size_t scm_to_size_t (SCM x)
416 @deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x)
417 @deftypefnx {C Function} scm_t_ptrdiff scm_to_ptrdiff_t (SCM x)
418 @deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x)
419 @deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x)
420 @deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x)
421 @deftypefnx {C Function} scm_t_uint16 scm_to_uint16 (SCM x)
422 @deftypefnx {C Function} scm_t_int32 scm_to_int32 (SCM x)
423 @deftypefnx {C Function} scm_t_uint32 scm_to_uint32 (SCM x)
424 @deftypefnx {C Function} scm_t_int64 scm_to_int64 (SCM x)
425 @deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x)
426 @deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x)
427 @deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x)
428 When @var{x} represents an exact integer that fits into the indicated
429 C type, return that integer. Else signal an error, either a
430 `wrong-type' error when @var{x} is not an exact integer, or an
431 `out-of-range' error when it doesn't fit the given range.
433 The functions @code{scm_to_long_long}, @code{scm_to_ulong_long},
434 @code{scm_to_int64}, and @code{scm_to_uint64} are only available when
435 the corresponding types are.
438 @deftypefn {C Function} SCM scm_from_char (char x)
439 @deftypefnx {C Function} SCM scm_from_schar (signed char x)
440 @deftypefnx {C Function} SCM scm_from_uchar (unsigned char x)
441 @deftypefnx {C Function} SCM scm_from_short (short x)
442 @deftypefnx {C Function} SCM scm_from_ushort (unsigned short x)
443 @deftypefnx {C Function} SCM scm_from_int (int x)
444 @deftypefnx {C Function} SCM scm_from_uint (unsigned int x)
445 @deftypefnx {C Function} SCM scm_from_long (long x)
446 @deftypefnx {C Function} SCM scm_from_ulong (unsigned long x)
447 @deftypefnx {C Function} SCM scm_from_long_long (long long x)
448 @deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x)
449 @deftypefnx {C Function} SCM scm_from_size_t (size_t x)
450 @deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x)
451 @deftypefnx {C Function} SCM scm_from_ptrdiff_t (scm_t_ptrdiff x)
452 @deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x)
453 @deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x)
454 @deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x)
455 @deftypefnx {C Function} SCM scm_from_uint16 (scm_t_uint16 x)
456 @deftypefnx {C Function} SCM scm_from_int32 (scm_t_int32 x)
457 @deftypefnx {C Function} SCM scm_from_uint32 (scm_t_uint32 x)
458 @deftypefnx {C Function} SCM scm_from_int64 (scm_t_int64 x)
459 @deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x)
460 @deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x)
461 @deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x)
462 Return the @code{SCM} value that represents the integer @var{x}.
463 These functions will always succeed and will always return an exact
467 @deftypefn {C Function} void scm_to_mpz (SCM val, mpz_t rop)
468 Assign @var{val} to the multiple precision integer @var{rop}.
469 @var{val} must be an exact integer, otherwise an error will be
470 signalled. @var{rop} must have been initialized with @code{mpz_init}
471 before this function is called. When @var{rop} is no longer needed
472 the occupied space must be freed with @code{mpz_clear}.
473 @xref{Initializing Integers,,, gmp, GNU MP Manual}, for details.
476 @deftypefn {C Function} SCM scm_from_mpz (mpz_t val)
477 Return the @code{SCM} value that represents @var{val}.
480 @node Reals and Rationals
481 @subsubsection Real and Rational Numbers
482 @tpindex Real numbers
483 @tpindex Rational numbers
488 Mathematically, the real numbers are the set of numbers that describe
489 all possible points along a continuous, infinite, one-dimensional line.
490 The rational numbers are the set of all numbers that can be written as
491 fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
492 All rational numbers are also real, but there are real numbers that
493 are not rational, for example @m{\sqrt{2}, the square root of 2}, and
496 Guile can represent both exact and inexact rational numbers, but it
497 cannot represent precise finite irrational numbers. Exact rationals are
498 represented by storing the numerator and denominator as two exact
499 integers. Inexact rationals are stored as floating point numbers using
500 the C type @code{double}.
502 Exact rationals are written as a fraction of integers. There must be
503 no whitespace around the slash:
510 Even though the actual encoding of inexact rationals is in binary, it
511 may be helpful to think of it as a decimal number with a limited
512 number of significant figures and a decimal point somewhere, since
513 this corresponds to the standard notation for non-whole numbers. For
519 -5648394822220000000000.0
523 The limited precision of Guile's encoding means that any finite ``real''
524 number in Guile can be written in a rational form, by multiplying and
525 then dividing by sufficient powers of 10 (or in fact, 2). For example,
526 @samp{-0.00000142857931198} is the same as @minus{}142857931198 divided
527 by 100000000000000000. In Guile's current incarnation, therefore, the
528 @code{rational?} and @code{real?} predicates are equivalent for finite
532 Dividing by an exact zero leads to a error message, as one might expect.
533 However, dividing by an inexact zero does not produce an error.
534 Instead, the result of the division is either plus or minus infinity,
535 depending on the sign of the divided number and the sign of the zero
536 divisor (some platforms support signed zeroes @samp{-0.0} and
537 @samp{+0.0}; @samp{0.0} is the same as @samp{+0.0}).
539 Dividing zero by an inexact zero yields a @acronym{NaN} (`not a number')
540 value, although they are actually considered numbers by Scheme.
541 Attempts to compare a @acronym{NaN} value with any number (including
542 itself) using @code{=}, @code{<}, @code{>}, @code{<=} or @code{>=}
543 always returns @code{#f}. Although a @acronym{NaN} value is not
544 @code{=} to itself, it is both @code{eqv?} and @code{equal?} to itself
545 and other @acronym{NaN} values. However, the preferred way to test for
546 them is by using @code{nan?}.
548 The real @acronym{NaN} values and infinities are written @samp{+nan.0},
549 @samp{+inf.0} and @samp{-inf.0}. This syntax is also recognized by
550 @code{read} as an extension to the usual Scheme syntax. These special
551 values are considered by Scheme to be inexact real numbers but not
552 rational. Note that non-real complex numbers may also contain
553 infinities or @acronym{NaN} values in their real or imaginary parts. To
554 test a real number to see if it is infinite, a @acronym{NaN} value, or
555 neither, use @code{inf?}, @code{nan?}, or @code{finite?}, respectively.
556 Every real number in Scheme belongs to precisely one of those three
559 On platforms that follow @acronym{IEEE} 754 for their floating point
560 arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
561 are implemented using the corresponding @acronym{IEEE} 754 values.
562 They behave in arithmetic operations like @acronym{IEEE} 754 describes
563 it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
565 @deffn {Scheme Procedure} real? obj
566 @deffnx {C Function} scm_real_p (obj)
567 Return @code{#t} if @var{obj} is a real number, else @code{#f}. Note
568 that the sets of integer and rational values form subsets of the set
569 of real numbers, so the predicate will also be fulfilled if @var{obj}
570 is an integer number or a rational number.
573 @deffn {Scheme Procedure} rational? x
574 @deffnx {C Function} scm_rational_p (x)
575 Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise.
576 Note that the set of integer values forms a subset of the set of
577 rational numbers, i.e.@: the predicate will also be fulfilled if
578 @var{x} is an integer number.
581 @deffn {Scheme Procedure} rationalize x eps
582 @deffnx {C Function} scm_rationalize (x, eps)
583 Returns the @emph{simplest} rational number differing
584 from @var{x} by no more than @var{eps}.
586 As required by @acronym{R5RS}, @code{rationalize} only returns an
587 exact result when both its arguments are exact. Thus, you might need
588 to use @code{inexact->exact} on the arguments.
591 (rationalize (inexact->exact 1.2) 1/100)
597 @deffn {Scheme Procedure} inf? x
598 @deffnx {C Function} scm_inf_p (x)
599 Return @code{#t} if the real number @var{x} is @samp{+inf.0} or
600 @samp{-inf.0}. Otherwise return @code{#f}.
603 @deffn {Scheme Procedure} nan? x
604 @deffnx {C Function} scm_nan_p (x)
605 Return @code{#t} if the real number @var{x} is @samp{+nan.0}, or
609 @deffn {Scheme Procedure} finite? x
610 @deffnx {C Function} scm_finite_p (x)
611 Return @code{#t} if the real number @var{x} is neither infinite nor a
612 NaN, @code{#f} otherwise.
615 @deffn {Scheme Procedure} nan
616 @deffnx {C Function} scm_nan ()
617 Return @samp{+nan.0}, a @acronym{NaN} value.
620 @deffn {Scheme Procedure} inf
621 @deffnx {C Function} scm_inf ()
622 Return @samp{+inf.0}, positive infinity.
625 @deffn {Scheme Procedure} numerator x
626 @deffnx {C Function} scm_numerator (x)
627 Return the numerator of the rational number @var{x}.
630 @deffn {Scheme Procedure} denominator x
631 @deffnx {C Function} scm_denominator (x)
632 Return the denominator of the rational number @var{x}.
635 @deftypefn {C Function} int scm_is_real (SCM val)
636 @deftypefnx {C Function} int scm_is_rational (SCM val)
637 Equivalent to @code{scm_is_true (scm_real_p (val))} and
638 @code{scm_is_true (scm_rational_p (val))}, respectively.
641 @deftypefn {C Function} double scm_to_double (SCM val)
642 Returns the number closest to @var{val} that is representable as a
643 @code{double}. Returns infinity for a @var{val} that is too large in
644 magnitude. The argument @var{val} must be a real number.
647 @deftypefn {C Function} SCM scm_from_double (double val)
648 Return the @code{SCM} value that represents @var{val}. The returned
649 value is inexact according to the predicate @code{inexact?}, but it
650 will be exactly equal to @var{val}.
653 @node Complex Numbers
654 @subsubsection Complex Numbers
655 @tpindex Complex numbers
659 Complex numbers are the set of numbers that describe all possible points
660 in a two-dimensional space. The two coordinates of a particular point
661 in this space are known as the @dfn{real} and @dfn{imaginary} parts of
662 the complex number that describes that point.
664 In Guile, complex numbers are written in rectangular form as the sum of
665 their real and imaginary parts, using the symbol @code{i} to indicate
680 Polar form can also be used, with an @samp{@@} between magnitude and
684 1@@3.141592 @result{} -1.0 (approx)
685 -1@@1.57079 @result{} 0.0-1.0i (approx)
688 Guile represents a complex number as a pair of inexact reals, so the
689 real and imaginary parts of a complex number have the same properties of
690 inexactness and limited precision as single inexact real numbers.
692 Note that each part of a complex number may contain any inexact real
693 value, including the special values @samp{+nan.0}, @samp{+inf.0} and
694 @samp{-inf.0}, as well as either of the signed zeroes @samp{0.0} or
698 @deffn {Scheme Procedure} complex? z
699 @deffnx {C Function} scm_complex_p (z)
700 Return @code{#t} if @var{z} is a complex number, @code{#f}
701 otherwise. Note that the sets of real, rational and integer
702 values form subsets of the set of complex numbers, i.e.@: the
703 predicate will also be fulfilled if @var{z} is a real,
704 rational or integer number.
707 @deftypefn {C Function} int scm_is_complex (SCM val)
708 Equivalent to @code{scm_is_true (scm_complex_p (val))}.
712 @subsubsection Exact and Inexact Numbers
713 @tpindex Exact numbers
714 @tpindex Inexact numbers
718 @rnindex exact->inexact
719 @rnindex inexact->exact
721 R5RS requires that, with few exceptions, a calculation involving inexact
722 numbers always produces an inexact result. To meet this requirement,
723 Guile distinguishes between an exact integer value such as @samp{5} and
724 the corresponding inexact integer value which, to the limited precision
725 available, has no fractional part, and is printed as @samp{5.0}. Guile
726 will only convert the latter value to the former when forced to do so by
727 an invocation of the @code{inexact->exact} procedure.
729 The only exception to the above requirement is when the values of the
730 inexact numbers do not affect the result. For example @code{(expt n 0)}
731 is @samp{1} for any value of @code{n}, therefore @code{(expt 5.0 0)} is
732 permitted to return an exact @samp{1}.
734 @deffn {Scheme Procedure} exact? z
735 @deffnx {C Function} scm_exact_p (z)
736 Return @code{#t} if the number @var{z} is exact, @code{#f}
752 @deftypefn {C Function} int scm_is_exact (SCM z)
753 Return a @code{1} if the number @var{z} is exact, and @code{0}
754 otherwise. This is equivalent to @code{scm_is_true (scm_exact_p (z))}.
756 An alternate approch to testing the exactness of a number is to
757 use @code{scm_is_signed_integer} or @code{scm_is_unsigned_integer}.
760 @deffn {Scheme Procedure} inexact? z
761 @deffnx {C Function} scm_inexact_p (z)
762 Return @code{#t} if the number @var{z} is inexact, @code{#f}
766 @deftypefn {C Function} int scm_is_inexact (SCM z)
767 Return a @code{1} if the number @var{z} is inexact, and @code{0}
768 otherwise. This is equivalent to @code{scm_is_true (scm_inexact_p (z))}.
771 @deffn {Scheme Procedure} inexact->exact z
772 @deffnx {C Function} scm_inexact_to_exact (z)
773 Return an exact number that is numerically closest to @var{z}, when
774 there is one. For inexact rationals, Guile returns the exact rational
775 that is numerically equal to the inexact rational. Inexact complex
776 numbers with a non-zero imaginary part can not be made exact.
783 The following happens because 12/10 is not exactly representable as a
784 @code{double} (on most platforms). However, when reading a decimal
785 number that has been marked exact with the ``#e'' prefix, Guile is
786 able to represent it correctly.
790 @result{} 5404319552844595/4503599627370496
798 @c begin (texi-doc-string "guile" "exact->inexact")
799 @deffn {Scheme Procedure} exact->inexact z
800 @deffnx {C Function} scm_exact_to_inexact (z)
801 Convert the number @var{z} to its inexact representation.
806 @subsubsection Read Syntax for Numerical Data
808 The read syntax for integers is a string of digits, optionally
809 preceded by a minus or plus character, a code indicating the
810 base in which the integer is encoded, and a code indicating whether
811 the number is exact or inexact. The supported base codes are:
816 the integer is written in binary (base 2)
820 the integer is written in octal (base 8)
824 the integer is written in decimal (base 10)
828 the integer is written in hexadecimal (base 16)
831 If the base code is omitted, the integer is assumed to be decimal. The
832 following examples show how these base codes are used.
851 The codes for indicating exactness (which can, incidentally, be applied
852 to all numerical values) are:
861 the number is inexact.
864 If the exactness indicator is omitted, the number is exact unless it
865 contains a radix point. Since Guile can not represent exact complex
866 numbers, an error is signalled when asking for them.
876 ERROR: Wrong type argument
879 Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
880 plus and minus infinity, respectively. The value must be written
881 exactly as shown, that is, they always must have a sign and exactly
882 one zero digit after the decimal point. It also understands
883 @samp{+nan.0} and @samp{-nan.0} for the special `not-a-number' value.
884 The sign is ignored for `not-a-number' and the value is always printed
887 @node Integer Operations
888 @subsubsection Operations on Integer Values
897 @deffn {Scheme Procedure} odd? n
898 @deffnx {C Function} scm_odd_p (n)
899 Return @code{#t} if @var{n} is an odd number, @code{#f}
903 @deffn {Scheme Procedure} even? n
904 @deffnx {C Function} scm_even_p (n)
905 Return @code{#t} if @var{n} is an even number, @code{#f}
909 @c begin (texi-doc-string "guile" "quotient")
910 @c begin (texi-doc-string "guile" "remainder")
911 @deffn {Scheme Procedure} quotient n d
912 @deffnx {Scheme Procedure} remainder n d
913 @deffnx {C Function} scm_quotient (n, d)
914 @deffnx {C Function} scm_remainder (n, d)
915 Return the quotient or remainder from @var{n} divided by @var{d}. The
916 quotient is rounded towards zero, and the remainder will have the same
917 sign as @var{n}. In all cases quotient and remainder satisfy
918 @math{@var{n} = @var{q}*@var{d} + @var{r}}.
921 (remainder 13 4) @result{} 1
922 (remainder -13 4) @result{} -1
925 See also @code{truncate-quotient}, @code{truncate-remainder} and
926 related operations in @ref{Arithmetic}.
929 @c begin (texi-doc-string "guile" "modulo")
930 @deffn {Scheme Procedure} modulo n d
931 @deffnx {C Function} scm_modulo (n, d)
932 Return the remainder from @var{n} divided by @var{d}, with the same
936 (modulo 13 4) @result{} 1
937 (modulo -13 4) @result{} 3
938 (modulo 13 -4) @result{} -3
939 (modulo -13 -4) @result{} -1
942 See also @code{floor-quotient}, @code{floor-remainder} and
943 related operations in @ref{Arithmetic}.
946 @c begin (texi-doc-string "guile" "gcd")
947 @deffn {Scheme Procedure} gcd x@dots{}
948 @deffnx {C Function} scm_gcd (x, y)
949 Return the greatest common divisor of all arguments.
950 If called without arguments, 0 is returned.
952 The C function @code{scm_gcd} always takes two arguments, while the
953 Scheme function can take an arbitrary number.
956 @c begin (texi-doc-string "guile" "lcm")
957 @deffn {Scheme Procedure} lcm x@dots{}
958 @deffnx {C Function} scm_lcm (x, y)
959 Return the least common multiple of the arguments.
960 If called without arguments, 1 is returned.
962 The C function @code{scm_lcm} always takes two arguments, while the
963 Scheme function can take an arbitrary number.
966 @deffn {Scheme Procedure} modulo-expt n k m
967 @deffnx {C Function} scm_modulo_expt (n, k, m)
968 Return @var{n} raised to the integer exponent
969 @var{k}, modulo @var{m}.
977 @deftypefn {Scheme Procedure} {} exact-integer-sqrt @var{k}
978 @deftypefnx {C Function} void scm_exact_integer_sqrt (SCM @var{k}, SCM *@var{s}, SCM *@var{r})
979 Return two exact non-negative integers @var{s} and @var{r}
980 such that @math{@var{k} = @var{s}^2 + @var{r}} and
981 @math{@var{s}^2 <= @var{k} < (@var{s} + 1)^2}.
982 An error is raised if @var{k} is not an exact non-negative integer.
985 (exact-integer-sqrt 10) @result{} 3 and 1
990 @subsubsection Comparison Predicates
995 The C comparison functions below always takes two arguments, while the
996 Scheme functions can take an arbitrary number. Also keep in mind that
997 the C functions return one of the Scheme boolean values
998 @code{SCM_BOOL_T} or @code{SCM_BOOL_F} which are both true as far as C
999 is concerned. Thus, always write @code{scm_is_true (scm_num_eq_p (x,
1000 y))} when testing the two Scheme numbers @code{x} and @code{y} for
1001 equality, for example.
1003 @c begin (texi-doc-string "guile" "=")
1004 @deffn {Scheme Procedure} =
1005 @deffnx {C Function} scm_num_eq_p (x, y)
1006 Return @code{#t} if all parameters are numerically equal.
1009 @c begin (texi-doc-string "guile" "<")
1010 @deffn {Scheme Procedure} <
1011 @deffnx {C Function} scm_less_p (x, y)
1012 Return @code{#t} if the list of parameters is monotonically
1016 @c begin (texi-doc-string "guile" ">")
1017 @deffn {Scheme Procedure} >
1018 @deffnx {C Function} scm_gr_p (x, y)
1019 Return @code{#t} if the list of parameters is monotonically
1023 @c begin (texi-doc-string "guile" "<=")
1024 @deffn {Scheme Procedure} <=
1025 @deffnx {C Function} scm_leq_p (x, y)
1026 Return @code{#t} if the list of parameters is monotonically
1030 @c begin (texi-doc-string "guile" ">=")
1031 @deffn {Scheme Procedure} >=
1032 @deffnx {C Function} scm_geq_p (x, y)
1033 Return @code{#t} if the list of parameters is monotonically
1037 @c begin (texi-doc-string "guile" "zero?")
1038 @deffn {Scheme Procedure} zero? z
1039 @deffnx {C Function} scm_zero_p (z)
1040 Return @code{#t} if @var{z} is an exact or inexact number equal to
1044 @c begin (texi-doc-string "guile" "positive?")
1045 @deffn {Scheme Procedure} positive? x
1046 @deffnx {C Function} scm_positive_p (x)
1047 Return @code{#t} if @var{x} is an exact or inexact number greater than
1051 @c begin (texi-doc-string "guile" "negative?")
1052 @deffn {Scheme Procedure} negative? x
1053 @deffnx {C Function} scm_negative_p (x)
1054 Return @code{#t} if @var{x} is an exact or inexact number less than
1060 @subsubsection Converting Numbers To and From Strings
1061 @rnindex number->string
1062 @rnindex string->number
1064 The following procedures read and write numbers according to their
1065 external representation as defined by R5RS (@pxref{Lexical structure,
1066 R5RS Lexical Structure,, r5rs, The Revised^5 Report on the Algorithmic
1067 Language Scheme}). @xref{Number Input and Output, the @code{(ice-9
1068 i18n)} module}, for locale-dependent number parsing.
1070 @deffn {Scheme Procedure} number->string n [radix]
1071 @deffnx {C Function} scm_number_to_string (n, radix)
1072 Return a string holding the external representation of the
1073 number @var{n} in the given @var{radix}. If @var{n} is
1074 inexact, a radix of 10 will be used.
1077 @deffn {Scheme Procedure} string->number string [radix]
1078 @deffnx {C Function} scm_string_to_number (string, radix)
1079 Return a number of the maximally precise representation
1080 expressed by the given @var{string}. @var{radix} must be an
1081 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
1082 is a default radix that may be overridden by an explicit radix
1083 prefix in @var{string} (e.g.@: "#o177"). If @var{radix} is not
1084 supplied, then the default radix is 10. If string is not a
1085 syntactically valid notation for a number, then
1086 @code{string->number} returns @code{#f}.
1089 @deftypefn {C Function} SCM scm_c_locale_stringn_to_number (const char *string, size_t len, unsigned radix)
1090 As per @code{string->number} above, but taking a C string, as pointer
1091 and length. The string characters should be in the current locale
1092 encoding (@code{locale} in the name refers only to that, there's no
1093 locale-dependent parsing).
1098 @subsubsection Complex Number Operations
1099 @rnindex make-rectangular
1106 @deffn {Scheme Procedure} make-rectangular real_part imaginary_part
1107 @deffnx {C Function} scm_make_rectangular (real_part, imaginary_part)
1108 Return a complex number constructed of the given @var{real-part} and @var{imaginary-part} parts.
1111 @deffn {Scheme Procedure} make-polar mag ang
1112 @deffnx {C Function} scm_make_polar (mag, ang)
1114 Return the complex number @var{mag} * e^(i * @var{ang}).
1117 @c begin (texi-doc-string "guile" "real-part")
1118 @deffn {Scheme Procedure} real-part z
1119 @deffnx {C Function} scm_real_part (z)
1120 Return the real part of the number @var{z}.
1123 @c begin (texi-doc-string "guile" "imag-part")
1124 @deffn {Scheme Procedure} imag-part z
1125 @deffnx {C Function} scm_imag_part (z)
1126 Return the imaginary part of the number @var{z}.
1129 @c begin (texi-doc-string "guile" "magnitude")
1130 @deffn {Scheme Procedure} magnitude z
1131 @deffnx {C Function} scm_magnitude (z)
1132 Return the magnitude of the number @var{z}. This is the same as
1133 @code{abs} for real arguments, but also allows complex numbers.
1136 @c begin (texi-doc-string "guile" "angle")
1137 @deffn {Scheme Procedure} angle z
1138 @deffnx {C Function} scm_angle (z)
1139 Return the angle of the complex number @var{z}.
1142 @deftypefn {C Function} SCM scm_c_make_rectangular (double re, double im)
1143 @deftypefnx {C Function} SCM scm_c_make_polar (double x, double y)
1144 Like @code{scm_make_rectangular} or @code{scm_make_polar},
1145 respectively, but these functions take @code{double}s as their
1149 @deftypefn {C Function} double scm_c_real_part (z)
1150 @deftypefnx {C Function} double scm_c_imag_part (z)
1151 Returns the real or imaginary part of @var{z} as a @code{double}.
1154 @deftypefn {C Function} double scm_c_magnitude (z)
1155 @deftypefnx {C Function} double scm_c_angle (z)
1156 Returns the magnitude or angle of @var{z} as a @code{double}.
1161 @subsubsection Arithmetic Functions
1176 @rnindex euclidean-quotient
1177 @rnindex euclidean-remainder
1179 @rnindex floor-quotient
1180 @rnindex floor-remainder
1182 @rnindex ceiling-quotient
1183 @rnindex ceiling-remainder
1185 @rnindex truncate-quotient
1186 @rnindex truncate-remainder
1188 @rnindex centered-quotient
1189 @rnindex centered-remainder
1191 @rnindex round-quotient
1192 @rnindex round-remainder
1194 The C arithmetic functions below always takes two arguments, while the
1195 Scheme functions can take an arbitrary number. When you need to
1196 invoke them with just one argument, for example to compute the
1197 equivalent of @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
1198 one: @code{scm_difference (x, SCM_UNDEFINED)}.
1200 @c begin (texi-doc-string "guile" "+")
1201 @deffn {Scheme Procedure} + z1 @dots{}
1202 @deffnx {C Function} scm_sum (z1, z2)
1203 Return the sum of all parameter values. Return 0 if called without any
1207 @c begin (texi-doc-string "guile" "-")
1208 @deffn {Scheme Procedure} - z1 z2 @dots{}
1209 @deffnx {C Function} scm_difference (z1, z2)
1210 If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
1211 the sum of all but the first argument are subtracted from the first
1215 @c begin (texi-doc-string "guile" "*")
1216 @deffn {Scheme Procedure} * z1 @dots{}
1217 @deffnx {C Function} scm_product (z1, z2)
1218 Return the product of all arguments. If called without arguments, 1 is
1222 @c begin (texi-doc-string "guile" "/")
1223 @deffn {Scheme Procedure} / z1 z2 @dots{}
1224 @deffnx {C Function} scm_divide (z1, z2)
1225 Divide the first argument by the product of the remaining arguments. If
1226 called with one argument @var{z1}, 1/@var{z1} is returned.
1229 @deffn {Scheme Procedure} 1+ z
1230 @deffnx {C Function} scm_oneplus (z)
1231 Return @math{@var{z} + 1}.
1234 @deffn {Scheme Procedure} 1- z
1235 @deffnx {C function} scm_oneminus (z)
1236 Return @math{@var{z} - 1}.
1239 @c begin (texi-doc-string "guile" "abs")
1240 @deffn {Scheme Procedure} abs x
1241 @deffnx {C Function} scm_abs (x)
1242 Return the absolute value of @var{x}.
1244 @var{x} must be a number with zero imaginary part. To calculate the
1245 magnitude of a complex number, use @code{magnitude} instead.
1248 @c begin (texi-doc-string "guile" "max")
1249 @deffn {Scheme Procedure} max x1 x2 @dots{}
1250 @deffnx {C Function} scm_max (x1, x2)
1251 Return the maximum of all parameter values.
1254 @c begin (texi-doc-string "guile" "min")
1255 @deffn {Scheme Procedure} min x1 x2 @dots{}
1256 @deffnx {C Function} scm_min (x1, x2)
1257 Return the minimum of all parameter values.
1260 @c begin (texi-doc-string "guile" "truncate")
1261 @deffn {Scheme Procedure} truncate x
1262 @deffnx {C Function} scm_truncate_number (x)
1263 Round the inexact number @var{x} towards zero.
1266 @c begin (texi-doc-string "guile" "round")
1267 @deffn {Scheme Procedure} round x
1268 @deffnx {C Function} scm_round_number (x)
1269 Round the inexact number @var{x} to the nearest integer. When exactly
1270 halfway between two integers, round to the even one.
1273 @c begin (texi-doc-string "guile" "floor")
1274 @deffn {Scheme Procedure} floor x
1275 @deffnx {C Function} scm_floor (x)
1276 Round the number @var{x} towards minus infinity.
1279 @c begin (texi-doc-string "guile" "ceiling")
1280 @deffn {Scheme Procedure} ceiling x
1281 @deffnx {C Function} scm_ceiling (x)
1282 Round the number @var{x} towards infinity.
1285 @deftypefn {C Function} double scm_c_truncate (double x)
1286 @deftypefnx {C Function} double scm_c_round (double x)
1287 Like @code{scm_truncate_number} or @code{scm_round_number},
1288 respectively, but these functions take and return @code{double}
1292 @deftypefn {Scheme Procedure} {} euclidean/ @var{x} @var{y}
1293 @deftypefnx {Scheme Procedure} {} euclidean-quotient @var{x} @var{y}
1294 @deftypefnx {Scheme Procedure} {} euclidean-remainder @var{x} @var{y}
1295 @deftypefnx {C Function} void scm_euclidean_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1296 @deftypefnx {C Function} SCM scm_euclidean_quotient (SCM @var{x}, SCM @var{y})
1297 @deftypefnx {C Function} SCM scm_euclidean_remainder (SCM @var{x}, SCM @var{y})
1298 These procedures accept two real numbers @var{x} and @var{y}, where the
1299 divisor @var{y} must be non-zero. @code{euclidean-quotient} returns the
1300 integer @var{q} and @code{euclidean-remainder} returns the real number
1301 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
1302 @math{0 <= @var{r} < |@var{y}|}. @code{euclidean/} returns both @var{q} and
1303 @var{r}, and is more efficient than computing each separately. Note
1304 that when @math{@var{y} > 0}, @code{euclidean-quotient} returns
1305 @math{floor(@var{x}/@var{y})}, otherwise it returns
1306 @math{ceiling(@var{x}/@var{y})}.
1308 Note that these operators are equivalent to the R6RS operators
1309 @code{div}, @code{mod}, and @code{div-and-mod}.
1312 (euclidean-quotient 123 10) @result{} 12
1313 (euclidean-remainder 123 10) @result{} 3
1314 (euclidean/ 123 10) @result{} 12 and 3
1315 (euclidean/ 123 -10) @result{} -12 and 3
1316 (euclidean/ -123 10) @result{} -13 and 7
1317 (euclidean/ -123 -10) @result{} 13 and 7
1318 (euclidean/ -123.2 -63.5) @result{} 2.0 and 3.8
1319 (euclidean/ 16/3 -10/7) @result{} -3 and 22/21
1323 @deftypefn {Scheme Procedure} {} floor/ @var{x} @var{y}
1324 @deftypefnx {Scheme Procedure} {} floor-quotient @var{x} @var{y}
1325 @deftypefnx {Scheme Procedure} {} floor-remainder @var{x} @var{y}
1326 @deftypefnx {C Function} void scm_floor_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1327 @deftypefnx {C Function} SCM scm_floor_quotient (@var{x}, @var{y})
1328 @deftypefnx {C Function} SCM scm_floor_remainder (@var{x}, @var{y})
1329 These procedures accept two real numbers @var{x} and @var{y}, where the
1330 divisor @var{y} must be non-zero. @code{floor-quotient} returns the
1331 integer @var{q} and @code{floor-remainder} returns the real number
1332 @var{r} such that @math{@var{q} = floor(@var{x}/@var{y})} and
1333 @math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{floor/} returns
1334 both @var{q} and @var{r}, and is more efficient than computing each
1335 separately. Note that @var{r}, if non-zero, will have the same sign
1338 When @var{x} and @var{y} are integers, @code{floor-remainder} is
1339 equivalent to the R5RS integer-only operator @code{modulo}.
1342 (floor-quotient 123 10) @result{} 12
1343 (floor-remainder 123 10) @result{} 3
1344 (floor/ 123 10) @result{} 12 and 3
1345 (floor/ 123 -10) @result{} -13 and -7
1346 (floor/ -123 10) @result{} -13 and 7
1347 (floor/ -123 -10) @result{} 12 and -3
1348 (floor/ -123.2 -63.5) @result{} 1.0 and -59.7
1349 (floor/ 16/3 -10/7) @result{} -4 and -8/21
1353 @deftypefn {Scheme Procedure} {} ceiling/ @var{x} @var{y}
1354 @deftypefnx {Scheme Procedure} {} ceiling-quotient @var{x} @var{y}
1355 @deftypefnx {Scheme Procedure} {} ceiling-remainder @var{x} @var{y}
1356 @deftypefnx {C Function} void scm_ceiling_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1357 @deftypefnx {C Function} SCM scm_ceiling_quotient (@var{x}, @var{y})
1358 @deftypefnx {C Function} SCM scm_ceiling_remainder (@var{x}, @var{y})
1359 These procedures accept two real numbers @var{x} and @var{y}, where the
1360 divisor @var{y} must be non-zero. @code{ceiling-quotient} returns the
1361 integer @var{q} and @code{ceiling-remainder} returns the real number
1362 @var{r} such that @math{@var{q} = ceiling(@var{x}/@var{y})} and
1363 @math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{ceiling/} returns
1364 both @var{q} and @var{r}, and is more efficient than computing each
1365 separately. Note that @var{r}, if non-zero, will have the opposite sign
1369 (ceiling-quotient 123 10) @result{} 13
1370 (ceiling-remainder 123 10) @result{} -7
1371 (ceiling/ 123 10) @result{} 13 and -7
1372 (ceiling/ 123 -10) @result{} -12 and 3
1373 (ceiling/ -123 10) @result{} -12 and -3
1374 (ceiling/ -123 -10) @result{} 13 and 7
1375 (ceiling/ -123.2 -63.5) @result{} 2.0 and 3.8
1376 (ceiling/ 16/3 -10/7) @result{} -3 and 22/21
1380 @deftypefn {Scheme Procedure} {} truncate/ @var{x} @var{y}
1381 @deftypefnx {Scheme Procedure} {} truncate-quotient @var{x} @var{y}
1382 @deftypefnx {Scheme Procedure} {} truncate-remainder @var{x} @var{y}
1383 @deftypefnx {C Function} void scm_truncate_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1384 @deftypefnx {C Function} SCM scm_truncate_quotient (@var{x}, @var{y})
1385 @deftypefnx {C Function} SCM scm_truncate_remainder (@var{x}, @var{y})
1386 These procedures accept two real numbers @var{x} and @var{y}, where the
1387 divisor @var{y} must be non-zero. @code{truncate-quotient} returns the
1388 integer @var{q} and @code{truncate-remainder} returns the real number
1389 @var{r} such that @var{q} is @math{@var{x}/@var{y}} rounded toward zero,
1390 and @math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{truncate/} returns
1391 both @var{q} and @var{r}, and is more efficient than computing each
1392 separately. Note that @var{r}, if non-zero, will have the same sign
1395 When @var{x} and @var{y} are integers, these operators are
1396 equivalent to the R5RS integer-only operators @code{quotient} and
1400 (truncate-quotient 123 10) @result{} 12
1401 (truncate-remainder 123 10) @result{} 3
1402 (truncate/ 123 10) @result{} 12 and 3
1403 (truncate/ 123 -10) @result{} -12 and 3
1404 (truncate/ -123 10) @result{} -12 and -3
1405 (truncate/ -123 -10) @result{} 12 and -3
1406 (truncate/ -123.2 -63.5) @result{} 1.0 and -59.7
1407 (truncate/ 16/3 -10/7) @result{} -3 and 22/21
1411 @deftypefn {Scheme Procedure} {} centered/ @var{x} @var{y}
1412 @deftypefnx {Scheme Procedure} {} centered-quotient @var{x} @var{y}
1413 @deftypefnx {Scheme Procedure} {} centered-remainder @var{x} @var{y}
1414 @deftypefnx {C Function} void scm_centered_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1415 @deftypefnx {C Function} SCM scm_centered_quotient (SCM @var{x}, SCM @var{y})
1416 @deftypefnx {C Function} SCM scm_centered_remainder (SCM @var{x}, SCM @var{y})
1417 These procedures accept two real numbers @var{x} and @var{y}, where the
1418 divisor @var{y} must be non-zero. @code{centered-quotient} returns the
1419 integer @var{q} and @code{centered-remainder} returns the real number
1420 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
1421 @math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}. @code{centered/}
1422 returns both @var{q} and @var{r}, and is more efficient than computing
1425 Note that @code{centered-quotient} returns @math{@var{x}/@var{y}}
1426 rounded to the nearest integer. When @math{@var{x}/@var{y}} lies
1427 exactly half-way between two integers, the tie is broken according to
1428 the sign of @var{y}. If @math{@var{y} > 0}, ties are rounded toward
1429 positive infinity, otherwise they are rounded toward negative infinity.
1430 This is a consequence of the requirement that
1431 @math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}.
1433 Note that these operators are equivalent to the R6RS operators
1434 @code{div0}, @code{mod0}, and @code{div0-and-mod0}.
1437 (centered-quotient 123 10) @result{} 12
1438 (centered-remainder 123 10) @result{} 3
1439 (centered/ 123 10) @result{} 12 and 3
1440 (centered/ 123 -10) @result{} -12 and 3
1441 (centered/ -123 10) @result{} -12 and -3
1442 (centered/ -123 -10) @result{} 12 and -3
1443 (centered/ 125 10) @result{} 13 and -5
1444 (centered/ 127 10) @result{} 13 and -3
1445 (centered/ 135 10) @result{} 14 and -5
1446 (centered/ -123.2 -63.5) @result{} 2.0 and 3.8
1447 (centered/ 16/3 -10/7) @result{} -4 and -8/21
1451 @deftypefn {Scheme Procedure} {} round/ @var{x} @var{y}
1452 @deftypefnx {Scheme Procedure} {} round-quotient @var{x} @var{y}
1453 @deftypefnx {Scheme Procedure} {} round-remainder @var{x} @var{y}
1454 @deftypefnx {C Function} void scm_round_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1455 @deftypefnx {C Function} SCM scm_round_quotient (@var{x}, @var{y})
1456 @deftypefnx {C Function} SCM scm_round_remainder (@var{x}, @var{y})
1457 These procedures accept two real numbers @var{x} and @var{y}, where the
1458 divisor @var{y} must be non-zero. @code{round-quotient} returns the
1459 integer @var{q} and @code{round-remainder} returns the real number
1460 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
1461 @var{q} is @math{@var{x}/@var{y}} rounded to the nearest integer,
1462 with ties going to the nearest even integer. @code{round/}
1463 returns both @var{q} and @var{r}, and is more efficient than computing
1466 Note that @code{round/} and @code{centered/} are almost equivalent, but
1467 their behavior differs when @math{@var{x}/@var{y}} lies exactly half-way
1468 between two integers. In this case, @code{round/} chooses the nearest
1469 even integer, whereas @code{centered/} chooses in such a way to satisfy
1470 the constraint @math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}, which
1471 is stronger than the corresponding constraint for @code{round/},
1472 @math{-|@var{y}/2| <= @var{r} <= |@var{y}/2|}. In particular,
1473 when @var{x} and @var{y} are integers, the number of possible remainders
1474 returned by @code{centered/} is @math{|@var{y}|}, whereas the number of
1475 possible remainders returned by @code{round/} is @math{|@var{y}|+1} when
1479 (round-quotient 123 10) @result{} 12
1480 (round-remainder 123 10) @result{} 3
1481 (round/ 123 10) @result{} 12 and 3
1482 (round/ 123 -10) @result{} -12 and 3
1483 (round/ -123 10) @result{} -12 and -3
1484 (round/ -123 -10) @result{} 12 and -3
1485 (round/ 125 10) @result{} 12 and 5
1486 (round/ 127 10) @result{} 13 and -3
1487 (round/ 135 10) @result{} 14 and -5
1488 (round/ -123.2 -63.5) @result{} 2.0 and 3.8
1489 (round/ 16/3 -10/7) @result{} -4 and -8/21
1494 @subsubsection Scientific Functions
1496 The following procedures accept any kind of number as arguments,
1497 including complex numbers.
1500 @c begin (texi-doc-string "guile" "sqrt")
1501 @deffn {Scheme Procedure} sqrt z
1502 Return the square root of @var{z}. Of the two possible roots
1503 (positive and negative), the one with a positive real part is
1504 returned, or if that's zero then a positive imaginary part. Thus,
1507 (sqrt 9.0) @result{} 3.0
1508 (sqrt -9.0) @result{} 0.0+3.0i
1509 (sqrt 1.0+1.0i) @result{} 1.09868411346781+0.455089860562227i
1510 (sqrt -1.0-1.0i) @result{} 0.455089860562227-1.09868411346781i
1515 @c begin (texi-doc-string "guile" "expt")
1516 @deffn {Scheme Procedure} expt z1 z2
1517 Return @var{z1} raised to the power of @var{z2}.
1521 @c begin (texi-doc-string "guile" "sin")
1522 @deffn {Scheme Procedure} sin z
1523 Return the sine of @var{z}.
1527 @c begin (texi-doc-string "guile" "cos")
1528 @deffn {Scheme Procedure} cos z
1529 Return the cosine of @var{z}.
1533 @c begin (texi-doc-string "guile" "tan")
1534 @deffn {Scheme Procedure} tan z
1535 Return the tangent of @var{z}.
1539 @c begin (texi-doc-string "guile" "asin")
1540 @deffn {Scheme Procedure} asin z
1541 Return the arcsine of @var{z}.
1545 @c begin (texi-doc-string "guile" "acos")
1546 @deffn {Scheme Procedure} acos z
1547 Return the arccosine of @var{z}.
1551 @c begin (texi-doc-string "guile" "atan")
1552 @deffn {Scheme Procedure} atan z
1553 @deffnx {Scheme Procedure} atan y x
1554 Return the arctangent of @var{z}, or of @math{@var{y}/@var{x}}.
1558 @c begin (texi-doc-string "guile" "exp")
1559 @deffn {Scheme Procedure} exp z
1560 Return e to the power of @var{z}, where e is the base of natural
1561 logarithms (2.71828@dots{}).
1565 @c begin (texi-doc-string "guile" "log")
1566 @deffn {Scheme Procedure} log z
1567 Return the natural logarithm of @var{z}.
1570 @c begin (texi-doc-string "guile" "log10")
1571 @deffn {Scheme Procedure} log10 z
1572 Return the base 10 logarithm of @var{z}.
1575 @c begin (texi-doc-string "guile" "sinh")
1576 @deffn {Scheme Procedure} sinh z
1577 Return the hyperbolic sine of @var{z}.
1580 @c begin (texi-doc-string "guile" "cosh")
1581 @deffn {Scheme Procedure} cosh z
1582 Return the hyperbolic cosine of @var{z}.
1585 @c begin (texi-doc-string "guile" "tanh")
1586 @deffn {Scheme Procedure} tanh z
1587 Return the hyperbolic tangent of @var{z}.
1590 @c begin (texi-doc-string "guile" "asinh")
1591 @deffn {Scheme Procedure} asinh z
1592 Return the hyperbolic arcsine of @var{z}.
1595 @c begin (texi-doc-string "guile" "acosh")
1596 @deffn {Scheme Procedure} acosh z
1597 Return the hyperbolic arccosine of @var{z}.
1600 @c begin (texi-doc-string "guile" "atanh")
1601 @deffn {Scheme Procedure} atanh z
1602 Return the hyperbolic arctangent of @var{z}.
1606 @node Bitwise Operations
1607 @subsubsection Bitwise Operations
1609 For the following bitwise functions, negative numbers are treated as
1610 infinite precision twos-complements. For instance @math{-6} is bits
1611 @math{@dots{}111010}, with infinitely many ones on the left. It can
1612 be seen that adding 6 (binary 110) to such a bit pattern gives all
1615 @deffn {Scheme Procedure} logand n1 n2 @dots{}
1616 @deffnx {C Function} scm_logand (n1, n2)
1617 Return the bitwise @sc{and} of the integer arguments.
1620 (logand) @result{} -1
1621 (logand 7) @result{} 7
1622 (logand #b111 #b011 #b001) @result{} 1
1626 @deffn {Scheme Procedure} logior n1 n2 @dots{}
1627 @deffnx {C Function} scm_logior (n1, n2)
1628 Return the bitwise @sc{or} of the integer arguments.
1631 (logior) @result{} 0
1632 (logior 7) @result{} 7
1633 (logior #b000 #b001 #b011) @result{} 3
1637 @deffn {Scheme Procedure} logxor n1 n2 @dots{}
1638 @deffnx {C Function} scm_loxor (n1, n2)
1639 Return the bitwise @sc{xor} of the integer arguments. A bit is
1640 set in the result if it is set in an odd number of arguments.
1643 (logxor) @result{} 0
1644 (logxor 7) @result{} 7
1645 (logxor #b000 #b001 #b011) @result{} 2
1646 (logxor #b000 #b001 #b011 #b011) @result{} 1
1650 @deffn {Scheme Procedure} lognot n
1651 @deffnx {C Function} scm_lognot (n)
1652 Return the integer which is the ones-complement of the integer
1653 argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
1656 (number->string (lognot #b10000000) 2)
1657 @result{} "-10000001"
1658 (number->string (lognot #b0) 2)
1663 @deffn {Scheme Procedure} logtest j k
1664 @deffnx {C Function} scm_logtest (j, k)
1665 Test whether @var{j} and @var{k} have any 1 bits in common. This is
1666 equivalent to @code{(not (zero? (logand j k)))}, but without actually
1667 calculating the @code{logand}, just testing for non-zero.
1670 (logtest #b0100 #b1011) @result{} #f
1671 (logtest #b0100 #b0111) @result{} #t
1675 @deffn {Scheme Procedure} logbit? index j
1676 @deffnx {C Function} scm_logbit_p (index, j)
1677 Test whether bit number @var{index} in @var{j} is set. @var{index}
1678 starts from 0 for the least significant bit.
1681 (logbit? 0 #b1101) @result{} #t
1682 (logbit? 1 #b1101) @result{} #f
1683 (logbit? 2 #b1101) @result{} #t
1684 (logbit? 3 #b1101) @result{} #t
1685 (logbit? 4 #b1101) @result{} #f
1689 @deffn {Scheme Procedure} ash n cnt
1690 @deffnx {C Function} scm_ash (n, cnt)
1691 Return @var{n} shifted left by @var{cnt} bits, or shifted right if
1692 @var{cnt} is negative. This is an ``arithmetic'' shift.
1694 This is effectively a multiplication by @m{2^{cnt}, 2^@var{cnt}}, and
1695 when @var{cnt} is negative it's a division, rounded towards negative
1696 infinity. (Note that this is not the same rounding as @code{quotient}
1699 With @var{n} viewed as an infinite precision twos complement,
1700 @code{ash} means a left shift introducing zero bits, or a right shift
1704 (number->string (ash #b1 3) 2) @result{} "1000"
1705 (number->string (ash #b1010 -1) 2) @result{} "101"
1707 ;; -23 is bits ...11101001, -6 is bits ...111010
1708 (ash -23 -2) @result{} -6
1712 @deffn {Scheme Procedure} logcount n
1713 @deffnx {C Function} scm_logcount (n)
1714 Return the number of bits in integer @var{n}. If @var{n} is
1715 positive, the 1-bits in its binary representation are counted.
1716 If negative, the 0-bits in its two's-complement binary
1717 representation are counted. If zero, 0 is returned.
1720 (logcount #b10101010)
1729 @deffn {Scheme Procedure} integer-length n
1730 @deffnx {C Function} scm_integer_length (n)
1731 Return the number of bits necessary to represent @var{n}.
1733 For positive @var{n} this is how many bits to the most significant one
1734 bit. For negative @var{n} it's how many bits to the most significant
1735 zero bit in twos complement form.
1738 (integer-length #b10101010) @result{} 8
1739 (integer-length #b1111) @result{} 4
1740 (integer-length 0) @result{} 0
1741 (integer-length -1) @result{} 0
1742 (integer-length -256) @result{} 8
1743 (integer-length -257) @result{} 9
1747 @deffn {Scheme Procedure} integer-expt n k
1748 @deffnx {C Function} scm_integer_expt (n, k)
1749 Return @var{n} raised to the power @var{k}. @var{k} must be an exact
1750 integer, @var{n} can be any number.
1752 Negative @var{k} is supported, and results in @m{1/n^|k|, 1/n^abs(k)}
1753 in the usual way. @math{@var{n}^0} is 1, as usual, and that includes
1757 (integer-expt 2 5) @result{} 32
1758 (integer-expt -3 3) @result{} -27
1759 (integer-expt 5 -3) @result{} 1/125
1760 (integer-expt 0 0) @result{} 1
1764 @deffn {Scheme Procedure} bit-extract n start end
1765 @deffnx {C Function} scm_bit_extract (n, start, end)
1766 Return the integer composed of the @var{start} (inclusive)
1767 through @var{end} (exclusive) bits of @var{n}. The
1768 @var{start}th bit becomes the 0-th bit in the result.
1771 (number->string (bit-extract #b1101101010 0 4) 2)
1773 (number->string (bit-extract #b1101101010 4 9) 2)
1780 @subsubsection Random Number Generation
1782 Pseudo-random numbers are generated from a random state object, which
1783 can be created with @code{seed->random-state} or
1784 @code{datum->random-state}. An external representation (i.e.@: one
1785 which can written with @code{write} and read with @code{read}) of a
1786 random state object can be obtained via
1787 @code{random-state->datum}. The @var{state} parameter to the
1788 various functions below is optional, it defaults to the state object
1789 in the @code{*random-state*} variable.
1791 @deffn {Scheme Procedure} copy-random-state [state]
1792 @deffnx {C Function} scm_copy_random_state (state)
1793 Return a copy of the random state @var{state}.
1796 @deffn {Scheme Procedure} random n [state]
1797 @deffnx {C Function} scm_random (n, state)
1798 Return a number in [0, @var{n}).
1800 Accepts a positive integer or real n and returns a
1801 number of the same type between zero (inclusive) and
1802 @var{n} (exclusive). The values returned have a uniform
1806 @deffn {Scheme Procedure} random:exp [state]
1807 @deffnx {C Function} scm_random_exp (state)
1808 Return an inexact real in an exponential distribution with mean
1809 1. For an exponential distribution with mean @var{u} use @code{(*
1810 @var{u} (random:exp))}.
1813 @deffn {Scheme Procedure} random:hollow-sphere! vect [state]
1814 @deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
1815 Fills @var{vect} with inexact real random numbers the sum of whose
1816 squares is equal to 1.0. Thinking of @var{vect} as coordinates in
1817 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1818 the coordinates are uniformly distributed over the surface of the unit
1822 @deffn {Scheme Procedure} random:normal [state]
1823 @deffnx {C Function} scm_random_normal (state)
1824 Return an inexact real in a normal distribution. The distribution
1825 used has mean 0 and standard deviation 1. For a normal distribution
1826 with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
1827 (* @var{d} (random:normal)))}.
1830 @deffn {Scheme Procedure} random:normal-vector! vect [state]
1831 @deffnx {C Function} scm_random_normal_vector_x (vect, state)
1832 Fills @var{vect} with inexact real random numbers that are
1833 independent and standard normally distributed
1834 (i.e., with mean 0 and variance 1).
1837 @deffn {Scheme Procedure} random:solid-sphere! vect [state]
1838 @deffnx {C Function} scm_random_solid_sphere_x (vect, state)
1839 Fills @var{vect} with inexact real random numbers the sum of whose
1840 squares is less than 1.0. Thinking of @var{vect} as coordinates in
1841 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1842 the coordinates are uniformly distributed within the unit
1844 @c FIXME: What does this mean, particularly the n-sphere part?
1847 @deffn {Scheme Procedure} random:uniform [state]
1848 @deffnx {C Function} scm_random_uniform (state)
1849 Return a uniformly distributed inexact real random number in
1853 @deffn {Scheme Procedure} seed->random-state seed
1854 @deffnx {C Function} scm_seed_to_random_state (seed)
1855 Return a new random state using @var{seed}.
1858 @deffn {Scheme Procedure} datum->random-state datum
1859 @deffnx {C Function} scm_datum_to_random_state (datum)
1860 Return a new random state from @var{datum}, which should have been
1861 obtained by @code{random-state->datum}.
1864 @deffn {Scheme Procedure} random-state->datum state
1865 @deffnx {C Function} scm_random_state_to_datum (state)
1866 Return a datum representation of @var{state} that may be written out and
1867 read back with the Scheme reader.
1870 @deffn {Scheme Procedure} random-state-from-platform
1871 @deffnx {C Function} scm_random_state_from_platform ()
1872 Construct a new random state seeded from a platform-specific source of
1873 entropy, appropriate for use in non-security-critical applications.
1874 Currently @file{/dev/urandom} is tried first, or else the seed is based
1875 on the time, date, process ID, an address from a freshly allocated heap
1876 cell, an address from the local stack frame, and a high-resolution timer
1880 @defvar *random-state*
1881 The global random state used by the above functions when the
1882 @var{state} parameter is not given.
1885 Note that the initial value of @code{*random-state*} is the same every
1886 time Guile starts up. Therefore, if you don't pass a @var{state}
1887 parameter to the above procedures, and you don't set
1888 @code{*random-state*} to @code{(seed->random-state your-seed)}, where
1889 @code{your-seed} is something that @emph{isn't} the same every time,
1890 you'll get the same sequence of ``random'' numbers on every run.
1892 For example, unless the relevant source code has changed, @code{(map
1893 random (cdr (iota 30)))}, if the first use of random numbers since
1894 Guile started up, will always give:
1897 (map random (cdr (iota 19)))
1899 (0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12)
1902 To seed the random state in a sensible way for non-security-critical
1903 applications, do this during initialization of your program:
1906 (set! *random-state* (random-state-from-platform))
1911 @subsection Characters
1914 In Scheme, there is a data type to describe a single character.
1916 Defining what exactly a character @emph{is} can be more complicated
1917 than it seems. Guile follows the advice of R6RS and uses The Unicode
1918 Standard to help define what a character is. So, for Guile, a
1919 character is anything in the Unicode Character Database.
1922 @cindex Unicode code point
1924 The Unicode Character Database is basically a table of characters
1925 indexed using integers called 'code points'. Valid code points are in
1926 the ranges 0 to @code{#xD7FF} inclusive or @code{#xE000} to
1927 @code{#x10FFFF} inclusive, which is about 1.1 million code points.
1929 @cindex designated code point
1930 @cindex code point, designated
1932 Any code point that has been assigned to a character or that has
1933 otherwise been given a meaning by Unicode is called a 'designated code
1934 point'. Most of the designated code points, about 200,000 of them,
1935 indicate characters, accents or other combining marks that modify
1936 other characters, symbols, whitespace, and control characters. Some
1937 are not characters but indicators that suggest how to format or
1938 display neighboring characters.
1940 @cindex reserved code point
1941 @cindex code point, reserved
1943 If a code point is not a designated code point -- if it has not been
1944 assigned to a character by The Unicode Standard -- it is a 'reserved
1945 code point', meaning that they are reserved for future use. Most of
1946 the code points, about 800,000, are 'reserved code points'.
1948 By convention, a Unicode code point is written as
1949 ``U+XXXX'' where ``XXXX'' is a hexadecimal number. Please note that
1950 this convenient notation is not valid code. Guile does not interpret
1951 ``U+XXXX'' as a character.
1953 In Scheme, a character literal is written as @code{#\@var{name}} where
1954 @var{name} is the name of the character that you want. Printable
1955 characters have their usual single character name; for example,
1956 @code{#\a} is a lower case @code{a}.
1958 Some of the code points are 'combining characters' that are not meant
1959 to be printed by themselves but are instead meant to modify the
1960 appearance of the previous character. For combining characters, an
1961 alternate form of the character literal is @code{#\} followed by
1962 U+25CC (a small, dotted circle), followed by the combining character.
1963 This allows the combining character to be drawn on the circle, not on
1964 the backslash of @code{#\}.
1966 Many of the non-printing characters, such as whitespace characters and
1967 control characters, also have names.
1969 The most commonly used non-printing characters have long character
1970 names, described in the table below.
1972 @multitable {@code{#\backspace}} {Preferred}
1973 @item Character Name @tab Codepoint
1974 @item @code{#\nul} @tab U+0000
1975 @item @code{#\alarm} @tab u+0007
1976 @item @code{#\backspace} @tab U+0008
1977 @item @code{#\tab} @tab U+0009
1978 @item @code{#\linefeed} @tab U+000A
1979 @item @code{#\newline} @tab U+000A
1980 @item @code{#\vtab} @tab U+000B
1981 @item @code{#\page} @tab U+000C
1982 @item @code{#\return} @tab U+000D
1983 @item @code{#\esc} @tab U+001B
1984 @item @code{#\space} @tab U+0020
1985 @item @code{#\delete} @tab U+007F
1988 There are also short names for all of the ``C0 control characters''
1989 (those with code points below 32). The following table lists the short
1990 name for each character.
1992 @multitable @columnfractions .25 .25 .25 .25
1993 @item 0 = @code{#\nul}
1994 @tab 1 = @code{#\soh}
1995 @tab 2 = @code{#\stx}
1996 @tab 3 = @code{#\etx}
1997 @item 4 = @code{#\eot}
1998 @tab 5 = @code{#\enq}
1999 @tab 6 = @code{#\ack}
2000 @tab 7 = @code{#\bel}
2001 @item 8 = @code{#\bs}
2002 @tab 9 = @code{#\ht}
2003 @tab 10 = @code{#\lf}
2004 @tab 11 = @code{#\vt}
2005 @item 12 = @code{#\ff}
2006 @tab 13 = @code{#\cr}
2007 @tab 14 = @code{#\so}
2008 @tab 15 = @code{#\si}
2009 @item 16 = @code{#\dle}
2010 @tab 17 = @code{#\dc1}
2011 @tab 18 = @code{#\dc2}
2012 @tab 19 = @code{#\dc3}
2013 @item 20 = @code{#\dc4}
2014 @tab 21 = @code{#\nak}
2015 @tab 22 = @code{#\syn}
2016 @tab 23 = @code{#\etb}
2017 @item 24 = @code{#\can}
2018 @tab 25 = @code{#\em}
2019 @tab 26 = @code{#\sub}
2020 @tab 27 = @code{#\esc}
2021 @item 28 = @code{#\fs}
2022 @tab 29 = @code{#\gs}
2023 @tab 30 = @code{#\rs}
2024 @tab 31 = @code{#\us}
2025 @item 32 = @code{#\sp}
2028 The short name for the ``delete'' character (code point U+007F) is
2031 There are also a few alternative names left over for compatibility with
2032 previous versions of Guile.
2034 @multitable {@code{#\backspace}} {Preferred}
2035 @item Alternate @tab Standard
2036 @item @code{#\nl} @tab @code{#\newline}
2037 @item @code{#\np} @tab @code{#\page}
2038 @item @code{#\null} @tab @code{#\nul}
2041 Characters may also be written using their code point values. They can
2042 be written with as an octal number, such as @code{#\10} for
2043 @code{#\bs} or @code{#\177} for @code{#\del}.
2045 If one prefers hex to octal, there is an additional syntax for character
2046 escapes: @code{#\xHHHH} -- the letter 'x' followed by a hexadecimal
2047 number of one to eight digits.
2050 @deffn {Scheme Procedure} char? x
2051 @deffnx {C Function} scm_char_p (x)
2052 Return @code{#t} iff @var{x} is a character, else @code{#f}.
2055 Fundamentally, the character comparison operations below are
2056 numeric comparisons of the character's code points.
2059 @deffn {Scheme Procedure} char=? x y
2060 Return @code{#t} iff code point of @var{x} is equal to the code point
2061 of @var{y}, else @code{#f}.
2065 @deffn {Scheme Procedure} char<? x y
2066 Return @code{#t} iff the code point of @var{x} is less than the code
2067 point of @var{y}, else @code{#f}.
2071 @deffn {Scheme Procedure} char<=? x y
2072 Return @code{#t} iff the code point of @var{x} is less than or equal
2073 to the code point of @var{y}, else @code{#f}.
2077 @deffn {Scheme Procedure} char>? x y
2078 Return @code{#t} iff the code point of @var{x} is greater than the
2079 code point of @var{y}, else @code{#f}.
2083 @deffn {Scheme Procedure} char>=? x y
2084 Return @code{#t} iff the code point of @var{x} is greater than or
2085 equal to the code point of @var{y}, else @code{#f}.
2088 @cindex case folding
2090 Case-insensitive character comparisons use @emph{Unicode case
2091 folding}. In case folding comparisons, if a character is lowercase
2092 and has an uppercase form that can be expressed as a single character,
2093 it is converted to uppercase before comparison. All other characters
2094 undergo no conversion before the comparison occurs. This includes the
2095 German sharp S (Eszett) which is not uppercased before conversion
2096 because its uppercase form has two characters. Unicode case folding
2097 is language independent: it uses rules that are generally true, but,
2098 it cannot cover all cases for all languages.
2101 @deffn {Scheme Procedure} char-ci=? x y
2102 Return @code{#t} iff the case-folded code point of @var{x} is the same
2103 as the case-folded code point of @var{y}, else @code{#f}.
2107 @deffn {Scheme Procedure} char-ci<? x y
2108 Return @code{#t} iff the case-folded code point of @var{x} is less
2109 than the case-folded code point of @var{y}, else @code{#f}.
2113 @deffn {Scheme Procedure} char-ci<=? x y
2114 Return @code{#t} iff the case-folded code point of @var{x} is less
2115 than or equal to the case-folded code point of @var{y}, else
2120 @deffn {Scheme Procedure} char-ci>? x y
2121 Return @code{#t} iff the case-folded code point of @var{x} is greater
2122 than the case-folded code point of @var{y}, else @code{#f}.
2126 @deffn {Scheme Procedure} char-ci>=? x y
2127 Return @code{#t} iff the case-folded code point of @var{x} is greater
2128 than or equal to the case-folded code point of @var{y}, else
2132 @rnindex char-alphabetic?
2133 @deffn {Scheme Procedure} char-alphabetic? chr
2134 @deffnx {C Function} scm_char_alphabetic_p (chr)
2135 Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
2138 @rnindex char-numeric?
2139 @deffn {Scheme Procedure} char-numeric? chr
2140 @deffnx {C Function} scm_char_numeric_p (chr)
2141 Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
2144 @rnindex char-whitespace?
2145 @deffn {Scheme Procedure} char-whitespace? chr
2146 @deffnx {C Function} scm_char_whitespace_p (chr)
2147 Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
2150 @rnindex char-upper-case?
2151 @deffn {Scheme Procedure} char-upper-case? chr
2152 @deffnx {C Function} scm_char_upper_case_p (chr)
2153 Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
2156 @rnindex char-lower-case?
2157 @deffn {Scheme Procedure} char-lower-case? chr
2158 @deffnx {C Function} scm_char_lower_case_p (chr)
2159 Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
2162 @deffn {Scheme Procedure} char-is-both? chr
2163 @deffnx {C Function} scm_char_is_both_p (chr)
2164 Return @code{#t} iff @var{chr} is either uppercase or lowercase, else
2168 @deffn {Scheme Procedure} char-general-category chr
2169 @deffnx {C Function} scm_char_general_category (chr)
2170 Return a symbol giving the two-letter name of the Unicode general
2171 category assigned to @var{chr} or @code{#f} if no named category is
2172 assigned. The following table provides a list of category names along
2173 with their meanings.
2175 @multitable @columnfractions .1 .4 .1 .4
2177 @tab Uppercase letter
2179 @tab Final quote punctuation
2181 @tab Lowercase letter
2183 @tab Other punctuation
2185 @tab Titlecase letter
2189 @tab Modifier letter
2191 @tab Currency symbol
2195 @tab Modifier symbol
2197 @tab Non-spacing mark
2201 @tab Combining spacing mark
2203 @tab Space separator
2209 @tab Decimal digit number
2211 @tab Paragraph separator
2221 @tab Connector punctuation
2225 @tab Dash punctuation
2229 @tab Open punctuation
2233 @tab Close punctuation
2237 @tab Initial quote punctuation
2243 @rnindex char->integer
2244 @deffn {Scheme Procedure} char->integer chr
2245 @deffnx {C Function} scm_char_to_integer (chr)
2246 Return the code point of @var{chr}.
2249 @rnindex integer->char
2250 @deffn {Scheme Procedure} integer->char n
2251 @deffnx {C Function} scm_integer_to_char (n)
2252 Return the character that has code point @var{n}. The integer @var{n}
2253 must be a valid code point. Valid code points are in the ranges 0 to
2254 @code{#xD7FF} inclusive or @code{#xE000} to @code{#x10FFFF} inclusive.
2257 @rnindex char-upcase
2258 @deffn {Scheme Procedure} char-upcase chr
2259 @deffnx {C Function} scm_char_upcase (chr)
2260 Return the uppercase character version of @var{chr}.
2263 @rnindex char-downcase
2264 @deffn {Scheme Procedure} char-downcase chr
2265 @deffnx {C Function} scm_char_downcase (chr)
2266 Return the lowercase character version of @var{chr}.
2269 @rnindex char-titlecase
2270 @deffn {Scheme Procedure} char-titlecase chr
2271 @deffnx {C Function} scm_char_titlecase (chr)
2272 Return the titlecase character version of @var{chr} if one exists;
2273 otherwise return the uppercase version.
2275 For most characters these will be the same, but the Unicode Standard
2276 includes certain digraph compatibility characters, such as @code{U+01F3}
2277 ``dz'', for which the uppercase and titlecase characters are different
2278 (@code{U+01F1} ``DZ'' and @code{U+01F2} ``Dz'' in this case,
2283 @deftypefn {C Function} scm_t_wchar scm_c_upcase (scm_t_wchar @var{c})
2284 @deftypefnx {C Function} scm_t_wchar scm_c_downcase (scm_t_wchar @var{c})
2285 @deftypefnx {C Function} scm_t_wchar scm_c_titlecase (scm_t_wchar @var{c})
2287 These C functions take an integer representation of a Unicode
2288 codepoint and return the codepoint corresponding to its uppercase,
2289 lowercase, and titlecase forms respectively. The type
2290 @code{scm_t_wchar} is a signed, 32-bit integer.
2293 @node Character Sets
2294 @subsection Character Sets
2296 The features described in this section correspond directly to SRFI-14.
2298 The data type @dfn{charset} implements sets of characters
2299 (@pxref{Characters}). Because the internal representation of
2300 character sets is not visible to the user, a lot of procedures for
2301 handling them are provided.
2303 Character sets can be created, extended, tested for the membership of a
2304 characters and be compared to other character sets.
2307 * Character Set Predicates/Comparison::
2308 * Iterating Over Character Sets:: Enumerate charset elements.
2309 * Creating Character Sets:: Making new charsets.
2310 * Querying Character Sets:: Test charsets for membership etc.
2311 * Character-Set Algebra:: Calculating new charsets.
2312 * Standard Character Sets:: Variables containing predefined charsets.
2315 @node Character Set Predicates/Comparison
2316 @subsubsection Character Set Predicates/Comparison
2318 Use these procedures for testing whether an object is a character set,
2319 or whether several character sets are equal or subsets of each other.
2320 @code{char-set-hash} can be used for calculating a hash value, maybe for
2321 usage in fast lookup procedures.
2323 @deffn {Scheme Procedure} char-set? obj
2324 @deffnx {C Function} scm_char_set_p (obj)
2325 Return @code{#t} if @var{obj} is a character set, @code{#f}
2329 @deffn {Scheme Procedure} char-set= char_set @dots{}
2330 @deffnx {C Function} scm_char_set_eq (char_sets)
2331 Return @code{#t} if all given character sets are equal.
2334 @deffn {Scheme Procedure} char-set<= char_set @dots{}
2335 @deffnx {C Function} scm_char_set_leq (char_sets)
2336 Return @code{#t} if every character set @var{char_set}i is a subset
2337 of character set @var{char_set}i+1.
2340 @deffn {Scheme Procedure} char-set-hash cs [bound]
2341 @deffnx {C Function} scm_char_set_hash (cs, bound)
2342 Compute a hash value for the character set @var{cs}. If
2343 @var{bound} is given and non-zero, it restricts the
2344 returned value to the range 0 @dots{} @var{bound} - 1.
2347 @c ===================================================================
2349 @node Iterating Over Character Sets
2350 @subsubsection Iterating Over Character Sets
2352 Character set cursors are a means for iterating over the members of a
2353 character sets. After creating a character set cursor with
2354 @code{char-set-cursor}, a cursor can be dereferenced with
2355 @code{char-set-ref}, advanced to the next member with
2356 @code{char-set-cursor-next}. Whether a cursor has passed past the last
2357 element of the set can be checked with @code{end-of-char-set?}.
2359 Additionally, mapping and (un-)folding procedures for character sets are
2362 @deffn {Scheme Procedure} char-set-cursor cs
2363 @deffnx {C Function} scm_char_set_cursor (cs)
2364 Return a cursor into the character set @var{cs}.
2367 @deffn {Scheme Procedure} char-set-ref cs cursor
2368 @deffnx {C Function} scm_char_set_ref (cs, cursor)
2369 Return the character at the current cursor position
2370 @var{cursor} in the character set @var{cs}. It is an error to
2371 pass a cursor for which @code{end-of-char-set?} returns true.
2374 @deffn {Scheme Procedure} char-set-cursor-next cs cursor
2375 @deffnx {C Function} scm_char_set_cursor_next (cs, cursor)
2376 Advance the character set cursor @var{cursor} to the next
2377 character in the character set @var{cs}. It is an error if the
2378 cursor given satisfies @code{end-of-char-set?}.
2381 @deffn {Scheme Procedure} end-of-char-set? cursor
2382 @deffnx {C Function} scm_end_of_char_set_p (cursor)
2383 Return @code{#t} if @var{cursor} has reached the end of a
2384 character set, @code{#f} otherwise.
2387 @deffn {Scheme Procedure} char-set-fold kons knil cs
2388 @deffnx {C Function} scm_char_set_fold (kons, knil, cs)
2389 Fold the procedure @var{kons} over the character set @var{cs},
2390 initializing it with @var{knil}.
2393 @deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
2394 @deffnx {C Function} scm_char_set_unfold (p, f, g, seed, base_cs)
2395 This is a fundamental constructor for character sets.
2397 @item @var{g} is used to generate a series of ``seed'' values
2398 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2399 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2400 @item @var{p} tells us when to stop -- when it returns true
2401 when applied to one of the seed values.
2402 @item @var{f} maps each seed value to a character. These
2403 characters are added to the base character set @var{base_cs} to
2404 form the result; @var{base_cs} defaults to the empty set.
2408 @deffn {Scheme Procedure} char-set-unfold! p f g seed base_cs
2409 @deffnx {C Function} scm_char_set_unfold_x (p, f, g, seed, base_cs)
2410 This is a fundamental constructor for character sets.
2412 @item @var{g} is used to generate a series of ``seed'' values
2413 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2414 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2415 @item @var{p} tells us when to stop -- when it returns true
2416 when applied to one of the seed values.
2417 @item @var{f} maps each seed value to a character. These
2418 characters are added to the base character set @var{base_cs} to
2419 form the result; @var{base_cs} defaults to the empty set.
2423 @deffn {Scheme Procedure} char-set-for-each proc cs
2424 @deffnx {C Function} scm_char_set_for_each (proc, cs)
2425 Apply @var{proc} to every character in the character set
2426 @var{cs}. The return value is not specified.
2429 @deffn {Scheme Procedure} char-set-map proc cs
2430 @deffnx {C Function} scm_char_set_map (proc, cs)
2431 Map the procedure @var{proc} over every character in @var{cs}.
2432 @var{proc} must be a character -> character procedure.
2435 @c ===================================================================
2437 @node Creating Character Sets
2438 @subsubsection Creating Character Sets
2440 New character sets are produced with these procedures.
2442 @deffn {Scheme Procedure} char-set-copy cs
2443 @deffnx {C Function} scm_char_set_copy (cs)
2444 Return a newly allocated character set containing all
2445 characters in @var{cs}.
2448 @deffn {Scheme Procedure} char-set chr @dots{}
2449 @deffnx {C Function} scm_char_set (chrs)
2450 Return a character set containing all given characters.
2453 @deffn {Scheme Procedure} list->char-set list [base_cs]
2454 @deffnx {C Function} scm_list_to_char_set (list, base_cs)
2455 Convert the character list @var{list} to a character set. If
2456 the character set @var{base_cs} is given, the character in this
2457 set are also included in the result.
2460 @deffn {Scheme Procedure} list->char-set! list base_cs
2461 @deffnx {C Function} scm_list_to_char_set_x (list, base_cs)
2462 Convert the character list @var{list} to a character set. The
2463 characters are added to @var{base_cs} and @var{base_cs} is
2467 @deffn {Scheme Procedure} string->char-set str [base_cs]
2468 @deffnx {C Function} scm_string_to_char_set (str, base_cs)
2469 Convert the string @var{str} to a character set. If the
2470 character set @var{base_cs} is given, the characters in this
2471 set are also included in the result.
2474 @deffn {Scheme Procedure} string->char-set! str base_cs
2475 @deffnx {C Function} scm_string_to_char_set_x (str, base_cs)
2476 Convert the string @var{str} to a character set. The
2477 characters from the string are added to @var{base_cs}, and
2478 @var{base_cs} is returned.
2481 @deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
2482 @deffnx {C Function} scm_char_set_filter (pred, cs, base_cs)
2483 Return a character set containing every character from @var{cs}
2484 so that it satisfies @var{pred}. If provided, the characters
2485 from @var{base_cs} are added to the result.
2488 @deffn {Scheme Procedure} char-set-filter! pred cs base_cs
2489 @deffnx {C Function} scm_char_set_filter_x (pred, cs, base_cs)
2490 Return a character set containing every character from @var{cs}
2491 so that it satisfies @var{pred}. The characters are added to
2492 @var{base_cs} and @var{base_cs} is returned.
2495 @deffn {Scheme Procedure} ucs-range->char-set lower upper [error [base_cs]]
2496 @deffnx {C Function} scm_ucs_range_to_char_set (lower, upper, error, base_cs)
2497 Return a character set containing all characters whose
2498 character codes lie in the half-open range
2499 [@var{lower},@var{upper}).
2501 If @var{error} is a true value, an error is signalled if the
2502 specified range contains characters which are not contained in
2503 the implemented character range. If @var{error} is @code{#f},
2504 these characters are silently left out of the resulting
2507 The characters in @var{base_cs} are added to the result, if
2511 @deffn {Scheme Procedure} ucs-range->char-set! lower upper error base_cs
2512 @deffnx {C Function} scm_ucs_range_to_char_set_x (lower, upper, error, base_cs)
2513 Return a character set containing all characters whose
2514 character codes lie in the half-open range
2515 [@var{lower},@var{upper}).
2517 If @var{error} is a true value, an error is signalled if the
2518 specified range contains characters which are not contained in
2519 the implemented character range. If @var{error} is @code{#f},
2520 these characters are silently left out of the resulting
2523 The characters are added to @var{base_cs} and @var{base_cs} is
2527 @deffn {Scheme Procedure} ->char-set x
2528 @deffnx {C Function} scm_to_char_set (x)
2529 Coerces x into a char-set. @var{x} may be a string, character or
2530 char-set. A string is converted to the set of its constituent
2531 characters; a character is converted to a singleton set; a char-set is
2535 @c ===================================================================
2537 @node Querying Character Sets
2538 @subsubsection Querying Character Sets
2540 Access the elements and other information of a character set with these
2543 @deffn {Scheme Procedure} %char-set-dump cs
2544 Returns an association list containing debugging information
2545 for @var{cs}. The association list has the following entries.
2550 The number of groups of contiguous code points the char-set
2553 A list of lists where each sublist is a range of code points
2554 and their associated characters
2556 The return value of this function cannot be relied upon to be
2557 consistent between versions of Guile and should not be used in code.
2560 @deffn {Scheme Procedure} char-set-size cs
2561 @deffnx {C Function} scm_char_set_size (cs)
2562 Return the number of elements in character set @var{cs}.
2565 @deffn {Scheme Procedure} char-set-count pred cs
2566 @deffnx {C Function} scm_char_set_count (pred, cs)
2567 Return the number of the elements int the character set
2568 @var{cs} which satisfy the predicate @var{pred}.
2571 @deffn {Scheme Procedure} char-set->list cs
2572 @deffnx {C Function} scm_char_set_to_list (cs)
2573 Return a list containing the elements of the character set
2577 @deffn {Scheme Procedure} char-set->string cs
2578 @deffnx {C Function} scm_char_set_to_string (cs)
2579 Return a string containing the elements of the character set
2580 @var{cs}. The order in which the characters are placed in the
2581 string is not defined.
2584 @deffn {Scheme Procedure} char-set-contains? cs ch
2585 @deffnx {C Function} scm_char_set_contains_p (cs, ch)
2586 Return @code{#t} iff the character @var{ch} is contained in the
2587 character set @var{cs}.
2590 @deffn {Scheme Procedure} char-set-every pred cs
2591 @deffnx {C Function} scm_char_set_every (pred, cs)
2592 Return a true value if every character in the character set
2593 @var{cs} satisfies the predicate @var{pred}.
2596 @deffn {Scheme Procedure} char-set-any pred cs
2597 @deffnx {C Function} scm_char_set_any (pred, cs)
2598 Return a true value if any character in the character set
2599 @var{cs} satisfies the predicate @var{pred}.
2602 @c ===================================================================
2604 @node Character-Set Algebra
2605 @subsubsection Character-Set Algebra
2607 Character sets can be manipulated with the common set algebra operation,
2608 such as union, complement, intersection etc. All of these procedures
2609 provide side-effecting variants, which modify their character set
2612 @deffn {Scheme Procedure} char-set-adjoin cs chr @dots{}
2613 @deffnx {C Function} scm_char_set_adjoin (cs, chrs)
2614 Add all character arguments to the first argument, which must
2618 @deffn {Scheme Procedure} char-set-delete cs chr @dots{}
2619 @deffnx {C Function} scm_char_set_delete (cs, chrs)
2620 Delete all character arguments from the first argument, which
2621 must be a character set.
2624 @deffn {Scheme Procedure} char-set-adjoin! cs chr @dots{}
2625 @deffnx {C Function} scm_char_set_adjoin_x (cs, chrs)
2626 Add all character arguments to the first argument, which must
2630 @deffn {Scheme Procedure} char-set-delete! cs chr @dots{}
2631 @deffnx {C Function} scm_char_set_delete_x (cs, chrs)
2632 Delete all character arguments from the first argument, which
2633 must be a character set.
2636 @deffn {Scheme Procedure} char-set-complement cs
2637 @deffnx {C Function} scm_char_set_complement (cs)
2638 Return the complement of the character set @var{cs}.
2641 Note that the complement of a character set is likely to contain many
2642 reserved code points (code points that are not associated with
2643 characters). It may be helpful to modify the output of
2644 @code{char-set-complement} by computing its intersection with the set
2645 of designated code points, @code{char-set:designated}.
2647 @deffn {Scheme Procedure} char-set-union cs @dots{}
2648 @deffnx {C Function} scm_char_set_union (char_sets)
2649 Return the union of all argument character sets.
2652 @deffn {Scheme Procedure} char-set-intersection cs @dots{}
2653 @deffnx {C Function} scm_char_set_intersection (char_sets)
2654 Return the intersection of all argument character sets.
2657 @deffn {Scheme Procedure} char-set-difference cs1 cs @dots{}
2658 @deffnx {C Function} scm_char_set_difference (cs1, char_sets)
2659 Return the difference of all argument character sets.
2662 @deffn {Scheme Procedure} char-set-xor cs @dots{}
2663 @deffnx {C Function} scm_char_set_xor (char_sets)
2664 Return the exclusive-or of all argument character sets.
2667 @deffn {Scheme Procedure} char-set-diff+intersection cs1 cs @dots{}
2668 @deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, char_sets)
2669 Return the difference and the intersection of all argument
2673 @deffn {Scheme Procedure} char-set-complement! cs
2674 @deffnx {C Function} scm_char_set_complement_x (cs)
2675 Return the complement of the character set @var{cs}.
2678 @deffn {Scheme Procedure} char-set-union! cs1 cs @dots{}
2679 @deffnx {C Function} scm_char_set_union_x (cs1, char_sets)
2680 Return the union of all argument character sets.
2683 @deffn {Scheme Procedure} char-set-intersection! cs1 cs @dots{}
2684 @deffnx {C Function} scm_char_set_intersection_x (cs1, char_sets)
2685 Return the intersection of all argument character sets.
2688 @deffn {Scheme Procedure} char-set-difference! cs1 cs @dots{}
2689 @deffnx {C Function} scm_char_set_difference_x (cs1, char_sets)
2690 Return the difference of all argument character sets.
2693 @deffn {Scheme Procedure} char-set-xor! cs1 cs @dots{}
2694 @deffnx {C Function} scm_char_set_xor_x (cs1, char_sets)
2695 Return the exclusive-or of all argument character sets.
2698 @deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 cs @dots{}
2699 @deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, char_sets)
2700 Return the difference and the intersection of all argument
2704 @c ===================================================================
2706 @node Standard Character Sets
2707 @subsubsection Standard Character Sets
2709 In order to make the use of the character set data type and procedures
2710 useful, several predefined character set variables exist.
2716 These character sets are locale independent and are not recomputed
2717 upon a @code{setlocale} call. They contain characters from the whole
2718 range of Unicode code points. For instance, @code{char-set:letter}
2719 contains about 100,000 characters.
2721 @defvr {Scheme Variable} char-set:lower-case
2722 @defvrx {C Variable} scm_char_set_lower_case
2723 All lower-case characters.
2726 @defvr {Scheme Variable} char-set:upper-case
2727 @defvrx {C Variable} scm_char_set_upper_case
2728 All upper-case characters.
2731 @defvr {Scheme Variable} char-set:title-case
2732 @defvrx {C Variable} scm_char_set_title_case
2733 All single characters that function as if they were an upper-case
2734 letter followed by a lower-case letter.
2737 @defvr {Scheme Variable} char-set:letter
2738 @defvrx {C Variable} scm_char_set_letter
2739 All letters. This includes @code{char-set:lower-case},
2740 @code{char-set:upper-case}, @code{char-set:title-case}, and many
2741 letters that have no case at all. For example, Chinese and Japanese
2742 characters typically have no concept of case.
2745 @defvr {Scheme Variable} char-set:digit
2746 @defvrx {C Variable} scm_char_set_digit
2750 @defvr {Scheme Variable} char-set:letter+digit
2751 @defvrx {C Variable} scm_char_set_letter_and_digit
2752 The union of @code{char-set:letter} and @code{char-set:digit}.
2755 @defvr {Scheme Variable} char-set:graphic
2756 @defvrx {C Variable} scm_char_set_graphic
2757 All characters which would put ink on the paper.
2760 @defvr {Scheme Variable} char-set:printing
2761 @defvrx {C Variable} scm_char_set_printing
2762 The union of @code{char-set:graphic} and @code{char-set:whitespace}.
2765 @defvr {Scheme Variable} char-set:whitespace
2766 @defvrx {C Variable} scm_char_set_whitespace
2767 All whitespace characters.
2770 @defvr {Scheme Variable} char-set:blank
2771 @defvrx {C Variable} scm_char_set_blank
2772 All horizontal whitespace characters, which notably includes
2773 @code{#\space} and @code{#\tab}.
2776 @defvr {Scheme Variable} char-set:iso-control
2777 @defvrx {C Variable} scm_char_set_iso_control
2778 The ISO control characters are the C0 control characters (U+0000 to
2779 U+001F), delete (U+007F), and the C1 control characters (U+0080 to
2783 @defvr {Scheme Variable} char-set:punctuation
2784 @defvrx {C Variable} scm_char_set_punctuation
2785 All punctuation characters, such as the characters
2786 @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
2789 @defvr {Scheme Variable} char-set:symbol
2790 @defvrx {C Variable} scm_char_set_symbol
2791 All symbol characters, such as the characters @code{$+<=>^`|~}.
2794 @defvr {Scheme Variable} char-set:hex-digit
2795 @defvrx {C Variable} scm_char_set_hex_digit
2796 The hexadecimal digits @code{0123456789abcdefABCDEF}.
2799 @defvr {Scheme Variable} char-set:ascii
2800 @defvrx {C Variable} scm_char_set_ascii
2801 All ASCII characters.
2804 @defvr {Scheme Variable} char-set:empty
2805 @defvrx {C Variable} scm_char_set_empty
2806 The empty character set.
2809 @defvr {Scheme Variable} char-set:designated
2810 @defvrx {C Variable} scm_char_set_designated
2811 This character set contains all designated code points. This includes
2812 all the code points to which Unicode has assigned a character or other
2816 @defvr {Scheme Variable} char-set:full
2817 @defvrx {C Variable} scm_char_set_full
2818 This character set contains all possible code points. This includes
2819 both designated and reserved code points.
2826 Strings are fixed-length sequences of characters. They can be created
2827 by calling constructor procedures, but they can also literally get
2828 entered at the @acronym{REPL} or in Scheme source files.
2830 @c Guile provides a rich set of string processing procedures, because text
2831 @c handling is very important when Guile is used as a scripting language.
2833 Strings always carry the information about how many characters they are
2834 composed of with them, so there is no special end-of-string character,
2835 like in C. That means that Scheme strings can contain any character,
2836 even the @samp{#\nul} character @samp{\0}.
2838 To use strings efficiently, you need to know a bit about how Guile
2839 implements them. In Guile, a string consists of two parts, a head and
2840 the actual memory where the characters are stored. When a string (or
2841 a substring of it) is copied, only a new head gets created, the memory
2842 is usually not copied. The two heads start out pointing to the same
2845 When one of these two strings is modified, as with @code{string-set!},
2846 their common memory does get copied so that each string has its own
2847 memory and modifying one does not accidentally modify the other as well.
2848 Thus, Guile's strings are `copy on write'; the actual copying of their
2849 memory is delayed until one string is written to.
2851 This implementation makes functions like @code{substring} very
2852 efficient in the common case that no modifications are done to the
2855 If you do know that your strings are getting modified right away, you
2856 can use @code{substring/copy} instead of @code{substring}. This
2857 function performs the copy immediately at the time of creation. This
2858 is more efficient, especially in a multi-threaded program. Also,
2859 @code{substring/copy} can avoid the problem that a short substring
2860 holds on to the memory of a very large original string that could
2861 otherwise be recycled.
2863 If you want to avoid the copy altogether, so that modifications of one
2864 string show up in the other, you can use @code{substring/shared}. The
2865 strings created by this procedure are called @dfn{mutation sharing
2866 substrings} since the substring and the original string share
2867 modifications to each other.
2869 If you want to prevent modifications, use @code{substring/read-only}.
2871 Guile provides all procedures of SRFI-13 and a few more.
2874 * String Syntax:: Read syntax for strings.
2875 * String Predicates:: Testing strings for certain properties.
2876 * String Constructors:: Creating new string objects.
2877 * List/String Conversion:: Converting from/to lists of characters.
2878 * String Selection:: Select portions from strings.
2879 * String Modification:: Modify parts or whole strings.
2880 * String Comparison:: Lexicographic ordering predicates.
2881 * String Searching:: Searching in strings.
2882 * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
2883 * Reversing and Appending Strings:: Appending strings to form a new string.
2884 * Mapping Folding and Unfolding:: Iterating over strings.
2885 * Miscellaneous String Operations:: Replicating, insertion, parsing, ...
2886 * Representing Strings as Bytes:: Encoding and decoding strings.
2887 * Conversion to/from C::
2888 * String Internals:: The storage strategy for strings.
2892 @subsubsection String Read Syntax
2894 @c In the following @code is used to get a good font in TeX etc, but
2895 @c is omitted for Info format, so as not to risk any confusion over
2896 @c whether surrounding ` ' quotes are part of the escape or are
2897 @c special in a string (they're not).
2899 The read syntax for strings is an arbitrarily long sequence of
2900 characters enclosed in double quotes (@nicode{"}).
2902 Backslash is an escape character and can be used to insert the following
2903 special characters. @nicode{\"} and @nicode{\\} are R5RS standard, the
2904 next seven are R6RS standard --- notice they follow C syntax --- and the
2905 remaining four are Guile extensions.
2909 Backslash character.
2912 Double quote character (an unescaped @nicode{"} is otherwise the end
2916 Bell character (ASCII 7).
2919 Formfeed character (ASCII 12).
2922 Newline character (ASCII 10).
2925 Carriage return character (ASCII 13).
2928 Tab character (ASCII 9).
2931 Vertical tab character (ASCII 11).
2934 Backspace character (ASCII 8).
2937 NUL character (ASCII 0).
2939 @item @nicode{\} followed by newline (ASCII 10)
2940 Nothing. This way if @nicode{\} is the last character in a line, the
2941 string will continue with the first character from the next line,
2942 without a line break.
2944 If the @code{hungry-eol-escapes} reader option is enabled, which is not
2945 the case by default, leading whitespace on the next line is discarded.
2951 (read-enable 'hungry-eol-escapes)
2957 Character code given by two hexadecimal digits. For example
2958 @nicode{\x7f} for an ASCII DEL (127).
2960 @item @nicode{\uHHHH}
2961 Character code given by four hexadecimal digits. For example
2962 @nicode{\u0100} for a capital A with macron (U+0100).
2964 @item @nicode{\UHHHHHH}
2965 Character code given by six hexadecimal digits. For example
2970 The following are examples of string literals:
2979 The three escape sequences @code{\xHH}, @code{\uHHHH} and @code{\UHHHHHH} were
2980 chosen to not break compatibility with code written for previous versions of
2981 Guile. The R6RS specification suggests a different, incompatible syntax for hex
2982 escapes: @code{\xHHHH;} -- a character code followed by one to eight hexadecimal
2983 digits terminated with a semicolon. If this escape format is desired instead,
2984 it can be enabled with the reader option @code{r6rs-hex-escapes}.
2987 (read-enable 'r6rs-hex-escapes)
2990 For more on reader options, @xref{Scheme Read}.
2992 @node String Predicates
2993 @subsubsection String Predicates
2995 The following procedures can be used to check whether a given string
2996 fulfills some specified property.
2999 @deffn {Scheme Procedure} string? obj
3000 @deffnx {C Function} scm_string_p (obj)
3001 Return @code{#t} if @var{obj} is a string, else @code{#f}.
3004 @deftypefn {C Function} int scm_is_string (SCM obj)
3005 Returns @code{1} if @var{obj} is a string, @code{0} otherwise.
3008 @deffn {Scheme Procedure} string-null? str
3009 @deffnx {C Function} scm_string_null_p (str)
3010 Return @code{#t} if @var{str}'s length is zero, and
3011 @code{#f} otherwise.
3013 (string-null? "") @result{} #t
3015 (string-null? y) @result{} #f
3019 @deffn {Scheme Procedure} string-any char_pred s [start [end]]
3020 @deffnx {C Function} scm_string_any (char_pred, s, start, end)
3021 Check if @var{char_pred} is true for any character in string @var{s}.
3023 @var{char_pred} can be a character to check for any equal to that, or
3024 a character set (@pxref{Character Sets}) to check for any in that set,
3025 or a predicate procedure to call.
3027 For a procedure, calls @code{(@var{char_pred} c)} are made
3028 successively on the characters from @var{start} to @var{end}. If
3029 @var{char_pred} returns true (ie.@: non-@code{#f}), @code{string-any}
3030 stops and that return value is the return from @code{string-any}. The
3031 call on the last character (ie.@: at @math{@var{end}-1}), if that
3032 point is reached, is a tail call.
3034 If there are no characters in @var{s} (ie.@: @var{start} equals
3035 @var{end}) then the return is @code{#f}.
3038 @deffn {Scheme Procedure} string-every char_pred s [start [end]]
3039 @deffnx {C Function} scm_string_every (char_pred, s, start, end)
3040 Check if @var{char_pred} is true for every character in string
3043 @var{char_pred} can be a character to check for every character equal
3044 to that, or a character set (@pxref{Character Sets}) to check for
3045 every character being in that set, or a predicate procedure to call.
3047 For a procedure, calls @code{(@var{char_pred} c)} are made
3048 successively on the characters from @var{start} to @var{end}. If
3049 @var{char_pred} returns @code{#f}, @code{string-every} stops and
3050 returns @code{#f}. The call on the last character (ie.@: at
3051 @math{@var{end}-1}), if that point is reached, is a tail call and the
3052 return from that call is the return from @code{string-every}.
3054 If there are no characters in @var{s} (ie.@: @var{start} equals
3055 @var{end}) then the return is @code{#t}.
3058 @node String Constructors
3059 @subsubsection String Constructors
3061 The string constructor procedures create new string objects, possibly
3062 initializing them with some specified character data. See also
3063 @xref{String Selection}, for ways to create strings from existing
3066 @c FIXME::martin: list->string belongs into `List/String Conversion'
3068 @deffn {Scheme Procedure} string char@dots{}
3070 Return a newly allocated string made from the given character
3074 (string #\x #\y #\z) @result{} "xyz"
3075 (string) @result{} ""
3079 @deffn {Scheme Procedure} list->string lst
3080 @deffnx {C Function} scm_string (lst)
3081 @rnindex list->string
3082 Return a newly allocated string made from a list of characters.
3085 (list->string '(#\a #\b #\c)) @result{} "abc"
3089 @deffn {Scheme Procedure} reverse-list->string lst
3090 @deffnx {C Function} scm_reverse_list_to_string (lst)
3091 Return a newly allocated string made from a list of characters, in
3095 (reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
3099 @rnindex make-string
3100 @deffn {Scheme Procedure} make-string k [chr]
3101 @deffnx {C Function} scm_make_string (k, chr)
3102 Return a newly allocated string of
3103 length @var{k}. If @var{chr} is given, then all elements of
3104 the string are initialized to @var{chr}, otherwise the contents
3105 of the string are unspecified.
3108 @deftypefn {C Function} SCM scm_c_make_string (size_t len, SCM chr)
3109 Like @code{scm_make_string}, but expects the length as a
3113 @deffn {Scheme Procedure} string-tabulate proc len
3114 @deffnx {C Function} scm_string_tabulate (proc, len)
3115 @var{proc} is an integer->char procedure. Construct a string
3116 of size @var{len} by applying @var{proc} to each index to
3117 produce the corresponding string element. The order in which
3118 @var{proc} is applied to the indices is not specified.
3121 @deffn {Scheme Procedure} string-join ls [delimiter [grammar]]
3122 @deffnx {C Function} scm_string_join (ls, delimiter, grammar)
3123 Append the string in the string list @var{ls}, using the string
3124 @var{delimiter} as a delimiter between the elements of @var{ls}.
3125 @var{grammar} is a symbol which specifies how the delimiter is
3126 placed between the strings, and defaults to the symbol
3131 Insert the separator between list elements. An empty string
3132 will produce an empty list.
3134 Like @code{infix}, but will raise an error if given the empty
3137 Insert the separator after every list element.
3139 Insert the separator before each list element.
3143 @node List/String Conversion
3144 @subsubsection List/String conversion
3146 When processing strings, it is often convenient to first convert them
3147 into a list representation by using the procedure @code{string->list},
3148 work with the resulting list, and then convert it back into a string.
3149 These procedures are useful for similar tasks.
3151 @rnindex string->list
3152 @deffn {Scheme Procedure} string->list str [start [end]]
3153 @deffnx {C Function} scm_substring_to_list (str, start, end)
3154 @deffnx {C Function} scm_string_to_list (str)
3155 Convert the string @var{str} into a list of characters.
3158 @deffn {Scheme Procedure} string-split str char_pred
3159 @deffnx {C Function} scm_string_split (str, char_pred)
3160 Split the string @var{str} into a list of substrings delimited
3161 by appearances of characters that
3165 equal @var{char_pred}, if it is a character,
3168 satisfy the predicate @var{char_pred}, if it is a procedure,
3171 are in the set @var{char_pred}, if it is a character set.
3174 Note that an empty substring between separator characters will result in
3175 an empty string in the result list.
3178 (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
3180 ("root" "x" "0" "0" "root" "/root" "/bin/bash")
3182 (string-split "::" #\:)
3186 (string-split "" #\:)
3193 @node String Selection
3194 @subsubsection String Selection
3196 Portions of strings can be extracted by these procedures.
3197 @code{string-ref} delivers individual characters whereas
3198 @code{substring} can be used to extract substrings from longer strings.
3200 @rnindex string-length
3201 @deffn {Scheme Procedure} string-length string
3202 @deffnx {C Function} scm_string_length (string)
3203 Return the number of characters in @var{string}.
3206 @deftypefn {C Function} size_t scm_c_string_length (SCM str)
3207 Return the number of characters in @var{str} as a @code{size_t}.
3211 @deffn {Scheme Procedure} string-ref str k
3212 @deffnx {C Function} scm_string_ref (str, k)
3213 Return character @var{k} of @var{str} using zero-origin
3214 indexing. @var{k} must be a valid index of @var{str}.
3217 @deftypefn {C Function} SCM scm_c_string_ref (SCM str, size_t k)
3218 Return character @var{k} of @var{str} using zero-origin
3219 indexing. @var{k} must be a valid index of @var{str}.
3222 @rnindex string-copy
3223 @deffn {Scheme Procedure} string-copy str [start [end]]
3224 @deffnx {C Function} scm_substring_copy (str, start, end)
3225 @deffnx {C Function} scm_string_copy (str)
3226 Return a copy of the given string @var{str}.
3228 The returned string shares storage with @var{str} initially, but it is
3229 copied as soon as one of the two strings is modified.
3233 @deffn {Scheme Procedure} substring str start [end]
3234 @deffnx {C Function} scm_substring (str, start, end)
3235 Return a new string formed from the characters
3236 of @var{str} beginning with index @var{start} (inclusive) and
3237 ending with index @var{end} (exclusive).
3238 @var{str} must be a string, @var{start} and @var{end} must be
3239 exact integers satisfying:
3241 0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
3243 The returned string shares storage with @var{str} initially, but it is
3244 copied as soon as one of the two strings is modified.
3247 @deffn {Scheme Procedure} substring/shared str start [end]
3248 @deffnx {C Function} scm_substring_shared (str, start, end)
3249 Like @code{substring}, but the strings continue to share their storage
3250 even if they are modified. Thus, modifications to @var{str} show up
3251 in the new string, and vice versa.
3254 @deffn {Scheme Procedure} substring/copy str start [end]
3255 @deffnx {C Function} scm_substring_copy (str, start, end)
3256 Like @code{substring}, but the storage for the new string is copied
3260 @deffn {Scheme Procedure} substring/read-only str start [end]
3261 @deffnx {C Function} scm_substring_read_only (str, start, end)
3262 Like @code{substring}, but the resulting string can not be modified.
3265 @deftypefn {C Function} SCM scm_c_substring (SCM str, size_t start, size_t end)
3266 @deftypefnx {C Function} SCM scm_c_substring_shared (SCM str, size_t start, size_t end)
3267 @deftypefnx {C Function} SCM scm_c_substring_copy (SCM str, size_t start, size_t end)
3268 @deftypefnx {C Function} SCM scm_c_substring_read_only (SCM str, size_t start, size_t end)
3269 Like @code{scm_substring}, etc. but the bounds are given as a @code{size_t}.
3272 @deffn {Scheme Procedure} string-take s n
3273 @deffnx {C Function} scm_string_take (s, n)
3274 Return the @var{n} first characters of @var{s}.
3277 @deffn {Scheme Procedure} string-drop s n
3278 @deffnx {C Function} scm_string_drop (s, n)
3279 Return all but the first @var{n} characters of @var{s}.
3282 @deffn {Scheme Procedure} string-take-right s n
3283 @deffnx {C Function} scm_string_take_right (s, n)
3284 Return the @var{n} last characters of @var{s}.
3287 @deffn {Scheme Procedure} string-drop-right s n
3288 @deffnx {C Function} scm_string_drop_right (s, n)
3289 Return all but the last @var{n} characters of @var{s}.
3292 @deffn {Scheme Procedure} string-pad s len [chr [start [end]]]
3293 @deffnx {Scheme Procedure} string-pad-right s len [chr [start [end]]]
3294 @deffnx {C Function} scm_string_pad (s, len, chr, start, end)
3295 @deffnx {C Function} scm_string_pad_right (s, len, chr, start, end)
3296 Take characters @var{start} to @var{end} from the string @var{s} and
3297 either pad with @var{chr} or truncate them to give @var{len}
3300 @code{string-pad} pads or truncates on the left, so for example
3303 (string-pad "x" 3) @result{} " x"
3304 (string-pad "abcde" 3) @result{} "cde"
3307 @code{string-pad-right} pads or truncates on the right, so for example
3310 (string-pad-right "x" 3) @result{} "x "
3311 (string-pad-right "abcde" 3) @result{} "abc"
3315 @deffn {Scheme Procedure} string-trim s [char_pred [start [end]]]
3316 @deffnx {Scheme Procedure} string-trim-right s [char_pred [start [end]]]
3317 @deffnx {Scheme Procedure} string-trim-both s [char_pred [start [end]]]
3318 @deffnx {C Function} scm_string_trim (s, char_pred, start, end)
3319 @deffnx {C Function} scm_string_trim_right (s, char_pred, start, end)
3320 @deffnx {C Function} scm_string_trim_both (s, char_pred, start, end)
3321 Trim occurrences of @var{char_pred} from the ends of @var{s}.
3323 @code{string-trim} trims @var{char_pred} characters from the left
3324 (start) of the string, @code{string-trim-right} trims them from the
3325 right (end) of the string, @code{string-trim-both} trims from both
3328 @var{char_pred} can be a character, a character set, or a predicate
3329 procedure to call on each character. If @var{char_pred} is not given
3330 the default is whitespace as per @code{char-set:whitespace}
3331 (@pxref{Standard Character Sets}).
3334 (string-trim " x ") @result{} "x "
3335 (string-trim-right "banana" #\a) @result{} "banan"
3336 (string-trim-both ".,xy:;" char-set:punctuation)
3338 (string-trim-both "xyzzy" (lambda (c)
3345 @node String Modification
3346 @subsubsection String Modification
3348 These procedures are for modifying strings in-place. This means that the
3349 result of the operation is not a new string; instead, the original string's
3350 memory representation is modified.
3352 @rnindex string-set!
3353 @deffn {Scheme Procedure} string-set! str k chr
3354 @deffnx {C Function} scm_string_set_x (str, k, chr)
3355 Store @var{chr} in element @var{k} of @var{str} and return
3356 an unspecified value. @var{k} must be a valid index of
3360 @deftypefn {C Function} void scm_c_string_set_x (SCM str, size_t k, SCM chr)
3361 Like @code{scm_string_set_x}, but the index is given as a @code{size_t}.
3364 @rnindex string-fill!
3365 @deffn {Scheme Procedure} string-fill! str chr [start [end]]
3366 @deffnx {C Function} scm_substring_fill_x (str, chr, start, end)
3367 @deffnx {C Function} scm_string_fill_x (str, chr)
3368 Stores @var{chr} in every element of the given @var{str} and
3369 returns an unspecified value.
3372 @deffn {Scheme Procedure} substring-fill! str start end fill
3373 @deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
3374 Change every character in @var{str} between @var{start} and
3375 @var{end} to @var{fill}.
3378 (define y (string-copy "abcdefg"))
3379 (substring-fill! y 1 3 #\r)
3385 @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
3386 @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
3387 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
3388 into @var{str2} beginning at position @var{start2}.
3389 @var{str1} and @var{str2} can be the same string.
3392 @deffn {Scheme Procedure} string-copy! target tstart s [start [end]]
3393 @deffnx {C Function} scm_string_copy_x (target, tstart, s, start, end)
3394 Copy the sequence of characters from index range [@var{start},
3395 @var{end}) in string @var{s} to string @var{target}, beginning
3396 at index @var{tstart}. The characters are copied left-to-right
3397 or right-to-left as needed -- the copy is guaranteed to work,
3398 even if @var{target} and @var{s} are the same string. It is an
3399 error if the copy operation runs off the end of the target
3404 @node String Comparison
3405 @subsubsection String Comparison
3407 The procedures in this section are similar to the character ordering
3408 predicates (@pxref{Characters}), but are defined on character sequences.
3410 The first set is specified in R5RS and has names that end in @code{?}.
3411 The second set is specified in SRFI-13 and the names have not ending
3414 The predicates ending in @code{-ci} ignore the character case
3415 when comparing strings. For now, case-insensitive comparison is done
3416 using the R5RS rules, where every lower-case character that has a
3417 single character upper-case form is converted to uppercase before
3418 comparison. See @xref{Text Collation, the @code{(ice-9
3419 i18n)} module}, for locale-dependent string comparison.
3422 @deffn {Scheme Procedure} string=? s1 s2 s3 @dots{}
3423 Lexicographic equality predicate; return @code{#t} if all strings are
3424 the same length and contain the same characters in the same positions,
3425 otherwise return @code{#f}.
3427 The procedure @code{string-ci=?} treats upper and lower case
3428 letters as though they were the same character, but
3429 @code{string=?} treats upper and lower case as distinct
3434 @deffn {Scheme Procedure} string<? s1 s2 s3 @dots{}
3435 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3436 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3437 lexicographically less than @var{str_i+1}.
3441 @deffn {Scheme Procedure} string<=? s1 s2 s3 @dots{}
3442 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3443 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3444 lexicographically less than or equal to @var{str_i+1}.
3448 @deffn {Scheme Procedure} string>? s1 s2 s3 @dots{}
3449 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3450 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3451 lexicographically greater than @var{str_i+1}.
3455 @deffn {Scheme Procedure} string>=? s1 s2 s3 @dots{}
3456 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3457 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3458 lexicographically greater than or equal to @var{str_i+1}.
3461 @rnindex string-ci=?
3462 @deffn {Scheme Procedure} string-ci=? s1 s2 s3 @dots{}
3463 Case-insensitive string equality predicate; return @code{#t} if
3464 all strings are the same length and their component
3465 characters match (ignoring case) at each position; otherwise
3469 @rnindex string-ci<?
3470 @deffn {Scheme Procedure} string-ci<? s1 s2 s3 @dots{}
3471 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3472 for every pair of consecutive string arguments @var{str_i} and
3473 @var{str_i+1}, @var{str_i} is lexicographically less than @var{str_i+1}
3478 @deffn {Scheme Procedure} string-ci<=? s1 s2 s3 @dots{}
3479 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3480 for every pair of consecutive string arguments @var{str_i} and
3481 @var{str_i+1}, @var{str_i} is lexicographically less than or equal to
3482 @var{str_i+1} regardless of case.
3485 @rnindex string-ci>?
3486 @deffn {Scheme Procedure} string-ci>? s1 s2 s3 @dots{}
3487 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3488 for every pair of consecutive string arguments @var{str_i} and
3489 @var{str_i+1}, @var{str_i} is lexicographically greater than
3490 @var{str_i+1} regardless of case.
3493 @rnindex string-ci>=?
3494 @deffn {Scheme Procedure} string-ci>=? s1 s2 s3 @dots{}
3495 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3496 for every pair of consecutive string arguments @var{str_i} and
3497 @var{str_i+1}, @var{str_i} is lexicographically greater than or equal to
3498 @var{str_i+1} regardless of case.
3501 @deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3502 @deffnx {C Function} scm_string_compare (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3503 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3504 mismatch index, depending upon whether @var{s1} is less than,
3505 equal to, or greater than @var{s2}. The mismatch index is the
3506 largest index @var{i} such that for every 0 <= @var{j} <
3507 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3508 @var{i} is the first position that does not match.
3511 @deffn {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3512 @deffnx {C Function} scm_string_compare_ci (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3513 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3514 mismatch index, depending upon whether @var{s1} is less than,
3515 equal to, or greater than @var{s2}. The mismatch index is the
3516 largest index @var{i} such that for every 0 <= @var{j} <
3517 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3518 @var{i} is the first position where the lowercased letters
3523 @deffn {Scheme Procedure} string= s1 s2 [start1 [end1 [start2 [end2]]]]
3524 @deffnx {C Function} scm_string_eq (s1, s2, start1, end1, start2, end2)
3525 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3529 @deffn {Scheme Procedure} string<> s1 s2 [start1 [end1 [start2 [end2]]]]
3530 @deffnx {C Function} scm_string_neq (s1, s2, start1, end1, start2, end2)
3531 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3535 @deffn {Scheme Procedure} string< s1 s2 [start1 [end1 [start2 [end2]]]]
3536 @deffnx {C Function} scm_string_lt (s1, s2, start1, end1, start2, end2)
3537 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3538 true value otherwise.
3541 @deffn {Scheme Procedure} string> s1 s2 [start1 [end1 [start2 [end2]]]]
3542 @deffnx {C Function} scm_string_gt (s1, s2, start1, end1, start2, end2)
3543 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3544 true value otherwise.
3547 @deffn {Scheme Procedure} string<= s1 s2 [start1 [end1 [start2 [end2]]]]
3548 @deffnx {C Function} scm_string_le (s1, s2, start1, end1, start2, end2)
3549 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3553 @deffn {Scheme Procedure} string>= s1 s2 [start1 [end1 [start2 [end2]]]]
3554 @deffnx {C Function} scm_string_ge (s1, s2, start1, end1, start2, end2)
3555 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3559 @deffn {Scheme Procedure} string-ci= s1 s2 [start1 [end1 [start2 [end2]]]]
3560 @deffnx {C Function} scm_string_ci_eq (s1, s2, start1, end1, start2, end2)
3561 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3562 value otherwise. The character comparison is done
3566 @deffn {Scheme Procedure} string-ci<> s1 s2 [start1 [end1 [start2 [end2]]]]
3567 @deffnx {C Function} scm_string_ci_neq (s1, s2, start1, end1, start2, end2)
3568 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3569 value otherwise. The character comparison is done
3573 @deffn {Scheme Procedure} string-ci< s1 s2 [start1 [end1 [start2 [end2]]]]
3574 @deffnx {C Function} scm_string_ci_lt (s1, s2, start1, end1, start2, end2)
3575 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3576 true value otherwise. The character comparison is done
3580 @deffn {Scheme Procedure} string-ci> s1 s2 [start1 [end1 [start2 [end2]]]]
3581 @deffnx {C Function} scm_string_ci_gt (s1, s2, start1, end1, start2, end2)
3582 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3583 true value otherwise. The character comparison is done
3587 @deffn {Scheme Procedure} string-ci<= s1 s2 [start1 [end1 [start2 [end2]]]]
3588 @deffnx {C Function} scm_string_ci_le (s1, s2, start1, end1, start2, end2)
3589 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3590 value otherwise. The character comparison is done
3594 @deffn {Scheme Procedure} string-ci>= s1 s2 [start1 [end1 [start2 [end2]]]]
3595 @deffnx {C Function} scm_string_ci_ge (s1, s2, start1, end1, start2, end2)
3596 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3597 otherwise. The character comparison is done
3601 @deffn {Scheme Procedure} string-hash s [bound [start [end]]]
3602 @deffnx {C Function} scm_substring_hash (s, bound, start, end)
3603 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).
3606 @deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
3607 @deffnx {C Function} scm_substring_hash_ci (s, bound, start, end)
3608 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).
3611 Because the same visual appearance of an abstract Unicode character can
3612 be obtained via multiple sequences of Unicode characters, even the
3613 case-insensitive string comparison functions described above may return
3614 @code{#f} when presented with strings containing different
3615 representations of the same character. For example, the Unicode
3616 character ``LATIN SMALL LETTER S WITH DOT BELOW AND DOT ABOVE'' can be
3617 represented with a single character (U+1E69) or by the character ``LATIN
3618 SMALL LETTER S'' (U+0073) followed by the combining marks ``COMBINING
3619 DOT BELOW'' (U+0323) and ``COMBINING DOT ABOVE'' (U+0307).
3621 For this reason, it is often desirable to ensure that the strings
3622 to be compared are using a mutually consistent representation for every
3623 character. The Unicode standard defines two methods of normalizing the
3624 contents of strings: Decomposition, which breaks composite characters
3625 into a set of constituent characters with an ordering defined by the
3626 Unicode Standard; and composition, which performs the converse.
3628 There are two decomposition operations. ``Canonical decomposition''
3629 produces character sequences that share the same visual appearance as
3630 the original characters, while ``compatibility decomposition'' produces
3631 ones whose visual appearances may differ from the originals but which
3632 represent the same abstract character.
3634 These operations are encapsulated in the following set of normalization
3639 Characters are decomposed to their canonical forms.
3642 Characters are decomposed to their compatibility forms.
3645 Characters are decomposed to their canonical forms, then composed.
3648 Characters are decomposed to their compatibility forms, then composed.
3652 The functions below put their arguments into one of the forms described
3655 @deffn {Scheme Procedure} string-normalize-nfd s
3656 @deffnx {C Function} scm_string_normalize_nfd (s)
3657 Return the @code{NFD} normalized form of @var{s}.
3660 @deffn {Scheme Procedure} string-normalize-nfkd s
3661 @deffnx {C Function} scm_string_normalize_nfkd (s)
3662 Return the @code{NFKD} normalized form of @var{s}.
3665 @deffn {Scheme Procedure} string-normalize-nfc s
3666 @deffnx {C Function} scm_string_normalize_nfc (s)
3667 Return the @code{NFC} normalized form of @var{s}.
3670 @deffn {Scheme Procedure} string-normalize-nfkc s
3671 @deffnx {C Function} scm_string_normalize_nfkc (s)
3672 Return the @code{NFKC} normalized form of @var{s}.
3675 @node String Searching
3676 @subsubsection String Searching
3678 @deffn {Scheme Procedure} string-index s char_pred [start [end]]
3679 @deffnx {C Function} scm_string_index (s, char_pred, start, end)
3680 Search through the string @var{s} from left to right, returning
3681 the index of the first occurrence of a character which
3685 equals @var{char_pred}, if it is character,
3688 satisfies the predicate @var{char_pred}, if it is a procedure,
3691 is in the set @var{char_pred}, if it is a character set.
3694 Return @code{#f} if no match is found.
3697 @deffn {Scheme Procedure} string-rindex s char_pred [start [end]]
3698 @deffnx {C Function} scm_string_rindex (s, char_pred, start, end)
3699 Search through the string @var{s} from right to left, returning
3700 the index of the last occurrence of a character which
3704 equals @var{char_pred}, if it is character,
3707 satisfies the predicate @var{char_pred}, if it is a procedure,
3710 is in the set if @var{char_pred} is a character set.
3713 Return @code{#f} if no match is found.
3716 @deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3717 @deffnx {C Function} scm_string_prefix_length (s1, s2, start1, end1, start2, end2)
3718 Return the length of the longest common prefix of the two
3722 @deffn {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3723 @deffnx {C Function} scm_string_prefix_length_ci (s1, s2, start1, end1, start2, end2)
3724 Return the length of the longest common prefix of the two
3725 strings, ignoring character case.
3728 @deffn {Scheme Procedure} string-suffix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3729 @deffnx {C Function} scm_string_suffix_length (s1, s2, start1, end1, start2, end2)
3730 Return the length of the longest common suffix of the two
3734 @deffn {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3735 @deffnx {C Function} scm_string_suffix_length_ci (s1, s2, start1, end1, start2, end2)
3736 Return the length of the longest common suffix of the two
3737 strings, ignoring character case.
3740 @deffn {Scheme Procedure} string-prefix? s1 s2 [start1 [end1 [start2 [end2]]]]
3741 @deffnx {C Function} scm_string_prefix_p (s1, s2, start1, end1, start2, end2)
3742 Is @var{s1} a prefix of @var{s2}?
3745 @deffn {Scheme Procedure} string-prefix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3746 @deffnx {C Function} scm_string_prefix_ci_p (s1, s2, start1, end1, start2, end2)
3747 Is @var{s1} a prefix of @var{s2}, ignoring character case?
3750 @deffn {Scheme Procedure} string-suffix? s1 s2 [start1 [end1 [start2 [end2]]]]
3751 @deffnx {C Function} scm_string_suffix_p (s1, s2, start1, end1, start2, end2)
3752 Is @var{s1} a suffix of @var{s2}?
3755 @deffn {Scheme Procedure} string-suffix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3756 @deffnx {C Function} scm_string_suffix_ci_p (s1, s2, start1, end1, start2, end2)
3757 Is @var{s1} a suffix of @var{s2}, ignoring character case?
3760 @deffn {Scheme Procedure} string-index-right s char_pred [start [end]]
3761 @deffnx {C Function} scm_string_index_right (s, char_pred, start, end)
3762 Search through the string @var{s} from right to left, returning
3763 the index of the last occurrence of a character which
3767 equals @var{char_pred}, if it is character,
3770 satisfies the predicate @var{char_pred}, if it is a procedure,
3773 is in the set if @var{char_pred} is a character set.
3776 Return @code{#f} if no match is found.
3779 @deffn {Scheme Procedure} string-skip s char_pred [start [end]]
3780 @deffnx {C Function} scm_string_skip (s, char_pred, start, end)
3781 Search through the string @var{s} from left to right, returning
3782 the index of the first occurrence of a character which
3786 does not equal @var{char_pred}, if it is character,
3789 does not satisfy the predicate @var{char_pred}, if it is a
3793 is not in the set if @var{char_pred} is a character set.
3797 @deffn {Scheme Procedure} string-skip-right s char_pred [start [end]]
3798 @deffnx {C Function} scm_string_skip_right (s, char_pred, start, end)
3799 Search through the string @var{s} from right to left, returning
3800 the index of the last occurrence of a character which
3804 does not equal @var{char_pred}, if it is character,
3807 does not satisfy the predicate @var{char_pred}, if it is a
3811 is not in the set if @var{char_pred} is a character set.
3815 @deffn {Scheme Procedure} string-count s char_pred [start [end]]
3816 @deffnx {C Function} scm_string_count (s, char_pred, start, end)
3817 Return the count of the number of characters in the string
3822 equals @var{char_pred}, if it is character,
3825 satisfies the predicate @var{char_pred}, if it is a procedure.
3828 is in the set @var{char_pred}, if it is a character set.
3832 @deffn {Scheme Procedure} string-contains s1 s2 [start1 [end1 [start2 [end2]]]]
3833 @deffnx {C Function} scm_string_contains (s1, s2, start1, end1, start2, end2)
3834 Does string @var{s1} contain string @var{s2}? Return the index
3835 in @var{s1} where @var{s2} occurs as a substring, or false.
3836 The optional start/end indices restrict the operation to the
3837 indicated substrings.
3840 @deffn {Scheme Procedure} string-contains-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3841 @deffnx {C Function} scm_string_contains_ci (s1, s2, start1, end1, start2, end2)
3842 Does string @var{s1} contain string @var{s2}? Return the index
3843 in @var{s1} where @var{s2} occurs as a substring, or false.
3844 The optional start/end indices restrict the operation to the
3845 indicated substrings. Character comparison is done
3849 @node Alphabetic Case Mapping
3850 @subsubsection Alphabetic Case Mapping
3852 These are procedures for mapping strings to their upper- or lower-case
3853 equivalents, respectively, or for capitalizing strings.
3855 They use the basic case mapping rules for Unicode characters. No
3856 special language or context rules are considered. The resulting strings
3857 are guaranteed to be the same length as the input strings.
3859 @xref{Character Case Mapping, the @code{(ice-9
3860 i18n)} module}, for locale-dependent case conversions.
3862 @deffn {Scheme Procedure} string-upcase str [start [end]]
3863 @deffnx {C Function} scm_substring_upcase (str, start, end)
3864 @deffnx {C Function} scm_string_upcase (str)
3865 Upcase every character in @code{str}.
3868 @deffn {Scheme Procedure} string-upcase! str [start [end]]
3869 @deffnx {C Function} scm_substring_upcase_x (str, start, end)
3870 @deffnx {C Function} scm_string_upcase_x (str)
3871 Destructively upcase every character in @code{str}.
3881 @deffn {Scheme Procedure} string-downcase str [start [end]]
3882 @deffnx {C Function} scm_substring_downcase (str, start, end)
3883 @deffnx {C Function} scm_string_downcase (str)
3884 Downcase every character in @var{str}.
3887 @deffn {Scheme Procedure} string-downcase! str [start [end]]
3888 @deffnx {C Function} scm_substring_downcase_x (str, start, end)
3889 @deffnx {C Function} scm_string_downcase_x (str)
3890 Destructively downcase every character in @var{str}.
3895 (string-downcase! y)
3902 @deffn {Scheme Procedure} string-capitalize str
3903 @deffnx {C Function} scm_string_capitalize (str)
3904 Return a freshly allocated string with the characters in
3905 @var{str}, where the first character of every word is
3909 @deffn {Scheme Procedure} string-capitalize! str
3910 @deffnx {C Function} scm_string_capitalize_x (str)
3911 Upcase the first character of every word in @var{str}
3912 destructively and return @var{str}.
3915 y @result{} "hello world"
3916 (string-capitalize! y) @result{} "Hello World"
3917 y @result{} "Hello World"
3921 @deffn {Scheme Procedure} string-titlecase str [start [end]]
3922 @deffnx {C Function} scm_string_titlecase (str, start, end)
3923 Titlecase every first character in a word in @var{str}.
3926 @deffn {Scheme Procedure} string-titlecase! str [start [end]]
3927 @deffnx {C Function} scm_string_titlecase_x (str, start, end)
3928 Destructively titlecase every first character in a word in
3932 @node Reversing and Appending Strings
3933 @subsubsection Reversing and Appending Strings
3935 @deffn {Scheme Procedure} string-reverse str [start [end]]
3936 @deffnx {C Function} scm_string_reverse (str, start, end)
3937 Reverse the string @var{str}. The optional arguments
3938 @var{start} and @var{end} delimit the region of @var{str} to
3942 @deffn {Scheme Procedure} string-reverse! str [start [end]]
3943 @deffnx {C Function} scm_string_reverse_x (str, start, end)
3944 Reverse the string @var{str} in-place. The optional arguments
3945 @var{start} and @var{end} delimit the region of @var{str} to
3946 operate on. The return value is unspecified.
3949 @rnindex string-append
3950 @deffn {Scheme Procedure} string-append arg @dots{}
3951 @deffnx {C Function} scm_string_append (args)
3952 Return a newly allocated string whose characters form the
3953 concatenation of the given strings, @var{arg} @enddots{}.
3957 (string-append h "world"))
3958 @result{} "hello world"
3962 @deffn {Scheme Procedure} string-append/shared arg @dots{}
3963 @deffnx {C Function} scm_string_append_shared (args)
3964 Like @code{string-append}, but the result may share memory
3965 with the argument strings.
3968 @deffn {Scheme Procedure} string-concatenate ls
3969 @deffnx {C Function} scm_string_concatenate (ls)
3970 Append the elements (which must be strings) of @var{ls} together into a
3971 single string. Guaranteed to return a freshly allocated string.
3974 @deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]]
3975 @deffnx {C Function} scm_string_concatenate_reverse (ls, final_string, end)
3976 Without optional arguments, this procedure is equivalent to
3979 (string-concatenate (reverse ls))
3982 If the optional argument @var{final_string} is specified, it is
3983 consed onto the beginning to @var{ls} before performing the
3984 list-reverse and string-concatenate operations. If @var{end}
3985 is given, only the characters of @var{final_string} up to index
3988 Guaranteed to return a freshly allocated string.
3991 @deffn {Scheme Procedure} string-concatenate/shared ls
3992 @deffnx {C Function} scm_string_concatenate_shared (ls)
3993 Like @code{string-concatenate}, but the result may share memory
3994 with the strings in the list @var{ls}.
3997 @deffn {Scheme Procedure} string-concatenate-reverse/shared ls [final_string [end]]
3998 @deffnx {C Function} scm_string_concatenate_reverse_shared (ls, final_string, end)
3999 Like @code{string-concatenate-reverse}, but the result may
4000 share memory with the strings in the @var{ls} arguments.
4003 @node Mapping Folding and Unfolding
4004 @subsubsection Mapping, Folding, and Unfolding
4006 @deffn {Scheme Procedure} string-map proc s [start [end]]
4007 @deffnx {C Function} scm_string_map (proc, s, start, end)
4008 @var{proc} is a char->char procedure, it is mapped over
4009 @var{s}. The order in which the procedure is applied to the
4010 string elements is not specified.
4013 @deffn {Scheme Procedure} string-map! proc s [start [end]]
4014 @deffnx {C Function} scm_string_map_x (proc, s, start, end)
4015 @var{proc} is a char->char procedure, it is mapped over
4016 @var{s}. The order in which the procedure is applied to the
4017 string elements is not specified. The string @var{s} is
4018 modified in-place, the return value is not specified.
4021 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
4022 @deffnx {C Function} scm_string_for_each (proc, s, start, end)
4023 @var{proc} is mapped over @var{s} in left-to-right order. The
4024 return value is not specified.
4027 @deffn {Scheme Procedure} string-for-each-index proc s [start [end]]
4028 @deffnx {C Function} scm_string_for_each_index (proc, s, start, end)
4029 Call @code{(@var{proc} i)} for each index i in @var{s}, from left to
4032 For example, to change characters to alternately upper and lower case,
4035 (define str (string-copy "studly"))
4036 (string-for-each-index
4039 ((if (even? i) char-upcase char-downcase)
4040 (string-ref str i))))
4042 str @result{} "StUdLy"
4046 @deffn {Scheme Procedure} string-fold kons knil s [start [end]]
4047 @deffnx {C Function} scm_string_fold (kons, knil, s, start, end)
4048 Fold @var{kons} over the characters of @var{s}, with @var{knil}
4049 as the terminating element, from left to right. @var{kons}
4050 must expect two arguments: The actual character and the last
4051 result of @var{kons}' application.
4054 @deffn {Scheme Procedure} string-fold-right kons knil s [start [end]]
4055 @deffnx {C Function} scm_string_fold_right (kons, knil, s, start, end)
4056 Fold @var{kons} over the characters of @var{s}, with @var{knil}
4057 as the terminating element, from right to left. @var{kons}
4058 must expect two arguments: The actual character and the last
4059 result of @var{kons}' application.
4062 @deffn {Scheme Procedure} string-unfold p f g seed [base [make_final]]
4063 @deffnx {C Function} scm_string_unfold (p, f, g, seed, base, make_final)
4065 @item @var{g} is used to generate a series of @emph{seed}
4066 values from the initial @var{seed}: @var{seed}, (@var{g}
4067 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
4069 @item @var{p} tells us when to stop -- when it returns true
4070 when applied to one of these seed values.
4071 @item @var{f} maps each seed value to the corresponding
4072 character in the result string. These chars are assembled
4073 into the string in a left-to-right order.
4074 @item @var{base} is the optional initial/leftmost portion
4075 of the constructed string; it default to the empty
4077 @item @var{make_final} is applied to the terminal seed
4078 value (on which @var{p} returns true) to produce
4079 the final/rightmost portion of the constructed string.
4080 The default is nothing extra.
4084 @deffn {Scheme Procedure} string-unfold-right p f g seed [base [make_final]]
4085 @deffnx {C Function} scm_string_unfold_right (p, f, g, seed, base, make_final)
4087 @item @var{g} is used to generate a series of @emph{seed}
4088 values from the initial @var{seed}: @var{seed}, (@var{g}
4089 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
4091 @item @var{p} tells us when to stop -- when it returns true
4092 when applied to one of these seed values.
4093 @item @var{f} maps each seed value to the corresponding
4094 character in the result string. These chars are assembled
4095 into the string in a right-to-left order.
4096 @item @var{base} is the optional initial/rightmost portion
4097 of the constructed string; it default to the empty
4099 @item @var{make_final} is applied to the terminal seed
4100 value (on which @var{p} returns true) to produce
4101 the final/leftmost portion of the constructed string.
4102 It defaults to @code{(lambda (x) )}.
4106 @node Miscellaneous String Operations
4107 @subsubsection Miscellaneous String Operations
4109 @deffn {Scheme Procedure} xsubstring s from [to [start [end]]]
4110 @deffnx {C Function} scm_xsubstring (s, from, to, start, end)
4111 This is the @emph{extended substring} procedure that implements
4112 replicated copying of a substring of some string.
4114 @var{s} is a string, @var{start} and @var{end} are optional
4115 arguments that demarcate a substring of @var{s}, defaulting to
4116 0 and the length of @var{s}. Replicate this substring up and
4117 down index space, in both the positive and negative directions.
4118 @code{xsubstring} returns the substring of this string
4119 beginning at index @var{from}, and ending at @var{to}, which
4120 defaults to @var{from} + (@var{end} - @var{start}).
4123 @deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto [start [end]]]
4124 @deffnx {C Function} scm_string_xcopy_x (target, tstart, s, sfrom, sto, start, end)
4125 Exactly the same as @code{xsubstring}, but the extracted text
4126 is written into the string @var{target} starting at index
4127 @var{tstart}. The operation is not defined if @code{(eq?
4128 @var{target} @var{s})} or these arguments share storage -- you
4129 cannot copy a string on top of itself.
4132 @deffn {Scheme Procedure} string-replace s1 s2 [start1 [end1 [start2 [end2]]]]
4133 @deffnx {C Function} scm_string_replace (s1, s2, start1, end1, start2, end2)
4134 Return the string @var{s1}, but with the characters
4135 @var{start1} @dots{} @var{end1} replaced by the characters
4136 @var{start2} @dots{} @var{end2} from @var{s2}.
4139 @deffn {Scheme Procedure} string-tokenize s [token_set [start [end]]]
4140 @deffnx {C Function} scm_string_tokenize (s, token_set, start, end)
4141 Split the string @var{s} into a list of substrings, where each
4142 substring is a maximal non-empty contiguous sequence of
4143 characters from the character set @var{token_set}, which
4144 defaults to @code{char-set:graphic}.
4145 If @var{start} or @var{end} indices are provided, they restrict
4146 @code{string-tokenize} to operating on the indicated substring
4150 @deffn {Scheme Procedure} string-filter char_pred s [start [end]]
4151 @deffnx {C Function} scm_string_filter (char_pred, s, start, end)
4152 Filter the string @var{s}, retaining only those characters which
4153 satisfy @var{char_pred}.
4155 If @var{char_pred} is a procedure, it is applied to each character as
4156 a predicate, if it is a character, it is tested for equality and if it
4157 is a character set, it is tested for membership.
4160 @deffn {Scheme Procedure} string-delete char_pred s [start [end]]
4161 @deffnx {C Function} scm_string_delete (char_pred, s, start, end)
4162 Delete characters satisfying @var{char_pred} from @var{s}.
4164 If @var{char_pred} is a procedure, it is applied to each character as
4165 a predicate, if it is a character, it is tested for equality and if it
4166 is a character set, it is tested for membership.
4169 @node Representing Strings as Bytes
4170 @subsubsection Representing Strings as Bytes
4172 Out in the cold world outside of Guile, not all strings are treated in
4173 the same way. Out there there are only bytes, and there are many ways
4174 of representing a strings (sequences of characters) as binary data
4175 (sequences of bytes).
4177 As a user, usually you don't have to think about this very much. When
4178 you type on your keyboard, your system encodes your keystrokes as bytes
4179 according to the locale that you have configured on your computer.
4180 Guile uses the locale to decode those bytes back into characters --
4181 hopefully the same characters that you typed in.
4183 All is not so clear when dealing with a system with multiple users, such
4184 as a web server. Your web server might get a request from one user for
4185 data encoded in the ISO-8859-1 character set, and then another request
4186 from a different user for UTF-8 data.
4189 @cindex character encoding
4190 Guile provides an @dfn{iconv} module for converting between strings and
4191 sequences of bytes. @xref{Bytevectors}, for more on how Guile
4192 represents raw byte sequences. This module gets its name from the
4193 common @sc{unix} command of the same name.
4195 Note that often it is sufficient to just read and write strings from
4196 ports instead of using these functions. To do this, specify the port
4197 encoding using @code{set-port-encoding!}. @xref{Ports}, for more on
4198 ports and character encodings.
4200 Unlike the rest of the procedures in this section, you have to load the
4201 @code{iconv} module before having access to these procedures:
4204 (use-modules (ice-9 iconv))
4207 @deffn string->bytevector string encoding [conversion-strategy]
4208 Encode @var{string} as a sequence of bytes.
4210 The string will be encoded in the character set specified by the
4211 @var{encoding} string. If the string has characters that cannot be
4212 represented in the encoding, by default this procedure raises an
4213 @code{encoding-error}. Pass a @var{conversion-strategy} argument to
4214 specify other behaviors.
4216 The return value is a bytevector. @xref{Bytevectors}, for more on
4217 bytevectors. @xref{Ports}, for more on character encodings and
4218 conversion strategies.
4221 @deffn bytevector->string bytevector encoding [conversion-strategy]
4222 Decode @var{bytevector} into a string.
4224 The bytes will be decoded from the character set by the @var{encoding}
4225 string. If the bytes do not form a valid encoding, by default this
4226 procedure raises an @code{decoding-error}. As with
4227 @code{string->bytevector}, pass the optional @var{conversion-strategy}
4228 argument to modify this behavior. @xref{Ports}, for more on character
4229 encodings and conversion strategies.
4232 @deffn call-with-output-encoded-string encoding proc [conversion-strategy]
4233 Like @code{call-with-output-string}, but instead of returning a string,
4234 returns a encoding of the string according to @var{encoding}, as a
4235 bytevector. This procedure can be more efficient than collecting a
4236 string and then converting it via @code{string->bytevector}.
4239 @node Conversion to/from C
4240 @subsubsection Conversion to/from C
4242 When creating a Scheme string from a C string or when converting a
4243 Scheme string to a C string, the concept of character encoding becomes
4246 In C, a string is just a sequence of bytes, and the character encoding
4247 describes the relation between these bytes and the actual characters
4248 that make up the string. For Scheme strings, character encoding is not
4249 an issue (most of the time), since in Scheme you usually treat strings
4250 as character sequences, not byte sequences.
4252 Converting to C and converting from C each have their own challenges.
4254 When converting from C to Scheme, it is important that the sequence of
4255 bytes in the C string be valid with respect to its encoding. ASCII
4256 strings, for example, can't have any bytes greater than 127. An ASCII
4257 byte greater than 127 is considered @emph{ill-formed} and cannot be
4258 converted into a Scheme character.
4260 Problems can occur in the reverse operation as well. Not all character
4261 encodings can hold all possible Scheme characters. Some encodings, like
4262 ASCII for example, can only describe a small subset of all possible
4263 characters. So, when converting to C, one must first decide what to do
4264 with Scheme characters that can't be represented in the C string.
4266 Converting a Scheme string to a C string will often allocate fresh
4267 memory to hold the result. You must take care that this memory is
4268 properly freed eventually. In many cases, this can be achieved by
4269 using @code{scm_dynwind_free} inside an appropriate dynwind context,
4270 @xref{Dynamic Wind}.
4272 @deftypefn {C Function} SCM scm_from_locale_string (const char *str)
4273 @deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
4274 Creates a new Scheme string that has the same contents as @var{str} when
4275 interpreted in the character encoding of the current locale.
4277 For @code{scm_from_locale_string}, @var{str} must be null-terminated.
4279 For @code{scm_from_locale_stringn}, @var{len} specifies the length of
4280 @var{str} in bytes, and @var{str} does not need to be null-terminated.
4281 If @var{len} is @code{(size_t)-1}, then @var{str} does need to be
4282 null-terminated and the real length will be found with @code{strlen}.
4284 If the C string is ill-formed, an error will be raised.
4286 Note that these functions should @emph{not} be used to convert C string
4287 constants, because there is no guarantee that the current locale will
4288 match that of the source code. To convert C string constants, use
4289 @code{scm_from_latin1_string}, @code{scm_from_utf8_string} or
4290 @code{scm_from_utf32_string}.
4293 @deftypefn {C Function} SCM scm_take_locale_string (char *str)
4294 @deftypefnx {C Function} SCM scm_take_locale_stringn (char *str, size_t len)
4295 Like @code{scm_from_locale_string} and @code{scm_from_locale_stringn},
4296 respectively, but also frees @var{str} with @code{free} eventually.
4297 Thus, you can use this function when you would free @var{str} anyway
4298 immediately after creating the Scheme string. In certain cases, Guile
4299 can then use @var{str} directly as its internal representation.
4302 @deftypefn {C Function} {char *} scm_to_locale_string (SCM str)
4303 @deftypefnx {C Function} {char *} scm_to_locale_stringn (SCM str, size_t *lenp)
4304 Returns a C string with the same contents as @var{str} in the character
4305 encoding of the current locale. The C string must be freed with
4306 @code{free} eventually, maybe by using @code{scm_dynwind_free},
4307 @xref{Dynamic Wind}.
4309 For @code{scm_to_locale_string}, the returned string is
4310 null-terminated and an error is signalled when @var{str} contains
4311 @code{#\nul} characters.
4313 For @code{scm_to_locale_stringn} and @var{lenp} not @code{NULL},
4314 @var{str} might contain @code{#\nul} characters and the length of the
4315 returned string in bytes is stored in @code{*@var{lenp}}. The
4316 returned string will not be null-terminated in this case. If
4317 @var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
4318 @code{scm_to_locale_string}.
4320 If a character in @var{str} cannot be represented in the character
4321 encoding of the current locale, the default port conversion strategy is
4322 used. @xref{Ports}, for more on conversion strategies.
4324 If the conversion strategy is @code{error}, an error will be raised. If
4325 it is @code{substitute}, a replacement character, such as a question
4326 mark, will be inserted in its place. If it is @code{escape}, a hex
4327 escape will be inserted in its place.
4330 @deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
4331 Puts @var{str} as a C string in the current locale encoding into the
4332 memory pointed to by @var{buf}. The buffer at @var{buf} has room for
4333 @var{max_len} bytes and @code{scm_to_local_stringbuf} will never store
4334 more than that. No terminating @code{'\0'} will be stored.
4336 The return value of @code{scm_to_locale_stringbuf} is the number of
4337 bytes that are needed for all of @var{str}, regardless of whether
4338 @var{buf} was large enough to hold them. Thus, when the return value
4339 is larger than @var{max_len}, only @var{max_len} bytes have been
4340 stored and you probably need to try again with a larger buffer.
4343 For most situations, string conversion should occur using the current
4344 locale, such as with the functions above. But there may be cases where
4345 one wants to convert strings from a character encoding other than the
4346 locale's character encoding. For these cases, the lower-level functions
4347 @code{scm_to_stringn} and @code{scm_from_stringn} are provided. These
4348 functions should seldom be necessary if one is properly using locales.
4350 @deftp {C Type} scm_t_string_failed_conversion_handler
4351 This is an enumerated type that can take one of three values:
4352 @code{SCM_FAILED_CONVERSION_ERROR},
4353 @code{SCM_FAILED_CONVERSION_QUESTION_MARK}, and
4354 @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE}. They are used to indicate
4355 a strategy for handling characters that cannot be converted to or from a
4356 given character encoding. @code{SCM_FAILED_CONVERSION_ERROR} indicates
4357 that a conversion should throw an error if some characters cannot be
4358 converted. @code{SCM_FAILED_CONVERSION_QUESTION_MARK} indicates that a
4359 conversion should replace unconvertable characters with the question
4360 mark character. And, @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE}
4361 requests that a conversion should replace an unconvertable character
4362 with an escape sequence.
4364 While all three strategies apply when converting Scheme strings to C,
4365 only @code{SCM_FAILED_CONVERSION_ERROR} and
4366 @code{SCM_FAILED_CONVERSION_QUESTION_MARK} can be used when converting C
4370 @deftypefn {C Function} char *scm_to_stringn (SCM str, size_t *lenp, const char *encoding, scm_t_string_failed_conversion_handler handler)
4371 This function returns a newly allocated C string from the Guile string
4372 @var{str}. The length of the returned string in bytes will be returned in
4373 @var{lenp}. The character encoding of the C string is passed as the ASCII,
4374 null-terminated C string @var{encoding}. The @var{handler} parameter
4375 gives a strategy for dealing with characters that cannot be converted
4376 into @var{encoding}.
4378 If @var{lenp} is @code{NULL}, this function will return a null-terminated C
4379 string. It will throw an error if the string contains a null
4382 The Scheme interface to this function is @code{string->bytevector}, from the
4383 @code{ice-9 iconv} module. @xref{Representing Strings as Bytes}.
4386 @deftypefn {C Function} SCM scm_from_stringn (const char *str, size_t len, const char *encoding, scm_t_string_failed_conversion_handler handler)
4387 This function returns a scheme string from the C string @var{str}. The
4388 length in bytes of the C string is input as @var{len}. The encoding of the C
4389 string is passed as the ASCII, null-terminated C string @code{encoding}.
4390 The @var{handler} parameters suggests a strategy for dealing with
4391 unconvertable characters.
4393 The Scheme interface to this function is @code{bytevector->string}.
4394 @xref{Representing Strings as Bytes}.
4397 The following conversion functions are provided as a convenience for the
4398 most commonly used encodings.
4400 @deftypefn {C Function} SCM scm_from_latin1_string (const char *str)
4401 @deftypefnx {C Function} SCM scm_from_utf8_string (const char *str)
4402 @deftypefnx {C Function} SCM scm_from_utf32_string (const scm_t_wchar *str)
4403 Return a scheme string from the null-terminated C string @var{str},
4404 which is ISO-8859-1-, UTF-8-, or UTF-32-encoded. These functions should
4405 be used to convert hard-coded C string constants into Scheme strings.
4408 @deftypefn {C Function} SCM scm_from_latin1_stringn (const char *str, size_t len)
4409 @deftypefnx {C Function} SCM scm_from_utf8_stringn (const char *str, size_t len)
4410 @deftypefnx {C Function} SCM scm_from_utf32_stringn (const scm_t_wchar *str, size_t len)
4411 Return a scheme string from C string @var{str}, which is ISO-8859-1-,
4412 UTF-8-, or UTF-32-encoded, of length @var{len}. @var{len} is the number
4413 of bytes pointed to by @var{str} for @code{scm_from_latin1_stringn} and
4414 @code{scm_from_utf8_stringn}; it is the number of elements (code points)
4415 in @var{str} in the case of @code{scm_from_utf32_stringn}.
4418 @deftypefn {C function} char *scm_to_latin1_stringn (SCM str, size_t *lenp)
4419 @deftypefnx {C function} char *scm_to_utf8_stringn (SCM str, size_t *lenp)
4420 @deftypefnx {C function} scm_t_wchar *scm_to_utf32_stringn (SCM str, size_t *lenp)
4421 Return a newly allocated, ISO-8859-1-, UTF-8-, or UTF-32-encoded C string
4422 from Scheme string @var{str}. An error is thrown when @var{str}
4423 cannot be converted to the specified encoding. If @var{lenp} is
4424 @code{NULL}, the returned C string will be null terminated, and an error
4425 will be thrown if the C string would otherwise contain null
4426 characters. If @var{lenp} is not @code{NULL}, the string is not null terminated,
4427 and the length of the returned string is returned in @var{lenp}. The length
4428 returned is the number of bytes for @code{scm_to_latin1_stringn} and
4429 @code{scm_to_utf8_stringn}; it is the number of elements (code points)
4430 for @code{scm_to_utf32_stringn}.
4433 @node String Internals
4434 @subsubsection String Internals
4436 Guile stores each string in memory as a contiguous array of Unicode code
4437 points along with an associated set of attributes. If all of the code
4438 points of a string have an integer range between 0 and 255 inclusive,
4439 the code point array is stored as one byte per code point: it is stored
4440 as an ISO-8859-1 (aka Latin-1) string. If any of the code points of the
4441 string has an integer value greater that 255, the code point array is
4442 stored as four bytes per code point: it is stored as a UTF-32 string.
4444 Conversion between the one-byte-per-code-point and
4445 four-bytes-per-code-point representations happens automatically as
4448 No API is provided to set the internal representation of strings;
4449 however, there are pair of procedures available to query it. These are
4450 debugging procedures. Using them in production code is discouraged,
4451 since the details of Guile's internal representation of strings may
4452 change from release to release.
4454 @deffn {Scheme Procedure} string-bytes-per-char str
4455 @deffnx {C Function} scm_string_bytes_per_char (str)
4456 Return the number of bytes used to encode a Unicode code point in string
4457 @var{str}. The result is one or four.
4460 @deffn {Scheme Procedure} %string-dump str
4461 @deffnx {C Function} scm_sys_string_dump (str)
4462 Returns an association list containing debugging information for
4463 @var{str}. The association list has the following entries.
4470 The start index of the string into its stringbuf
4473 The length of the string
4476 If this string is a substring, it returns its
4477 parent string. Otherwise, it returns @code{#f}
4480 @code{#t} if the string is read-only
4482 @item stringbuf-chars
4483 A new string containing this string's stringbuf's characters
4485 @item stringbuf-length
4486 The number of characters in this stringbuf
4488 @item stringbuf-shared
4489 @code{#t} if this stringbuf is shared
4491 @item stringbuf-wide
4492 @code{#t} if this stringbuf's characters are stored in a 32-bit buffer,
4493 or @code{#f} if they are stored in an 8-bit buffer
4499 @subsection Bytevectors
4504 A @dfn{bytevector} is a raw bit string. The @code{(rnrs bytevectors)}
4505 module provides the programming interface specified by the
4506 @uref{http://www.r6rs.org/, Revised^6 Report on the Algorithmic Language
4507 Scheme (R6RS)}. It contains procedures to manipulate bytevectors and
4508 interpret their contents in a number of ways: bytevector contents can be
4509 accessed as signed or unsigned integer of various sizes and endianness,
4510 as IEEE-754 floating point numbers, or as strings. It is a useful tool
4511 to encode and decode binary data.
4513 The R6RS (Section 4.3.4) specifies an external representation for
4514 bytevectors, whereby the octets (integers in the range 0--255) contained
4515 in the bytevector are represented as a list prefixed by @code{#vu8}:
4521 denotes a 3-byte bytevector containing the octets 1, 53, and 204. Like
4522 string literals, booleans, etc., bytevectors are ``self-quoting'', i.e.,
4523 they do not need to be quoted:
4527 @result{} #vu8(1 53 204)
4530 Bytevectors can be used with the binary input/output primitives of the
4531 R6RS (@pxref{R6RS I/O Ports}).
4534 * Bytevector Endianness:: Dealing with byte order.
4535 * Bytevector Manipulation:: Creating, copying, manipulating bytevectors.
4536 * Bytevectors as Integers:: Interpreting bytes as integers.
4537 * Bytevectors and Integer Lists:: Converting to/from an integer list.
4538 * Bytevectors as Floats:: Interpreting bytes as real numbers.
4539 * Bytevectors as Strings:: Interpreting bytes as Unicode strings.
4540 * Bytevectors as Generalized Vectors:: Guile extension to the bytevector API.
4541 * Bytevectors as Uniform Vectors:: Bytevectors and SRFI-4.
4544 @node Bytevector Endianness
4545 @subsubsection Endianness
4551 Some of the following procedures take an @var{endianness} parameter.
4552 The @dfn{endianness} is defined as the order of bytes in multi-byte
4553 numbers: numbers encoded in @dfn{big endian} have their most
4554 significant bytes written first, whereas numbers encoded in
4555 @dfn{little endian} have their least significant bytes
4556 first@footnote{Big-endian and little-endian are the most common
4557 ``endiannesses'', but others do exist. For instance, the GNU MP
4558 library allows @dfn{word order} to be specified independently of
4559 @dfn{byte order} (@pxref{Integer Import and Export,,, gmp, The GNU
4560 Multiple Precision Arithmetic Library Manual}).}.
4562 Little-endian is the native endianness of the IA32 architecture and
4563 its derivatives, while big-endian is native to SPARC and PowerPC,
4564 among others. The @code{native-endianness} procedure returns the
4565 native endianness of the machine it runs on.
4567 @deffn {Scheme Procedure} native-endianness
4568 @deffnx {C Function} scm_native_endianness ()
4569 Return a value denoting the native endianness of the host machine.
4572 @deffn {Scheme Macro} endianness symbol
4573 Return an object denoting the endianness specified by @var{symbol}. If
4574 @var{symbol} is neither @code{big} nor @code{little} then an error is
4575 raised at expand-time.
4578 @defvr {C Variable} scm_endianness_big
4579 @defvrx {C Variable} scm_endianness_little
4580 The objects denoting big- and little-endianness, respectively.
4584 @node Bytevector Manipulation
4585 @subsubsection Manipulating Bytevectors
4587 Bytevectors can be created, copied, and analyzed with the following
4588 procedures and C functions.
4590 @deffn {Scheme Procedure} make-bytevector len [fill]
4591 @deffnx {C Function} scm_make_bytevector (len, fill)
4592 @deffnx {C Function} scm_c_make_bytevector (size_t len)
4593 Return a new bytevector of @var{len} bytes. Optionally, if @var{fill}
4594 is given, fill it with @var{fill}; @var{fill} must be in the range
4598 @deffn {Scheme Procedure} bytevector? obj
4599 @deffnx {C Function} scm_bytevector_p (obj)
4600 Return true if @var{obj} is a bytevector.
4603 @deftypefn {C Function} int scm_is_bytevector (SCM obj)
4604 Equivalent to @code{scm_is_true (scm_bytevector_p (obj))}.
4607 @deffn {Scheme Procedure} bytevector-length bv
4608 @deffnx {C Function} scm_bytevector_length (bv)
4609 Return the length in bytes of bytevector @var{bv}.
4612 @deftypefn {C Function} size_t scm_c_bytevector_length (SCM bv)
4613 Likewise, return the length in bytes of bytevector @var{bv}.
4616 @deffn {Scheme Procedure} bytevector=? bv1 bv2
4617 @deffnx {C Function} scm_bytevector_eq_p (bv1, bv2)
4618 Return is @var{bv1} equals to @var{bv2}---i.e., if they have the same
4619 length and contents.
4622 @deffn {Scheme Procedure} bytevector-fill! bv fill
4623 @deffnx {C Function} scm_bytevector_fill_x (bv, fill)
4624 Fill bytevector @var{bv} with @var{fill}, a byte.
4627 @deffn {Scheme Procedure} bytevector-copy! source source-start target target-start len
4628 @deffnx {C Function} scm_bytevector_copy_x (source, source_start, target, target_start, len)
4629 Copy @var{len} bytes from @var{source} into @var{target}, starting
4630 reading from @var{source-start} (a positive index within @var{source})
4631 and start writing at @var{target-start}. It is permitted for the
4632 @var{source} and @var{target} regions to overlap.
4635 @deffn {Scheme Procedure} bytevector-copy bv
4636 @deffnx {C Function} scm_bytevector_copy (bv)
4637 Return a newly allocated copy of @var{bv}.
4640 @deftypefn {C Function} scm_t_uint8 scm_c_bytevector_ref (SCM bv, size_t index)
4641 Return the byte at @var{index} in bytevector @var{bv}.
4644 @deftypefn {C Function} void scm_c_bytevector_set_x (SCM bv, size_t index, scm_t_uint8 value)
4645 Set the byte at @var{index} in @var{bv} to @var{value}.
4648 Low-level C macros are available. They do not perform any
4649 type-checking; as such they should be used with care.
4651 @deftypefn {C Macro} size_t SCM_BYTEVECTOR_LENGTH (bv)
4652 Return the length in bytes of bytevector @var{bv}.
4655 @deftypefn {C Macro} {signed char *} SCM_BYTEVECTOR_CONTENTS (bv)
4656 Return a pointer to the contents of bytevector @var{bv}.
4660 @node Bytevectors as Integers
4661 @subsubsection Interpreting Bytevector Contents as Integers
4663 The contents of a bytevector can be interpreted as a sequence of
4664 integers of any given size, sign, and endianness.
4667 (let ((bv (make-bytevector 4)))
4668 (bytevector-u8-set! bv 0 #x12)
4669 (bytevector-u8-set! bv 1 #x34)
4670 (bytevector-u8-set! bv 2 #x56)
4671 (bytevector-u8-set! bv 3 #x78)
4673 (map (lambda (number)
4674 (number->string number 16))
4675 (list (bytevector-u8-ref bv 0)
4676 (bytevector-u16-ref bv 0 (endianness big))
4677 (bytevector-u32-ref bv 0 (endianness little)))))
4679 @result{} ("12" "1234" "78563412")
4682 The most generic procedures to interpret bytevector contents as integers
4683 are described below.
4685 @deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
4686 @deffnx {C Function} scm_bytevector_uint_ref (bv, index, endianness, size)
4687 Return the @var{size}-byte long unsigned integer at index @var{index} in
4688 @var{bv}, decoded according to @var{endianness}.
4691 @deffn {Scheme Procedure} bytevector-sint-ref bv index endianness size
4692 @deffnx {C Function} scm_bytevector_sint_ref (bv, index, endianness, size)
4693 Return the @var{size}-byte long signed integer at index @var{index} in
4694 @var{bv}, decoded according to @var{endianness}.
4697 @deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
4698 @deffnx {C Function} scm_bytevector_uint_set_x (bv, index, value, endianness, size)
4699 Set the @var{size}-byte long unsigned integer at @var{index} to
4700 @var{value}, encoded according to @var{endianness}.
4703 @deffn {Scheme Procedure} bytevector-sint-set! bv index value endianness size
4704 @deffnx {C Function} scm_bytevector_sint_set_x (bv, index, value, endianness, size)
4705 Set the @var{size}-byte long signed integer at @var{index} to
4706 @var{value}, encoded according to @var{endianness}.
4709 The following procedures are similar to the ones above, but specialized
4710 to a given integer size:
4712 @deffn {Scheme Procedure} bytevector-u8-ref bv index
4713 @deffnx {Scheme Procedure} bytevector-s8-ref bv index
4714 @deffnx {Scheme Procedure} bytevector-u16-ref bv index endianness
4715 @deffnx {Scheme Procedure} bytevector-s16-ref bv index endianness
4716 @deffnx {Scheme Procedure} bytevector-u32-ref bv index endianness
4717 @deffnx {Scheme Procedure} bytevector-s32-ref bv index endianness
4718 @deffnx {Scheme Procedure} bytevector-u64-ref bv index endianness
4719 @deffnx {Scheme Procedure} bytevector-s64-ref bv index endianness
4720 @deffnx {C Function} scm_bytevector_u8_ref (bv, index)
4721 @deffnx {C Function} scm_bytevector_s8_ref (bv, index)
4722 @deffnx {C Function} scm_bytevector_u16_ref (bv, index, endianness)
4723 @deffnx {C Function} scm_bytevector_s16_ref (bv, index, endianness)
4724 @deffnx {C Function} scm_bytevector_u32_ref (bv, index, endianness)
4725 @deffnx {C Function} scm_bytevector_s32_ref (bv, index, endianness)
4726 @deffnx {C Function} scm_bytevector_u64_ref (bv, index, endianness)
4727 @deffnx {C Function} scm_bytevector_s64_ref (bv, index, endianness)
4728 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
4729 16, 32 or 64) from @var{bv} at @var{index}, decoded according to
4733 @deffn {Scheme Procedure} bytevector-u8-set! bv index value
4734 @deffnx {Scheme Procedure} bytevector-s8-set! bv index value
4735 @deffnx {Scheme Procedure} bytevector-u16-set! bv index value endianness
4736 @deffnx {Scheme Procedure} bytevector-s16-set! bv index value endianness
4737 @deffnx {Scheme Procedure} bytevector-u32-set! bv index value endianness
4738 @deffnx {Scheme Procedure} bytevector-s32-set! bv index value endianness
4739 @deffnx {Scheme Procedure} bytevector-u64-set! bv index value endianness
4740 @deffnx {Scheme Procedure} bytevector-s64-set! bv index value endianness
4741 @deffnx {C Function} scm_bytevector_u8_set_x (bv, index, value)
4742 @deffnx {C Function} scm_bytevector_s8_set_x (bv, index, value)
4743 @deffnx {C Function} scm_bytevector_u16_set_x (bv, index, value, endianness)
4744 @deffnx {C Function} scm_bytevector_s16_set_x (bv, index, value, endianness)
4745 @deffnx {C Function} scm_bytevector_u32_set_x (bv, index, value, endianness)
4746 @deffnx {C Function} scm_bytevector_s32_set_x (bv, index, value, endianness)
4747 @deffnx {C Function} scm_bytevector_u64_set_x (bv, index, value, endianness)
4748 @deffnx {C Function} scm_bytevector_s64_set_x (bv, index, value, endianness)
4749 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
4750 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to
4754 Finally, a variant specialized for the host's endianness is available
4755 for each of these functions (with the exception of the @code{u8}
4756 accessors, for obvious reasons):
4758 @deffn {Scheme Procedure} bytevector-u16-native-ref bv index
4759 @deffnx {Scheme Procedure} bytevector-s16-native-ref bv index
4760 @deffnx {Scheme Procedure} bytevector-u32-native-ref bv index
4761 @deffnx {Scheme Procedure} bytevector-s32-native-ref bv index
4762 @deffnx {Scheme Procedure} bytevector-u64-native-ref bv index
4763 @deffnx {Scheme Procedure} bytevector-s64-native-ref bv index
4764 @deffnx {C Function} scm_bytevector_u16_native_ref (bv, index)
4765 @deffnx {C Function} scm_bytevector_s16_native_ref (bv, index)
4766 @deffnx {C Function} scm_bytevector_u32_native_ref (bv, index)
4767 @deffnx {C Function} scm_bytevector_s32_native_ref (bv, index)
4768 @deffnx {C Function} scm_bytevector_u64_native_ref (bv, index)
4769 @deffnx {C Function} scm_bytevector_s64_native_ref (bv, index)
4770 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
4771 16, 32 or 64) from @var{bv} at @var{index}, decoded according to the
4772 host's native endianness.
4775 @deffn {Scheme Procedure} bytevector-u16-native-set! bv index value
4776 @deffnx {Scheme Procedure} bytevector-s16-native-set! bv index value
4777 @deffnx {Scheme Procedure} bytevector-u32-native-set! bv index value
4778 @deffnx {Scheme Procedure} bytevector-s32-native-set! bv index value
4779 @deffnx {Scheme Procedure} bytevector-u64-native-set! bv index value
4780 @deffnx {Scheme Procedure} bytevector-s64-native-set! bv index value
4781 @deffnx {C Function} scm_bytevector_u16_native_set_x (bv, index, value)
4782 @deffnx {C Function} scm_bytevector_s16_native_set_x (bv, index, value)
4783 @deffnx {C Function} scm_bytevector_u32_native_set_x (bv, index, value)
4784 @deffnx {C Function} scm_bytevector_s32_native_set_x (bv, index, value)
4785 @deffnx {C Function} scm_bytevector_u64_native_set_x (bv, index, value)
4786 @deffnx {C Function} scm_bytevector_s64_native_set_x (bv, index, value)
4787 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
4788 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to the
4789 host's native endianness.
4793 @node Bytevectors and Integer Lists
4794 @subsubsection Converting Bytevectors to/from Integer Lists
4796 Bytevector contents can readily be converted to/from lists of signed or
4800 (bytevector->sint-list (u8-list->bytevector (make-list 4 255))
4801 (endianness little) 2)
4805 @deffn {Scheme Procedure} bytevector->u8-list bv
4806 @deffnx {C Function} scm_bytevector_to_u8_list (bv)
4807 Return a newly allocated list of unsigned 8-bit integers from the
4808 contents of @var{bv}.
4811 @deffn {Scheme Procedure} u8-list->bytevector lst
4812 @deffnx {C Function} scm_u8_list_to_bytevector (lst)
4813 Return a newly allocated bytevector consisting of the unsigned 8-bit
4814 integers listed in @var{lst}.
4817 @deffn {Scheme Procedure} bytevector->uint-list bv endianness size
4818 @deffnx {C Function} scm_bytevector_to_uint_list (bv, endianness, size)
4819 Return a list of unsigned integers of @var{size} bytes representing the
4820 contents of @var{bv}, decoded according to @var{endianness}.
4823 @deffn {Scheme Procedure} bytevector->sint-list bv endianness size
4824 @deffnx {C Function} scm_bytevector_to_sint_list (bv, endianness, size)
4825 Return a list of signed integers of @var{size} bytes representing the
4826 contents of @var{bv}, decoded according to @var{endianness}.
4829 @deffn {Scheme Procedure} uint-list->bytevector lst endianness size
4830 @deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
4831 Return a new bytevector containing the unsigned integers listed in
4832 @var{lst} and encoded on @var{size} bytes according to @var{endianness}.
4835 @deffn {Scheme Procedure} sint-list->bytevector lst endianness size
4836 @deffnx {C Function} scm_sint_list_to_bytevector (lst, endianness, size)
4837 Return a new bytevector containing the signed integers listed in
4838 @var{lst} and encoded on @var{size} bytes according to @var{endianness}.
4841 @node Bytevectors as Floats
4842 @subsubsection Interpreting Bytevector Contents as Floating Point Numbers
4844 @cindex IEEE-754 floating point numbers
4846 Bytevector contents can also be accessed as IEEE-754 single- or
4847 double-precision floating point numbers (respectively 32 and 64-bit
4848 long) using the procedures described here.
4850 @deffn {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
4851 @deffnx {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
4852 @deffnx {C Function} scm_bytevector_ieee_single_ref (bv, index, endianness)
4853 @deffnx {C Function} scm_bytevector_ieee_double_ref (bv, index, endianness)
4854 Return the IEEE-754 single-precision floating point number from @var{bv}
4855 at @var{index} according to @var{endianness}.
4858 @deffn {Scheme Procedure} bytevector-ieee-single-set! bv index value endianness
4859 @deffnx {Scheme Procedure} bytevector-ieee-double-set! bv index value endianness
4860 @deffnx {C Function} scm_bytevector_ieee_single_set_x (bv, index, value, endianness)
4861 @deffnx {C Function} scm_bytevector_ieee_double_set_x (bv, index, value, endianness)
4862 Store real number @var{value} in @var{bv} at @var{index} according to
4866 Specialized procedures are also available:
4868 @deffn {Scheme Procedure} bytevector-ieee-single-native-ref bv index
4869 @deffnx {Scheme Procedure} bytevector-ieee-double-native-ref bv index
4870 @deffnx {C Function} scm_bytevector_ieee_single_native_ref (bv, index)
4871 @deffnx {C Function} scm_bytevector_ieee_double_native_ref (bv, index)
4872 Return the IEEE-754 single-precision floating point number from @var{bv}
4873 at @var{index} according to the host's native endianness.
4876 @deffn {Scheme Procedure} bytevector-ieee-single-native-set! bv index value
4877 @deffnx {Scheme Procedure} bytevector-ieee-double-native-set! bv index value
4878 @deffnx {C Function} scm_bytevector_ieee_single_native_set_x (bv, index, value)
4879 @deffnx {C Function} scm_bytevector_ieee_double_native_set_x (bv, index, value)
4880 Store real number @var{value} in @var{bv} at @var{index} according to
4881 the host's native endianness.
4885 @node Bytevectors as Strings
4886 @subsubsection Interpreting Bytevector Contents as Unicode Strings
4888 @cindex Unicode string encoding
4890 Bytevector contents can also be interpreted as Unicode strings encoded
4891 in one of the most commonly available encoding formats.
4892 @xref{Representing Strings as Bytes}, for a more generic interface.
4895 (utf8->string (u8-list->bytevector '(99 97 102 101)))
4898 (string->utf8 "caf@'e") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT
4899 @result{} #vu8(99 97 102 195 169)
4902 @deffn {Scheme Procedure} string->utf8 str
4903 @deffnx {Scheme Procedure} string->utf16 str [endianness]
4904 @deffnx {Scheme Procedure} string->utf32 str [endianness]
4905 @deffnx {C Function} scm_string_to_utf8 (str)
4906 @deffnx {C Function} scm_string_to_utf16 (str, endianness)
4907 @deffnx {C Function} scm_string_to_utf32 (str, endianness)
4908 Return a newly allocated bytevector that contains the UTF-8, UTF-16, or
4909 UTF-32 (aka. UCS-4) encoding of @var{str}. For UTF-16 and UTF-32,
4910 @var{endianness} should be the symbol @code{big} or @code{little}; when omitted,
4911 it defaults to big endian.
4914 @deffn {Scheme Procedure} utf8->string utf
4915 @deffnx {Scheme Procedure} utf16->string utf [endianness]
4916 @deffnx {Scheme Procedure} utf32->string utf [endianness]
4917 @deffnx {C Function} scm_utf8_to_string (utf)
4918 @deffnx {C Function} scm_utf16_to_string (utf, endianness)
4919 @deffnx {C Function} scm_utf32_to_string (utf, endianness)
4920 Return a newly allocated string that contains from the UTF-8-, UTF-16-,
4921 or UTF-32-decoded contents of bytevector @var{utf}. For UTF-16 and UTF-32,
4922 @var{endianness} should be the symbol @code{big} or @code{little}; when omitted,
4923 it defaults to big endian.
4926 @node Bytevectors as Generalized Vectors
4927 @subsubsection Accessing Bytevectors with the Generalized Vector API
4929 As an extension to the R6RS, Guile allows bytevectors to be manipulated
4930 with the @dfn{generalized vector} procedures (@pxref{Generalized
4931 Vectors}). This also allows bytevectors to be accessed using the
4932 generic @dfn{array} procedures (@pxref{Array Procedures}). When using
4933 these APIs, bytes are accessed one at a time as 8-bit unsigned integers:
4936 (define bv #vu8(0 1 2 3))
4938 (generalized-vector? bv)
4941 (generalized-vector-ref bv 2)
4944 (generalized-vector-set! bv 2 77)
4953 @node Bytevectors as Uniform Vectors
4954 @subsubsection Accessing Bytevectors with the SRFI-4 API
4956 Bytevectors may also be accessed with the SRFI-4 API. @xref{SRFI-4 and
4957 Bytevectors}, for more information.
4964 Symbols in Scheme are widely used in three ways: as items of discrete
4965 data, as lookup keys for alists and hash tables, and to denote variable
4968 A @dfn{symbol} is similar to a string in that it is defined by a
4969 sequence of characters. The sequence of characters is known as the
4970 symbol's @dfn{name}. In the usual case --- that is, where the symbol's
4971 name doesn't include any characters that could be confused with other
4972 elements of Scheme syntax --- a symbol is written in a Scheme program by
4973 writing the sequence of characters that make up the name, @emph{without}
4974 any quotation marks or other special syntax. For example, the symbol
4975 whose name is ``multiply-by-2'' is written, simply:
4981 Notice how this differs from a @emph{string} with contents
4982 ``multiply-by-2'', which is written with double quotation marks, like
4989 Looking beyond how they are written, symbols are different from strings
4990 in two important respects.
4992 The first important difference is uniqueness. If the same-looking
4993 string is read twice from two different places in a program, the result
4994 is two @emph{different} string objects whose contents just happen to be
4995 the same. If, on the other hand, the same-looking symbol is read twice
4996 from two different places in a program, the result is the @emph{same}
4997 symbol object both times.
4999 Given two read symbols, you can use @code{eq?} to test whether they are
5000 the same (that is, have the same name). @code{eq?} is the most
5001 efficient comparison operator in Scheme, and comparing two symbols like
5002 this is as fast as comparing, for example, two numbers. Given two
5003 strings, on the other hand, you must use @code{equal?} or
5004 @code{string=?}, which are much slower comparison operators, to
5005 determine whether the strings have the same contents.
5008 (define sym1 (quote hello))
5009 (define sym2 (quote hello))
5010 (eq? sym1 sym2) @result{} #t
5012 (define str1 "hello")
5013 (define str2 "hello")
5014 (eq? str1 str2) @result{} #f
5015 (equal? str1 str2) @result{} #t
5018 The second important difference is that symbols, unlike strings, are not
5019 self-evaluating. This is why we need the @code{(quote @dots{})}s in the
5020 example above: @code{(quote hello)} evaluates to the symbol named
5021 "hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
5022 symbol named "hello" and evaluated as a variable reference @dots{} about
5023 which more below (@pxref{Symbol Variables}).
5026 * Symbol Data:: Symbols as discrete data.
5027 * Symbol Keys:: Symbols as lookup keys.
5028 * Symbol Variables:: Symbols as denoting variables.
5029 * Symbol Primitives:: Operations related to symbols.
5030 * Symbol Props:: Function slots and property lists.
5031 * Symbol Read Syntax:: Extended read syntax for symbols.
5032 * Symbol Uninterned:: Uninterned symbols.
5037 @subsubsection Symbols as Discrete Data
5039 Numbers and symbols are similar to the extent that they both lend
5040 themselves to @code{eq?} comparison. But symbols are more descriptive
5041 than numbers, because a symbol's name can be used directly to describe
5042 the concept for which that symbol stands.
5044 For example, imagine that you need to represent some colours in a
5045 computer program. Using numbers, you would have to choose arbitrarily
5046 some mapping between numbers and colours, and then take care to use that
5047 mapping consistently:
5050 ;; 1=red, 2=green, 3=purple
5052 (if (eq? (colour-of car) 1)
5057 You can make the mapping more explicit and the code more readable by
5065 (if (eq? (colour-of car) red)
5070 But the simplest and clearest approach is not to use numbers at all, but
5071 symbols whose names specify the colours that they refer to:
5074 (if (eq? (colour-of car) 'red)
5078 The descriptive advantages of symbols over numbers increase as the set
5079 of concepts that you want to describe grows. Suppose that a car object
5080 can have other properties as well, such as whether it has or uses:
5084 automatic or manual transmission
5086 leaded or unleaded fuel
5088 power steering (or not).
5092 Then a car's combined property set could be naturally represented and
5093 manipulated as a list of symbols:
5096 (properties-of car1)
5098 (red manual unleaded power-steering)
5100 (if (memq 'power-steering (properties-of car1))
5101 (display "Unfit people can drive this car.\n")
5102 (display "You'll need strong arms to drive this car!\n"))
5104 Unfit people can drive this car.
5107 Remember, the fundamental property of symbols that we are relying on
5108 here is that an occurrence of @code{'red} in one part of a program is an
5109 @emph{indistinguishable} symbol from an occurrence of @code{'red} in
5110 another part of a program; this means that symbols can usefully be
5111 compared using @code{eq?}. At the same time, symbols have naturally
5112 descriptive names. This combination of efficiency and descriptive power
5113 makes them ideal for use as discrete data.
5117 @subsubsection Symbols as Lookup Keys
5119 Given their efficiency and descriptive power, it is natural to use
5120 symbols as the keys in an association list or hash table.
5122 To illustrate this, consider a more structured representation of the car
5123 properties example from the preceding subsection. Rather than
5124 mixing all the properties up together in a flat list, we could use an
5125 association list like this:
5128 (define car1-properties '((colour . red)
5129 (transmission . manual)
5131 (steering . power-assisted)))
5134 Notice how this structure is more explicit and extensible than the flat
5135 list. For example it makes clear that @code{manual} refers to the
5136 transmission rather than, say, the windows or the locking of the car.
5137 It also allows further properties to use the same symbols among their
5138 possible values without becoming ambiguous:
5141 (define car1-properties '((colour . red)
5142 (transmission . manual)
5144 (steering . power-assisted)
5146 (locking . manual)))
5149 With a representation like this, it is easy to use the efficient
5150 @code{assq-XXX} family of procedures (@pxref{Association Lists}) to
5151 extract or change individual pieces of information:
5154 (assq-ref car1-properties 'fuel) @result{} unleaded
5155 (assq-ref car1-properties 'transmission) @result{} manual
5157 (assq-set! car1-properties 'seat-colour 'black)
5160 (transmission . manual)
5162 (steering . power-assisted)
5163 (seat-colour . black)
5164 (locking . manual)))
5167 Hash tables also have keys, and exactly the same arguments apply to the
5168 use of symbols in hash tables as in association lists. The hash value
5169 that Guile uses to decide where to add a symbol-keyed entry to a hash
5170 table can be obtained by calling the @code{symbol-hash} procedure:
5172 @deffn {Scheme Procedure} symbol-hash symbol
5173 @deffnx {C Function} scm_symbol_hash (symbol)
5174 Return a hash value for @var{symbol}.
5177 See @ref{Hash Tables} for information about hash tables in general, and
5178 for why you might choose to use a hash table rather than an association
5182 @node Symbol Variables
5183 @subsubsection Symbols as Denoting Variables
5185 When an unquoted symbol in a Scheme program is evaluated, it is
5186 interpreted as a variable reference, and the result of the evaluation is
5187 the appropriate variable's value.
5189 For example, when the expression @code{(string-length "abcd")} is read
5190 and evaluated, the sequence of characters @code{string-length} is read
5191 as the symbol whose name is "string-length". This symbol is associated
5192 with a variable whose value is the procedure that implements string
5193 length calculation. Therefore evaluation of the @code{string-length}
5194 symbol results in that procedure.
5196 The details of the connection between an unquoted symbol and the
5197 variable to which it refers are explained elsewhere. See @ref{Binding
5198 Constructs}, for how associations between symbols and variables are
5199 created, and @ref{Modules}, for how those associations are affected by
5200 Guile's module system.
5203 @node Symbol Primitives
5204 @subsubsection Operations Related to Symbols
5206 Given any Scheme value, you can determine whether it is a symbol using
5207 the @code{symbol?} primitive:
5210 @deffn {Scheme Procedure} symbol? obj
5211 @deffnx {C Function} scm_symbol_p (obj)
5212 Return @code{#t} if @var{obj} is a symbol, otherwise return
5216 @deftypefn {C Function} int scm_is_symbol (SCM val)
5217 Equivalent to @code{scm_is_true (scm_symbol_p (val))}.
5220 Once you know that you have a symbol, you can obtain its name as a
5221 string by calling @code{symbol->string}. Note that Guile differs by
5222 default from R5RS on the details of @code{symbol->string} as regards
5225 @rnindex symbol->string
5226 @deffn {Scheme Procedure} symbol->string s
5227 @deffnx {C Function} scm_symbol_to_string (s)
5228 Return the name of symbol @var{s} as a string. By default, Guile reads
5229 symbols case-sensitively, so the string returned will have the same case
5230 variation as the sequence of characters that caused @var{s} to be
5233 If Guile is set to read symbols case-insensitively (as specified by
5234 R5RS), and @var{s} comes into being as part of a literal expression
5235 (@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
5236 by a call to the @code{read} or @code{string-ci->symbol} procedures,
5237 Guile converts any alphabetic characters in the symbol's name to
5238 lower case before creating the symbol object, so the string returned
5239 here will be in lower case.
5241 If @var{s} was created by @code{string->symbol}, the case of characters
5242 in the string returned will be the same as that in the string that was
5243 passed to @code{string->symbol}, regardless of Guile's case-sensitivity
5244 setting at the time @var{s} was created.
5246 It is an error to apply mutation procedures like @code{string-set!} to
5247 strings returned by this procedure.
5250 Most symbols are created by writing them literally in code. However it
5251 is also possible to create symbols programmatically using the following
5254 @deffn {Scheme Procedure} symbol char@dots{}
5256 Return a newly allocated symbol made from the given character arguments.
5259 (symbol #\x #\y #\z) @result{} xyz
5263 @deffn {Scheme Procedure} list->symbol lst
5264 @rnindex list->symbol
5265 Return a newly allocated symbol made from a list of characters.
5268 (list->symbol '(#\a #\b #\c)) @result{} abc
5272 @rnindex symbol-append
5273 @deffn {Scheme Procedure} symbol-append arg @dots{}
5274 Return a newly allocated symbol whose characters form the
5275 concatenation of the given symbols, @var{arg} @enddots{}.
5279 (symbol-append h 'world))
5280 @result{} helloworld
5284 @rnindex string->symbol
5285 @deffn {Scheme Procedure} string->symbol string
5286 @deffnx {C Function} scm_string_to_symbol (string)
5287 Return the symbol whose name is @var{string}. This procedure can create
5288 symbols with names containing special characters or letters in the
5289 non-standard case, but it is usually a bad idea to create such symbols
5290 because in some implementations of Scheme they cannot be read as
5294 @deffn {Scheme Procedure} string-ci->symbol str
5295 @deffnx {C Function} scm_string_ci_to_symbol (str)
5296 Return the symbol whose name is @var{str}. If Guile is currently
5297 reading symbols case-insensitively, @var{str} is converted to lowercase
5298 before the returned symbol is looked up or created.
5301 The following examples illustrate Guile's detailed behaviour as regards
5302 the case-sensitivity of symbols:
5305 (read-enable 'case-insensitive) ; R5RS compliant behaviour
5307 (symbol->string 'flying-fish) @result{} "flying-fish"
5308 (symbol->string 'Martin) @result{} "martin"
5310 (string->symbol "Malvina")) @result{} "Malvina"
5312 (eq? 'mISSISSIppi 'mississippi) @result{} #t
5313 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
5314 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
5316 (string->symbol (symbol->string 'LolliPop))) @result{} #t
5317 (string=? "K. Harper, M.D."
5319 (string->symbol "K. Harper, M.D."))) @result{} #t
5321 (read-disable 'case-insensitive) ; Guile default behaviour
5323 (symbol->string 'flying-fish) @result{} "flying-fish"
5324 (symbol->string 'Martin) @result{} "Martin"
5326 (string->symbol "Malvina")) @result{} "Malvina"
5328 (eq? 'mISSISSIppi 'mississippi) @result{} #f
5329 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
5330 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
5332 (string->symbol (symbol->string 'LolliPop))) @result{} #t
5333 (string=? "K. Harper, M.D."
5335 (string->symbol "K. Harper, M.D."))) @result{} #t
5338 From C, there are lower level functions that construct a Scheme symbol
5339 from a C string in the current locale encoding.
5341 When you want to do more from C, you should convert between symbols
5342 and strings using @code{scm_symbol_to_string} and
5343 @code{scm_string_to_symbol} and work with the strings.
5345 @deftypefn {C Function} scm_from_latin1_symbol (const char *name)
5346 @deftypefnx {C Function} scm_from_utf8_symbol (const char *name)
5347 Construct and return a Scheme symbol whose name is specified by the
5348 null-terminated C string @var{name}. These are appropriate when
5349 the C string is hard-coded in the source code.
5352 @deftypefn {C Function} scm_from_locale_symbol (const char *name)
5353 @deftypefnx {C Function} scm_from_locale_symboln (const char *name, size_t len)
5354 Construct and return a Scheme symbol whose name is specified by
5355 @var{name}. For @code{scm_from_locale_symbol}, @var{name} must be null
5356 terminated; for @code{scm_from_locale_symboln} the length of @var{name} is
5357 specified explicitly by @var{len}.
5359 Note that these functions should @emph{not} be used when @var{name} is a
5360 C string constant, because there is no guarantee that the current locale
5361 will match that of the source code. In such cases, use
5362 @code{scm_from_latin1_symbol} or @code{scm_from_utf8_symbol}.
5365 @deftypefn {C Function} SCM scm_take_locale_symbol (char *str)
5366 @deftypefnx {C Function} SCM scm_take_locale_symboln (char *str, size_t len)
5367 Like @code{scm_from_locale_symbol} and @code{scm_from_locale_symboln},
5368 respectively, but also frees @var{str} with @code{free} eventually.
5369 Thus, you can use this function when you would free @var{str} anyway
5370 immediately after creating the Scheme string. In certain cases, Guile
5371 can then use @var{str} directly as its internal representation.
5374 The size of a symbol can also be obtained from C:
5376 @deftypefn {C Function} size_t scm_c_symbol_length (SCM sym)
5377 Return the number of characters in @var{sym}.
5380 Finally, some applications, especially those that generate new Scheme
5381 code dynamically, need to generate symbols for use in the generated
5382 code. The @code{gensym} primitive meets this need:
5384 @deffn {Scheme Procedure} gensym [prefix]
5385 @deffnx {C Function} scm_gensym (prefix)
5386 Create a new symbol with a name constructed from a prefix and a counter
5387 value. The string @var{prefix} can be specified as an optional
5388 argument. Default prefix is @samp{@w{ g}}. The counter is increased by 1
5389 at each call. There is no provision for resetting the counter.
5392 The symbols generated by @code{gensym} are @emph{likely} to be unique,
5393 since their names begin with a space and it is only otherwise possible
5394 to generate such symbols if a programmer goes out of their way to do
5395 so. Uniqueness can be guaranteed by instead using uninterned symbols
5396 (@pxref{Symbol Uninterned}), though they can't be usefully written out
5401 @subsubsection Function Slots and Property Lists
5403 In traditional Lisp dialects, symbols are often understood as having
5404 three kinds of value at once:
5408 a @dfn{variable} value, which is used when the symbol appears in
5409 code in a variable reference context
5412 a @dfn{function} value, which is used when the symbol appears in
5413 code in a function name position (i.e.@: as the first element in an
5417 a @dfn{property list} value, which is used when the symbol is given as
5418 the first argument to Lisp's @code{put} or @code{get} functions.
5421 Although Scheme (as one of its simplifications with respect to Lisp)
5422 does away with the distinction between variable and function namespaces,
5423 Guile currently retains some elements of the traditional structure in
5424 case they turn out to be useful when implementing translators for other
5425 languages, in particular Emacs Lisp.
5427 Specifically, Guile symbols have two extra slots, one for a symbol's
5428 property list, and one for its ``function value.'' The following procedures
5429 are provided to access these slots.
5431 @deffn {Scheme Procedure} symbol-fref symbol
5432 @deffnx {C Function} scm_symbol_fref (symbol)
5433 Return the contents of @var{symbol}'s @dfn{function slot}.
5436 @deffn {Scheme Procedure} symbol-fset! symbol value
5437 @deffnx {C Function} scm_symbol_fset_x (symbol, value)
5438 Set the contents of @var{symbol}'s function slot to @var{value}.
5441 @deffn {Scheme Procedure} symbol-pref symbol
5442 @deffnx {C Function} scm_symbol_pref (symbol)
5443 Return the @dfn{property list} currently associated with @var{symbol}.
5446 @deffn {Scheme Procedure} symbol-pset! symbol value
5447 @deffnx {C Function} scm_symbol_pset_x (symbol, value)
5448 Set @var{symbol}'s property list to @var{value}.
5451 @deffn {Scheme Procedure} symbol-property sym prop
5452 From @var{sym}'s property list, return the value for property
5453 @var{prop}. The assumption is that @var{sym}'s property list is an
5454 association list whose keys are distinguished from each other using
5455 @code{equal?}; @var{prop} should be one of the keys in that list. If
5456 the property list has no entry for @var{prop}, @code{symbol-property}
5460 @deffn {Scheme Procedure} set-symbol-property! sym prop val
5461 In @var{sym}'s property list, set the value for property @var{prop} to
5462 @var{val}, or add a new entry for @var{prop}, with value @var{val}, if
5463 none already exists. For the structure of the property list, see
5464 @code{symbol-property}.
5467 @deffn {Scheme Procedure} symbol-property-remove! sym prop
5468 From @var{sym}'s property list, remove the entry for property
5469 @var{prop}, if there is one. For the structure of the property list,
5470 see @code{symbol-property}.
5473 Support for these extra slots may be removed in a future release, and it
5474 is probably better to avoid using them. For a more modern and Schemely
5475 approach to properties, see @ref{Object Properties}.
5478 @node Symbol Read Syntax
5479 @subsubsection Extended Read Syntax for Symbols
5481 The read syntax for a symbol is a sequence of letters, digits, and
5482 @dfn{extended alphabetic characters}, beginning with a character that
5483 cannot begin a number. In addition, the special cases of @code{+},
5484 @code{-}, and @code{...} are read as symbols even though numbers can
5485 begin with @code{+}, @code{-} or @code{.}.
5487 Extended alphabetic characters may be used within identifiers as if
5488 they were letters. The set of extended alphabetic characters is:
5491 ! $ % & * + - . / : < = > ? @@ ^ _ ~
5494 In addition to the standard read syntax defined above (which is taken
5495 from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
5496 Scheme})), Guile provides an extended symbol read syntax that allows the
5497 inclusion of unusual characters such as space characters, newlines and
5498 parentheses. If (for whatever reason) you need to write a symbol
5499 containing characters not mentioned above, you can do so as follows.
5503 Begin the symbol with the characters @code{#@{},
5506 write the characters of the symbol and
5509 finish the symbol with the characters @code{@}#}.
5512 Here are a few examples of this form of read syntax. The first symbol
5513 needs to use extended syntax because it contains a space character, the
5514 second because it contains a line break, and the last because it looks
5526 Although Guile provides this extended read syntax for symbols,
5527 widespread usage of it is discouraged because it is not portable and not
5531 @node Symbol Uninterned
5532 @subsubsection Uninterned Symbols
5534 What makes symbols useful is that they are automatically kept unique.
5535 There are no two symbols that are distinct objects but have the same
5536 name. But of course, there is no rule without exception. In addition
5537 to the normal symbols that have been discussed up to now, you can also
5538 create special @dfn{uninterned} symbols that behave slightly
5541 To understand what is different about them and why they might be useful,
5542 we look at how normal symbols are actually kept unique.
5544 Whenever Guile wants to find the symbol with a specific name, for
5545 example during @code{read} or when executing @code{string->symbol}, it
5546 first looks into a table of all existing symbols to find out whether a
5547 symbol with the given name already exists. When this is the case, Guile
5548 just returns that symbol. When not, a new symbol with the name is
5549 created and entered into the table so that it can be found later.
5551 Sometimes you might want to create a symbol that is guaranteed `fresh',
5552 i.e.@: a symbol that did not exist previously. You might also want to
5553 somehow guarantee that no one else will ever unintentionally stumble
5554 across your symbol in the future. These properties of a symbol are
5555 often needed when generating code during macro expansion. When
5556 introducing new temporary variables, you want to guarantee that they
5557 don't conflict with variables in other people's code.
5559 The simplest way to arrange for this is to create a new symbol but
5560 not enter it into the global table of all symbols. That way, no one
5561 will ever get access to your symbol by chance. Symbols that are not in
5562 the table are called @dfn{uninterned}. Of course, symbols that
5563 @emph{are} in the table are called @dfn{interned}.
5565 You create new uninterned symbols with the function @code{make-symbol}.
5566 You can test whether a symbol is interned or not with
5567 @code{symbol-interned?}.
5569 Uninterned symbols break the rule that the name of a symbol uniquely
5570 identifies the symbol object. Because of this, they can not be written
5571 out and read back in like interned symbols. Currently, Guile has no
5572 support for reading uninterned symbols. Note that the function
5573 @code{gensym} does not return uninterned symbols for this reason.
5575 @deffn {Scheme Procedure} make-symbol name
5576 @deffnx {C Function} scm_make_symbol (name)
5577 Return a new uninterned symbol with the name @var{name}. The returned
5578 symbol is guaranteed to be unique and future calls to
5579 @code{string->symbol} will not return it.
5582 @deffn {Scheme Procedure} symbol-interned? symbol
5583 @deffnx {C Function} scm_symbol_interned_p (symbol)
5584 Return @code{#t} if @var{symbol} is interned, otherwise return
5591 (define foo-1 (string->symbol "foo"))
5592 (define foo-2 (string->symbol "foo"))
5593 (define foo-3 (make-symbol "foo"))
5594 (define foo-4 (make-symbol "foo"))
5598 ; Two interned symbols with the same name are the same object,
5602 ; but a call to make-symbol with the same name returns a
5607 ; A call to make-symbol always returns a new object, even for
5611 @result{} #<uninterned-symbol foo 8085290>
5612 ; Uninterned symbols print differently from interned symbols,
5616 ; but they are still symbols,
5618 (symbol-interned? foo-3)
5620 ; just not interned.
5625 @subsection Keywords
5628 Keywords are self-evaluating objects with a convenient read syntax that
5629 makes them easy to type.
5631 Guile's keyword support conforms to R5RS, and adds a (switchable) read
5632 syntax extension to permit keywords to begin with @code{:} as well as
5633 @code{#:}, or to end with @code{:}.
5636 * Why Use Keywords?:: Motivation for keyword usage.
5637 * Coding With Keywords:: How to use keywords.
5638 * Keyword Read Syntax:: Read syntax for keywords.
5639 * Keyword Procedures:: Procedures for dealing with keywords.
5642 @node Why Use Keywords?
5643 @subsubsection Why Use Keywords?
5645 Keywords are useful in contexts where a program or procedure wants to be
5646 able to accept a large number of optional arguments without making its
5647 interface unmanageable.
5649 To illustrate this, consider a hypothetical @code{make-window}
5650 procedure, which creates a new window on the screen for drawing into
5651 using some graphical toolkit. There are many parameters that the caller
5652 might like to specify, but which could also be sensibly defaulted, for
5657 color depth -- Default: the color depth for the screen
5660 background color -- Default: white
5663 width -- Default: 600
5666 height -- Default: 400
5669 If @code{make-window} did not use keywords, the caller would have to
5670 pass in a value for each possible argument, remembering the correct
5671 argument order and using a special value to indicate the default value
5675 (make-window 'default ;; Color depth
5676 'default ;; Background color
5679 @dots{}) ;; More make-window arguments
5682 With keywords, on the other hand, defaulted arguments are omitted, and
5683 non-default arguments are clearly tagged by the appropriate keyword. As
5684 a result, the invocation becomes much clearer:
5687 (make-window #:width 800 #:height 100)
5690 On the other hand, for a simpler procedure with few arguments, the use
5691 of keywords would be a hindrance rather than a help. The primitive
5692 procedure @code{cons}, for example, would not be improved if it had to
5696 (cons #:car x #:cdr y)
5699 So the decision whether to use keywords or not is purely pragmatic: use
5700 them if they will clarify the procedure invocation at point of call.
5702 @node Coding With Keywords
5703 @subsubsection Coding With Keywords
5705 If a procedure wants to support keywords, it should take a rest argument
5706 and then use whatever means is convenient to extract keywords and their
5707 corresponding arguments from the contents of that rest argument.
5709 The following example illustrates the principle: the code for
5710 @code{make-window} uses a helper procedure called
5711 @code{get-keyword-value} to extract individual keyword arguments from
5715 (define (get-keyword-value args keyword default)
5716 (let ((kv (memq keyword args)))
5717 (if (and kv (>= (length kv) 2))
5721 (define (make-window . args)
5722 (let ((depth (get-keyword-value args #:depth screen-depth))
5723 (bg (get-keyword-value args #:bg "white"))
5724 (width (get-keyword-value args #:width 800))
5725 (height (get-keyword-value args #:height 100))
5730 But you don't need to write @code{get-keyword-value}. The @code{(ice-9
5731 optargs)} module provides a set of powerful macros that you can use to
5732 implement keyword-supporting procedures like this:
5735 (use-modules (ice-9 optargs))
5737 (define (make-window . args)
5738 (let-keywords args #f ((depth screen-depth)
5746 Or, even more economically, like this:
5749 (use-modules (ice-9 optargs))
5751 (define* (make-window #:key (depth screen-depth)
5758 For further details on @code{let-keywords}, @code{define*} and other
5759 facilities provided by the @code{(ice-9 optargs)} module, see
5760 @ref{Optional Arguments}.
5763 @node Keyword Read Syntax
5764 @subsubsection Keyword Read Syntax
5766 Guile, by default, only recognizes a keyword syntax that is compatible
5767 with R5RS. A token of the form @code{#:NAME}, where @code{NAME} has the
5768 same syntax as a Scheme symbol (@pxref{Symbol Read Syntax}), is the
5769 external representation of the keyword named @code{NAME}. Keyword
5770 objects print using this syntax as well, so values containing keyword
5771 objects can be read back into Guile. When used in an expression,
5772 keywords are self-quoting objects.
5774 If the @code{keyword} read option is set to @code{'prefix}, Guile also
5775 recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
5776 of the form @code{:NAME} are read as symbols, as required by R5RS.
5778 @cindex SRFI-88 keyword syntax
5780 If the @code{keyword} read option is set to @code{'postfix}, Guile
5781 recognizes the SRFI-88 read syntax @code{NAME:} (@pxref{SRFI-88}).
5782 Otherwise, tokens of this form are read as symbols.
5784 To enable and disable the alternative non-R5RS keyword syntax, you use
5785 the @code{read-set!} procedure documented @ref{Scheme Read}. Note that
5786 the @code{prefix} and @code{postfix} syntax are mutually exclusive.
5789 (read-set! keywords 'prefix)
5799 (read-set! keywords 'postfix)
5809 (read-set! keywords #f)
5817 ERROR: In expression :type:
5818 ERROR: Unbound variable: :type
5819 ABORT: (unbound-variable)
5822 @node Keyword Procedures
5823 @subsubsection Keyword Procedures
5825 @deffn {Scheme Procedure} keyword? obj
5826 @deffnx {C Function} scm_keyword_p (obj)
5827 Return @code{#t} if the argument @var{obj} is a keyword, else
5831 @deffn {Scheme Procedure} keyword->symbol keyword
5832 @deffnx {C Function} scm_keyword_to_symbol (keyword)
5833 Return the symbol with the same name as @var{keyword}.
5836 @deffn {Scheme Procedure} symbol->keyword symbol
5837 @deffnx {C Function} scm_symbol_to_keyword (symbol)
5838 Return the keyword with the same name as @var{symbol}.
5841 @deftypefn {C Function} int scm_is_keyword (SCM obj)
5842 Equivalent to @code{scm_is_true (scm_keyword_p (@var{obj}))}.
5845 @deftypefn {C Function} SCM scm_from_locale_keyword (const char *name)
5846 @deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *name, size_t len)
5847 Equivalent to @code{scm_symbol_to_keyword (scm_from_locale_symbol
5848 (@var{name}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln
5849 (@var{name}, @var{len}))}, respectively.
5851 Note that these functions should @emph{not} be used when @var{name} is a
5852 C string constant, because there is no guarantee that the current locale
5853 will match that of the source code. In such cases, use
5854 @code{scm_from_latin1_keyword} or @code{scm_from_utf8_keyword}.
5857 @deftypefn {C Function} SCM scm_from_latin1_keyword (const char *name)
5858 @deftypefnx {C Function} SCM scm_from_utf8_keyword (const char *name)
5859 Equivalent to @code{scm_symbol_to_keyword (scm_from_latin1_symbol
5860 (@var{name}))} and @code{scm_symbol_to_keyword (scm_from_utf8_symbol
5861 (@var{name}))}, respectively.
5865 @subsection ``Functionality-Centric'' Data Types
5867 Procedures and macros are documented in their own sections: see
5868 @ref{Procedures} and @ref{Macros}.
5870 Variable objects are documented as part of the description of Guile's
5871 module system: see @ref{Variables}.
5873 Asyncs, dynamic roots and fluids are described in the section on
5874 scheduling: see @ref{Scheduling}.
5876 Hooks are documented in the section on general utility functions: see
5879 Ports are described in the section on I/O: see @ref{Input and Output}.
5881 Regular expressions are described in their own section: see @ref{Regular
5885 @c TeX-master: "guile.texi"