2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000-2004, 2006-2014
4 @c 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.
59 They can also be written as @code{#true} and @code{#false}, as per R7RS.
61 Boolean values are returned by predicate procedures, such as the general
62 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
63 (@pxref{Equality}) and numerical and string comparison operators like
64 @code{string=?} (@pxref{String Comparison}) and @code{<=}
74 (equal? "house" "houses")
82 In test condition contexts like @code{if} and @code{cond}
83 (@pxref{Conditionals}), where a group of subexpressions will be
84 evaluated only if a @var{condition} expression evaluates to ``true'',
85 ``true'' means any value at all except @code{#f}.
98 A result of this asymmetry is that typical Scheme source code more often
99 uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
100 represent an @code{if} or @code{cond} false value, whereas @code{#t} is
101 not necessary to represent an @code{if} or @code{cond} true value.
103 It is important to note that @code{#f} is @strong{not} equivalent to any
104 other Scheme value. In particular, @code{#f} is not the same as the
105 number 0 (like in C and C++), and not the same as the ``empty list''
106 (like in some Lisp dialects).
108 In C, the two Scheme boolean values are available as the two constants
109 @code{SCM_BOOL_T} for @code{#t} and @code{SCM_BOOL_F} for @code{#f}.
110 Care must be taken with the false value @code{SCM_BOOL_F}: it is not
111 false when used in C conditionals. In order to test for it, use
112 @code{scm_is_false} or @code{scm_is_true}.
115 @deffn {Scheme Procedure} not x
116 @deffnx {C Function} scm_not (x)
117 Return @code{#t} if @var{x} is @code{#f}, else return @code{#f}.
121 @deffn {Scheme Procedure} boolean? obj
122 @deffnx {C Function} scm_boolean_p (obj)
123 Return @code{#t} if @var{obj} is either @code{#t} or @code{#f}, else
127 @deftypevr {C Macro} SCM SCM_BOOL_T
128 The @code{SCM} representation of the Scheme object @code{#t}.
131 @deftypevr {C Macro} SCM SCM_BOOL_F
132 The @code{SCM} representation of the Scheme object @code{#f}.
135 @deftypefn {C Function} int scm_is_true (SCM obj)
136 Return @code{0} if @var{obj} is @code{#f}, else return @code{1}.
139 @deftypefn {C Function} int scm_is_false (SCM obj)
140 Return @code{1} if @var{obj} is @code{#f}, else return @code{0}.
143 @deftypefn {C Function} int scm_is_bool (SCM obj)
144 Return @code{1} if @var{obj} is either @code{#t} or @code{#f}, else
148 @deftypefn {C Function} SCM scm_from_bool (int val)
149 Return @code{#f} if @var{val} is @code{0}, else return @code{#t}.
152 @deftypefn {C Function} int scm_to_bool (SCM val)
153 Return @code{1} if @var{val} is @code{SCM_BOOL_T}, return @code{0}
154 when @var{val} is @code{SCM_BOOL_F}, else signal a `wrong type' error.
156 You should probably use @code{scm_is_true} instead of this function
157 when you just want to test a @code{SCM} value for trueness.
161 @subsection Numerical data types
164 Guile supports a rich ``tower'' of numerical types --- integer,
165 rational, real and complex --- and provides an extensive set of
166 mathematical and scientific functions for operating on numerical
167 data. This section of the manual documents those types and functions.
169 You may also find it illuminating to read R5RS's presentation of numbers
170 in Scheme, which is particularly clear and accessible: see
171 @ref{Numbers,,,r5rs,R5RS}.
174 * Numerical Tower:: Scheme's numerical "tower".
175 * Integers:: Whole numbers.
176 * Reals and Rationals:: Real and rational numbers.
177 * Complex Numbers:: Complex numbers.
178 * Exactness:: Exactness and inexactness.
179 * Number Syntax:: Read syntax for numerical data.
180 * Integer Operations:: Operations on integer values.
181 * Comparison:: Comparison predicates.
182 * Conversion:: Converting numbers to and from strings.
183 * Complex:: Complex number operations.
184 * Arithmetic:: Arithmetic functions.
185 * Scientific:: Scientific functions.
186 * Bitwise Operations:: Logical AND, OR, NOT, and so on.
187 * Random:: Random number generation.
191 @node Numerical Tower
192 @subsubsection Scheme's Numerical ``Tower''
195 Scheme's numerical ``tower'' consists of the following categories of
200 Whole numbers, positive or negative; e.g.@: --5, 0, 18.
203 The set of numbers that can be expressed as @math{@var{p}/@var{q}}
204 where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
205 pi (an irrational number) doesn't. These include integers
209 The set of numbers that describes all possible positions along a
210 one-dimensional line. This includes rationals as well as irrational
213 @item complex numbers
214 The set of numbers that describes all possible positions in a two
215 dimensional space. This includes real as well as imaginary numbers
216 (@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
217 @var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
221 It is called a tower because each category ``sits on'' the one that
222 follows it, in the sense that every integer is also a rational, every
223 rational is also real, and every real number is also a complex number
224 (but with zero imaginary part).
226 In addition to the classification into integers, rationals, reals and
227 complex numbers, Scheme also distinguishes between whether a number is
228 represented exactly or not. For example, the result of
229 @m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)}, but Guile
230 can represent neither @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
231 Instead, it stores an inexact approximation, using the C type
234 Guile can represent exact rationals of any magnitude, inexact
235 rationals that fit into a C @code{double}, and inexact complex numbers
236 with @code{double} real and imaginary parts.
238 The @code{number?} predicate may be applied to any Scheme value to
239 discover whether the value is any of the supported numerical types.
241 @deffn {Scheme Procedure} number? obj
242 @deffnx {C Function} scm_number_p (obj)
243 Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
252 (number? "hello there!")
255 (define pi 3.141592654)
260 @deftypefn {C Function} int scm_is_number (SCM obj)
261 This is equivalent to @code{scm_is_true (scm_number_p (obj))}.
264 The next few subsections document each of Guile's numerical data types
268 @subsubsection Integers
270 @tpindex Integer numbers
274 Integers are whole numbers, that is numbers with no fractional part,
275 such as 2, 83, and @minus{}3789.
277 Integers in Guile can be arbitrarily big, as shown by the following
281 (define (factorial n)
282 (let loop ((n n) (product 1))
285 (loop (- n 1) (* product n)))))
291 @result{} 2432902008176640000
294 @result{} -119622220865480194561963161495657715064383733760000000000
297 Readers whose background is in programming languages where integers are
298 limited by the need to fit into just 4 or 8 bytes of memory may find
299 this surprising, or suspect that Guile's representation of integers is
300 inefficient. In fact, Guile achieves a near optimal balance of
301 convenience and efficiency by using the host computer's native
302 representation of integers where possible, and a more general
303 representation where the required number does not fit in the native
304 form. Conversion between these two representations is automatic and
305 completely invisible to the Scheme level programmer.
307 C has a host of different integer types, and Guile offers a host of
308 functions to convert between them and the @code{SCM} representation.
309 For example, a C @code{int} can be handled with @code{scm_to_int} and
310 @code{scm_from_int}. Guile also defines a few C integer types of its
311 own, to help with differences between systems.
313 C integer types that are not covered can be handled with the generic
314 @code{scm_to_signed_integer} and @code{scm_from_signed_integer} for
315 signed types, or with @code{scm_to_unsigned_integer} and
316 @code{scm_from_unsigned_integer} for unsigned types.
318 Scheme integers can be exact and inexact. For example, a number
319 written as @code{3.0} with an explicit decimal-point is inexact, but
320 it is also an integer. The functions @code{integer?} and
321 @code{scm_is_integer} report true for such a number, but the functions
322 @code{exact-integer?}, @code{scm_is_exact_integer},
323 @code{scm_is_signed_integer}, and @code{scm_is_unsigned_integer} only
324 allow exact integers and thus report false. Likewise, the conversion
325 functions like @code{scm_to_signed_integer} only accept exact
328 The motivation for this behavior is that the inexactness of a number
329 should not be lost silently. If you want to allow inexact integers,
330 you can explicitly insert a call to @code{inexact->exact} or to its C
331 equivalent @code{scm_inexact_to_exact}. (Only inexact integers will
332 be converted by this call into exact integers; inexact non-integers
333 will become exact fractions.)
335 @deffn {Scheme Procedure} integer? x
336 @deffnx {C Function} scm_integer_p (x)
337 Return @code{#t} if @var{x} is an exact or inexact integer number, else
355 @deftypefn {C Function} int scm_is_integer (SCM x)
356 This is equivalent to @code{scm_is_true (scm_integer_p (x))}.
359 @deffn {Scheme Procedure} exact-integer? x
360 @deffnx {C Function} scm_exact_integer_p (x)
361 Return @code{#t} if @var{x} is an exact integer number, else
373 @deftypefn {C Function} int scm_is_exact_integer (SCM x)
374 This is equivalent to @code{scm_is_true (scm_exact_integer_p (x))}.
377 @defvr {C Type} scm_t_int8
378 @defvrx {C Type} scm_t_uint8
379 @defvrx {C Type} scm_t_int16
380 @defvrx {C Type} scm_t_uint16
381 @defvrx {C Type} scm_t_int32
382 @defvrx {C Type} scm_t_uint32
383 @defvrx {C Type} scm_t_int64
384 @defvrx {C Type} scm_t_uint64
385 @defvrx {C Type} scm_t_intmax
386 @defvrx {C Type} scm_t_uintmax
387 The C types are equivalent to the corresponding ISO C types but are
388 defined on all platforms, with the exception of @code{scm_t_int64} and
389 @code{scm_t_uint64}, which are only defined when a 64-bit type is
390 available. For example, @code{scm_t_int8} is equivalent to
393 You can regard these definitions as a stop-gap measure until all
394 platforms provide these types. If you know that all the platforms
395 that you are interested in already provide these types, it is better
396 to use them directly instead of the types provided by Guile.
399 @deftypefn {C Function} int scm_is_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
400 @deftypefnx {C Function} int scm_is_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
401 Return @code{1} when @var{x} represents an exact integer that is
402 between @var{min} and @var{max}, inclusive.
404 These functions can be used to check whether a @code{SCM} value will
405 fit into a given range, such as the range of a given C integer type.
406 If you just want to convert a @code{SCM} value to a given C integer
407 type, use one of the conversion functions directly.
410 @deftypefn {C Function} scm_t_intmax scm_to_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
411 @deftypefnx {C Function} scm_t_uintmax scm_to_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
412 When @var{x} represents an exact integer that is between @var{min} and
413 @var{max} inclusive, return that integer. Else signal an error,
414 either a `wrong-type' error when @var{x} is not an exact integer, or
415 an `out-of-range' error when it doesn't fit the given range.
418 @deftypefn {C Function} SCM scm_from_signed_integer (scm_t_intmax x)
419 @deftypefnx {C Function} SCM scm_from_unsigned_integer (scm_t_uintmax x)
420 Return the @code{SCM} value that represents the integer @var{x}. This
421 function will always succeed and will always return an exact number.
424 @deftypefn {C Function} char scm_to_char (SCM x)
425 @deftypefnx {C Function} {signed char} scm_to_schar (SCM x)
426 @deftypefnx {C Function} {unsigned char} scm_to_uchar (SCM x)
427 @deftypefnx {C Function} short scm_to_short (SCM x)
428 @deftypefnx {C Function} {unsigned short} scm_to_ushort (SCM x)
429 @deftypefnx {C Function} int scm_to_int (SCM x)
430 @deftypefnx {C Function} {unsigned int} scm_to_uint (SCM x)
431 @deftypefnx {C Function} long scm_to_long (SCM x)
432 @deftypefnx {C Function} {unsigned long} scm_to_ulong (SCM x)
433 @deftypefnx {C Function} {long long} scm_to_long_long (SCM x)
434 @deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x)
435 @deftypefnx {C Function} size_t scm_to_size_t (SCM x)
436 @deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x)
437 @deftypefnx {C Function} scm_t_ptrdiff scm_to_ptrdiff_t (SCM x)
438 @deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x)
439 @deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x)
440 @deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x)
441 @deftypefnx {C Function} scm_t_uint16 scm_to_uint16 (SCM x)
442 @deftypefnx {C Function} scm_t_int32 scm_to_int32 (SCM x)
443 @deftypefnx {C Function} scm_t_uint32 scm_to_uint32 (SCM x)
444 @deftypefnx {C Function} scm_t_int64 scm_to_int64 (SCM x)
445 @deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x)
446 @deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x)
447 @deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x)
448 @deftypefnx {C Function} scm_t_intptr scm_to_intptr_t (SCM x)
449 @deftypefnx {C Function} scm_t_uintptr scm_to_uintptr_t (SCM x)
450 When @var{x} represents an exact integer that fits into the indicated
451 C type, return that integer. Else signal an error, either a
452 `wrong-type' error when @var{x} is not an exact integer, or an
453 `out-of-range' error when it doesn't fit the given range.
455 The functions @code{scm_to_long_long}, @code{scm_to_ulong_long},
456 @code{scm_to_int64}, and @code{scm_to_uint64} are only available when
457 the corresponding types are.
460 @deftypefn {C Function} SCM scm_from_char (char x)
461 @deftypefnx {C Function} SCM scm_from_schar (signed char x)
462 @deftypefnx {C Function} SCM scm_from_uchar (unsigned char x)
463 @deftypefnx {C Function} SCM scm_from_short (short x)
464 @deftypefnx {C Function} SCM scm_from_ushort (unsigned short x)
465 @deftypefnx {C Function} SCM scm_from_int (int x)
466 @deftypefnx {C Function} SCM scm_from_uint (unsigned int x)
467 @deftypefnx {C Function} SCM scm_from_long (long x)
468 @deftypefnx {C Function} SCM scm_from_ulong (unsigned long x)
469 @deftypefnx {C Function} SCM scm_from_long_long (long long x)
470 @deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x)
471 @deftypefnx {C Function} SCM scm_from_size_t (size_t x)
472 @deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x)
473 @deftypefnx {C Function} SCM scm_from_ptrdiff_t (scm_t_ptrdiff x)
474 @deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x)
475 @deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x)
476 @deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x)
477 @deftypefnx {C Function} SCM scm_from_uint16 (scm_t_uint16 x)
478 @deftypefnx {C Function} SCM scm_from_int32 (scm_t_int32 x)
479 @deftypefnx {C Function} SCM scm_from_uint32 (scm_t_uint32 x)
480 @deftypefnx {C Function} SCM scm_from_int64 (scm_t_int64 x)
481 @deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x)
482 @deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x)
483 @deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x)
484 @deftypefnx {C Function} SCM scm_from_intptr_t (scm_t_intptr x)
485 @deftypefnx {C Function} SCM scm_from_uintptr_t (scm_t_uintptr x)
486 Return the @code{SCM} value that represents the integer @var{x}.
487 These functions will always succeed and will always return an exact
491 @deftypefn {C Function} void scm_to_mpz (SCM val, mpz_t rop)
492 Assign @var{val} to the multiple precision integer @var{rop}.
493 @var{val} must be an exact integer, otherwise an error will be
494 signalled. @var{rop} must have been initialized with @code{mpz_init}
495 before this function is called. When @var{rop} is no longer needed
496 the occupied space must be freed with @code{mpz_clear}.
497 @xref{Initializing Integers,,, gmp, GNU MP Manual}, for details.
500 @deftypefn {C Function} SCM scm_from_mpz (mpz_t val)
501 Return the @code{SCM} value that represents @var{val}.
504 @node Reals and Rationals
505 @subsubsection Real and Rational Numbers
506 @tpindex Real numbers
507 @tpindex Rational numbers
512 Mathematically, the real numbers are the set of numbers that describe
513 all possible points along a continuous, infinite, one-dimensional line.
514 The rational numbers are the set of all numbers that can be written as
515 fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
516 All rational numbers are also real, but there are real numbers that
517 are not rational, for example @m{\sqrt{2}, the square root of 2}, and
520 Guile can represent both exact and inexact rational numbers, but it
521 cannot represent precise finite irrational numbers. Exact rationals are
522 represented by storing the numerator and denominator as two exact
523 integers. Inexact rationals are stored as floating point numbers using
524 the C type @code{double}.
526 Exact rationals are written as a fraction of integers. There must be
527 no whitespace around the slash:
534 Even though the actual encoding of inexact rationals is in binary, it
535 may be helpful to think of it as a decimal number with a limited
536 number of significant figures and a decimal point somewhere, since
537 this corresponds to the standard notation for non-whole numbers. For
543 -5648394822220000000000.0
547 The limited precision of Guile's encoding means that any finite ``real''
548 number in Guile can be written in a rational form, by multiplying and
549 then dividing by sufficient powers of 10 (or in fact, 2). For example,
550 @samp{-0.00000142857931198} is the same as @minus{}142857931198 divided
551 by 100000000000000000. In Guile's current incarnation, therefore, the
552 @code{rational?} and @code{real?} predicates are equivalent for finite
556 Dividing by an exact zero leads to a error message, as one might expect.
557 However, dividing by an inexact zero does not produce an error.
558 Instead, the result of the division is either plus or minus infinity,
559 depending on the sign of the divided number and the sign of the zero
560 divisor (some platforms support signed zeroes @samp{-0.0} and
561 @samp{+0.0}; @samp{0.0} is the same as @samp{+0.0}).
563 Dividing zero by an inexact zero yields a @acronym{NaN} (`not a number')
564 value, although they are actually considered numbers by Scheme.
565 Attempts to compare a @acronym{NaN} value with any number (including
566 itself) using @code{=}, @code{<}, @code{>}, @code{<=} or @code{>=}
567 always returns @code{#f}. Although a @acronym{NaN} value is not
568 @code{=} to itself, it is both @code{eqv?} and @code{equal?} to itself
569 and other @acronym{NaN} values. However, the preferred way to test for
570 them is by using @code{nan?}.
572 The real @acronym{NaN} values and infinities are written @samp{+nan.0},
573 @samp{+inf.0} and @samp{-inf.0}. This syntax is also recognized by
574 @code{read} as an extension to the usual Scheme syntax. These special
575 values are considered by Scheme to be inexact real numbers but not
576 rational. Note that non-real complex numbers may also contain
577 infinities or @acronym{NaN} values in their real or imaginary parts. To
578 test a real number to see if it is infinite, a @acronym{NaN} value, or
579 neither, use @code{inf?}, @code{nan?}, or @code{finite?}, respectively.
580 Every real number in Scheme belongs to precisely one of those three
583 On platforms that follow @acronym{IEEE} 754 for their floating point
584 arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
585 are implemented using the corresponding @acronym{IEEE} 754 values.
586 They behave in arithmetic operations like @acronym{IEEE} 754 describes
587 it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
589 @deffn {Scheme Procedure} real? obj
590 @deffnx {C Function} scm_real_p (obj)
591 Return @code{#t} if @var{obj} is a real number, else @code{#f}. Note
592 that the sets of integer and rational values form subsets of the set
593 of real numbers, so the predicate will also be fulfilled if @var{obj}
594 is an integer number or a rational number.
597 @deffn {Scheme Procedure} rational? x
598 @deffnx {C Function} scm_rational_p (x)
599 Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise.
600 Note that the set of integer values forms a subset of the set of
601 rational numbers, i.e.@: the predicate will also be fulfilled if
602 @var{x} is an integer number.
605 @deffn {Scheme Procedure} rationalize x eps
606 @deffnx {C Function} scm_rationalize (x, eps)
607 Returns the @emph{simplest} rational number differing
608 from @var{x} by no more than @var{eps}.
610 As required by @acronym{R5RS}, @code{rationalize} only returns an
611 exact result when both its arguments are exact. Thus, you might need
612 to use @code{inexact->exact} on the arguments.
615 (rationalize (inexact->exact 1.2) 1/100)
621 @deffn {Scheme Procedure} inf? x
622 @deffnx {C Function} scm_inf_p (x)
623 Return @code{#t} if the real number @var{x} is @samp{+inf.0} or
624 @samp{-inf.0}. Otherwise return @code{#f}.
627 @deffn {Scheme Procedure} nan? x
628 @deffnx {C Function} scm_nan_p (x)
629 Return @code{#t} if the real number @var{x} is @samp{+nan.0}, or
633 @deffn {Scheme Procedure} finite? x
634 @deffnx {C Function} scm_finite_p (x)
635 Return @code{#t} if the real number @var{x} is neither infinite nor a
636 NaN, @code{#f} otherwise.
639 @deffn {Scheme Procedure} nan
640 @deffnx {C Function} scm_nan ()
641 Return @samp{+nan.0}, a @acronym{NaN} value.
644 @deffn {Scheme Procedure} inf
645 @deffnx {C Function} scm_inf ()
646 Return @samp{+inf.0}, positive infinity.
649 @deffn {Scheme Procedure} numerator x
650 @deffnx {C Function} scm_numerator (x)
651 Return the numerator of the rational number @var{x}.
654 @deffn {Scheme Procedure} denominator x
655 @deffnx {C Function} scm_denominator (x)
656 Return the denominator of the rational number @var{x}.
659 @deftypefn {C Function} int scm_is_real (SCM val)
660 @deftypefnx {C Function} int scm_is_rational (SCM val)
661 Equivalent to @code{scm_is_true (scm_real_p (val))} and
662 @code{scm_is_true (scm_rational_p (val))}, respectively.
665 @deftypefn {C Function} double scm_to_double (SCM val)
666 Returns the number closest to @var{val} that is representable as a
667 @code{double}. Returns infinity for a @var{val} that is too large in
668 magnitude. The argument @var{val} must be a real number.
671 @deftypefn {C Function} SCM scm_from_double (double val)
672 Return the @code{SCM} value that represents @var{val}. The returned
673 value is inexact according to the predicate @code{inexact?}, but it
674 will be exactly equal to @var{val}.
677 @node Complex Numbers
678 @subsubsection Complex Numbers
679 @tpindex Complex numbers
683 Complex numbers are the set of numbers that describe all possible points
684 in a two-dimensional space. The two coordinates of a particular point
685 in this space are known as the @dfn{real} and @dfn{imaginary} parts of
686 the complex number that describes that point.
688 In Guile, complex numbers are written in rectangular form as the sum of
689 their real and imaginary parts, using the symbol @code{i} to indicate
704 Polar form can also be used, with an @samp{@@} between magnitude and
708 1@@3.141592 @result{} -1.0 (approx)
709 -1@@1.57079 @result{} 0.0-1.0i (approx)
712 Guile represents a complex number as a pair of inexact reals, so the
713 real and imaginary parts of a complex number have the same properties of
714 inexactness and limited precision as single inexact real numbers.
716 Note that each part of a complex number may contain any inexact real
717 value, including the special values @samp{+nan.0}, @samp{+inf.0} and
718 @samp{-inf.0}, as well as either of the signed zeroes @samp{0.0} or
722 @deffn {Scheme Procedure} complex? z
723 @deffnx {C Function} scm_complex_p (z)
724 Return @code{#t} if @var{z} is a complex number, @code{#f}
725 otherwise. Note that the sets of real, rational and integer
726 values form subsets of the set of complex numbers, i.e.@: the
727 predicate will also be fulfilled if @var{z} is a real,
728 rational or integer number.
731 @deftypefn {C Function} int scm_is_complex (SCM val)
732 Equivalent to @code{scm_is_true (scm_complex_p (val))}.
736 @subsubsection Exact and Inexact Numbers
737 @tpindex Exact numbers
738 @tpindex Inexact numbers
742 @rnindex exact->inexact
743 @rnindex inexact->exact
745 R5RS requires that, with few exceptions, a calculation involving inexact
746 numbers always produces an inexact result. To meet this requirement,
747 Guile distinguishes between an exact integer value such as @samp{5} and
748 the corresponding inexact integer value which, to the limited precision
749 available, has no fractional part, and is printed as @samp{5.0}. Guile
750 will only convert the latter value to the former when forced to do so by
751 an invocation of the @code{inexact->exact} procedure.
753 The only exception to the above requirement is when the values of the
754 inexact numbers do not affect the result. For example @code{(expt n 0)}
755 is @samp{1} for any value of @code{n}, therefore @code{(expt 5.0 0)} is
756 permitted to return an exact @samp{1}.
758 @deffn {Scheme Procedure} exact? z
759 @deffnx {C Function} scm_exact_p (z)
760 Return @code{#t} if the number @var{z} is exact, @code{#f}
776 @deftypefn {C Function} int scm_is_exact (SCM z)
777 Return a @code{1} if the number @var{z} is exact, and @code{0}
778 otherwise. This is equivalent to @code{scm_is_true (scm_exact_p (z))}.
780 An alternate approch to testing the exactness of a number is to
781 use @code{scm_is_signed_integer} or @code{scm_is_unsigned_integer}.
784 @deffn {Scheme Procedure} inexact? z
785 @deffnx {C Function} scm_inexact_p (z)
786 Return @code{#t} if the number @var{z} is inexact, @code{#f}
790 @deftypefn {C Function} int scm_is_inexact (SCM z)
791 Return a @code{1} if the number @var{z} is inexact, and @code{0}
792 otherwise. This is equivalent to @code{scm_is_true (scm_inexact_p (z))}.
795 @deffn {Scheme Procedure} inexact->exact z
796 @deffnx {C Function} scm_inexact_to_exact (z)
797 Return an exact number that is numerically closest to @var{z}, when
798 there is one. For inexact rationals, Guile returns the exact rational
799 that is numerically equal to the inexact rational. Inexact complex
800 numbers with a non-zero imaginary part can not be made exact.
807 The following happens because 12/10 is not exactly representable as a
808 @code{double} (on most platforms). However, when reading a decimal
809 number that has been marked exact with the ``#e'' prefix, Guile is
810 able to represent it correctly.
814 @result{} 5404319552844595/4503599627370496
822 @c begin (texi-doc-string "guile" "exact->inexact")
823 @deffn {Scheme Procedure} exact->inexact z
824 @deffnx {C Function} scm_exact_to_inexact (z)
825 Convert the number @var{z} to its inexact representation.
830 @subsubsection Read Syntax for Numerical Data
832 The read syntax for integers is a string of digits, optionally
833 preceded by a minus or plus character, a code indicating the
834 base in which the integer is encoded, and a code indicating whether
835 the number is exact or inexact. The supported base codes are:
840 the integer is written in binary (base 2)
844 the integer is written in octal (base 8)
848 the integer is written in decimal (base 10)
852 the integer is written in hexadecimal (base 16)
855 If the base code is omitted, the integer is assumed to be decimal. The
856 following examples show how these base codes are used.
875 The codes for indicating exactness (which can, incidentally, be applied
876 to all numerical values) are:
885 the number is inexact.
888 If the exactness indicator is omitted, the number is exact unless it
889 contains a radix point. Since Guile can not represent exact complex
890 numbers, an error is signalled when asking for them.
900 ERROR: Wrong type argument
903 Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
904 plus and minus infinity, respectively. The value must be written
905 exactly as shown, that is, they always must have a sign and exactly
906 one zero digit after the decimal point. It also understands
907 @samp{+nan.0} and @samp{-nan.0} for the special `not-a-number' value.
908 The sign is ignored for `not-a-number' and the value is always printed
911 @node Integer Operations
912 @subsubsection Operations on Integer Values
921 @deffn {Scheme Procedure} odd? n
922 @deffnx {C Function} scm_odd_p (n)
923 Return @code{#t} if @var{n} is an odd number, @code{#f}
927 @deffn {Scheme Procedure} even? n
928 @deffnx {C Function} scm_even_p (n)
929 Return @code{#t} if @var{n} is an even number, @code{#f}
933 @c begin (texi-doc-string "guile" "quotient")
934 @c begin (texi-doc-string "guile" "remainder")
935 @deffn {Scheme Procedure} quotient n d
936 @deffnx {Scheme Procedure} remainder n d
937 @deffnx {C Function} scm_quotient (n, d)
938 @deffnx {C Function} scm_remainder (n, d)
939 Return the quotient or remainder from @var{n} divided by @var{d}. The
940 quotient is rounded towards zero, and the remainder will have the same
941 sign as @var{n}. In all cases quotient and remainder satisfy
942 @math{@var{n} = @var{q}*@var{d} + @var{r}}.
945 (remainder 13 4) @result{} 1
946 (remainder -13 4) @result{} -1
949 See also @code{truncate-quotient}, @code{truncate-remainder} and
950 related operations in @ref{Arithmetic}.
953 @c begin (texi-doc-string "guile" "modulo")
954 @deffn {Scheme Procedure} modulo n d
955 @deffnx {C Function} scm_modulo (n, d)
956 Return the remainder from @var{n} divided by @var{d}, with the same
960 (modulo 13 4) @result{} 1
961 (modulo -13 4) @result{} 3
962 (modulo 13 -4) @result{} -3
963 (modulo -13 -4) @result{} -1
966 See also @code{floor-quotient}, @code{floor-remainder} and
967 related operations in @ref{Arithmetic}.
970 @c begin (texi-doc-string "guile" "gcd")
971 @deffn {Scheme Procedure} gcd x@dots{}
972 @deffnx {C Function} scm_gcd (x, y)
973 Return the greatest common divisor of all arguments.
974 If called without arguments, 0 is returned.
976 The C function @code{scm_gcd} always takes two arguments, while the
977 Scheme function can take an arbitrary number.
980 @c begin (texi-doc-string "guile" "lcm")
981 @deffn {Scheme Procedure} lcm x@dots{}
982 @deffnx {C Function} scm_lcm (x, y)
983 Return the least common multiple of the arguments.
984 If called without arguments, 1 is returned.
986 The C function @code{scm_lcm} always takes two arguments, while the
987 Scheme function can take an arbitrary number.
990 @deffn {Scheme Procedure} modulo-expt n k m
991 @deffnx {C Function} scm_modulo_expt (n, k, m)
992 Return @var{n} raised to the integer exponent
993 @var{k}, modulo @var{m}.
1001 @deftypefn {Scheme Procedure} {} exact-integer-sqrt @var{k}
1002 @deftypefnx {C Function} void scm_exact_integer_sqrt (SCM @var{k}, SCM *@var{s}, SCM *@var{r})
1003 Return two exact non-negative integers @var{s} and @var{r}
1004 such that @math{@var{k} = @var{s}^2 + @var{r}} and
1005 @math{@var{s}^2 <= @var{k} < (@var{s} + 1)^2}.
1006 An error is raised if @var{k} is not an exact non-negative integer.
1009 (exact-integer-sqrt 10) @result{} 3 and 1
1014 @subsubsection Comparison Predicates
1019 The C comparison functions below always takes two arguments, while the
1020 Scheme functions can take an arbitrary number. Also keep in mind that
1021 the C functions return one of the Scheme boolean values
1022 @code{SCM_BOOL_T} or @code{SCM_BOOL_F} which are both true as far as C
1023 is concerned. Thus, always write @code{scm_is_true (scm_num_eq_p (x,
1024 y))} when testing the two Scheme numbers @code{x} and @code{y} for
1025 equality, for example.
1027 @c begin (texi-doc-string "guile" "=")
1028 @deffn {Scheme Procedure} =
1029 @deffnx {C Function} scm_num_eq_p (x, y)
1030 Return @code{#t} if all parameters are numerically equal.
1033 @c begin (texi-doc-string "guile" "<")
1034 @deffn {Scheme Procedure} <
1035 @deffnx {C Function} scm_less_p (x, y)
1036 Return @code{#t} if the list of parameters is monotonically
1040 @c begin (texi-doc-string "guile" ">")
1041 @deffn {Scheme Procedure} >
1042 @deffnx {C Function} scm_gr_p (x, y)
1043 Return @code{#t} if the list of parameters is monotonically
1047 @c begin (texi-doc-string "guile" "<=")
1048 @deffn {Scheme Procedure} <=
1049 @deffnx {C Function} scm_leq_p (x, y)
1050 Return @code{#t} if the list of parameters is monotonically
1054 @c begin (texi-doc-string "guile" ">=")
1055 @deffn {Scheme Procedure} >=
1056 @deffnx {C Function} scm_geq_p (x, y)
1057 Return @code{#t} if the list of parameters is monotonically
1061 @c begin (texi-doc-string "guile" "zero?")
1062 @deffn {Scheme Procedure} zero? z
1063 @deffnx {C Function} scm_zero_p (z)
1064 Return @code{#t} if @var{z} is an exact or inexact number equal to
1068 @c begin (texi-doc-string "guile" "positive?")
1069 @deffn {Scheme Procedure} positive? x
1070 @deffnx {C Function} scm_positive_p (x)
1071 Return @code{#t} if @var{x} is an exact or inexact number greater than
1075 @c begin (texi-doc-string "guile" "negative?")
1076 @deffn {Scheme Procedure} negative? x
1077 @deffnx {C Function} scm_negative_p (x)
1078 Return @code{#t} if @var{x} is an exact or inexact number less than
1084 @subsubsection Converting Numbers To and From Strings
1085 @rnindex number->string
1086 @rnindex string->number
1088 The following procedures read and write numbers according to their
1089 external representation as defined by R5RS (@pxref{Lexical structure,
1090 R5RS Lexical Structure,, r5rs, The Revised^5 Report on the Algorithmic
1091 Language Scheme}). @xref{Number Input and Output, the @code{(ice-9
1092 i18n)} module}, for locale-dependent number parsing.
1094 @deffn {Scheme Procedure} number->string n [radix]
1095 @deffnx {C Function} scm_number_to_string (n, radix)
1096 Return a string holding the external representation of the
1097 number @var{n} in the given @var{radix}. If @var{n} is
1098 inexact, a radix of 10 will be used.
1101 @deffn {Scheme Procedure} string->number string [radix]
1102 @deffnx {C Function} scm_string_to_number (string, radix)
1103 Return a number of the maximally precise representation
1104 expressed by the given @var{string}. @var{radix} must be an
1105 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
1106 is a default radix that may be overridden by an explicit radix
1107 prefix in @var{string} (e.g.@: "#o177"). If @var{radix} is not
1108 supplied, then the default radix is 10. If string is not a
1109 syntactically valid notation for a number, then
1110 @code{string->number} returns @code{#f}.
1113 @deftypefn {C Function} SCM scm_c_locale_stringn_to_number (const char *string, size_t len, unsigned radix)
1114 As per @code{string->number} above, but taking a C string, as pointer
1115 and length. The string characters should be in the current locale
1116 encoding (@code{locale} in the name refers only to that, there's no
1117 locale-dependent parsing).
1122 @subsubsection Complex Number Operations
1123 @rnindex make-rectangular
1130 @deffn {Scheme Procedure} make-rectangular real_part imaginary_part
1131 @deffnx {C Function} scm_make_rectangular (real_part, imaginary_part)
1132 Return a complex number constructed of the given @var{real-part} and @var{imaginary-part} parts.
1135 @deffn {Scheme Procedure} make-polar mag ang
1136 @deffnx {C Function} scm_make_polar (mag, ang)
1138 Return the complex number @var{mag} * e^(i * @var{ang}).
1141 @c begin (texi-doc-string "guile" "real-part")
1142 @deffn {Scheme Procedure} real-part z
1143 @deffnx {C Function} scm_real_part (z)
1144 Return the real part of the number @var{z}.
1147 @c begin (texi-doc-string "guile" "imag-part")
1148 @deffn {Scheme Procedure} imag-part z
1149 @deffnx {C Function} scm_imag_part (z)
1150 Return the imaginary part of the number @var{z}.
1153 @c begin (texi-doc-string "guile" "magnitude")
1154 @deffn {Scheme Procedure} magnitude z
1155 @deffnx {C Function} scm_magnitude (z)
1156 Return the magnitude of the number @var{z}. This is the same as
1157 @code{abs} for real arguments, but also allows complex numbers.
1160 @c begin (texi-doc-string "guile" "angle")
1161 @deffn {Scheme Procedure} angle z
1162 @deffnx {C Function} scm_angle (z)
1163 Return the angle of the complex number @var{z}.
1166 @deftypefn {C Function} SCM scm_c_make_rectangular (double re, double im)
1167 @deftypefnx {C Function} SCM scm_c_make_polar (double x, double y)
1168 Like @code{scm_make_rectangular} or @code{scm_make_polar},
1169 respectively, but these functions take @code{double}s as their
1173 @deftypefn {C Function} double scm_c_real_part (z)
1174 @deftypefnx {C Function} double scm_c_imag_part (z)
1175 Returns the real or imaginary part of @var{z} as a @code{double}.
1178 @deftypefn {C Function} double scm_c_magnitude (z)
1179 @deftypefnx {C Function} double scm_c_angle (z)
1180 Returns the magnitude or angle of @var{z} as a @code{double}.
1185 @subsubsection Arithmetic Functions
1200 @rnindex euclidean-quotient
1201 @rnindex euclidean-remainder
1203 @rnindex floor-quotient
1204 @rnindex floor-remainder
1206 @rnindex ceiling-quotient
1207 @rnindex ceiling-remainder
1209 @rnindex truncate-quotient
1210 @rnindex truncate-remainder
1212 @rnindex centered-quotient
1213 @rnindex centered-remainder
1215 @rnindex round-quotient
1216 @rnindex round-remainder
1218 The C arithmetic functions below always takes two arguments, while the
1219 Scheme functions can take an arbitrary number. When you need to
1220 invoke them with just one argument, for example to compute the
1221 equivalent of @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
1222 one: @code{scm_difference (x, SCM_UNDEFINED)}.
1224 @c begin (texi-doc-string "guile" "+")
1225 @deffn {Scheme Procedure} + z1 @dots{}
1226 @deffnx {C Function} scm_sum (z1, z2)
1227 Return the sum of all parameter values. Return 0 if called without any
1231 @c begin (texi-doc-string "guile" "-")
1232 @deffn {Scheme Procedure} - z1 z2 @dots{}
1233 @deffnx {C Function} scm_difference (z1, z2)
1234 If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
1235 the sum of all but the first argument are subtracted from the first
1239 @c begin (texi-doc-string "guile" "*")
1240 @deffn {Scheme Procedure} * z1 @dots{}
1241 @deffnx {C Function} scm_product (z1, z2)
1242 Return the product of all arguments. If called without arguments, 1 is
1246 @c begin (texi-doc-string "guile" "/")
1247 @deffn {Scheme Procedure} / z1 z2 @dots{}
1248 @deffnx {C Function} scm_divide (z1, z2)
1249 Divide the first argument by the product of the remaining arguments. If
1250 called with one argument @var{z1}, 1/@var{z1} is returned.
1253 @deffn {Scheme Procedure} 1+ z
1254 @deffnx {C Function} scm_oneplus (z)
1255 Return @math{@var{z} + 1}.
1258 @deffn {Scheme Procedure} 1- z
1259 @deffnx {C function} scm_oneminus (z)
1260 Return @math{@var{z} - 1}.
1263 @c begin (texi-doc-string "guile" "abs")
1264 @deffn {Scheme Procedure} abs x
1265 @deffnx {C Function} scm_abs (x)
1266 Return the absolute value of @var{x}.
1268 @var{x} must be a number with zero imaginary part. To calculate the
1269 magnitude of a complex number, use @code{magnitude} instead.
1272 @c begin (texi-doc-string "guile" "max")
1273 @deffn {Scheme Procedure} max x1 x2 @dots{}
1274 @deffnx {C Function} scm_max (x1, x2)
1275 Return the maximum of all parameter values.
1278 @c begin (texi-doc-string "guile" "min")
1279 @deffn {Scheme Procedure} min x1 x2 @dots{}
1280 @deffnx {C Function} scm_min (x1, x2)
1281 Return the minimum of all parameter values.
1284 @c begin (texi-doc-string "guile" "truncate")
1285 @deffn {Scheme Procedure} truncate x
1286 @deffnx {C Function} scm_truncate_number (x)
1287 Round the inexact number @var{x} towards zero.
1290 @c begin (texi-doc-string "guile" "round")
1291 @deffn {Scheme Procedure} round x
1292 @deffnx {C Function} scm_round_number (x)
1293 Round the inexact number @var{x} to the nearest integer. When exactly
1294 halfway between two integers, round to the even one.
1297 @c begin (texi-doc-string "guile" "floor")
1298 @deffn {Scheme Procedure} floor x
1299 @deffnx {C Function} scm_floor (x)
1300 Round the number @var{x} towards minus infinity.
1303 @c begin (texi-doc-string "guile" "ceiling")
1304 @deffn {Scheme Procedure} ceiling x
1305 @deffnx {C Function} scm_ceiling (x)
1306 Round the number @var{x} towards infinity.
1309 @deftypefn {C Function} double scm_c_truncate (double x)
1310 @deftypefnx {C Function} double scm_c_round (double x)
1311 Like @code{scm_truncate_number} or @code{scm_round_number},
1312 respectively, but these functions take and return @code{double}
1316 @deftypefn {Scheme Procedure} {} euclidean/ @var{x} @var{y}
1317 @deftypefnx {Scheme Procedure} {} euclidean-quotient @var{x} @var{y}
1318 @deftypefnx {Scheme Procedure} {} euclidean-remainder @var{x} @var{y}
1319 @deftypefnx {C Function} void scm_euclidean_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1320 @deftypefnx {C Function} SCM scm_euclidean_quotient (SCM @var{x}, SCM @var{y})
1321 @deftypefnx {C Function} SCM scm_euclidean_remainder (SCM @var{x}, SCM @var{y})
1322 These procedures accept two real numbers @var{x} and @var{y}, where the
1323 divisor @var{y} must be non-zero. @code{euclidean-quotient} returns the
1324 integer @var{q} and @code{euclidean-remainder} returns the real number
1325 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
1326 @math{0 <= @var{r} < |@var{y}|}. @code{euclidean/} returns both @var{q} and
1327 @var{r}, and is more efficient than computing each separately. Note
1328 that when @math{@var{y} > 0}, @code{euclidean-quotient} returns
1329 @math{floor(@var{x}/@var{y})}, otherwise it returns
1330 @math{ceiling(@var{x}/@var{y})}.
1332 Note that these operators are equivalent to the R6RS operators
1333 @code{div}, @code{mod}, and @code{div-and-mod}.
1336 (euclidean-quotient 123 10) @result{} 12
1337 (euclidean-remainder 123 10) @result{} 3
1338 (euclidean/ 123 10) @result{} 12 and 3
1339 (euclidean/ 123 -10) @result{} -12 and 3
1340 (euclidean/ -123 10) @result{} -13 and 7
1341 (euclidean/ -123 -10) @result{} 13 and 7
1342 (euclidean/ -123.2 -63.5) @result{} 2.0 and 3.8
1343 (euclidean/ 16/3 -10/7) @result{} -3 and 22/21
1347 @deftypefn {Scheme Procedure} {} floor/ @var{x} @var{y}
1348 @deftypefnx {Scheme Procedure} {} floor-quotient @var{x} @var{y}
1349 @deftypefnx {Scheme Procedure} {} floor-remainder @var{x} @var{y}
1350 @deftypefnx {C Function} void scm_floor_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1351 @deftypefnx {C Function} SCM scm_floor_quotient (@var{x}, @var{y})
1352 @deftypefnx {C Function} SCM scm_floor_remainder (@var{x}, @var{y})
1353 These procedures accept two real numbers @var{x} and @var{y}, where the
1354 divisor @var{y} must be non-zero. @code{floor-quotient} returns the
1355 integer @var{q} and @code{floor-remainder} returns the real number
1356 @var{r} such that @math{@var{q} = floor(@var{x}/@var{y})} and
1357 @math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{floor/} returns
1358 both @var{q} and @var{r}, and is more efficient than computing each
1359 separately. Note that @var{r}, if non-zero, will have the same sign
1362 When @var{x} and @var{y} are integers, @code{floor-remainder} is
1363 equivalent to the R5RS integer-only operator @code{modulo}.
1366 (floor-quotient 123 10) @result{} 12
1367 (floor-remainder 123 10) @result{} 3
1368 (floor/ 123 10) @result{} 12 and 3
1369 (floor/ 123 -10) @result{} -13 and -7
1370 (floor/ -123 10) @result{} -13 and 7
1371 (floor/ -123 -10) @result{} 12 and -3
1372 (floor/ -123.2 -63.5) @result{} 1.0 and -59.7
1373 (floor/ 16/3 -10/7) @result{} -4 and -8/21
1377 @deftypefn {Scheme Procedure} {} ceiling/ @var{x} @var{y}
1378 @deftypefnx {Scheme Procedure} {} ceiling-quotient @var{x} @var{y}
1379 @deftypefnx {Scheme Procedure} {} ceiling-remainder @var{x} @var{y}
1380 @deftypefnx {C Function} void scm_ceiling_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1381 @deftypefnx {C Function} SCM scm_ceiling_quotient (@var{x}, @var{y})
1382 @deftypefnx {C Function} SCM scm_ceiling_remainder (@var{x}, @var{y})
1383 These procedures accept two real numbers @var{x} and @var{y}, where the
1384 divisor @var{y} must be non-zero. @code{ceiling-quotient} returns the
1385 integer @var{q} and @code{ceiling-remainder} returns the real number
1386 @var{r} such that @math{@var{q} = ceiling(@var{x}/@var{y})} and
1387 @math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{ceiling/} returns
1388 both @var{q} and @var{r}, and is more efficient than computing each
1389 separately. Note that @var{r}, if non-zero, will have the opposite sign
1393 (ceiling-quotient 123 10) @result{} 13
1394 (ceiling-remainder 123 10) @result{} -7
1395 (ceiling/ 123 10) @result{} 13 and -7
1396 (ceiling/ 123 -10) @result{} -12 and 3
1397 (ceiling/ -123 10) @result{} -12 and -3
1398 (ceiling/ -123 -10) @result{} 13 and 7
1399 (ceiling/ -123.2 -63.5) @result{} 2.0 and 3.8
1400 (ceiling/ 16/3 -10/7) @result{} -3 and 22/21
1404 @deftypefn {Scheme Procedure} {} truncate/ @var{x} @var{y}
1405 @deftypefnx {Scheme Procedure} {} truncate-quotient @var{x} @var{y}
1406 @deftypefnx {Scheme Procedure} {} truncate-remainder @var{x} @var{y}
1407 @deftypefnx {C Function} void scm_truncate_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1408 @deftypefnx {C Function} SCM scm_truncate_quotient (@var{x}, @var{y})
1409 @deftypefnx {C Function} SCM scm_truncate_remainder (@var{x}, @var{y})
1410 These procedures accept two real numbers @var{x} and @var{y}, where the
1411 divisor @var{y} must be non-zero. @code{truncate-quotient} returns the
1412 integer @var{q} and @code{truncate-remainder} returns the real number
1413 @var{r} such that @var{q} is @math{@var{x}/@var{y}} rounded toward zero,
1414 and @math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{truncate/} returns
1415 both @var{q} and @var{r}, and is more efficient than computing each
1416 separately. Note that @var{r}, if non-zero, will have the same sign
1419 When @var{x} and @var{y} are integers, these operators are
1420 equivalent to the R5RS integer-only operators @code{quotient} and
1424 (truncate-quotient 123 10) @result{} 12
1425 (truncate-remainder 123 10) @result{} 3
1426 (truncate/ 123 10) @result{} 12 and 3
1427 (truncate/ 123 -10) @result{} -12 and 3
1428 (truncate/ -123 10) @result{} -12 and -3
1429 (truncate/ -123 -10) @result{} 12 and -3
1430 (truncate/ -123.2 -63.5) @result{} 1.0 and -59.7
1431 (truncate/ 16/3 -10/7) @result{} -3 and 22/21
1435 @deftypefn {Scheme Procedure} {} centered/ @var{x} @var{y}
1436 @deftypefnx {Scheme Procedure} {} centered-quotient @var{x} @var{y}
1437 @deftypefnx {Scheme Procedure} {} centered-remainder @var{x} @var{y}
1438 @deftypefnx {C Function} void scm_centered_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1439 @deftypefnx {C Function} SCM scm_centered_quotient (SCM @var{x}, SCM @var{y})
1440 @deftypefnx {C Function} SCM scm_centered_remainder (SCM @var{x}, SCM @var{y})
1441 These procedures accept two real numbers @var{x} and @var{y}, where the
1442 divisor @var{y} must be non-zero. @code{centered-quotient} returns the
1443 integer @var{q} and @code{centered-remainder} returns the real number
1444 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
1445 @math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}. @code{centered/}
1446 returns both @var{q} and @var{r}, and is more efficient than computing
1449 Note that @code{centered-quotient} returns @math{@var{x}/@var{y}}
1450 rounded to the nearest integer. When @math{@var{x}/@var{y}} lies
1451 exactly half-way between two integers, the tie is broken according to
1452 the sign of @var{y}. If @math{@var{y} > 0}, ties are rounded toward
1453 positive infinity, otherwise they are rounded toward negative infinity.
1454 This is a consequence of the requirement that
1455 @math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}.
1457 Note that these operators are equivalent to the R6RS operators
1458 @code{div0}, @code{mod0}, and @code{div0-and-mod0}.
1461 (centered-quotient 123 10) @result{} 12
1462 (centered-remainder 123 10) @result{} 3
1463 (centered/ 123 10) @result{} 12 and 3
1464 (centered/ 123 -10) @result{} -12 and 3
1465 (centered/ -123 10) @result{} -12 and -3
1466 (centered/ -123 -10) @result{} 12 and -3
1467 (centered/ 125 10) @result{} 13 and -5
1468 (centered/ 127 10) @result{} 13 and -3
1469 (centered/ 135 10) @result{} 14 and -5
1470 (centered/ -123.2 -63.5) @result{} 2.0 and 3.8
1471 (centered/ 16/3 -10/7) @result{} -4 and -8/21
1475 @deftypefn {Scheme Procedure} {} round/ @var{x} @var{y}
1476 @deftypefnx {Scheme Procedure} {} round-quotient @var{x} @var{y}
1477 @deftypefnx {Scheme Procedure} {} round-remainder @var{x} @var{y}
1478 @deftypefnx {C Function} void scm_round_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1479 @deftypefnx {C Function} SCM scm_round_quotient (@var{x}, @var{y})
1480 @deftypefnx {C Function} SCM scm_round_remainder (@var{x}, @var{y})
1481 These procedures accept two real numbers @var{x} and @var{y}, where the
1482 divisor @var{y} must be non-zero. @code{round-quotient} returns the
1483 integer @var{q} and @code{round-remainder} returns the real number
1484 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
1485 @var{q} is @math{@var{x}/@var{y}} rounded to the nearest integer,
1486 with ties going to the nearest even integer. @code{round/}
1487 returns both @var{q} and @var{r}, and is more efficient than computing
1490 Note that @code{round/} and @code{centered/} are almost equivalent, but
1491 their behavior differs when @math{@var{x}/@var{y}} lies exactly half-way
1492 between two integers. In this case, @code{round/} chooses the nearest
1493 even integer, whereas @code{centered/} chooses in such a way to satisfy
1494 the constraint @math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}, which
1495 is stronger than the corresponding constraint for @code{round/},
1496 @math{-|@var{y}/2| <= @var{r} <= |@var{y}/2|}. In particular,
1497 when @var{x} and @var{y} are integers, the number of possible remainders
1498 returned by @code{centered/} is @math{|@var{y}|}, whereas the number of
1499 possible remainders returned by @code{round/} is @math{|@var{y}|+1} when
1503 (round-quotient 123 10) @result{} 12
1504 (round-remainder 123 10) @result{} 3
1505 (round/ 123 10) @result{} 12 and 3
1506 (round/ 123 -10) @result{} -12 and 3
1507 (round/ -123 10) @result{} -12 and -3
1508 (round/ -123 -10) @result{} 12 and -3
1509 (round/ 125 10) @result{} 12 and 5
1510 (round/ 127 10) @result{} 13 and -3
1511 (round/ 135 10) @result{} 14 and -5
1512 (round/ -123.2 -63.5) @result{} 2.0 and 3.8
1513 (round/ 16/3 -10/7) @result{} -4 and -8/21
1518 @subsubsection Scientific Functions
1520 The following procedures accept any kind of number as arguments,
1521 including complex numbers.
1524 @c begin (texi-doc-string "guile" "sqrt")
1525 @deffn {Scheme Procedure} sqrt z
1526 Return the square root of @var{z}. Of the two possible roots
1527 (positive and negative), the one with a positive real part is
1528 returned, or if that's zero then a positive imaginary part. Thus,
1531 (sqrt 9.0) @result{} 3.0
1532 (sqrt -9.0) @result{} 0.0+3.0i
1533 (sqrt 1.0+1.0i) @result{} 1.09868411346781+0.455089860562227i
1534 (sqrt -1.0-1.0i) @result{} 0.455089860562227-1.09868411346781i
1539 @c begin (texi-doc-string "guile" "expt")
1540 @deffn {Scheme Procedure} expt z1 z2
1541 Return @var{z1} raised to the power of @var{z2}.
1545 @c begin (texi-doc-string "guile" "sin")
1546 @deffn {Scheme Procedure} sin z
1547 Return the sine of @var{z}.
1551 @c begin (texi-doc-string "guile" "cos")
1552 @deffn {Scheme Procedure} cos z
1553 Return the cosine of @var{z}.
1557 @c begin (texi-doc-string "guile" "tan")
1558 @deffn {Scheme Procedure} tan z
1559 Return the tangent of @var{z}.
1563 @c begin (texi-doc-string "guile" "asin")
1564 @deffn {Scheme Procedure} asin z
1565 Return the arcsine of @var{z}.
1569 @c begin (texi-doc-string "guile" "acos")
1570 @deffn {Scheme Procedure} acos z
1571 Return the arccosine of @var{z}.
1575 @c begin (texi-doc-string "guile" "atan")
1576 @deffn {Scheme Procedure} atan z
1577 @deffnx {Scheme Procedure} atan y x
1578 Return the arctangent of @var{z}, or of @math{@var{y}/@var{x}}.
1582 @c begin (texi-doc-string "guile" "exp")
1583 @deffn {Scheme Procedure} exp z
1584 Return e to the power of @var{z}, where e is the base of natural
1585 logarithms (2.71828@dots{}).
1589 @c begin (texi-doc-string "guile" "log")
1590 @deffn {Scheme Procedure} log z
1591 Return the natural logarithm of @var{z}.
1594 @c begin (texi-doc-string "guile" "log10")
1595 @deffn {Scheme Procedure} log10 z
1596 Return the base 10 logarithm of @var{z}.
1599 @c begin (texi-doc-string "guile" "sinh")
1600 @deffn {Scheme Procedure} sinh z
1601 Return the hyperbolic sine of @var{z}.
1604 @c begin (texi-doc-string "guile" "cosh")
1605 @deffn {Scheme Procedure} cosh z
1606 Return the hyperbolic cosine of @var{z}.
1609 @c begin (texi-doc-string "guile" "tanh")
1610 @deffn {Scheme Procedure} tanh z
1611 Return the hyperbolic tangent of @var{z}.
1614 @c begin (texi-doc-string "guile" "asinh")
1615 @deffn {Scheme Procedure} asinh z
1616 Return the hyperbolic arcsine of @var{z}.
1619 @c begin (texi-doc-string "guile" "acosh")
1620 @deffn {Scheme Procedure} acosh z
1621 Return the hyperbolic arccosine of @var{z}.
1624 @c begin (texi-doc-string "guile" "atanh")
1625 @deffn {Scheme Procedure} atanh z
1626 Return the hyperbolic arctangent of @var{z}.
1630 @node Bitwise Operations
1631 @subsubsection Bitwise Operations
1633 For the following bitwise functions, negative numbers are treated as
1634 infinite precision twos-complements. For instance @math{-6} is bits
1635 @math{@dots{}111010}, with infinitely many ones on the left. It can
1636 be seen that adding 6 (binary 110) to such a bit pattern gives all
1639 @deffn {Scheme Procedure} logand n1 n2 @dots{}
1640 @deffnx {C Function} scm_logand (n1, n2)
1641 Return the bitwise @sc{and} of the integer arguments.
1644 (logand) @result{} -1
1645 (logand 7) @result{} 7
1646 (logand #b111 #b011 #b001) @result{} 1
1650 @deffn {Scheme Procedure} logior n1 n2 @dots{}
1651 @deffnx {C Function} scm_logior (n1, n2)
1652 Return the bitwise @sc{or} of the integer arguments.
1655 (logior) @result{} 0
1656 (logior 7) @result{} 7
1657 (logior #b000 #b001 #b011) @result{} 3
1661 @deffn {Scheme Procedure} logxor n1 n2 @dots{}
1662 @deffnx {C Function} scm_loxor (n1, n2)
1663 Return the bitwise @sc{xor} of the integer arguments. A bit is
1664 set in the result if it is set in an odd number of arguments.
1667 (logxor) @result{} 0
1668 (logxor 7) @result{} 7
1669 (logxor #b000 #b001 #b011) @result{} 2
1670 (logxor #b000 #b001 #b011 #b011) @result{} 1
1674 @deffn {Scheme Procedure} lognot n
1675 @deffnx {C Function} scm_lognot (n)
1676 Return the integer which is the ones-complement of the integer
1677 argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
1680 (number->string (lognot #b10000000) 2)
1681 @result{} "-10000001"
1682 (number->string (lognot #b0) 2)
1687 @deffn {Scheme Procedure} logtest j k
1688 @deffnx {C Function} scm_logtest (j, k)
1689 Test whether @var{j} and @var{k} have any 1 bits in common. This is
1690 equivalent to @code{(not (zero? (logand j k)))}, but without actually
1691 calculating the @code{logand}, just testing for non-zero.
1694 (logtest #b0100 #b1011) @result{} #f
1695 (logtest #b0100 #b0111) @result{} #t
1699 @deffn {Scheme Procedure} logbit? index j
1700 @deffnx {C Function} scm_logbit_p (index, j)
1701 Test whether bit number @var{index} in @var{j} is set. @var{index}
1702 starts from 0 for the least significant bit.
1705 (logbit? 0 #b1101) @result{} #t
1706 (logbit? 1 #b1101) @result{} #f
1707 (logbit? 2 #b1101) @result{} #t
1708 (logbit? 3 #b1101) @result{} #t
1709 (logbit? 4 #b1101) @result{} #f
1713 @deffn {Scheme Procedure} ash n count
1714 @deffnx {C Function} scm_ash (n, count)
1715 Return @math{floor(n * 2^count)}.
1716 @var{n} and @var{count} must be exact integers.
1718 With @var{n} viewed as an infinite-precision twos-complement
1719 integer, @code{ash} means a left shift introducing zero bits
1720 when @var{count} is positive, or a right shift dropping bits
1721 when @var{count} is negative. This is an ``arithmetic'' shift.
1724 (number->string (ash #b1 3) 2) @result{} "1000"
1725 (number->string (ash #b1010 -1) 2) @result{} "101"
1727 ;; -23 is bits ...11101001, -6 is bits ...111010
1728 (ash -23 -2) @result{} -6
1732 @deffn {Scheme Procedure} round-ash n count
1733 @deffnx {C Function} scm_round_ash (n, count)
1734 Return @math{round(n * 2^count)}.
1735 @var{n} and @var{count} must be exact integers.
1737 With @var{n} viewed as an infinite-precision twos-complement
1738 integer, @code{round-ash} means a left shift introducing zero
1739 bits when @var{count} is positive, or a right shift rounding
1740 to the nearest integer (with ties going to the nearest even
1741 integer) when @var{count} is negative. This is a rounded
1742 ``arithmetic'' shift.
1745 (number->string (round-ash #b1 3) 2) @result{} \"1000\"
1746 (number->string (round-ash #b1010 -1) 2) @result{} \"101\"
1747 (number->string (round-ash #b1010 -2) 2) @result{} \"10\"
1748 (number->string (round-ash #b1011 -2) 2) @result{} \"11\"
1749 (number->string (round-ash #b1101 -2) 2) @result{} \"11\"
1750 (number->string (round-ash #b1110 -2) 2) @result{} \"100\"
1754 @deffn {Scheme Procedure} logcount n
1755 @deffnx {C Function} scm_logcount (n)
1756 Return the number of bits in integer @var{n}. If @var{n} is
1757 positive, the 1-bits in its binary representation are counted.
1758 If negative, the 0-bits in its two's-complement binary
1759 representation are counted. If zero, 0 is returned.
1762 (logcount #b10101010)
1771 @deffn {Scheme Procedure} integer-length n
1772 @deffnx {C Function} scm_integer_length (n)
1773 Return the number of bits necessary to represent @var{n}.
1775 For positive @var{n} this is how many bits to the most significant one
1776 bit. For negative @var{n} it's how many bits to the most significant
1777 zero bit in twos complement form.
1780 (integer-length #b10101010) @result{} 8
1781 (integer-length #b1111) @result{} 4
1782 (integer-length 0) @result{} 0
1783 (integer-length -1) @result{} 0
1784 (integer-length -256) @result{} 8
1785 (integer-length -257) @result{} 9
1789 @deffn {Scheme Procedure} integer-expt n k
1790 @deffnx {C Function} scm_integer_expt (n, k)
1791 Return @var{n} raised to the power @var{k}. @var{k} must be an exact
1792 integer, @var{n} can be any number.
1794 Negative @var{k} is supported, and results in @m{1/n^|k|, 1/n^abs(k)}
1795 in the usual way. @math{@var{n}^0} is 1, as usual, and that includes
1799 (integer-expt 2 5) @result{} 32
1800 (integer-expt -3 3) @result{} -27
1801 (integer-expt 5 -3) @result{} 1/125
1802 (integer-expt 0 0) @result{} 1
1806 @deffn {Scheme Procedure} bit-extract n start end
1807 @deffnx {C Function} scm_bit_extract (n, start, end)
1808 Return the integer composed of the @var{start} (inclusive)
1809 through @var{end} (exclusive) bits of @var{n}. The
1810 @var{start}th bit becomes the 0-th bit in the result.
1813 (number->string (bit-extract #b1101101010 0 4) 2)
1815 (number->string (bit-extract #b1101101010 4 9) 2)
1822 @subsubsection Random Number Generation
1824 Pseudo-random numbers are generated from a random state object, which
1825 can be created with @code{seed->random-state} or
1826 @code{datum->random-state}. An external representation (i.e.@: one
1827 which can written with @code{write} and read with @code{read}) of a
1828 random state object can be obtained via
1829 @code{random-state->datum}. The @var{state} parameter to the
1830 various functions below is optional, it defaults to the state object
1831 in the @code{*random-state*} variable.
1833 @deffn {Scheme Procedure} copy-random-state [state]
1834 @deffnx {C Function} scm_copy_random_state (state)
1835 Return a copy of the random state @var{state}.
1838 @deffn {Scheme Procedure} random n [state]
1839 @deffnx {C Function} scm_random (n, state)
1840 Return a number in [0, @var{n}).
1842 Accepts a positive integer or real n and returns a
1843 number of the same type between zero (inclusive) and
1844 @var{n} (exclusive). The values returned have a uniform
1848 @deffn {Scheme Procedure} random:exp [state]
1849 @deffnx {C Function} scm_random_exp (state)
1850 Return an inexact real in an exponential distribution with mean
1851 1. For an exponential distribution with mean @var{u} use @code{(*
1852 @var{u} (random:exp))}.
1855 @deffn {Scheme Procedure} random:hollow-sphere! vect [state]
1856 @deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
1857 Fills @var{vect} with inexact real random numbers the sum of whose
1858 squares is equal to 1.0. Thinking of @var{vect} as coordinates in
1859 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1860 the coordinates are uniformly distributed over the surface of the unit
1864 @deffn {Scheme Procedure} random:normal [state]
1865 @deffnx {C Function} scm_random_normal (state)
1866 Return an inexact real in a normal distribution. The distribution
1867 used has mean 0 and standard deviation 1. For a normal distribution
1868 with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
1869 (* @var{d} (random:normal)))}.
1872 @deffn {Scheme Procedure} random:normal-vector! vect [state]
1873 @deffnx {C Function} scm_random_normal_vector_x (vect, state)
1874 Fills @var{vect} with inexact real random numbers that are
1875 independent and standard normally distributed
1876 (i.e., with mean 0 and variance 1).
1879 @deffn {Scheme Procedure} random:solid-sphere! vect [state]
1880 @deffnx {C Function} scm_random_solid_sphere_x (vect, state)
1881 Fills @var{vect} with inexact real random numbers the sum of whose
1882 squares is less than 1.0. Thinking of @var{vect} as coordinates in
1883 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1884 the coordinates are uniformly distributed within the unit
1886 @c FIXME: What does this mean, particularly the n-sphere part?
1889 @deffn {Scheme Procedure} random:uniform [state]
1890 @deffnx {C Function} scm_random_uniform (state)
1891 Return a uniformly distributed inexact real random number in
1895 @deffn {Scheme Procedure} seed->random-state seed
1896 @deffnx {C Function} scm_seed_to_random_state (seed)
1897 Return a new random state using @var{seed}.
1900 @deffn {Scheme Procedure} datum->random-state datum
1901 @deffnx {C Function} scm_datum_to_random_state (datum)
1902 Return a new random state from @var{datum}, which should have been
1903 obtained by @code{random-state->datum}.
1906 @deffn {Scheme Procedure} random-state->datum state
1907 @deffnx {C Function} scm_random_state_to_datum (state)
1908 Return a datum representation of @var{state} that may be written out and
1909 read back with the Scheme reader.
1912 @deffn {Scheme Procedure} random-state-from-platform
1913 @deffnx {C Function} scm_random_state_from_platform ()
1914 Construct a new random state seeded from a platform-specific source of
1915 entropy, appropriate for use in non-security-critical applications.
1916 Currently @file{/dev/urandom} is tried first, or else the seed is based
1917 on the time, date, process ID, an address from a freshly allocated heap
1918 cell, an address from the local stack frame, and a high-resolution timer
1922 @defvar *random-state*
1923 The global random state used by the above functions when the
1924 @var{state} parameter is not given.
1927 Note that the initial value of @code{*random-state*} is the same every
1928 time Guile starts up. Therefore, if you don't pass a @var{state}
1929 parameter to the above procedures, and you don't set
1930 @code{*random-state*} to @code{(seed->random-state your-seed)}, where
1931 @code{your-seed} is something that @emph{isn't} the same every time,
1932 you'll get the same sequence of ``random'' numbers on every run.
1934 For example, unless the relevant source code has changed, @code{(map
1935 random (cdr (iota 30)))}, if the first use of random numbers since
1936 Guile started up, will always give:
1939 (map random (cdr (iota 19)))
1941 (0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12)
1944 To seed the random state in a sensible way for non-security-critical
1945 applications, do this during initialization of your program:
1948 (set! *random-state* (random-state-from-platform))
1953 @subsection Characters
1956 In Scheme, there is a data type to describe a single character.
1958 Defining what exactly a character @emph{is} can be more complicated
1959 than it seems. Guile follows the advice of R6RS and uses The Unicode
1960 Standard to help define what a character is. So, for Guile, a
1961 character is anything in the Unicode Character Database.
1964 @cindex Unicode code point
1966 The Unicode Character Database is basically a table of characters
1967 indexed using integers called 'code points'. Valid code points are in
1968 the ranges 0 to @code{#xD7FF} inclusive or @code{#xE000} to
1969 @code{#x10FFFF} inclusive, which is about 1.1 million code points.
1971 @cindex designated code point
1972 @cindex code point, designated
1974 Any code point that has been assigned to a character or that has
1975 otherwise been given a meaning by Unicode is called a 'designated code
1976 point'. Most of the designated code points, about 200,000 of them,
1977 indicate characters, accents or other combining marks that modify
1978 other characters, symbols, whitespace, and control characters. Some
1979 are not characters but indicators that suggest how to format or
1980 display neighboring characters.
1982 @cindex reserved code point
1983 @cindex code point, reserved
1985 If a code point is not a designated code point -- if it has not been
1986 assigned to a character by The Unicode Standard -- it is a 'reserved
1987 code point', meaning that they are reserved for future use. Most of
1988 the code points, about 800,000, are 'reserved code points'.
1990 By convention, a Unicode code point is written as
1991 ``U+XXXX'' where ``XXXX'' is a hexadecimal number. Please note that
1992 this convenient notation is not valid code. Guile does not interpret
1993 ``U+XXXX'' as a character.
1995 In Scheme, a character literal is written as @code{#\@var{name}} where
1996 @var{name} is the name of the character that you want. Printable
1997 characters have their usual single character name; for example,
1998 @code{#\a} is a lower case @code{a}.
2000 Some of the code points are 'combining characters' that are not meant
2001 to be printed by themselves but are instead meant to modify the
2002 appearance of the previous character. For combining characters, an
2003 alternate form of the character literal is @code{#\} followed by
2004 U+25CC (a small, dotted circle), followed by the combining character.
2005 This allows the combining character to be drawn on the circle, not on
2006 the backslash of @code{#\}.
2008 Many of the non-printing characters, such as whitespace characters and
2009 control characters, also have names.
2011 The most commonly used non-printing characters have long character
2012 names, described in the table below.
2014 @multitable {@code{#\backspace}} {Preferred}
2015 @item Character Name @tab Codepoint
2016 @item @code{#\nul} @tab U+0000
2017 @item @code{#\alarm} @tab u+0007
2018 @item @code{#\backspace} @tab U+0008
2019 @item @code{#\tab} @tab U+0009
2020 @item @code{#\linefeed} @tab U+000A
2021 @item @code{#\newline} @tab U+000A
2022 @item @code{#\vtab} @tab U+000B
2023 @item @code{#\page} @tab U+000C
2024 @item @code{#\return} @tab U+000D
2025 @item @code{#\esc} @tab U+001B
2026 @item @code{#\space} @tab U+0020
2027 @item @code{#\delete} @tab U+007F
2030 There are also short names for all of the ``C0 control characters''
2031 (those with code points below 32). The following table lists the short
2032 name for each character.
2034 @multitable @columnfractions .25 .25 .25 .25
2035 @item 0 = @code{#\nul}
2036 @tab 1 = @code{#\soh}
2037 @tab 2 = @code{#\stx}
2038 @tab 3 = @code{#\etx}
2039 @item 4 = @code{#\eot}
2040 @tab 5 = @code{#\enq}
2041 @tab 6 = @code{#\ack}
2042 @tab 7 = @code{#\bel}
2043 @item 8 = @code{#\bs}
2044 @tab 9 = @code{#\ht}
2045 @tab 10 = @code{#\lf}
2046 @tab 11 = @code{#\vt}
2047 @item 12 = @code{#\ff}
2048 @tab 13 = @code{#\cr}
2049 @tab 14 = @code{#\so}
2050 @tab 15 = @code{#\si}
2051 @item 16 = @code{#\dle}
2052 @tab 17 = @code{#\dc1}
2053 @tab 18 = @code{#\dc2}
2054 @tab 19 = @code{#\dc3}
2055 @item 20 = @code{#\dc4}
2056 @tab 21 = @code{#\nak}
2057 @tab 22 = @code{#\syn}
2058 @tab 23 = @code{#\etb}
2059 @item 24 = @code{#\can}
2060 @tab 25 = @code{#\em}
2061 @tab 26 = @code{#\sub}
2062 @tab 27 = @code{#\esc}
2063 @item 28 = @code{#\fs}
2064 @tab 29 = @code{#\gs}
2065 @tab 30 = @code{#\rs}
2066 @tab 31 = @code{#\us}
2067 @item 32 = @code{#\sp}
2070 The short name for the ``delete'' character (code point U+007F) is
2073 The R7RS name for the ``escape'' character (code point U+001B) is
2076 There are also a few alternative names left over for compatibility with
2077 previous versions of Guile.
2079 @multitable {@code{#\backspace}} {Preferred}
2080 @item Alternate @tab Standard
2081 @item @code{#\nl} @tab @code{#\newline}
2082 @item @code{#\np} @tab @code{#\page}
2083 @item @code{#\null} @tab @code{#\nul}
2086 Characters may also be written using their code point values. They can
2087 be written with as an octal number, such as @code{#\10} for
2088 @code{#\bs} or @code{#\177} for @code{#\del}.
2090 If one prefers hex to octal, there is an additional syntax for character
2091 escapes: @code{#\xHHHH} -- the letter 'x' followed by a hexadecimal
2092 number of one to eight digits.
2095 @deffn {Scheme Procedure} char? x
2096 @deffnx {C Function} scm_char_p (x)
2097 Return @code{#t} if @var{x} is a character, else @code{#f}.
2100 Fundamentally, the character comparison operations below are
2101 numeric comparisons of the character's code points.
2104 @deffn {Scheme Procedure} char=? x y
2105 Return @code{#t} if code point of @var{x} is equal to the code point
2106 of @var{y}, else @code{#f}.
2110 @deffn {Scheme Procedure} char<? x y
2111 Return @code{#t} if the code point of @var{x} is less than the code
2112 point of @var{y}, else @code{#f}.
2116 @deffn {Scheme Procedure} char<=? x y
2117 Return @code{#t} if the code point of @var{x} is less than or equal
2118 to the code point of @var{y}, else @code{#f}.
2122 @deffn {Scheme Procedure} char>? x y
2123 Return @code{#t} if the code point of @var{x} is greater than the
2124 code point of @var{y}, else @code{#f}.
2128 @deffn {Scheme Procedure} char>=? x y
2129 Return @code{#t} if the code point of @var{x} is greater than or
2130 equal to the code point of @var{y}, else @code{#f}.
2133 @cindex case folding
2135 Case-insensitive character comparisons use @emph{Unicode case
2136 folding}. In case folding comparisons, if a character is lowercase
2137 and has an uppercase form that can be expressed as a single character,
2138 it is converted to uppercase before comparison. All other characters
2139 undergo no conversion before the comparison occurs. This includes the
2140 German sharp S (Eszett) which is not uppercased before conversion
2141 because its uppercase form has two characters. Unicode case folding
2142 is language independent: it uses rules that are generally true, but,
2143 it cannot cover all cases for all languages.
2146 @deffn {Scheme Procedure} char-ci=? x y
2147 Return @code{#t} if the case-folded code point of @var{x} is the same
2148 as the case-folded code point of @var{y}, else @code{#f}.
2152 @deffn {Scheme Procedure} char-ci<? x y
2153 Return @code{#t} if the case-folded code point of @var{x} is less
2154 than the case-folded code point of @var{y}, else @code{#f}.
2158 @deffn {Scheme Procedure} char-ci<=? x y
2159 Return @code{#t} if the case-folded code point of @var{x} is less
2160 than or equal to the case-folded code point of @var{y}, else
2165 @deffn {Scheme Procedure} char-ci>? x y
2166 Return @code{#t} if the case-folded code point of @var{x} is greater
2167 than the case-folded code point of @var{y}, else @code{#f}.
2171 @deffn {Scheme Procedure} char-ci>=? x y
2172 Return @code{#t} if the case-folded code point of @var{x} is greater
2173 than or equal to the case-folded code point of @var{y}, else
2177 @rnindex char-alphabetic?
2178 @deffn {Scheme Procedure} char-alphabetic? chr
2179 @deffnx {C Function} scm_char_alphabetic_p (chr)
2180 Return @code{#t} if @var{chr} is alphabetic, else @code{#f}.
2183 @rnindex char-numeric?
2184 @deffn {Scheme Procedure} char-numeric? chr
2185 @deffnx {C Function} scm_char_numeric_p (chr)
2186 Return @code{#t} if @var{chr} is numeric, else @code{#f}.
2189 @rnindex char-whitespace?
2190 @deffn {Scheme Procedure} char-whitespace? chr
2191 @deffnx {C Function} scm_char_whitespace_p (chr)
2192 Return @code{#t} if @var{chr} is whitespace, else @code{#f}.
2195 @rnindex char-upper-case?
2196 @deffn {Scheme Procedure} char-upper-case? chr
2197 @deffnx {C Function} scm_char_upper_case_p (chr)
2198 Return @code{#t} if @var{chr} is uppercase, else @code{#f}.
2201 @rnindex char-lower-case?
2202 @deffn {Scheme Procedure} char-lower-case? chr
2203 @deffnx {C Function} scm_char_lower_case_p (chr)
2204 Return @code{#t} if @var{chr} is lowercase, else @code{#f}.
2207 @deffn {Scheme Procedure} char-is-both? chr
2208 @deffnx {C Function} scm_char_is_both_p (chr)
2209 Return @code{#t} if @var{chr} is either uppercase or lowercase, else
2213 @deffn {Scheme Procedure} char-general-category chr
2214 @deffnx {C Function} scm_char_general_category (chr)
2215 Return a symbol giving the two-letter name of the Unicode general
2216 category assigned to @var{chr} or @code{#f} if no named category is
2217 assigned. The following table provides a list of category names along
2218 with their meanings.
2220 @multitable @columnfractions .1 .4 .1 .4
2222 @tab Uppercase letter
2224 @tab Final quote punctuation
2226 @tab Lowercase letter
2228 @tab Other punctuation
2230 @tab Titlecase letter
2234 @tab Modifier letter
2236 @tab Currency symbol
2240 @tab Modifier symbol
2242 @tab Non-spacing mark
2246 @tab Combining spacing mark
2248 @tab Space separator
2254 @tab Decimal digit number
2256 @tab Paragraph separator
2266 @tab Connector punctuation
2270 @tab Dash punctuation
2274 @tab Open punctuation
2278 @tab Close punctuation
2282 @tab Initial quote punctuation
2288 @rnindex char->integer
2289 @deffn {Scheme Procedure} char->integer chr
2290 @deffnx {C Function} scm_char_to_integer (chr)
2291 Return the code point of @var{chr}.
2294 @rnindex integer->char
2295 @deffn {Scheme Procedure} integer->char n
2296 @deffnx {C Function} scm_integer_to_char (n)
2297 Return the character that has code point @var{n}. The integer @var{n}
2298 must be a valid code point. Valid code points are in the ranges 0 to
2299 @code{#xD7FF} inclusive or @code{#xE000} to @code{#x10FFFF} inclusive.
2302 @rnindex char-upcase
2303 @deffn {Scheme Procedure} char-upcase chr
2304 @deffnx {C Function} scm_char_upcase (chr)
2305 Return the uppercase character version of @var{chr}.
2308 @rnindex char-downcase
2309 @deffn {Scheme Procedure} char-downcase chr
2310 @deffnx {C Function} scm_char_downcase (chr)
2311 Return the lowercase character version of @var{chr}.
2314 @rnindex char-titlecase
2315 @deffn {Scheme Procedure} char-titlecase chr
2316 @deffnx {C Function} scm_char_titlecase (chr)
2317 Return the titlecase character version of @var{chr} if one exists;
2318 otherwise return the uppercase version.
2320 For most characters these will be the same, but the Unicode Standard
2321 includes certain digraph compatibility characters, such as @code{U+01F3}
2322 ``dz'', for which the uppercase and titlecase characters are different
2323 (@code{U+01F1} ``DZ'' and @code{U+01F2} ``Dz'' in this case,
2328 @deftypefn {C Function} scm_t_wchar scm_c_upcase (scm_t_wchar @var{c})
2329 @deftypefnx {C Function} scm_t_wchar scm_c_downcase (scm_t_wchar @var{c})
2330 @deftypefnx {C Function} scm_t_wchar scm_c_titlecase (scm_t_wchar @var{c})
2332 These C functions take an integer representation of a Unicode
2333 codepoint and return the codepoint corresponding to its uppercase,
2334 lowercase, and titlecase forms respectively. The type
2335 @code{scm_t_wchar} is a signed, 32-bit integer.
2338 Characters also have ``formal names'', which are defined by Unicode.
2339 These names can be accessed in Guile from the @code{(ice-9 unicode)}
2343 (use-modules (ice-9 unicode))
2346 @deffn {Scheme Procedure} char->formal-name chr
2347 Return the formal all-upper-case Unicode name of @var{ch},
2348 as a string, or @code{#f} if the character has no name.
2351 @deffn {Scheme Procedure} formal-name->char name
2352 Return the character whose formal all-upper-case Unicode name is
2353 @var{name}, or @code{#f} if no such character is known.
2356 @node Character Sets
2357 @subsection Character Sets
2359 The features described in this section correspond directly to SRFI-14.
2361 The data type @dfn{charset} implements sets of characters
2362 (@pxref{Characters}). Because the internal representation of
2363 character sets is not visible to the user, a lot of procedures for
2364 handling them are provided.
2366 Character sets can be created, extended, tested for the membership of a
2367 characters and be compared to other character sets.
2370 * Character Set Predicates/Comparison::
2371 * Iterating Over Character Sets:: Enumerate charset elements.
2372 * Creating Character Sets:: Making new charsets.
2373 * Querying Character Sets:: Test charsets for membership etc.
2374 * Character-Set Algebra:: Calculating new charsets.
2375 * Standard Character Sets:: Variables containing predefined charsets.
2378 @node Character Set Predicates/Comparison
2379 @subsubsection Character Set Predicates/Comparison
2381 Use these procedures for testing whether an object is a character set,
2382 or whether several character sets are equal or subsets of each other.
2383 @code{char-set-hash} can be used for calculating a hash value, maybe for
2384 usage in fast lookup procedures.
2386 @deffn {Scheme Procedure} char-set? obj
2387 @deffnx {C Function} scm_char_set_p (obj)
2388 Return @code{#t} if @var{obj} is a character set, @code{#f}
2392 @deffn {Scheme Procedure} char-set= char_set @dots{}
2393 @deffnx {C Function} scm_char_set_eq (char_sets)
2394 Return @code{#t} if all given character sets are equal.
2397 @deffn {Scheme Procedure} char-set<= char_set @dots{}
2398 @deffnx {C Function} scm_char_set_leq (char_sets)
2399 Return @code{#t} if every character set @var{char_set}i is a subset
2400 of character set @var{char_set}i+1.
2403 @deffn {Scheme Procedure} char-set-hash cs [bound]
2404 @deffnx {C Function} scm_char_set_hash (cs, bound)
2405 Compute a hash value for the character set @var{cs}. If
2406 @var{bound} is given and non-zero, it restricts the
2407 returned value to the range 0 @dots{} @var{bound} - 1.
2410 @c ===================================================================
2412 @node Iterating Over Character Sets
2413 @subsubsection Iterating Over Character Sets
2415 Character set cursors are a means for iterating over the members of a
2416 character sets. After creating a character set cursor with
2417 @code{char-set-cursor}, a cursor can be dereferenced with
2418 @code{char-set-ref}, advanced to the next member with
2419 @code{char-set-cursor-next}. Whether a cursor has passed past the last
2420 element of the set can be checked with @code{end-of-char-set?}.
2422 Additionally, mapping and (un-)folding procedures for character sets are
2425 @deffn {Scheme Procedure} char-set-cursor cs
2426 @deffnx {C Function} scm_char_set_cursor (cs)
2427 Return a cursor into the character set @var{cs}.
2430 @deffn {Scheme Procedure} char-set-ref cs cursor
2431 @deffnx {C Function} scm_char_set_ref (cs, cursor)
2432 Return the character at the current cursor position
2433 @var{cursor} in the character set @var{cs}. It is an error to
2434 pass a cursor for which @code{end-of-char-set?} returns true.
2437 @deffn {Scheme Procedure} char-set-cursor-next cs cursor
2438 @deffnx {C Function} scm_char_set_cursor_next (cs, cursor)
2439 Advance the character set cursor @var{cursor} to the next
2440 character in the character set @var{cs}. It is an error if the
2441 cursor given satisfies @code{end-of-char-set?}.
2444 @deffn {Scheme Procedure} end-of-char-set? cursor
2445 @deffnx {C Function} scm_end_of_char_set_p (cursor)
2446 Return @code{#t} if @var{cursor} has reached the end of a
2447 character set, @code{#f} otherwise.
2450 @deffn {Scheme Procedure} char-set-fold kons knil cs
2451 @deffnx {C Function} scm_char_set_fold (kons, knil, cs)
2452 Fold the procedure @var{kons} over the character set @var{cs},
2453 initializing it with @var{knil}.
2456 @deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
2457 @deffnx {C Function} scm_char_set_unfold (p, f, g, seed, base_cs)
2458 This is a fundamental constructor for character sets.
2460 @item @var{g} is used to generate a series of ``seed'' values
2461 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2462 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2463 @item @var{p} tells us when to stop -- when it returns true
2464 when applied to one of the seed values.
2465 @item @var{f} maps each seed value to a character. These
2466 characters are added to the base character set @var{base_cs} to
2467 form the result; @var{base_cs} defaults to the empty set.
2471 @deffn {Scheme Procedure} char-set-unfold! p f g seed base_cs
2472 @deffnx {C Function} scm_char_set_unfold_x (p, f, g, seed, base_cs)
2473 This is a fundamental constructor for character sets.
2475 @item @var{g} is used to generate a series of ``seed'' values
2476 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2477 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2478 @item @var{p} tells us when to stop -- when it returns true
2479 when applied to one of the seed values.
2480 @item @var{f} maps each seed value to a character. These
2481 characters are added to the base character set @var{base_cs} to
2482 form the result; @var{base_cs} defaults to the empty set.
2486 @deffn {Scheme Procedure} char-set-for-each proc cs
2487 @deffnx {C Function} scm_char_set_for_each (proc, cs)
2488 Apply @var{proc} to every character in the character set
2489 @var{cs}. The return value is not specified.
2492 @deffn {Scheme Procedure} char-set-map proc cs
2493 @deffnx {C Function} scm_char_set_map (proc, cs)
2494 Map the procedure @var{proc} over every character in @var{cs}.
2495 @var{proc} must be a character -> character procedure.
2498 @c ===================================================================
2500 @node Creating Character Sets
2501 @subsubsection Creating Character Sets
2503 New character sets are produced with these procedures.
2505 @deffn {Scheme Procedure} char-set-copy cs
2506 @deffnx {C Function} scm_char_set_copy (cs)
2507 Return a newly allocated character set containing all
2508 characters in @var{cs}.
2511 @deffn {Scheme Procedure} char-set chr @dots{}
2512 @deffnx {C Function} scm_char_set (chrs)
2513 Return a character set containing all given characters.
2516 @deffn {Scheme Procedure} list->char-set list [base_cs]
2517 @deffnx {C Function} scm_list_to_char_set (list, base_cs)
2518 Convert the character list @var{list} to a character set. If
2519 the character set @var{base_cs} is given, the character in this
2520 set are also included in the result.
2523 @deffn {Scheme Procedure} list->char-set! list base_cs
2524 @deffnx {C Function} scm_list_to_char_set_x (list, base_cs)
2525 Convert the character list @var{list} to a character set. The
2526 characters are added to @var{base_cs} and @var{base_cs} is
2530 @deffn {Scheme Procedure} string->char-set str [base_cs]
2531 @deffnx {C Function} scm_string_to_char_set (str, base_cs)
2532 Convert the string @var{str} to a character set. If the
2533 character set @var{base_cs} is given, the characters in this
2534 set are also included in the result.
2537 @deffn {Scheme Procedure} string->char-set! str base_cs
2538 @deffnx {C Function} scm_string_to_char_set_x (str, base_cs)
2539 Convert the string @var{str} to a character set. The
2540 characters from the string are added to @var{base_cs}, and
2541 @var{base_cs} is returned.
2544 @deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
2545 @deffnx {C Function} scm_char_set_filter (pred, cs, base_cs)
2546 Return a character set containing every character from @var{cs}
2547 so that it satisfies @var{pred}. If provided, the characters
2548 from @var{base_cs} are added to the result.
2551 @deffn {Scheme Procedure} char-set-filter! pred cs base_cs
2552 @deffnx {C Function} scm_char_set_filter_x (pred, cs, base_cs)
2553 Return a character set containing every character from @var{cs}
2554 so that it satisfies @var{pred}. The characters are added to
2555 @var{base_cs} and @var{base_cs} is returned.
2558 @deffn {Scheme Procedure} ucs-range->char-set lower upper [error [base_cs]]
2559 @deffnx {C Function} scm_ucs_range_to_char_set (lower, upper, error, base_cs)
2560 Return a character set containing all characters whose
2561 character codes lie in the half-open range
2562 [@var{lower},@var{upper}).
2564 If @var{error} is a true value, an error is signalled if the
2565 specified range contains characters which are not contained in
2566 the implemented character range. If @var{error} is @code{#f},
2567 these characters are silently left out of the resulting
2570 The characters in @var{base_cs} are added to the result, if
2574 @deffn {Scheme Procedure} ucs-range->char-set! lower upper error base_cs
2575 @deffnx {C Function} scm_ucs_range_to_char_set_x (lower, upper, error, base_cs)
2576 Return a character set containing all characters whose
2577 character codes lie in the half-open range
2578 [@var{lower},@var{upper}).
2580 If @var{error} is a true value, an error is signalled if the
2581 specified range contains characters which are not contained in
2582 the implemented character range. If @var{error} is @code{#f},
2583 these characters are silently left out of the resulting
2586 The characters are added to @var{base_cs} and @var{base_cs} is
2590 @deffn {Scheme Procedure} ->char-set x
2591 @deffnx {C Function} scm_to_char_set (x)
2592 Coerces x into a char-set. @var{x} may be a string, character or
2593 char-set. A string is converted to the set of its constituent
2594 characters; a character is converted to a singleton set; a char-set is
2598 @c ===================================================================
2600 @node Querying Character Sets
2601 @subsubsection Querying Character Sets
2603 Access the elements and other information of a character set with these
2606 @deffn {Scheme Procedure} %char-set-dump cs
2607 Returns an association list containing debugging information
2608 for @var{cs}. The association list has the following entries.
2613 The number of groups of contiguous code points the char-set
2616 A list of lists where each sublist is a range of code points
2617 and their associated characters
2619 The return value of this function cannot be relied upon to be
2620 consistent between versions of Guile and should not be used in code.
2623 @deffn {Scheme Procedure} char-set-size cs
2624 @deffnx {C Function} scm_char_set_size (cs)
2625 Return the number of elements in character set @var{cs}.
2628 @deffn {Scheme Procedure} char-set-count pred cs
2629 @deffnx {C Function} scm_char_set_count (pred, cs)
2630 Return the number of the elements int the character set
2631 @var{cs} which satisfy the predicate @var{pred}.
2634 @deffn {Scheme Procedure} char-set->list cs
2635 @deffnx {C Function} scm_char_set_to_list (cs)
2636 Return a list containing the elements of the character set
2640 @deffn {Scheme Procedure} char-set->string cs
2641 @deffnx {C Function} scm_char_set_to_string (cs)
2642 Return a string containing the elements of the character set
2643 @var{cs}. The order in which the characters are placed in the
2644 string is not defined.
2647 @deffn {Scheme Procedure} char-set-contains? cs ch
2648 @deffnx {C Function} scm_char_set_contains_p (cs, ch)
2649 Return @code{#t} if the character @var{ch} is contained in the
2650 character set @var{cs}, or @code{#f} otherwise.
2653 @deffn {Scheme Procedure} char-set-every pred cs
2654 @deffnx {C Function} scm_char_set_every (pred, cs)
2655 Return a true value if every character in the character set
2656 @var{cs} satisfies the predicate @var{pred}.
2659 @deffn {Scheme Procedure} char-set-any pred cs
2660 @deffnx {C Function} scm_char_set_any (pred, cs)
2661 Return a true value if any character in the character set
2662 @var{cs} satisfies the predicate @var{pred}.
2665 @c ===================================================================
2667 @node Character-Set Algebra
2668 @subsubsection Character-Set Algebra
2670 Character sets can be manipulated with the common set algebra operation,
2671 such as union, complement, intersection etc. All of these procedures
2672 provide side-effecting variants, which modify their character set
2675 @deffn {Scheme Procedure} char-set-adjoin cs chr @dots{}
2676 @deffnx {C Function} scm_char_set_adjoin (cs, chrs)
2677 Add all character arguments to the first argument, which must
2681 @deffn {Scheme Procedure} char-set-delete cs chr @dots{}
2682 @deffnx {C Function} scm_char_set_delete (cs, chrs)
2683 Delete all character arguments from the first argument, which
2684 must be a character set.
2687 @deffn {Scheme Procedure} char-set-adjoin! cs chr @dots{}
2688 @deffnx {C Function} scm_char_set_adjoin_x (cs, chrs)
2689 Add all character arguments to the first argument, which must
2693 @deffn {Scheme Procedure} char-set-delete! cs chr @dots{}
2694 @deffnx {C Function} scm_char_set_delete_x (cs, chrs)
2695 Delete all character arguments from the first argument, which
2696 must be a character set.
2699 @deffn {Scheme Procedure} char-set-complement cs
2700 @deffnx {C Function} scm_char_set_complement (cs)
2701 Return the complement of the character set @var{cs}.
2704 Note that the complement of a character set is likely to contain many
2705 reserved code points (code points that are not associated with
2706 characters). It may be helpful to modify the output of
2707 @code{char-set-complement} by computing its intersection with the set
2708 of designated code points, @code{char-set:designated}.
2710 @deffn {Scheme Procedure} char-set-union cs @dots{}
2711 @deffnx {C Function} scm_char_set_union (char_sets)
2712 Return the union of all argument character sets.
2715 @deffn {Scheme Procedure} char-set-intersection cs @dots{}
2716 @deffnx {C Function} scm_char_set_intersection (char_sets)
2717 Return the intersection of all argument character sets.
2720 @deffn {Scheme Procedure} char-set-difference cs1 cs @dots{}
2721 @deffnx {C Function} scm_char_set_difference (cs1, char_sets)
2722 Return the difference of all argument character sets.
2725 @deffn {Scheme Procedure} char-set-xor cs @dots{}
2726 @deffnx {C Function} scm_char_set_xor (char_sets)
2727 Return the exclusive-or of all argument character sets.
2730 @deffn {Scheme Procedure} char-set-diff+intersection cs1 cs @dots{}
2731 @deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, char_sets)
2732 Return the difference and the intersection of all argument
2736 @deffn {Scheme Procedure} char-set-complement! cs
2737 @deffnx {C Function} scm_char_set_complement_x (cs)
2738 Return the complement of the character set @var{cs}.
2741 @deffn {Scheme Procedure} char-set-union! cs1 cs @dots{}
2742 @deffnx {C Function} scm_char_set_union_x (cs1, char_sets)
2743 Return the union of all argument character sets.
2746 @deffn {Scheme Procedure} char-set-intersection! cs1 cs @dots{}
2747 @deffnx {C Function} scm_char_set_intersection_x (cs1, char_sets)
2748 Return the intersection of all argument character sets.
2751 @deffn {Scheme Procedure} char-set-difference! cs1 cs @dots{}
2752 @deffnx {C Function} scm_char_set_difference_x (cs1, char_sets)
2753 Return the difference of all argument character sets.
2756 @deffn {Scheme Procedure} char-set-xor! cs1 cs @dots{}
2757 @deffnx {C Function} scm_char_set_xor_x (cs1, char_sets)
2758 Return the exclusive-or of all argument character sets.
2761 @deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 cs @dots{}
2762 @deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, char_sets)
2763 Return the difference and the intersection of all argument
2767 @c ===================================================================
2769 @node Standard Character Sets
2770 @subsubsection Standard Character Sets
2772 In order to make the use of the character set data type and procedures
2773 useful, several predefined character set variables exist.
2779 These character sets are locale independent and are not recomputed
2780 upon a @code{setlocale} call. They contain characters from the whole
2781 range of Unicode code points. For instance, @code{char-set:letter}
2782 contains about 100,000 characters.
2784 @defvr {Scheme Variable} char-set:lower-case
2785 @defvrx {C Variable} scm_char_set_lower_case
2786 All lower-case characters.
2789 @defvr {Scheme Variable} char-set:upper-case
2790 @defvrx {C Variable} scm_char_set_upper_case
2791 All upper-case characters.
2794 @defvr {Scheme Variable} char-set:title-case
2795 @defvrx {C Variable} scm_char_set_title_case
2796 All single characters that function as if they were an upper-case
2797 letter followed by a lower-case letter.
2800 @defvr {Scheme Variable} char-set:letter
2801 @defvrx {C Variable} scm_char_set_letter
2802 All letters. This includes @code{char-set:lower-case},
2803 @code{char-set:upper-case}, @code{char-set:title-case}, and many
2804 letters that have no case at all. For example, Chinese and Japanese
2805 characters typically have no concept of case.
2808 @defvr {Scheme Variable} char-set:digit
2809 @defvrx {C Variable} scm_char_set_digit
2813 @defvr {Scheme Variable} char-set:letter+digit
2814 @defvrx {C Variable} scm_char_set_letter_and_digit
2815 The union of @code{char-set:letter} and @code{char-set:digit}.
2818 @defvr {Scheme Variable} char-set:graphic
2819 @defvrx {C Variable} scm_char_set_graphic
2820 All characters which would put ink on the paper.
2823 @defvr {Scheme Variable} char-set:printing
2824 @defvrx {C Variable} scm_char_set_printing
2825 The union of @code{char-set:graphic} and @code{char-set:whitespace}.
2828 @defvr {Scheme Variable} char-set:whitespace
2829 @defvrx {C Variable} scm_char_set_whitespace
2830 All whitespace characters.
2833 @defvr {Scheme Variable} char-set:blank
2834 @defvrx {C Variable} scm_char_set_blank
2835 All horizontal whitespace characters, which notably includes
2836 @code{#\space} and @code{#\tab}.
2839 @defvr {Scheme Variable} char-set:iso-control
2840 @defvrx {C Variable} scm_char_set_iso_control
2841 The ISO control characters are the C0 control characters (U+0000 to
2842 U+001F), delete (U+007F), and the C1 control characters (U+0080 to
2846 @defvr {Scheme Variable} char-set:punctuation
2847 @defvrx {C Variable} scm_char_set_punctuation
2848 All punctuation characters, such as the characters
2849 @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
2852 @defvr {Scheme Variable} char-set:symbol
2853 @defvrx {C Variable} scm_char_set_symbol
2854 All symbol characters, such as the characters @code{$+<=>^`|~}.
2857 @defvr {Scheme Variable} char-set:hex-digit
2858 @defvrx {C Variable} scm_char_set_hex_digit
2859 The hexadecimal digits @code{0123456789abcdefABCDEF}.
2862 @defvr {Scheme Variable} char-set:ascii
2863 @defvrx {C Variable} scm_char_set_ascii
2864 All ASCII characters.
2867 @defvr {Scheme Variable} char-set:empty
2868 @defvrx {C Variable} scm_char_set_empty
2869 The empty character set.
2872 @defvr {Scheme Variable} char-set:designated
2873 @defvrx {C Variable} scm_char_set_designated
2874 This character set contains all designated code points. This includes
2875 all the code points to which Unicode has assigned a character or other
2879 @defvr {Scheme Variable} char-set:full
2880 @defvrx {C Variable} scm_char_set_full
2881 This character set contains all possible code points. This includes
2882 both designated and reserved code points.
2889 Strings are fixed-length sequences of characters. They can be created
2890 by calling constructor procedures, but they can also literally get
2891 entered at the @acronym{REPL} or in Scheme source files.
2893 @c Guile provides a rich set of string processing procedures, because text
2894 @c handling is very important when Guile is used as a scripting language.
2896 Strings always carry the information about how many characters they are
2897 composed of with them, so there is no special end-of-string character,
2898 like in C. That means that Scheme strings can contain any character,
2899 even the @samp{#\nul} character @samp{\0}.
2901 To use strings efficiently, you need to know a bit about how Guile
2902 implements them. In Guile, a string consists of two parts, a head and
2903 the actual memory where the characters are stored. When a string (or
2904 a substring of it) is copied, only a new head gets created, the memory
2905 is usually not copied. The two heads start out pointing to the same
2908 When one of these two strings is modified, as with @code{string-set!},
2909 their common memory does get copied so that each string has its own
2910 memory and modifying one does not accidentally modify the other as well.
2911 Thus, Guile's strings are `copy on write'; the actual copying of their
2912 memory is delayed until one string is written to.
2914 This implementation makes functions like @code{substring} very
2915 efficient in the common case that no modifications are done to the
2918 If you do know that your strings are getting modified right away, you
2919 can use @code{substring/copy} instead of @code{substring}. This
2920 function performs the copy immediately at the time of creation. This
2921 is more efficient, especially in a multi-threaded program. Also,
2922 @code{substring/copy} can avoid the problem that a short substring
2923 holds on to the memory of a very large original string that could
2924 otherwise be recycled.
2926 If you want to avoid the copy altogether, so that modifications of one
2927 string show up in the other, you can use @code{substring/shared}. The
2928 strings created by this procedure are called @dfn{mutation sharing
2929 substrings} since the substring and the original string share
2930 modifications to each other.
2932 If you want to prevent modifications, use @code{substring/read-only}.
2934 Guile provides all procedures of SRFI-13 and a few more.
2937 * String Syntax:: Read syntax for strings.
2938 * String Predicates:: Testing strings for certain properties.
2939 * String Constructors:: Creating new string objects.
2940 * List/String Conversion:: Converting from/to lists of characters.
2941 * String Selection:: Select portions from strings.
2942 * String Modification:: Modify parts or whole strings.
2943 * String Comparison:: Lexicographic ordering predicates.
2944 * String Searching:: Searching in strings.
2945 * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
2946 * Reversing and Appending Strings:: Appending strings to form a new string.
2947 * Mapping Folding and Unfolding:: Iterating over strings.
2948 * Miscellaneous String Operations:: Replicating, insertion, parsing, ...
2949 * Representing Strings as Bytes:: Encoding and decoding strings.
2950 * Conversion to/from C::
2951 * String Internals:: The storage strategy for strings.
2955 @subsubsection String Read Syntax
2957 @c In the following @code is used to get a good font in TeX etc, but
2958 @c is omitted for Info format, so as not to risk any confusion over
2959 @c whether surrounding ` ' quotes are part of the escape or are
2960 @c special in a string (they're not).
2962 The read syntax for strings is an arbitrarily long sequence of
2963 characters enclosed in double quotes (@nicode{"}).
2965 Backslash is an escape character and can be used to insert the following
2966 special characters. @nicode{\"} and @nicode{\\} are R5RS standard,
2967 @nicode{\|} is R7RS standard, the next seven are R6RS standard ---
2968 notice they follow C syntax --- and the remaining four are Guile
2973 Backslash character.
2976 Double quote character (an unescaped @nicode{"} is otherwise the end
2980 Vertical bar character.
2983 Bell character (ASCII 7).
2986 Formfeed character (ASCII 12).
2989 Newline character (ASCII 10).
2992 Carriage return character (ASCII 13).
2995 Tab character (ASCII 9).
2998 Vertical tab character (ASCII 11).
3001 Backspace character (ASCII 8).
3004 NUL character (ASCII 0).
3007 Open parenthesis. This is intended for use at the beginning of lines in
3008 multiline strings to avoid confusing Emacs lisp modes.
3010 @item @nicode{\} followed by newline (ASCII 10)
3011 Nothing. This way if @nicode{\} is the last character in a line, the
3012 string will continue with the first character from the next line,
3013 without a line break.
3015 If the @code{hungry-eol-escapes} reader option is enabled, which is not
3016 the case by default, leading whitespace on the next line is discarded.
3022 (read-enable 'hungry-eol-escapes)
3028 Character code given by two hexadecimal digits. For example
3029 @nicode{\x7f} for an ASCII DEL (127).
3031 @item @nicode{\uHHHH}
3032 Character code given by four hexadecimal digits. For example
3033 @nicode{\u0100} for a capital A with macron (U+0100).
3035 @item @nicode{\UHHHHHH}
3036 Character code given by six hexadecimal digits. For example
3041 The following are examples of string literals:
3050 The three escape sequences @code{\xHH}, @code{\uHHHH} and @code{\UHHHHHH} were
3051 chosen to not break compatibility with code written for previous versions of
3052 Guile. The R6RS specification suggests a different, incompatible syntax for hex
3053 escapes: @code{\xHHHH;} -- a character code followed by one to eight hexadecimal
3054 digits terminated with a semicolon. If this escape format is desired instead,
3055 it can be enabled with the reader option @code{r6rs-hex-escapes}.
3058 (read-enable 'r6rs-hex-escapes)
3061 For more on reader options, @xref{Scheme Read}.
3063 @node String Predicates
3064 @subsubsection String Predicates
3066 The following procedures can be used to check whether a given string
3067 fulfills some specified property.
3070 @deffn {Scheme Procedure} string? obj
3071 @deffnx {C Function} scm_string_p (obj)
3072 Return @code{#t} if @var{obj} is a string, else @code{#f}.
3075 @deftypefn {C Function} int scm_is_string (SCM obj)
3076 Returns @code{1} if @var{obj} is a string, @code{0} otherwise.
3079 @deffn {Scheme Procedure} string-null? str
3080 @deffnx {C Function} scm_string_null_p (str)
3081 Return @code{#t} if @var{str}'s length is zero, and
3082 @code{#f} otherwise.
3084 (string-null? "") @result{} #t
3086 (string-null? y) @result{} #f
3090 @deffn {Scheme Procedure} string-any char_pred s [start [end]]
3091 @deffnx {C Function} scm_string_any (char_pred, s, start, end)
3092 Check if @var{char_pred} is true for any character in string @var{s}.
3094 @var{char_pred} can be a character to check for any equal to that, or
3095 a character set (@pxref{Character Sets}) to check for any in that set,
3096 or a predicate procedure to call.
3098 For a procedure, calls @code{(@var{char_pred} c)} are made
3099 successively on the characters from @var{start} to @var{end}. If
3100 @var{char_pred} returns true (ie.@: non-@code{#f}), @code{string-any}
3101 stops and that return value is the return from @code{string-any}. The
3102 call on the last character (ie.@: at @math{@var{end}-1}), if that
3103 point is reached, is a tail call.
3105 If there are no characters in @var{s} (ie.@: @var{start} equals
3106 @var{end}) then the return is @code{#f}.
3109 @deffn {Scheme Procedure} string-every char_pred s [start [end]]
3110 @deffnx {C Function} scm_string_every (char_pred, s, start, end)
3111 Check if @var{char_pred} is true for every character in string
3114 @var{char_pred} can be a character to check for every character equal
3115 to that, or a character set (@pxref{Character Sets}) to check for
3116 every character being in that set, or a predicate procedure to call.
3118 For a procedure, calls @code{(@var{char_pred} c)} are made
3119 successively on the characters from @var{start} to @var{end}. If
3120 @var{char_pred} returns @code{#f}, @code{string-every} stops and
3121 returns @code{#f}. The call on the last character (ie.@: at
3122 @math{@var{end}-1}), if that point is reached, is a tail call and the
3123 return from that call is the return from @code{string-every}.
3125 If there are no characters in @var{s} (ie.@: @var{start} equals
3126 @var{end}) then the return is @code{#t}.
3129 @node String Constructors
3130 @subsubsection String Constructors
3132 The string constructor procedures create new string objects, possibly
3133 initializing them with some specified character data. See also
3134 @xref{String Selection}, for ways to create strings from existing
3137 @c FIXME::martin: list->string belongs into `List/String Conversion'
3139 @deffn {Scheme Procedure} string char@dots{}
3141 Return a newly allocated string made from the given character
3145 (string #\x #\y #\z) @result{} "xyz"
3146 (string) @result{} ""
3150 @deffn {Scheme Procedure} list->string lst
3151 @deffnx {C Function} scm_string (lst)
3152 @rnindex list->string
3153 Return a newly allocated string made from a list of characters.
3156 (list->string '(#\a #\b #\c)) @result{} "abc"
3160 @deffn {Scheme Procedure} reverse-list->string lst
3161 @deffnx {C Function} scm_reverse_list_to_string (lst)
3162 Return a newly allocated string made from a list of characters, in
3166 (reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
3170 @rnindex make-string
3171 @deffn {Scheme Procedure} make-string k [chr]
3172 @deffnx {C Function} scm_make_string (k, chr)
3173 Return a newly allocated string of
3174 length @var{k}. If @var{chr} is given, then all elements of
3175 the string are initialized to @var{chr}, otherwise the contents
3176 of the string are unspecified.
3179 @deftypefn {C Function} SCM scm_c_make_string (size_t len, SCM chr)
3180 Like @code{scm_make_string}, but expects the length as a
3184 @deffn {Scheme Procedure} string-tabulate proc len
3185 @deffnx {C Function} scm_string_tabulate (proc, len)
3186 @var{proc} is an integer->char procedure. Construct a string
3187 of size @var{len} by applying @var{proc} to each index to
3188 produce the corresponding string element. The order in which
3189 @var{proc} is applied to the indices is not specified.
3192 @deffn {Scheme Procedure} string-join ls [delimiter [grammar]]
3193 @deffnx {C Function} scm_string_join (ls, delimiter, grammar)
3194 Append the string in the string list @var{ls}, using the string
3195 @var{delimiter} as a delimiter between the elements of @var{ls}.
3196 @var{grammar} is a symbol which specifies how the delimiter is
3197 placed between the strings, and defaults to the symbol
3202 Insert the separator between list elements. An empty string
3203 will produce an empty list.
3205 Like @code{infix}, but will raise an error if given the empty
3208 Insert the separator after every list element.
3210 Insert the separator before each list element.
3214 @node List/String Conversion
3215 @subsubsection List/String conversion
3217 When processing strings, it is often convenient to first convert them
3218 into a list representation by using the procedure @code{string->list},
3219 work with the resulting list, and then convert it back into a string.
3220 These procedures are useful for similar tasks.
3222 @rnindex string->list
3223 @deffn {Scheme Procedure} string->list str [start [end]]
3224 @deffnx {C Function} scm_substring_to_list (str, start, end)
3225 @deffnx {C Function} scm_string_to_list (str)
3226 Convert the string @var{str} into a list of characters.
3229 @deffn {Scheme Procedure} string-split str char_pred
3230 @deffnx {C Function} scm_string_split (str, char_pred)
3231 Split the string @var{str} into a list of substrings delimited
3232 by appearances of characters that
3236 equal @var{char_pred}, if it is a character,
3239 satisfy the predicate @var{char_pred}, if it is a procedure,
3242 are in the set @var{char_pred}, if it is a character set.
3245 Note that an empty substring between separator characters will result in
3246 an empty string in the result list.
3249 (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
3251 ("root" "x" "0" "0" "root" "/root" "/bin/bash")
3253 (string-split "::" #\:)
3257 (string-split "" #\:)
3264 @node String Selection
3265 @subsubsection String Selection
3267 Portions of strings can be extracted by these procedures.
3268 @code{string-ref} delivers individual characters whereas
3269 @code{substring} can be used to extract substrings from longer strings.
3271 @rnindex string-length
3272 @deffn {Scheme Procedure} string-length string
3273 @deffnx {C Function} scm_string_length (string)
3274 Return the number of characters in @var{string}.
3277 @deftypefn {C Function} size_t scm_c_string_length (SCM str)
3278 Return the number of characters in @var{str} as a @code{size_t}.
3282 @deffn {Scheme Procedure} string-ref str k
3283 @deffnx {C Function} scm_string_ref (str, k)
3284 Return character @var{k} of @var{str} using zero-origin
3285 indexing. @var{k} must be a valid index of @var{str}.
3288 @deftypefn {C Function} SCM scm_c_string_ref (SCM str, size_t k)
3289 Return character @var{k} of @var{str} using zero-origin
3290 indexing. @var{k} must be a valid index of @var{str}.
3293 @rnindex string-copy
3294 @deffn {Scheme Procedure} string-copy str [start [end]]
3295 @deffnx {C Function} scm_substring_copy (str, start, end)
3296 @deffnx {C Function} scm_string_copy (str)
3297 Return a copy of the given string @var{str}.
3299 The returned string shares storage with @var{str} initially, but it is
3300 copied as soon as one of the two strings is modified.
3304 @deffn {Scheme Procedure} substring str start [end]
3305 @deffnx {C Function} scm_substring (str, start, end)
3306 Return a new string formed from the characters
3307 of @var{str} beginning with index @var{start} (inclusive) and
3308 ending with index @var{end} (exclusive).
3309 @var{str} must be a string, @var{start} and @var{end} must be
3310 exact integers satisfying:
3312 0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
3314 The returned string shares storage with @var{str} initially, but it is
3315 copied as soon as one of the two strings is modified.
3318 @deffn {Scheme Procedure} substring/shared str start [end]
3319 @deffnx {C Function} scm_substring_shared (str, start, end)
3320 Like @code{substring}, but the strings continue to share their storage
3321 even if they are modified. Thus, modifications to @var{str} show up
3322 in the new string, and vice versa.
3325 @deffn {Scheme Procedure} substring/copy str start [end]
3326 @deffnx {C Function} scm_substring_copy (str, start, end)
3327 Like @code{substring}, but the storage for the new string is copied
3331 @deffn {Scheme Procedure} substring/read-only str start [end]
3332 @deffnx {C Function} scm_substring_read_only (str, start, end)
3333 Like @code{substring}, but the resulting string can not be modified.
3336 @deftypefn {C Function} SCM scm_c_substring (SCM str, size_t start, size_t end)
3337 @deftypefnx {C Function} SCM scm_c_substring_shared (SCM str, size_t start, size_t end)
3338 @deftypefnx {C Function} SCM scm_c_substring_copy (SCM str, size_t start, size_t end)
3339 @deftypefnx {C Function} SCM scm_c_substring_read_only (SCM str, size_t start, size_t end)
3340 Like @code{scm_substring}, etc. but the bounds are given as a @code{size_t}.
3343 @deffn {Scheme Procedure} string-take s n
3344 @deffnx {C Function} scm_string_take (s, n)
3345 Return the @var{n} first characters of @var{s}.
3348 @deffn {Scheme Procedure} string-drop s n
3349 @deffnx {C Function} scm_string_drop (s, n)
3350 Return all but the first @var{n} characters of @var{s}.
3353 @deffn {Scheme Procedure} string-take-right s n
3354 @deffnx {C Function} scm_string_take_right (s, n)
3355 Return the @var{n} last characters of @var{s}.
3358 @deffn {Scheme Procedure} string-drop-right s n
3359 @deffnx {C Function} scm_string_drop_right (s, n)
3360 Return all but the last @var{n} characters of @var{s}.
3363 @deffn {Scheme Procedure} string-pad s len [chr [start [end]]]
3364 @deffnx {Scheme Procedure} string-pad-right s len [chr [start [end]]]
3365 @deffnx {C Function} scm_string_pad (s, len, chr, start, end)
3366 @deffnx {C Function} scm_string_pad_right (s, len, chr, start, end)
3367 Take characters @var{start} to @var{end} from the string @var{s} and
3368 either pad with @var{chr} or truncate them to give @var{len}
3371 @code{string-pad} pads or truncates on the left, so for example
3374 (string-pad "x" 3) @result{} " x"
3375 (string-pad "abcde" 3) @result{} "cde"
3378 @code{string-pad-right} pads or truncates on the right, so for example
3381 (string-pad-right "x" 3) @result{} "x "
3382 (string-pad-right "abcde" 3) @result{} "abc"
3386 @deffn {Scheme Procedure} string-trim s [char_pred [start [end]]]
3387 @deffnx {Scheme Procedure} string-trim-right s [char_pred [start [end]]]
3388 @deffnx {Scheme Procedure} string-trim-both s [char_pred [start [end]]]
3389 @deffnx {C Function} scm_string_trim (s, char_pred, start, end)
3390 @deffnx {C Function} scm_string_trim_right (s, char_pred, start, end)
3391 @deffnx {C Function} scm_string_trim_both (s, char_pred, start, end)
3392 Trim occurrences of @var{char_pred} from the ends of @var{s}.
3394 @code{string-trim} trims @var{char_pred} characters from the left
3395 (start) of the string, @code{string-trim-right} trims them from the
3396 right (end) of the string, @code{string-trim-both} trims from both
3399 @var{char_pred} can be a character, a character set, or a predicate
3400 procedure to call on each character. If @var{char_pred} is not given
3401 the default is whitespace as per @code{char-set:whitespace}
3402 (@pxref{Standard Character Sets}).
3405 (string-trim " x ") @result{} "x "
3406 (string-trim-right "banana" #\a) @result{} "banan"
3407 (string-trim-both ".,xy:;" char-set:punctuation)
3409 (string-trim-both "xyzzy" (lambda (c)
3416 @node String Modification
3417 @subsubsection String Modification
3419 These procedures are for modifying strings in-place. This means that the
3420 result of the operation is not a new string; instead, the original string's
3421 memory representation is modified.
3423 @rnindex string-set!
3424 @deffn {Scheme Procedure} string-set! str k chr
3425 @deffnx {C Function} scm_string_set_x (str, k, chr)
3426 Store @var{chr} in element @var{k} of @var{str} and return
3427 an unspecified value. @var{k} must be a valid index of
3431 @deftypefn {C Function} void scm_c_string_set_x (SCM str, size_t k, SCM chr)
3432 Like @code{scm_string_set_x}, but the index is given as a @code{size_t}.
3435 @rnindex string-fill!
3436 @deffn {Scheme Procedure} string-fill! str chr [start [end]]
3437 @deffnx {C Function} scm_substring_fill_x (str, chr, start, end)
3438 @deffnx {C Function} scm_string_fill_x (str, chr)
3439 Stores @var{chr} in every element of the given @var{str} and
3440 returns an unspecified value.
3443 @deffn {Scheme Procedure} substring-fill! str start end fill
3444 @deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
3445 Change every character in @var{str} between @var{start} and
3446 @var{end} to @var{fill}.
3449 (define y (string-copy "abcdefg"))
3450 (substring-fill! y 1 3 #\r)
3456 @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
3457 @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
3458 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
3459 into @var{str2} beginning at position @var{start2}.
3460 @var{str1} and @var{str2} can be the same string.
3463 @deffn {Scheme Procedure} string-copy! target tstart s [start [end]]
3464 @deffnx {C Function} scm_string_copy_x (target, tstart, s, start, end)
3465 Copy the sequence of characters from index range [@var{start},
3466 @var{end}) in string @var{s} to string @var{target}, beginning
3467 at index @var{tstart}. The characters are copied left-to-right
3468 or right-to-left as needed -- the copy is guaranteed to work,
3469 even if @var{target} and @var{s} are the same string. It is an
3470 error if the copy operation runs off the end of the target
3475 @node String Comparison
3476 @subsubsection String Comparison
3478 The procedures in this section are similar to the character ordering
3479 predicates (@pxref{Characters}), but are defined on character sequences.
3481 The first set is specified in R5RS and has names that end in @code{?}.
3482 The second set is specified in SRFI-13 and the names have not ending
3485 The predicates ending in @code{-ci} ignore the character case
3486 when comparing strings. For now, case-insensitive comparison is done
3487 using the R5RS rules, where every lower-case character that has a
3488 single character upper-case form is converted to uppercase before
3489 comparison. See @xref{Text Collation, the @code{(ice-9
3490 i18n)} module}, for locale-dependent string comparison.
3493 @deffn {Scheme Procedure} string=? s1 s2 s3 @dots{}
3494 Lexicographic equality predicate; return @code{#t} if all strings are
3495 the same length and contain the same characters in the same positions,
3496 otherwise return @code{#f}.
3498 The procedure @code{string-ci=?} treats upper and lower case
3499 letters as though they were the same character, but
3500 @code{string=?} treats upper and lower case as distinct
3505 @deffn {Scheme Procedure} string<? s1 s2 s3 @dots{}
3506 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3507 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3508 lexicographically less than @var{str_i+1}.
3512 @deffn {Scheme Procedure} string<=? s1 s2 s3 @dots{}
3513 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3514 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3515 lexicographically less than or equal to @var{str_i+1}.
3519 @deffn {Scheme Procedure} string>? s1 s2 s3 @dots{}
3520 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3521 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3522 lexicographically greater than @var{str_i+1}.
3526 @deffn {Scheme Procedure} string>=? s1 s2 s3 @dots{}
3527 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3528 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3529 lexicographically greater than or equal to @var{str_i+1}.
3532 @rnindex string-ci=?
3533 @deffn {Scheme Procedure} string-ci=? s1 s2 s3 @dots{}
3534 Case-insensitive string equality predicate; return @code{#t} if
3535 all strings are the same length and their component
3536 characters match (ignoring case) at each position; otherwise
3540 @rnindex string-ci<?
3541 @deffn {Scheme Procedure} string-ci<? s1 s2 s3 @dots{}
3542 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3543 for every pair of consecutive string arguments @var{str_i} and
3544 @var{str_i+1}, @var{str_i} is lexicographically less than @var{str_i+1}
3549 @deffn {Scheme Procedure} string-ci<=? s1 s2 s3 @dots{}
3550 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3551 for every pair of consecutive string arguments @var{str_i} and
3552 @var{str_i+1}, @var{str_i} is lexicographically less than or equal to
3553 @var{str_i+1} regardless of case.
3556 @rnindex string-ci>?
3557 @deffn {Scheme Procedure} string-ci>? s1 s2 s3 @dots{}
3558 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3559 for every pair of consecutive string arguments @var{str_i} and
3560 @var{str_i+1}, @var{str_i} is lexicographically greater than
3561 @var{str_i+1} regardless of case.
3564 @rnindex string-ci>=?
3565 @deffn {Scheme Procedure} string-ci>=? s1 s2 s3 @dots{}
3566 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3567 for every pair of consecutive string arguments @var{str_i} and
3568 @var{str_i+1}, @var{str_i} is lexicographically greater than or equal to
3569 @var{str_i+1} regardless of case.
3572 @deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3573 @deffnx {C Function} scm_string_compare (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3574 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3575 mismatch index, depending upon whether @var{s1} is less than,
3576 equal to, or greater than @var{s2}. The mismatch index is the
3577 largest index @var{i} such that for every 0 <= @var{j} <
3578 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3579 @var{i} is the first position that does not match.
3582 @deffn {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3583 @deffnx {C Function} scm_string_compare_ci (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3584 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3585 mismatch index, depending upon whether @var{s1} is less than,
3586 equal to, or greater than @var{s2}. The mismatch index is the
3587 largest index @var{i} such that for every 0 <= @var{j} <
3588 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3589 @var{i} is the first position where the lowercased letters
3594 @deffn {Scheme Procedure} string= s1 s2 [start1 [end1 [start2 [end2]]]]
3595 @deffnx {C Function} scm_string_eq (s1, s2, start1, end1, start2, end2)
3596 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3600 @deffn {Scheme Procedure} string<> s1 s2 [start1 [end1 [start2 [end2]]]]
3601 @deffnx {C Function} scm_string_neq (s1, s2, start1, end1, start2, end2)
3602 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3606 @deffn {Scheme Procedure} string< s1 s2 [start1 [end1 [start2 [end2]]]]
3607 @deffnx {C Function} scm_string_lt (s1, s2, start1, end1, start2, end2)
3608 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3609 true value otherwise.
3612 @deffn {Scheme Procedure} string> s1 s2 [start1 [end1 [start2 [end2]]]]
3613 @deffnx {C Function} scm_string_gt (s1, s2, start1, end1, start2, end2)
3614 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3615 true value otherwise.
3618 @deffn {Scheme Procedure} string<= s1 s2 [start1 [end1 [start2 [end2]]]]
3619 @deffnx {C Function} scm_string_le (s1, s2, start1, end1, start2, end2)
3620 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3624 @deffn {Scheme Procedure} string>= s1 s2 [start1 [end1 [start2 [end2]]]]
3625 @deffnx {C Function} scm_string_ge (s1, s2, start1, end1, start2, end2)
3626 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3630 @deffn {Scheme Procedure} string-ci= s1 s2 [start1 [end1 [start2 [end2]]]]
3631 @deffnx {C Function} scm_string_ci_eq (s1, s2, start1, end1, start2, end2)
3632 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3633 value otherwise. The character comparison is done
3637 @deffn {Scheme Procedure} string-ci<> s1 s2 [start1 [end1 [start2 [end2]]]]
3638 @deffnx {C Function} scm_string_ci_neq (s1, s2, start1, end1, start2, end2)
3639 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3640 value otherwise. The character comparison is done
3644 @deffn {Scheme Procedure} string-ci< s1 s2 [start1 [end1 [start2 [end2]]]]
3645 @deffnx {C Function} scm_string_ci_lt (s1, s2, start1, end1, start2, end2)
3646 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3647 true value otherwise. The character comparison is done
3651 @deffn {Scheme Procedure} string-ci> s1 s2 [start1 [end1 [start2 [end2]]]]
3652 @deffnx {C Function} scm_string_ci_gt (s1, s2, start1, end1, start2, end2)
3653 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3654 true value otherwise. The character comparison is done
3658 @deffn {Scheme Procedure} string-ci<= s1 s2 [start1 [end1 [start2 [end2]]]]
3659 @deffnx {C Function} scm_string_ci_le (s1, s2, start1, end1, start2, end2)
3660 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3661 value otherwise. The character comparison is done
3665 @deffn {Scheme Procedure} string-ci>= s1 s2 [start1 [end1 [start2 [end2]]]]
3666 @deffnx {C Function} scm_string_ci_ge (s1, s2, start1, end1, start2, end2)
3667 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3668 otherwise. The character comparison is done
3672 @deffn {Scheme Procedure} string-hash s [bound [start [end]]]
3673 @deffnx {C Function} scm_substring_hash (s, bound, start, end)
3674 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).
3677 @deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
3678 @deffnx {C Function} scm_substring_hash_ci (s, bound, start, end)
3679 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).
3682 Because the same visual appearance of an abstract Unicode character can
3683 be obtained via multiple sequences of Unicode characters, even the
3684 case-insensitive string comparison functions described above may return
3685 @code{#f} when presented with strings containing different
3686 representations of the same character. For example, the Unicode
3687 character ``LATIN SMALL LETTER S WITH DOT BELOW AND DOT ABOVE'' can be
3688 represented with a single character (U+1E69) or by the character ``LATIN
3689 SMALL LETTER S'' (U+0073) followed by the combining marks ``COMBINING
3690 DOT BELOW'' (U+0323) and ``COMBINING DOT ABOVE'' (U+0307).
3692 For this reason, it is often desirable to ensure that the strings
3693 to be compared are using a mutually consistent representation for every
3694 character. The Unicode standard defines two methods of normalizing the
3695 contents of strings: Decomposition, which breaks composite characters
3696 into a set of constituent characters with an ordering defined by the
3697 Unicode Standard; and composition, which performs the converse.
3699 There are two decomposition operations. ``Canonical decomposition''
3700 produces character sequences that share the same visual appearance as
3701 the original characters, while ``compatibility decomposition'' produces
3702 ones whose visual appearances may differ from the originals but which
3703 represent the same abstract character.
3705 These operations are encapsulated in the following set of normalization
3710 Characters are decomposed to their canonical forms.
3713 Characters are decomposed to their compatibility forms.
3716 Characters are decomposed to their canonical forms, then composed.
3719 Characters are decomposed to their compatibility forms, then composed.
3723 The functions below put their arguments into one of the forms described
3726 @deffn {Scheme Procedure} string-normalize-nfd s
3727 @deffnx {C Function} scm_string_normalize_nfd (s)
3728 Return the @code{NFD} normalized form of @var{s}.
3731 @deffn {Scheme Procedure} string-normalize-nfkd s
3732 @deffnx {C Function} scm_string_normalize_nfkd (s)
3733 Return the @code{NFKD} normalized form of @var{s}.
3736 @deffn {Scheme Procedure} string-normalize-nfc s
3737 @deffnx {C Function} scm_string_normalize_nfc (s)
3738 Return the @code{NFC} normalized form of @var{s}.
3741 @deffn {Scheme Procedure} string-normalize-nfkc s
3742 @deffnx {C Function} scm_string_normalize_nfkc (s)
3743 Return the @code{NFKC} normalized form of @var{s}.
3746 @node String Searching
3747 @subsubsection String Searching
3749 @deffn {Scheme Procedure} string-index s char_pred [start [end]]
3750 @deffnx {C Function} scm_string_index (s, char_pred, start, end)
3751 Search through the string @var{s} from left to right, returning
3752 the index of the first occurrence of a character which
3756 equals @var{char_pred}, if it is character,
3759 satisfies the predicate @var{char_pred}, if it is a procedure,
3762 is in the set @var{char_pred}, if it is a character set.
3765 Return @code{#f} if no match is found.
3768 @deffn {Scheme Procedure} string-rindex s char_pred [start [end]]
3769 @deffnx {C Function} scm_string_rindex (s, char_pred, start, end)
3770 Search through the string @var{s} from right to left, returning
3771 the index of the last occurrence of a character which
3775 equals @var{char_pred}, if it is character,
3778 satisfies the predicate @var{char_pred}, if it is a procedure,
3781 is in the set if @var{char_pred} is a character set.
3784 Return @code{#f} if no match is found.
3787 @deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3788 @deffnx {C Function} scm_string_prefix_length (s1, s2, start1, end1, start2, end2)
3789 Return the length of the longest common prefix of the two
3793 @deffn {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3794 @deffnx {C Function} scm_string_prefix_length_ci (s1, s2, start1, end1, start2, end2)
3795 Return the length of the longest common prefix of the two
3796 strings, ignoring character case.
3799 @deffn {Scheme Procedure} string-suffix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3800 @deffnx {C Function} scm_string_suffix_length (s1, s2, start1, end1, start2, end2)
3801 Return the length of the longest common suffix of the two
3805 @deffn {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3806 @deffnx {C Function} scm_string_suffix_length_ci (s1, s2, start1, end1, start2, end2)
3807 Return the length of the longest common suffix of the two
3808 strings, ignoring character case.
3811 @deffn {Scheme Procedure} string-prefix? s1 s2 [start1 [end1 [start2 [end2]]]]
3812 @deffnx {C Function} scm_string_prefix_p (s1, s2, start1, end1, start2, end2)
3813 Is @var{s1} a prefix of @var{s2}?
3816 @deffn {Scheme Procedure} string-prefix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3817 @deffnx {C Function} scm_string_prefix_ci_p (s1, s2, start1, end1, start2, end2)
3818 Is @var{s1} a prefix of @var{s2}, ignoring character case?
3821 @deffn {Scheme Procedure} string-suffix? s1 s2 [start1 [end1 [start2 [end2]]]]
3822 @deffnx {C Function} scm_string_suffix_p (s1, s2, start1, end1, start2, end2)
3823 Is @var{s1} a suffix of @var{s2}?
3826 @deffn {Scheme Procedure} string-suffix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3827 @deffnx {C Function} scm_string_suffix_ci_p (s1, s2, start1, end1, start2, end2)
3828 Is @var{s1} a suffix of @var{s2}, ignoring character case?
3831 @deffn {Scheme Procedure} string-index-right s char_pred [start [end]]
3832 @deffnx {C Function} scm_string_index_right (s, char_pred, start, end)
3833 Search through the string @var{s} from right to left, returning
3834 the index of the last occurrence of a character which
3838 equals @var{char_pred}, if it is character,
3841 satisfies the predicate @var{char_pred}, if it is a procedure,
3844 is in the set if @var{char_pred} is a character set.
3847 Return @code{#f} if no match is found.
3850 @deffn {Scheme Procedure} string-skip s char_pred [start [end]]
3851 @deffnx {C Function} scm_string_skip (s, char_pred, start, end)
3852 Search through the string @var{s} from left to right, returning
3853 the index of the first occurrence of a character which
3857 does not equal @var{char_pred}, if it is character,
3860 does not satisfy the predicate @var{char_pred}, if it is a
3864 is not in the set if @var{char_pred} is a character set.
3868 @deffn {Scheme Procedure} string-skip-right s char_pred [start [end]]
3869 @deffnx {C Function} scm_string_skip_right (s, char_pred, start, end)
3870 Search through the string @var{s} from right to left, returning
3871 the index of the last occurrence of a character which
3875 does not equal @var{char_pred}, if it is character,
3878 does not satisfy the predicate @var{char_pred}, if it is a
3882 is not in the set if @var{char_pred} is a character set.
3886 @deffn {Scheme Procedure} string-count s char_pred [start [end]]
3887 @deffnx {C Function} scm_string_count (s, char_pred, start, end)
3888 Return the count of the number of characters in the string
3893 equals @var{char_pred}, if it is character,
3896 satisfies the predicate @var{char_pred}, if it is a procedure.
3899 is in the set @var{char_pred}, if it is a character set.
3903 @deffn {Scheme Procedure} string-contains s1 s2 [start1 [end1 [start2 [end2]]]]
3904 @deffnx {C Function} scm_string_contains (s1, s2, start1, end1, start2, end2)
3905 Does string @var{s1} contain string @var{s2}? Return the index
3906 in @var{s1} where @var{s2} occurs as a substring, or false.
3907 The optional start/end indices restrict the operation to the
3908 indicated substrings.
3911 @deffn {Scheme Procedure} string-contains-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3912 @deffnx {C Function} scm_string_contains_ci (s1, s2, start1, end1, start2, end2)
3913 Does string @var{s1} contain string @var{s2}? Return the index
3914 in @var{s1} where @var{s2} occurs as a substring, or false.
3915 The optional start/end indices restrict the operation to the
3916 indicated substrings. Character comparison is done
3920 @node Alphabetic Case Mapping
3921 @subsubsection Alphabetic Case Mapping
3923 These are procedures for mapping strings to their upper- or lower-case
3924 equivalents, respectively, or for capitalizing strings.
3926 They use the basic case mapping rules for Unicode characters. No
3927 special language or context rules are considered. The resulting strings
3928 are guaranteed to be the same length as the input strings.
3930 @xref{Character Case Mapping, the @code{(ice-9
3931 i18n)} module}, for locale-dependent case conversions.
3933 @deffn {Scheme Procedure} string-upcase str [start [end]]
3934 @deffnx {C Function} scm_substring_upcase (str, start, end)
3935 @deffnx {C Function} scm_string_upcase (str)
3936 Upcase every character in @code{str}.
3939 @deffn {Scheme Procedure} string-upcase! str [start [end]]
3940 @deffnx {C Function} scm_substring_upcase_x (str, start, end)
3941 @deffnx {C Function} scm_string_upcase_x (str)
3942 Destructively upcase every character in @code{str}.
3952 @deffn {Scheme Procedure} string-downcase str [start [end]]
3953 @deffnx {C Function} scm_substring_downcase (str, start, end)
3954 @deffnx {C Function} scm_string_downcase (str)
3955 Downcase every character in @var{str}.
3958 @deffn {Scheme Procedure} string-downcase! str [start [end]]
3959 @deffnx {C Function} scm_substring_downcase_x (str, start, end)
3960 @deffnx {C Function} scm_string_downcase_x (str)
3961 Destructively downcase every character in @var{str}.
3966 (string-downcase! y)
3973 @deffn {Scheme Procedure} string-capitalize str
3974 @deffnx {C Function} scm_string_capitalize (str)
3975 Return a freshly allocated string with the characters in
3976 @var{str}, where the first character of every word is
3980 @deffn {Scheme Procedure} string-capitalize! str
3981 @deffnx {C Function} scm_string_capitalize_x (str)
3982 Upcase the first character of every word in @var{str}
3983 destructively and return @var{str}.
3986 y @result{} "hello world"
3987 (string-capitalize! y) @result{} "Hello World"
3988 y @result{} "Hello World"
3992 @deffn {Scheme Procedure} string-titlecase str [start [end]]
3993 @deffnx {C Function} scm_string_titlecase (str, start, end)
3994 Titlecase every first character in a word in @var{str}.
3997 @deffn {Scheme Procedure} string-titlecase! str [start [end]]
3998 @deffnx {C Function} scm_string_titlecase_x (str, start, end)
3999 Destructively titlecase every first character in a word in
4003 @node Reversing and Appending Strings
4004 @subsubsection Reversing and Appending Strings
4006 @deffn {Scheme Procedure} string-reverse str [start [end]]
4007 @deffnx {C Function} scm_string_reverse (str, start, end)
4008 Reverse the string @var{str}. The optional arguments
4009 @var{start} and @var{end} delimit the region of @var{str} to
4013 @deffn {Scheme Procedure} string-reverse! str [start [end]]
4014 @deffnx {C Function} scm_string_reverse_x (str, start, end)
4015 Reverse the string @var{str} in-place. The optional arguments
4016 @var{start} and @var{end} delimit the region of @var{str} to
4017 operate on. The return value is unspecified.
4020 @rnindex string-append
4021 @deffn {Scheme Procedure} string-append arg @dots{}
4022 @deffnx {C Function} scm_string_append (args)
4023 Return a newly allocated string whose characters form the
4024 concatenation of the given strings, @var{arg} @enddots{}.
4028 (string-append h "world"))
4029 @result{} "hello world"
4033 @deffn {Scheme Procedure} string-append/shared arg @dots{}
4034 @deffnx {C Function} scm_string_append_shared (args)
4035 Like @code{string-append}, but the result may share memory
4036 with the argument strings.
4039 @deffn {Scheme Procedure} string-concatenate ls
4040 @deffnx {C Function} scm_string_concatenate (ls)
4041 Append the elements (which must be strings) of @var{ls} together into a
4042 single string. Guaranteed to return a freshly allocated string.
4045 @deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]]
4046 @deffnx {C Function} scm_string_concatenate_reverse (ls, final_string, end)
4047 Without optional arguments, this procedure is equivalent to
4050 (string-concatenate (reverse ls))
4053 If the optional argument @var{final_string} is specified, it is
4054 consed onto the beginning to @var{ls} before performing the
4055 list-reverse and string-concatenate operations. If @var{end}
4056 is given, only the characters of @var{final_string} up to index
4059 Guaranteed to return a freshly allocated string.
4062 @deffn {Scheme Procedure} string-concatenate/shared ls
4063 @deffnx {C Function} scm_string_concatenate_shared (ls)
4064 Like @code{string-concatenate}, but the result may share memory
4065 with the strings in the list @var{ls}.
4068 @deffn {Scheme Procedure} string-concatenate-reverse/shared ls [final_string [end]]
4069 @deffnx {C Function} scm_string_concatenate_reverse_shared (ls, final_string, end)
4070 Like @code{string-concatenate-reverse}, but the result may
4071 share memory with the strings in the @var{ls} arguments.
4074 @node Mapping Folding and Unfolding
4075 @subsubsection Mapping, Folding, and Unfolding
4077 @deffn {Scheme Procedure} string-map proc s [start [end]]
4078 @deffnx {C Function} scm_string_map (proc, s, start, end)
4079 @var{proc} is a char->char procedure, it is mapped over
4080 @var{s}. The order in which the procedure is applied to the
4081 string elements is not specified.
4084 @deffn {Scheme Procedure} string-map! proc s [start [end]]
4085 @deffnx {C Function} scm_string_map_x (proc, s, start, end)
4086 @var{proc} is a char->char procedure, it is mapped over
4087 @var{s}. The order in which the procedure is applied to the
4088 string elements is not specified. The string @var{s} is
4089 modified in-place, the return value is not specified.
4092 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
4093 @deffnx {C Function} scm_string_for_each (proc, s, start, end)
4094 @var{proc} is mapped over @var{s} in left-to-right order. The
4095 return value is not specified.
4098 @deffn {Scheme Procedure} string-for-each-index proc s [start [end]]
4099 @deffnx {C Function} scm_string_for_each_index (proc, s, start, end)
4100 Call @code{(@var{proc} i)} for each index i in @var{s}, from left to
4103 For example, to change characters to alternately upper and lower case,
4106 (define str (string-copy "studly"))
4107 (string-for-each-index
4110 ((if (even? i) char-upcase char-downcase)
4111 (string-ref str i))))
4113 str @result{} "StUdLy"
4117 @deffn {Scheme Procedure} string-fold kons knil s [start [end]]
4118 @deffnx {C Function} scm_string_fold (kons, knil, s, start, end)
4119 Fold @var{kons} over the characters of @var{s}, with @var{knil}
4120 as the terminating element, from left to right. @var{kons}
4121 must expect two arguments: The actual character and the last
4122 result of @var{kons}' application.
4125 @deffn {Scheme Procedure} string-fold-right kons knil s [start [end]]
4126 @deffnx {C Function} scm_string_fold_right (kons, knil, s, start, end)
4127 Fold @var{kons} over the characters of @var{s}, with @var{knil}
4128 as the terminating element, from right to left. @var{kons}
4129 must expect two arguments: The actual character and the last
4130 result of @var{kons}' application.
4133 @deffn {Scheme Procedure} string-unfold p f g seed [base [make_final]]
4134 @deffnx {C Function} scm_string_unfold (p, f, g, seed, base, make_final)
4136 @item @var{g} is used to generate a series of @emph{seed}
4137 values from the initial @var{seed}: @var{seed}, (@var{g}
4138 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
4140 @item @var{p} tells us when to stop -- when it returns true
4141 when applied to one of these seed values.
4142 @item @var{f} maps each seed value to the corresponding
4143 character in the result string. These chars are assembled
4144 into the string in a left-to-right order.
4145 @item @var{base} is the optional initial/leftmost portion
4146 of the constructed string; it default to the empty
4148 @item @var{make_final} is applied to the terminal seed
4149 value (on which @var{p} returns true) to produce
4150 the final/rightmost portion of the constructed string.
4151 The default is nothing extra.
4155 @deffn {Scheme Procedure} string-unfold-right p f g seed [base [make_final]]
4156 @deffnx {C Function} scm_string_unfold_right (p, f, g, seed, base, make_final)
4158 @item @var{g} is used to generate a series of @emph{seed}
4159 values from the initial @var{seed}: @var{seed}, (@var{g}
4160 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
4162 @item @var{p} tells us when to stop -- when it returns true
4163 when applied to one of these seed values.
4164 @item @var{f} maps each seed value to the corresponding
4165 character in the result string. These chars are assembled
4166 into the string in a right-to-left order.
4167 @item @var{base} is the optional initial/rightmost portion
4168 of the constructed string; it default to the empty
4170 @item @var{make_final} is applied to the terminal seed
4171 value (on which @var{p} returns true) to produce
4172 the final/leftmost portion of the constructed string.
4173 It defaults to @code{(lambda (x) )}.
4177 @node Miscellaneous String Operations
4178 @subsubsection Miscellaneous String Operations
4180 @deffn {Scheme Procedure} xsubstring s from [to [start [end]]]
4181 @deffnx {C Function} scm_xsubstring (s, from, to, start, end)
4182 This is the @emph{extended substring} procedure that implements
4183 replicated copying of a substring of some string.
4185 @var{s} is a string, @var{start} and @var{end} are optional
4186 arguments that demarcate a substring of @var{s}, defaulting to
4187 0 and the length of @var{s}. Replicate this substring up and
4188 down index space, in both the positive and negative directions.
4189 @code{xsubstring} returns the substring of this string
4190 beginning at index @var{from}, and ending at @var{to}, which
4191 defaults to @var{from} + (@var{end} - @var{start}).
4194 @deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto [start [end]]]
4195 @deffnx {C Function} scm_string_xcopy_x (target, tstart, s, sfrom, sto, start, end)
4196 Exactly the same as @code{xsubstring}, but the extracted text
4197 is written into the string @var{target} starting at index
4198 @var{tstart}. The operation is not defined if @code{(eq?
4199 @var{target} @var{s})} or these arguments share storage -- you
4200 cannot copy a string on top of itself.
4203 @deffn {Scheme Procedure} string-replace s1 s2 [start1 [end1 [start2 [end2]]]]
4204 @deffnx {C Function} scm_string_replace (s1, s2, start1, end1, start2, end2)
4205 Return the string @var{s1}, but with the characters
4206 @var{start1} @dots{} @var{end1} replaced by the characters
4207 @var{start2} @dots{} @var{end2} from @var{s2}.
4210 @deffn {Scheme Procedure} string-tokenize s [token_set [start [end]]]
4211 @deffnx {C Function} scm_string_tokenize (s, token_set, start, end)
4212 Split the string @var{s} into a list of substrings, where each
4213 substring is a maximal non-empty contiguous sequence of
4214 characters from the character set @var{token_set}, which
4215 defaults to @code{char-set:graphic}.
4216 If @var{start} or @var{end} indices are provided, they restrict
4217 @code{string-tokenize} to operating on the indicated substring
4221 @deffn {Scheme Procedure} string-filter char_pred s [start [end]]
4222 @deffnx {C Function} scm_string_filter (char_pred, s, start, end)
4223 Filter the string @var{s}, retaining only those characters which
4224 satisfy @var{char_pred}.
4226 If @var{char_pred} is a procedure, it is applied to each character as
4227 a predicate, if it is a character, it is tested for equality and if it
4228 is a character set, it is tested for membership.
4231 @deffn {Scheme Procedure} string-delete char_pred s [start [end]]
4232 @deffnx {C Function} scm_string_delete (char_pred, s, start, end)
4233 Delete characters satisfying @var{char_pred} from @var{s}.
4235 If @var{char_pred} is a procedure, it is applied to each character as
4236 a predicate, if it is a character, it is tested for equality and if it
4237 is a character set, it is tested for membership.
4240 @node Representing Strings as Bytes
4241 @subsubsection Representing Strings as Bytes
4243 Out in the cold world outside of Guile, not all strings are treated in
4244 the same way. Out there there are only bytes, and there are many ways
4245 of representing a strings (sequences of characters) as binary data
4246 (sequences of bytes).
4248 As a user, usually you don't have to think about this very much. When
4249 you type on your keyboard, your system encodes your keystrokes as bytes
4250 according to the locale that you have configured on your computer.
4251 Guile uses the locale to decode those bytes back into characters --
4252 hopefully the same characters that you typed in.
4254 All is not so clear when dealing with a system with multiple users, such
4255 as a web server. Your web server might get a request from one user for
4256 data encoded in the ISO-8859-1 character set, and then another request
4257 from a different user for UTF-8 data.
4260 @cindex character encoding
4261 Guile provides an @dfn{iconv} module for converting between strings and
4262 sequences of bytes. @xref{Bytevectors}, for more on how Guile
4263 represents raw byte sequences. This module gets its name from the
4264 common @sc{unix} command of the same name.
4266 Note that often it is sufficient to just read and write strings from
4267 ports instead of using these functions. To do this, specify the port
4268 encoding using @code{set-port-encoding!}. @xref{Ports}, for more on
4269 ports and character encodings.
4271 Unlike the rest of the procedures in this section, you have to load the
4272 @code{iconv} module before having access to these procedures:
4275 (use-modules (ice-9 iconv))
4278 @deffn {Scheme Procedure} string->bytevector string encoding [conversion-strategy]
4279 Encode @var{string} as a sequence of bytes.
4281 The string will be encoded in the character set specified by the
4282 @var{encoding} string. If the string has characters that cannot be
4283 represented in the encoding, by default this procedure raises an
4284 @code{encoding-error}. Pass a @var{conversion-strategy} argument to
4285 specify other behaviors.
4287 The return value is a bytevector. @xref{Bytevectors}, for more on
4288 bytevectors. @xref{Ports}, for more on character encodings and
4289 conversion strategies.
4292 @deffn {Scheme Procedure} bytevector->string bytevector encoding [conversion-strategy]
4293 Decode @var{bytevector} into a string.
4295 The bytes will be decoded from the character set by the @var{encoding}
4296 string. If the bytes do not form a valid encoding, by default this
4297 procedure raises an @code{decoding-error}. As with
4298 @code{string->bytevector}, pass the optional @var{conversion-strategy}
4299 argument to modify this behavior. @xref{Ports}, for more on character
4300 encodings and conversion strategies.
4303 @deffn {Scheme Procedure} call-with-output-encoded-string encoding proc [conversion-strategy]
4304 Like @code{call-with-output-string}, but instead of returning a string,
4305 returns a encoding of the string according to @var{encoding}, as a
4306 bytevector. This procedure can be more efficient than collecting a
4307 string and then converting it via @code{string->bytevector}.
4310 @node Conversion to/from C
4311 @subsubsection Conversion to/from C
4313 When creating a Scheme string from a C string or when converting a
4314 Scheme string to a C string, the concept of character encoding becomes
4317 In C, a string is just a sequence of bytes, and the character encoding
4318 describes the relation between these bytes and the actual characters
4319 that make up the string. For Scheme strings, character encoding is not
4320 an issue (most of the time), since in Scheme you usually treat strings
4321 as character sequences, not byte sequences.
4323 Converting to C and converting from C each have their own challenges.
4325 When converting from C to Scheme, it is important that the sequence of
4326 bytes in the C string be valid with respect to its encoding. ASCII
4327 strings, for example, can't have any bytes greater than 127. An ASCII
4328 byte greater than 127 is considered @emph{ill-formed} and cannot be
4329 converted into a Scheme character.
4331 Problems can occur in the reverse operation as well. Not all character
4332 encodings can hold all possible Scheme characters. Some encodings, like
4333 ASCII for example, can only describe a small subset of all possible
4334 characters. So, when converting to C, one must first decide what to do
4335 with Scheme characters that can't be represented in the C string.
4337 Converting a Scheme string to a C string will often allocate fresh
4338 memory to hold the result. You must take care that this memory is
4339 properly freed eventually. In many cases, this can be achieved by
4340 using @code{scm_dynwind_free} inside an appropriate dynwind context,
4341 @xref{Dynamic Wind}.
4343 @deftypefn {C Function} SCM scm_from_locale_string (const char *str)
4344 @deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
4345 Creates a new Scheme string that has the same contents as @var{str} when
4346 interpreted in the character encoding of the current locale.
4348 For @code{scm_from_locale_string}, @var{str} must be null-terminated.
4350 For @code{scm_from_locale_stringn}, @var{len} specifies the length of
4351 @var{str} in bytes, and @var{str} does not need to be null-terminated.
4352 If @var{len} is @code{(size_t)-1}, then @var{str} does need to be
4353 null-terminated and the real length will be found with @code{strlen}.
4355 If the C string is ill-formed, an error will be raised.
4357 Note that these functions should @emph{not} be used to convert C string
4358 constants, because there is no guarantee that the current locale will
4359 match that of the execution character set, used for string and character
4360 constants. Most modern C compilers use UTF-8 by default, so to convert
4361 C string constants we recommend @code{scm_from_utf8_string}.
4364 @deftypefn {C Function} SCM scm_take_locale_string (char *str)
4365 @deftypefnx {C Function} SCM scm_take_locale_stringn (char *str, size_t len)
4366 Like @code{scm_from_locale_string} and @code{scm_from_locale_stringn},
4367 respectively, but also frees @var{str} with @code{free} eventually.
4368 Thus, you can use this function when you would free @var{str} anyway
4369 immediately after creating the Scheme string. In certain cases, Guile
4370 can then use @var{str} directly as its internal representation.
4373 @deftypefn {C Function} {char *} scm_to_locale_string (SCM str)
4374 @deftypefnx {C Function} {char *} scm_to_locale_stringn (SCM str, size_t *lenp)
4375 Returns a C string with the same contents as @var{str} in the character
4376 encoding of the current locale. The C string must be freed with
4377 @code{free} eventually, maybe by using @code{scm_dynwind_free},
4378 @xref{Dynamic Wind}.
4380 For @code{scm_to_locale_string}, the returned string is
4381 null-terminated and an error is signalled when @var{str} contains
4382 @code{#\nul} characters.
4384 For @code{scm_to_locale_stringn} and @var{lenp} not @code{NULL},
4385 @var{str} might contain @code{#\nul} characters and the length of the
4386 returned string in bytes is stored in @code{*@var{lenp}}. The
4387 returned string will not be null-terminated in this case. If
4388 @var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
4389 @code{scm_to_locale_string}.
4391 If a character in @var{str} cannot be represented in the character
4392 encoding of the current locale, the default port conversion strategy is
4393 used. @xref{Ports}, for more on conversion strategies.
4395 If the conversion strategy is @code{error}, an error will be raised. If
4396 it is @code{substitute}, a replacement character, such as a question
4397 mark, will be inserted in its place. If it is @code{escape}, a hex
4398 escape will be inserted in its place.
4401 @deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
4402 Puts @var{str} as a C string in the current locale encoding into the
4403 memory pointed to by @var{buf}. The buffer at @var{buf} has room for
4404 @var{max_len} bytes and @code{scm_to_local_stringbuf} will never store
4405 more than that. No terminating @code{'\0'} will be stored.
4407 The return value of @code{scm_to_locale_stringbuf} is the number of
4408 bytes that are needed for all of @var{str}, regardless of whether
4409 @var{buf} was large enough to hold them. Thus, when the return value
4410 is larger than @var{max_len}, only @var{max_len} bytes have been
4411 stored and you probably need to try again with a larger buffer.
4414 For most situations, string conversion should occur using the current
4415 locale, such as with the functions above. But there may be cases where
4416 one wants to convert strings from a character encoding other than the
4417 locale's character encoding. For these cases, the lower-level functions
4418 @code{scm_to_stringn} and @code{scm_from_stringn} are provided. These
4419 functions should seldom be necessary if one is properly using locales.
4421 @deftp {C Type} scm_t_string_failed_conversion_handler
4422 This is an enumerated type that can take one of three values:
4423 @code{SCM_FAILED_CONVERSION_ERROR},
4424 @code{SCM_FAILED_CONVERSION_QUESTION_MARK}, and
4425 @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE}. They are used to indicate
4426 a strategy for handling characters that cannot be converted to or from a
4427 given character encoding. @code{SCM_FAILED_CONVERSION_ERROR} indicates
4428 that a conversion should throw an error if some characters cannot be
4429 converted. @code{SCM_FAILED_CONVERSION_QUESTION_MARK} indicates that a
4430 conversion should replace unconvertable characters with the question
4431 mark character. And, @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE}
4432 requests that a conversion should replace an unconvertable character
4433 with an escape sequence.
4435 While all three strategies apply when converting Scheme strings to C,
4436 only @code{SCM_FAILED_CONVERSION_ERROR} and
4437 @code{SCM_FAILED_CONVERSION_QUESTION_MARK} can be used when converting C
4441 @deftypefn {C Function} char *scm_to_stringn (SCM str, size_t *lenp, const char *encoding, scm_t_string_failed_conversion_handler handler)
4442 This function returns a newly allocated C string from the Guile string
4443 @var{str}. The length of the returned string in bytes will be returned in
4444 @var{lenp}. The character encoding of the C string is passed as the ASCII,
4445 null-terminated C string @var{encoding}. The @var{handler} parameter
4446 gives a strategy for dealing with characters that cannot be converted
4447 into @var{encoding}.
4449 If @var{lenp} is @code{NULL}, this function will return a null-terminated C
4450 string. It will throw an error if the string contains a null
4453 The Scheme interface to this function is @code{string->bytevector}, from the
4454 @code{ice-9 iconv} module. @xref{Representing Strings as Bytes}.
4457 @deftypefn {C Function} SCM scm_from_stringn (const char *str, size_t len, const char *encoding, scm_t_string_failed_conversion_handler handler)
4458 This function returns a scheme string from the C string @var{str}. The
4459 length in bytes of the C string is input as @var{len}. The encoding of the C
4460 string is passed as the ASCII, null-terminated C string @code{encoding}.
4461 The @var{handler} parameters suggests a strategy for dealing with
4462 unconvertable characters.
4464 The Scheme interface to this function is @code{bytevector->string}.
4465 @xref{Representing Strings as Bytes}.
4468 The following conversion functions are provided as a convenience for the
4469 most commonly used encodings.
4471 @deftypefn {C Function} SCM scm_from_latin1_string (const char *str)
4472 @deftypefnx {C Function} SCM scm_from_utf8_string (const char *str)
4473 @deftypefnx {C Function} SCM scm_from_utf32_string (const scm_t_wchar *str)
4474 Return a scheme string from the null-terminated C string @var{str},
4475 which is ISO-8859-1-, UTF-8-, or UTF-32-encoded. These functions should
4476 be used to convert hard-coded C string constants into Scheme strings.
4479 @deftypefn {C Function} SCM scm_from_latin1_stringn (const char *str, size_t len)
4480 @deftypefnx {C Function} SCM scm_from_utf8_stringn (const char *str, size_t len)
4481 @deftypefnx {C Function} SCM scm_from_utf32_stringn (const scm_t_wchar *str, size_t len)
4482 Return a scheme string from C string @var{str}, which is ISO-8859-1-,
4483 UTF-8-, or UTF-32-encoded, of length @var{len}. @var{len} is the number
4484 of bytes pointed to by @var{str} for @code{scm_from_latin1_stringn} and
4485 @code{scm_from_utf8_stringn}; it is the number of elements (code points)
4486 in @var{str} in the case of @code{scm_from_utf32_stringn}.
4489 @deftypefn {C function} char *scm_to_latin1_stringn (SCM str, size_t *lenp)
4490 @deftypefnx {C function} char *scm_to_utf8_stringn (SCM str, size_t *lenp)
4491 @deftypefnx {C function} scm_t_wchar *scm_to_utf32_stringn (SCM str, size_t *lenp)
4492 Return a newly allocated, ISO-8859-1-, UTF-8-, or UTF-32-encoded C string
4493 from Scheme string @var{str}. An error is thrown when @var{str}
4494 cannot be converted to the specified encoding. If @var{lenp} is
4495 @code{NULL}, the returned C string will be null terminated, and an error
4496 will be thrown if the C string would otherwise contain null
4497 characters. If @var{lenp} is not @code{NULL}, the string is not null terminated,
4498 and the length of the returned string is returned in @var{lenp}. The length
4499 returned is the number of bytes for @code{scm_to_latin1_stringn} and
4500 @code{scm_to_utf8_stringn}; it is the number of elements (code points)
4501 for @code{scm_to_utf32_stringn}.
4504 It is not often the case, but sometimes when you are dealing with the
4505 implementation details of a port, you need to encode and decode strings
4506 according to the encoding and conversion strategy of the port. There
4507 are some convenience functions for that purpose as well.
4509 @deftypefn {C Function} SCM scm_from_port_string (const char *str, SCM port)
4510 @deftypefnx {C Function} SCM scm_from_port_stringn (const char *str, size_t len, SCM port)
4511 @deftypefnx {C Function} char* scm_to_port_string (SCM str, SCM port)
4512 @deftypefnx {C Function} char* scm_to_port_stringn (SCM str, size_t *lenp, SCM port)
4513 Like @code{scm_from_stringn} and friends, except they take their
4514 encoding and conversion strategy from a given port object.
4517 @node String Internals
4518 @subsubsection String Internals
4520 Guile stores each string in memory as a contiguous array of Unicode code
4521 points along with an associated set of attributes. If all of the code
4522 points of a string have an integer range between 0 and 255 inclusive,
4523 the code point array is stored as one byte per code point: it is stored
4524 as an ISO-8859-1 (aka Latin-1) string. If any of the code points of the
4525 string has an integer value greater that 255, the code point array is
4526 stored as four bytes per code point: it is stored as a UTF-32 string.
4528 Conversion between the one-byte-per-code-point and
4529 four-bytes-per-code-point representations happens automatically as
4532 No API is provided to set the internal representation of strings;
4533 however, there are pair of procedures available to query it. These are
4534 debugging procedures. Using them in production code is discouraged,
4535 since the details of Guile's internal representation of strings may
4536 change from release to release.
4538 @deffn {Scheme Procedure} string-bytes-per-char str
4539 @deffnx {C Function} scm_string_bytes_per_char (str)
4540 Return the number of bytes used to encode a Unicode code point in string
4541 @var{str}. The result is one or four.
4544 @deffn {Scheme Procedure} %string-dump str
4545 @deffnx {C Function} scm_sys_string_dump (str)
4546 Returns an association list containing debugging information for
4547 @var{str}. The association list has the following entries.
4554 The start index of the string into its stringbuf
4557 The length of the string
4560 If this string is a substring, it returns its
4561 parent string. Otherwise, it returns @code{#f}
4564 @code{#t} if the string is read-only
4566 @item stringbuf-chars
4567 A new string containing this string's stringbuf's characters
4569 @item stringbuf-length
4570 The number of characters in this stringbuf
4572 @item stringbuf-shared
4573 @code{#t} if this stringbuf is shared
4575 @item stringbuf-wide
4576 @code{#t} if this stringbuf's characters are stored in a 32-bit buffer,
4577 or @code{#f} if they are stored in an 8-bit buffer
4583 @subsection Bytevectors
4588 A @dfn{bytevector} is a raw bit string. The @code{(rnrs bytevectors)}
4589 module provides the programming interface specified by the
4590 @uref{http://www.r6rs.org/, Revised^6 Report on the Algorithmic Language
4591 Scheme (R6RS)}. It contains procedures to manipulate bytevectors and
4592 interpret their contents in a number of ways: bytevector contents can be
4593 accessed as signed or unsigned integer of various sizes and endianness,
4594 as IEEE-754 floating point numbers, or as strings. It is a useful tool
4595 to encode and decode binary data.
4597 The R6RS (Section 4.3.4) specifies an external representation for
4598 bytevectors, whereby the octets (integers in the range 0--255) contained
4599 in the bytevector are represented as a list prefixed by @code{#vu8}:
4605 denotes a 3-byte bytevector containing the octets 1, 53, and 204. Like
4606 string literals, booleans, etc., bytevectors are ``self-quoting'', i.e.,
4607 they do not need to be quoted:
4611 @result{} #vu8(1 53 204)
4614 Bytevectors can be used with the binary input/output primitives of the
4615 R6RS (@pxref{R6RS I/O Ports}).
4618 * Bytevector Endianness:: Dealing with byte order.
4619 * Bytevector Manipulation:: Creating, copying, manipulating bytevectors.
4620 * Bytevectors as Integers:: Interpreting bytes as integers.
4621 * Bytevectors and Integer Lists:: Converting to/from an integer list.
4622 * Bytevectors as Floats:: Interpreting bytes as real numbers.
4623 * Bytevectors as Strings:: Interpreting bytes as Unicode strings.
4624 * Bytevectors as Arrays:: Guile extension to the bytevector API.
4625 * Bytevectors as Uniform Vectors:: Bytevectors and SRFI-4.
4628 @node Bytevector Endianness
4629 @subsubsection Endianness
4635 Some of the following procedures take an @var{endianness} parameter.
4636 The @dfn{endianness} is defined as the order of bytes in multi-byte
4637 numbers: numbers encoded in @dfn{big endian} have their most
4638 significant bytes written first, whereas numbers encoded in
4639 @dfn{little endian} have their least significant bytes
4640 first@footnote{Big-endian and little-endian are the most common
4641 ``endiannesses'', but others do exist. For instance, the GNU MP
4642 library allows @dfn{word order} to be specified independently of
4643 @dfn{byte order} (@pxref{Integer Import and Export,,, gmp, The GNU
4644 Multiple Precision Arithmetic Library Manual}).}.
4646 Little-endian is the native endianness of the IA32 architecture and
4647 its derivatives, while big-endian is native to SPARC and PowerPC,
4648 among others. The @code{native-endianness} procedure returns the
4649 native endianness of the machine it runs on.
4651 @deffn {Scheme Procedure} native-endianness
4652 @deffnx {C Function} scm_native_endianness ()
4653 Return a value denoting the native endianness of the host machine.
4656 @deffn {Scheme Macro} endianness symbol
4657 Return an object denoting the endianness specified by @var{symbol}. If
4658 @var{symbol} is neither @code{big} nor @code{little} then an error is
4659 raised at expand-time.
4662 @defvr {C Variable} scm_endianness_big
4663 @defvrx {C Variable} scm_endianness_little
4664 The objects denoting big- and little-endianness, respectively.
4668 @node Bytevector Manipulation
4669 @subsubsection Manipulating Bytevectors
4671 Bytevectors can be created, copied, and analyzed with the following
4672 procedures and C functions.
4674 @deffn {Scheme Procedure} make-bytevector len [fill]
4675 @deffnx {C Function} scm_make_bytevector (len, fill)
4676 @deffnx {C Function} scm_c_make_bytevector (size_t len)
4677 Return a new bytevector of @var{len} bytes. Optionally, if @var{fill}
4678 is given, fill it with @var{fill}; @var{fill} must be in the range
4682 @deffn {Scheme Procedure} bytevector? obj
4683 @deffnx {C Function} scm_bytevector_p (obj)
4684 Return true if @var{obj} is a bytevector.
4687 @deftypefn {C Function} int scm_is_bytevector (SCM obj)
4688 Equivalent to @code{scm_is_true (scm_bytevector_p (obj))}.
4691 @deffn {Scheme Procedure} bytevector-length bv
4692 @deffnx {C Function} scm_bytevector_length (bv)
4693 Return the length in bytes of bytevector @var{bv}.
4696 @deftypefn {C Function} size_t scm_c_bytevector_length (SCM bv)
4697 Likewise, return the length in bytes of bytevector @var{bv}.
4700 @deffn {Scheme Procedure} bytevector=? bv1 bv2
4701 @deffnx {C Function} scm_bytevector_eq_p (bv1, bv2)
4702 Return is @var{bv1} equals to @var{bv2}---i.e., if they have the same
4703 length and contents.
4706 @deffn {Scheme Procedure} bytevector-fill! bv fill
4707 @deffnx {C Function} scm_bytevector_fill_x (bv, fill)
4708 Fill bytevector @var{bv} with @var{fill}, a byte.
4711 @deffn {Scheme Procedure} bytevector-copy! source source-start target target-start len
4712 @deffnx {C Function} scm_bytevector_copy_x (source, source_start, target, target_start, len)
4713 Copy @var{len} bytes from @var{source} into @var{target}, starting
4714 reading from @var{source-start} (a positive index within @var{source})
4715 and start writing at @var{target-start}. It is permitted for the
4716 @var{source} and @var{target} regions to overlap.
4719 @deffn {Scheme Procedure} bytevector-copy bv
4720 @deffnx {C Function} scm_bytevector_copy (bv)
4721 Return a newly allocated copy of @var{bv}.
4724 @deftypefn {C Function} scm_t_uint8 scm_c_bytevector_ref (SCM bv, size_t index)
4725 Return the byte at @var{index} in bytevector @var{bv}.
4728 @deftypefn {C Function} void scm_c_bytevector_set_x (SCM bv, size_t index, scm_t_uint8 value)
4729 Set the byte at @var{index} in @var{bv} to @var{value}.
4732 Low-level C macros are available. They do not perform any
4733 type-checking; as such they should be used with care.
4735 @deftypefn {C Macro} size_t SCM_BYTEVECTOR_LENGTH (bv)
4736 Return the length in bytes of bytevector @var{bv}.
4739 @deftypefn {C Macro} {signed char *} SCM_BYTEVECTOR_CONTENTS (bv)
4740 Return a pointer to the contents of bytevector @var{bv}.
4744 @node Bytevectors as Integers
4745 @subsubsection Interpreting Bytevector Contents as Integers
4747 The contents of a bytevector can be interpreted as a sequence of
4748 integers of any given size, sign, and endianness.
4751 (let ((bv (make-bytevector 4)))
4752 (bytevector-u8-set! bv 0 #x12)
4753 (bytevector-u8-set! bv 1 #x34)
4754 (bytevector-u8-set! bv 2 #x56)
4755 (bytevector-u8-set! bv 3 #x78)
4757 (map (lambda (number)
4758 (number->string number 16))
4759 (list (bytevector-u8-ref bv 0)
4760 (bytevector-u16-ref bv 0 (endianness big))
4761 (bytevector-u32-ref bv 0 (endianness little)))))
4763 @result{} ("12" "1234" "78563412")
4766 The most generic procedures to interpret bytevector contents as integers
4767 are described below.
4769 @deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
4770 @deffnx {C Function} scm_bytevector_uint_ref (bv, index, endianness, size)
4771 Return the @var{size}-byte long unsigned integer at index @var{index} in
4772 @var{bv}, decoded according to @var{endianness}.
4775 @deffn {Scheme Procedure} bytevector-sint-ref bv index endianness size
4776 @deffnx {C Function} scm_bytevector_sint_ref (bv, index, endianness, size)
4777 Return the @var{size}-byte long signed integer at index @var{index} in
4778 @var{bv}, decoded according to @var{endianness}.
4781 @deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
4782 @deffnx {C Function} scm_bytevector_uint_set_x (bv, index, value, endianness, size)
4783 Set the @var{size}-byte long unsigned integer at @var{index} to
4784 @var{value}, encoded according to @var{endianness}.
4787 @deffn {Scheme Procedure} bytevector-sint-set! bv index value endianness size
4788 @deffnx {C Function} scm_bytevector_sint_set_x (bv, index, value, endianness, size)
4789 Set the @var{size}-byte long signed integer at @var{index} to
4790 @var{value}, encoded according to @var{endianness}.
4793 The following procedures are similar to the ones above, but specialized
4794 to a given integer size:
4796 @deffn {Scheme Procedure} bytevector-u8-ref bv index
4797 @deffnx {Scheme Procedure} bytevector-s8-ref bv index
4798 @deffnx {Scheme Procedure} bytevector-u16-ref bv index endianness
4799 @deffnx {Scheme Procedure} bytevector-s16-ref bv index endianness
4800 @deffnx {Scheme Procedure} bytevector-u32-ref bv index endianness
4801 @deffnx {Scheme Procedure} bytevector-s32-ref bv index endianness
4802 @deffnx {Scheme Procedure} bytevector-u64-ref bv index endianness
4803 @deffnx {Scheme Procedure} bytevector-s64-ref bv index endianness
4804 @deffnx {C Function} scm_bytevector_u8_ref (bv, index)
4805 @deffnx {C Function} scm_bytevector_s8_ref (bv, index)
4806 @deffnx {C Function} scm_bytevector_u16_ref (bv, index, endianness)
4807 @deffnx {C Function} scm_bytevector_s16_ref (bv, index, endianness)
4808 @deffnx {C Function} scm_bytevector_u32_ref (bv, index, endianness)
4809 @deffnx {C Function} scm_bytevector_s32_ref (bv, index, endianness)
4810 @deffnx {C Function} scm_bytevector_u64_ref (bv, index, endianness)
4811 @deffnx {C Function} scm_bytevector_s64_ref (bv, index, endianness)
4812 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
4813 16, 32 or 64) from @var{bv} at @var{index}, decoded according to
4817 @deffn {Scheme Procedure} bytevector-u8-set! bv index value
4818 @deffnx {Scheme Procedure} bytevector-s8-set! bv index value
4819 @deffnx {Scheme Procedure} bytevector-u16-set! bv index value endianness
4820 @deffnx {Scheme Procedure} bytevector-s16-set! bv index value endianness
4821 @deffnx {Scheme Procedure} bytevector-u32-set! bv index value endianness
4822 @deffnx {Scheme Procedure} bytevector-s32-set! bv index value endianness
4823 @deffnx {Scheme Procedure} bytevector-u64-set! bv index value endianness
4824 @deffnx {Scheme Procedure} bytevector-s64-set! bv index value endianness
4825 @deffnx {C Function} scm_bytevector_u8_set_x (bv, index, value)
4826 @deffnx {C Function} scm_bytevector_s8_set_x (bv, index, value)
4827 @deffnx {C Function} scm_bytevector_u16_set_x (bv, index, value, endianness)
4828 @deffnx {C Function} scm_bytevector_s16_set_x (bv, index, value, endianness)
4829 @deffnx {C Function} scm_bytevector_u32_set_x (bv, index, value, endianness)
4830 @deffnx {C Function} scm_bytevector_s32_set_x (bv, index, value, endianness)
4831 @deffnx {C Function} scm_bytevector_u64_set_x (bv, index, value, endianness)
4832 @deffnx {C Function} scm_bytevector_s64_set_x (bv, index, value, endianness)
4833 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
4834 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to
4838 Finally, a variant specialized for the host's endianness is available
4839 for each of these functions (with the exception of the @code{u8}
4840 accessors, for obvious reasons):
4842 @deffn {Scheme Procedure} bytevector-u16-native-ref bv index
4843 @deffnx {Scheme Procedure} bytevector-s16-native-ref bv index
4844 @deffnx {Scheme Procedure} bytevector-u32-native-ref bv index
4845 @deffnx {Scheme Procedure} bytevector-s32-native-ref bv index
4846 @deffnx {Scheme Procedure} bytevector-u64-native-ref bv index
4847 @deffnx {Scheme Procedure} bytevector-s64-native-ref bv index
4848 @deffnx {C Function} scm_bytevector_u16_native_ref (bv, index)
4849 @deffnx {C Function} scm_bytevector_s16_native_ref (bv, index)
4850 @deffnx {C Function} scm_bytevector_u32_native_ref (bv, index)
4851 @deffnx {C Function} scm_bytevector_s32_native_ref (bv, index)
4852 @deffnx {C Function} scm_bytevector_u64_native_ref (bv, index)
4853 @deffnx {C Function} scm_bytevector_s64_native_ref (bv, index)
4854 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
4855 16, 32 or 64) from @var{bv} at @var{index}, decoded according to the
4856 host's native endianness.
4859 @deffn {Scheme Procedure} bytevector-u16-native-set! bv index value
4860 @deffnx {Scheme Procedure} bytevector-s16-native-set! bv index value
4861 @deffnx {Scheme Procedure} bytevector-u32-native-set! bv index value
4862 @deffnx {Scheme Procedure} bytevector-s32-native-set! bv index value
4863 @deffnx {Scheme Procedure} bytevector-u64-native-set! bv index value
4864 @deffnx {Scheme Procedure} bytevector-s64-native-set! bv index value
4865 @deffnx {C Function} scm_bytevector_u16_native_set_x (bv, index, value)
4866 @deffnx {C Function} scm_bytevector_s16_native_set_x (bv, index, value)
4867 @deffnx {C Function} scm_bytevector_u32_native_set_x (bv, index, value)
4868 @deffnx {C Function} scm_bytevector_s32_native_set_x (bv, index, value)
4869 @deffnx {C Function} scm_bytevector_u64_native_set_x (bv, index, value)
4870 @deffnx {C Function} scm_bytevector_s64_native_set_x (bv, index, value)
4871 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
4872 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to the
4873 host's native endianness.
4877 @node Bytevectors and Integer Lists
4878 @subsubsection Converting Bytevectors to/from Integer Lists
4880 Bytevector contents can readily be converted to/from lists of signed or
4884 (bytevector->sint-list (u8-list->bytevector (make-list 4 255))
4885 (endianness little) 2)
4889 @deffn {Scheme Procedure} bytevector->u8-list bv
4890 @deffnx {C Function} scm_bytevector_to_u8_list (bv)
4891 Return a newly allocated list of unsigned 8-bit integers from the
4892 contents of @var{bv}.
4895 @deffn {Scheme Procedure} u8-list->bytevector lst
4896 @deffnx {C Function} scm_u8_list_to_bytevector (lst)
4897 Return a newly allocated bytevector consisting of the unsigned 8-bit
4898 integers listed in @var{lst}.
4901 @deffn {Scheme Procedure} bytevector->uint-list bv endianness size
4902 @deffnx {C Function} scm_bytevector_to_uint_list (bv, endianness, size)
4903 Return a list of unsigned integers of @var{size} bytes representing the
4904 contents of @var{bv}, decoded according to @var{endianness}.
4907 @deffn {Scheme Procedure} bytevector->sint-list bv endianness size
4908 @deffnx {C Function} scm_bytevector_to_sint_list (bv, endianness, size)
4909 Return a list of signed integers of @var{size} bytes representing the
4910 contents of @var{bv}, decoded according to @var{endianness}.
4913 @deffn {Scheme Procedure} uint-list->bytevector lst endianness size
4914 @deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
4915 Return a new bytevector containing the unsigned integers listed in
4916 @var{lst} and encoded on @var{size} bytes according to @var{endianness}.
4919 @deffn {Scheme Procedure} sint-list->bytevector lst endianness size
4920 @deffnx {C Function} scm_sint_list_to_bytevector (lst, endianness, size)
4921 Return a new bytevector containing the signed integers listed in
4922 @var{lst} and encoded on @var{size} bytes according to @var{endianness}.
4925 @node Bytevectors as Floats
4926 @subsubsection Interpreting Bytevector Contents as Floating Point Numbers
4928 @cindex IEEE-754 floating point numbers
4930 Bytevector contents can also be accessed as IEEE-754 single- or
4931 double-precision floating point numbers (respectively 32 and 64-bit
4932 long) using the procedures described here.
4934 @deffn {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
4935 @deffnx {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
4936 @deffnx {C Function} scm_bytevector_ieee_single_ref (bv, index, endianness)
4937 @deffnx {C Function} scm_bytevector_ieee_double_ref (bv, index, endianness)
4938 Return the IEEE-754 single-precision floating point number from @var{bv}
4939 at @var{index} according to @var{endianness}.
4942 @deffn {Scheme Procedure} bytevector-ieee-single-set! bv index value endianness
4943 @deffnx {Scheme Procedure} bytevector-ieee-double-set! bv index value endianness
4944 @deffnx {C Function} scm_bytevector_ieee_single_set_x (bv, index, value, endianness)
4945 @deffnx {C Function} scm_bytevector_ieee_double_set_x (bv, index, value, endianness)
4946 Store real number @var{value} in @var{bv} at @var{index} according to
4950 Specialized procedures are also available:
4952 @deffn {Scheme Procedure} bytevector-ieee-single-native-ref bv index
4953 @deffnx {Scheme Procedure} bytevector-ieee-double-native-ref bv index
4954 @deffnx {C Function} scm_bytevector_ieee_single_native_ref (bv, index)
4955 @deffnx {C Function} scm_bytevector_ieee_double_native_ref (bv, index)
4956 Return the IEEE-754 single-precision floating point number from @var{bv}
4957 at @var{index} according to the host's native endianness.
4960 @deffn {Scheme Procedure} bytevector-ieee-single-native-set! bv index value
4961 @deffnx {Scheme Procedure} bytevector-ieee-double-native-set! bv index value
4962 @deffnx {C Function} scm_bytevector_ieee_single_native_set_x (bv, index, value)
4963 @deffnx {C Function} scm_bytevector_ieee_double_native_set_x (bv, index, value)
4964 Store real number @var{value} in @var{bv} at @var{index} according to
4965 the host's native endianness.
4969 @node Bytevectors as Strings
4970 @subsubsection Interpreting Bytevector Contents as Unicode Strings
4972 @cindex Unicode string encoding
4974 Bytevector contents can also be interpreted as Unicode strings encoded
4975 in one of the most commonly available encoding formats.
4976 @xref{Representing Strings as Bytes}, for a more generic interface.
4979 (utf8->string (u8-list->bytevector '(99 97 102 101)))
4982 (string->utf8 "caf@'e") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT
4983 @result{} #vu8(99 97 102 195 169)
4986 @deffn {Scheme Procedure} string->utf8 str
4987 @deffnx {Scheme Procedure} string->utf16 str [endianness]
4988 @deffnx {Scheme Procedure} string->utf32 str [endianness]
4989 @deffnx {C Function} scm_string_to_utf8 (str)
4990 @deffnx {C Function} scm_string_to_utf16 (str, endianness)
4991 @deffnx {C Function} scm_string_to_utf32 (str, endianness)
4992 Return a newly allocated bytevector that contains the UTF-8, UTF-16, or
4993 UTF-32 (aka. UCS-4) encoding of @var{str}. For UTF-16 and UTF-32,
4994 @var{endianness} should be the symbol @code{big} or @code{little}; when omitted,
4995 it defaults to big endian.
4998 @deffn {Scheme Procedure} utf8->string utf
4999 @deffnx {Scheme Procedure} utf16->string utf [endianness]
5000 @deffnx {Scheme Procedure} utf32->string utf [endianness]
5001 @deffnx {C Function} scm_utf8_to_string (utf)
5002 @deffnx {C Function} scm_utf16_to_string (utf, endianness)
5003 @deffnx {C Function} scm_utf32_to_string (utf, endianness)
5004 Return a newly allocated string that contains from the UTF-8-, UTF-16-,
5005 or UTF-32-decoded contents of bytevector @var{utf}. For UTF-16 and UTF-32,
5006 @var{endianness} should be the symbol @code{big} or @code{little}; when omitted,
5007 it defaults to big endian.
5010 @node Bytevectors as Arrays
5011 @subsubsection Accessing Bytevectors with the Array API
5013 As an extension to the R6RS, Guile allows bytevectors to be manipulated
5014 with the @dfn{array} procedures (@pxref{Arrays}). When using these
5015 APIs, bytes are accessed one at a time as 8-bit unsigned integers:
5018 (define bv #vu8(0 1 2 3))
5029 ;; Note the different argument order on array-set!.
5030 (array-set! bv 77 2)
5039 @node Bytevectors as Uniform Vectors
5040 @subsubsection Accessing Bytevectors with the SRFI-4 API
5042 Bytevectors may also be accessed with the SRFI-4 API. @xref{SRFI-4 and
5043 Bytevectors}, for more information.
5050 Symbols in Scheme are widely used in three ways: as items of discrete
5051 data, as lookup keys for alists and hash tables, and to denote variable
5054 A @dfn{symbol} is similar to a string in that it is defined by a
5055 sequence of characters. The sequence of characters is known as the
5056 symbol's @dfn{name}. In the usual case --- that is, where the symbol's
5057 name doesn't include any characters that could be confused with other
5058 elements of Scheme syntax --- a symbol is written in a Scheme program by
5059 writing the sequence of characters that make up the name, @emph{without}
5060 any quotation marks or other special syntax. For example, the symbol
5061 whose name is ``multiply-by-2'' is written, simply:
5067 Notice how this differs from a @emph{string} with contents
5068 ``multiply-by-2'', which is written with double quotation marks, like
5075 Looking beyond how they are written, symbols are different from strings
5076 in two important respects.
5078 The first important difference is uniqueness. If the same-looking
5079 string is read twice from two different places in a program, the result
5080 is two @emph{different} string objects whose contents just happen to be
5081 the same. If, on the other hand, the same-looking symbol is read twice
5082 from two different places in a program, the result is the @emph{same}
5083 symbol object both times.
5085 Given two read symbols, you can use @code{eq?} to test whether they are
5086 the same (that is, have the same name). @code{eq?} is the most
5087 efficient comparison operator in Scheme, and comparing two symbols like
5088 this is as fast as comparing, for example, two numbers. Given two
5089 strings, on the other hand, you must use @code{equal?} or
5090 @code{string=?}, which are much slower comparison operators, to
5091 determine whether the strings have the same contents.
5094 (define sym1 (quote hello))
5095 (define sym2 (quote hello))
5096 (eq? sym1 sym2) @result{} #t
5098 (define str1 "hello")
5099 (define str2 "hello")
5100 (eq? str1 str2) @result{} #f
5101 (equal? str1 str2) @result{} #t
5104 The second important difference is that symbols, unlike strings, are not
5105 self-evaluating. This is why we need the @code{(quote @dots{})}s in the
5106 example above: @code{(quote hello)} evaluates to the symbol named
5107 "hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
5108 symbol named "hello" and evaluated as a variable reference @dots{} about
5109 which more below (@pxref{Symbol Variables}).
5112 * Symbol Data:: Symbols as discrete data.
5113 * Symbol Keys:: Symbols as lookup keys.
5114 * Symbol Variables:: Symbols as denoting variables.
5115 * Symbol Primitives:: Operations related to symbols.
5116 * Symbol Props:: Function slots and property lists.
5117 * Symbol Read Syntax:: Extended read syntax for symbols.
5118 * Symbol Uninterned:: Uninterned symbols.
5123 @subsubsection Symbols as Discrete Data
5125 Numbers and symbols are similar to the extent that they both lend
5126 themselves to @code{eq?} comparison. But symbols are more descriptive
5127 than numbers, because a symbol's name can be used directly to describe
5128 the concept for which that symbol stands.
5130 For example, imagine that you need to represent some colours in a
5131 computer program. Using numbers, you would have to choose arbitrarily
5132 some mapping between numbers and colours, and then take care to use that
5133 mapping consistently:
5136 ;; 1=red, 2=green, 3=purple
5138 (if (eq? (colour-of car) 1)
5143 You can make the mapping more explicit and the code more readable by
5151 (if (eq? (colour-of car) red)
5156 But the simplest and clearest approach is not to use numbers at all, but
5157 symbols whose names specify the colours that they refer to:
5160 (if (eq? (colour-of car) 'red)
5164 The descriptive advantages of symbols over numbers increase as the set
5165 of concepts that you want to describe grows. Suppose that a car object
5166 can have other properties as well, such as whether it has or uses:
5170 automatic or manual transmission
5172 leaded or unleaded fuel
5174 power steering (or not).
5178 Then a car's combined property set could be naturally represented and
5179 manipulated as a list of symbols:
5182 (properties-of car1)
5184 (red manual unleaded power-steering)
5186 (if (memq 'power-steering (properties-of car1))
5187 (display "Unfit people can drive this car.\n")
5188 (display "You'll need strong arms to drive this car!\n"))
5190 Unfit people can drive this car.
5193 Remember, the fundamental property of symbols that we are relying on
5194 here is that an occurrence of @code{'red} in one part of a program is an
5195 @emph{indistinguishable} symbol from an occurrence of @code{'red} in
5196 another part of a program; this means that symbols can usefully be
5197 compared using @code{eq?}. At the same time, symbols have naturally
5198 descriptive names. This combination of efficiency and descriptive power
5199 makes them ideal for use as discrete data.
5203 @subsubsection Symbols as Lookup Keys
5205 Given their efficiency and descriptive power, it is natural to use
5206 symbols as the keys in an association list or hash table.
5208 To illustrate this, consider a more structured representation of the car
5209 properties example from the preceding subsection. Rather than
5210 mixing all the properties up together in a flat list, we could use an
5211 association list like this:
5214 (define car1-properties '((colour . red)
5215 (transmission . manual)
5217 (steering . power-assisted)))
5220 Notice how this structure is more explicit and extensible than the flat
5221 list. For example it makes clear that @code{manual} refers to the
5222 transmission rather than, say, the windows or the locking of the car.
5223 It also allows further properties to use the same symbols among their
5224 possible values without becoming ambiguous:
5227 (define car1-properties '((colour . red)
5228 (transmission . manual)
5230 (steering . power-assisted)
5232 (locking . manual)))
5235 With a representation like this, it is easy to use the efficient
5236 @code{assq-XXX} family of procedures (@pxref{Association Lists}) to
5237 extract or change individual pieces of information:
5240 (assq-ref car1-properties 'fuel) @result{} unleaded
5241 (assq-ref car1-properties 'transmission) @result{} manual
5243 (assq-set! car1-properties 'seat-colour 'black)
5246 (transmission . manual)
5248 (steering . power-assisted)
5249 (seat-colour . black)
5250 (locking . manual)))
5253 Hash tables also have keys, and exactly the same arguments apply to the
5254 use of symbols in hash tables as in association lists. The hash value
5255 that Guile uses to decide where to add a symbol-keyed entry to a hash
5256 table can be obtained by calling the @code{symbol-hash} procedure:
5258 @deffn {Scheme Procedure} symbol-hash symbol
5259 @deffnx {C Function} scm_symbol_hash (symbol)
5260 Return a hash value for @var{symbol}.
5263 See @ref{Hash Tables} for information about hash tables in general, and
5264 for why you might choose to use a hash table rather than an association
5268 @node Symbol Variables
5269 @subsubsection Symbols as Denoting Variables
5271 When an unquoted symbol in a Scheme program is evaluated, it is
5272 interpreted as a variable reference, and the result of the evaluation is
5273 the appropriate variable's value.
5275 For example, when the expression @code{(string-length "abcd")} is read
5276 and evaluated, the sequence of characters @code{string-length} is read
5277 as the symbol whose name is "string-length". This symbol is associated
5278 with a variable whose value is the procedure that implements string
5279 length calculation. Therefore evaluation of the @code{string-length}
5280 symbol results in that procedure.
5282 The details of the connection between an unquoted symbol and the
5283 variable to which it refers are explained elsewhere. See @ref{Binding
5284 Constructs}, for how associations between symbols and variables are
5285 created, and @ref{Modules}, for how those associations are affected by
5286 Guile's module system.
5289 @node Symbol Primitives
5290 @subsubsection Operations Related to Symbols
5292 Given any Scheme value, you can determine whether it is a symbol using
5293 the @code{symbol?} primitive:
5296 @deffn {Scheme Procedure} symbol? obj
5297 @deffnx {C Function} scm_symbol_p (obj)
5298 Return @code{#t} if @var{obj} is a symbol, otherwise return
5302 @deftypefn {C Function} int scm_is_symbol (SCM val)
5303 Equivalent to @code{scm_is_true (scm_symbol_p (val))}.
5306 Once you know that you have a symbol, you can obtain its name as a
5307 string by calling @code{symbol->string}. Note that Guile differs by
5308 default from R5RS on the details of @code{symbol->string} as regards
5311 @rnindex symbol->string
5312 @deffn {Scheme Procedure} symbol->string s
5313 @deffnx {C Function} scm_symbol_to_string (s)
5314 Return the name of symbol @var{s} as a string. By default, Guile reads
5315 symbols case-sensitively, so the string returned will have the same case
5316 variation as the sequence of characters that caused @var{s} to be
5319 If Guile is set to read symbols case-insensitively (as specified by
5320 R5RS), and @var{s} comes into being as part of a literal expression
5321 (@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
5322 by a call to the @code{read} or @code{string-ci->symbol} procedures,
5323 Guile converts any alphabetic characters in the symbol's name to
5324 lower case before creating the symbol object, so the string returned
5325 here will be in lower case.
5327 If @var{s} was created by @code{string->symbol}, the case of characters
5328 in the string returned will be the same as that in the string that was
5329 passed to @code{string->symbol}, regardless of Guile's case-sensitivity
5330 setting at the time @var{s} was created.
5332 It is an error to apply mutation procedures like @code{string-set!} to
5333 strings returned by this procedure.
5336 Most symbols are created by writing them literally in code. However it
5337 is also possible to create symbols programmatically using the following
5340 @deffn {Scheme Procedure} symbol char@dots{}
5342 Return a newly allocated symbol made from the given character arguments.
5345 (symbol #\x #\y #\z) @result{} xyz
5349 @deffn {Scheme Procedure} list->symbol lst
5350 @rnindex list->symbol
5351 Return a newly allocated symbol made from a list of characters.
5354 (list->symbol '(#\a #\b #\c)) @result{} abc
5358 @rnindex symbol-append
5359 @deffn {Scheme Procedure} symbol-append arg @dots{}
5360 Return a newly allocated symbol whose characters form the
5361 concatenation of the given symbols, @var{arg} @enddots{}.
5365 (symbol-append h 'world))
5366 @result{} helloworld
5370 @rnindex string->symbol
5371 @deffn {Scheme Procedure} string->symbol string
5372 @deffnx {C Function} scm_string_to_symbol (string)
5373 Return the symbol whose name is @var{string}. This procedure can create
5374 symbols with names containing special characters or letters in the
5375 non-standard case, but it is usually a bad idea to create such symbols
5376 because in some implementations of Scheme they cannot be read as
5380 @deffn {Scheme Procedure} string-ci->symbol str
5381 @deffnx {C Function} scm_string_ci_to_symbol (str)
5382 Return the symbol whose name is @var{str}. If Guile is currently
5383 reading symbols case-insensitively, @var{str} is converted to lowercase
5384 before the returned symbol is looked up or created.
5387 The following examples illustrate Guile's detailed behaviour as regards
5388 the case-sensitivity of symbols:
5391 (read-enable 'case-insensitive) ; R5RS compliant behaviour
5393 (symbol->string 'flying-fish) @result{} "flying-fish"
5394 (symbol->string 'Martin) @result{} "martin"
5396 (string->symbol "Malvina")) @result{} "Malvina"
5398 (eq? 'mISSISSIppi 'mississippi) @result{} #t
5399 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
5400 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
5402 (string->symbol (symbol->string 'LolliPop))) @result{} #t
5403 (string=? "K. Harper, M.D."
5405 (string->symbol "K. Harper, M.D."))) @result{} #t
5407 (read-disable 'case-insensitive) ; Guile default behaviour
5409 (symbol->string 'flying-fish) @result{} "flying-fish"
5410 (symbol->string 'Martin) @result{} "Martin"
5412 (string->symbol "Malvina")) @result{} "Malvina"
5414 (eq? 'mISSISSIppi 'mississippi) @result{} #f
5415 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
5416 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
5418 (string->symbol (symbol->string 'LolliPop))) @result{} #t
5419 (string=? "K. Harper, M.D."
5421 (string->symbol "K. Harper, M.D."))) @result{} #t
5424 From C, there are lower level functions that construct a Scheme symbol
5425 from a C string in the current locale encoding.
5427 When you want to do more from C, you should convert between symbols
5428 and strings using @code{scm_symbol_to_string} and
5429 @code{scm_string_to_symbol} and work with the strings.
5431 @deftypefn {C Function} SCM scm_from_latin1_symbol (const char *name)
5432 @deftypefnx {C Function} SCM scm_from_utf8_symbol (const char *name)
5433 Construct and return a Scheme symbol whose name is specified by the
5434 null-terminated C string @var{name}. These are appropriate when
5435 the C string is hard-coded in the source code.
5438 @deftypefn {C Function} SCM scm_from_locale_symbol (const char *name)
5439 @deftypefnx {C Function} SCM scm_from_locale_symboln (const char *name, size_t len)
5440 Construct and return a Scheme symbol whose name is specified by
5441 @var{name}. For @code{scm_from_locale_symbol}, @var{name} must be null
5442 terminated; for @code{scm_from_locale_symboln} the length of @var{name} is
5443 specified explicitly by @var{len}.
5445 Note that these functions should @emph{not} be used when @var{name} is a
5446 C string constant, because there is no guarantee that the current locale
5447 will match that of the execution character set, used for string and
5448 character constants. Most modern C compilers use UTF-8 by default, so
5449 in such cases we recommend @code{scm_from_utf8_symbol}.
5452 @deftypefn {C Function} SCM scm_take_locale_symbol (char *str)
5453 @deftypefnx {C Function} SCM scm_take_locale_symboln (char *str, size_t len)
5454 Like @code{scm_from_locale_symbol} and @code{scm_from_locale_symboln},
5455 respectively, but also frees @var{str} with @code{free} eventually.
5456 Thus, you can use this function when you would free @var{str} anyway
5457 immediately after creating the Scheme string. In certain cases, Guile
5458 can then use @var{str} directly as its internal representation.
5461 The size of a symbol can also be obtained from C:
5463 @deftypefn {C Function} size_t scm_c_symbol_length (SCM sym)
5464 Return the number of characters in @var{sym}.
5467 Finally, some applications, especially those that generate new Scheme
5468 code dynamically, need to generate symbols for use in the generated
5469 code. The @code{gensym} primitive meets this need:
5471 @deffn {Scheme Procedure} gensym [prefix]
5472 @deffnx {C Function} scm_gensym (prefix)
5473 Create a new symbol with a name constructed from a prefix and a counter
5474 value. The string @var{prefix} can be specified as an optional
5475 argument. Default prefix is @samp{@w{ g}}. The counter is increased by 1
5476 at each call. There is no provision for resetting the counter.
5479 The symbols generated by @code{gensym} are @emph{likely} to be unique,
5480 since their names begin with a space and it is only otherwise possible
5481 to generate such symbols if a programmer goes out of their way to do
5482 so. Uniqueness can be guaranteed by instead using uninterned symbols
5483 (@pxref{Symbol Uninterned}), though they can't be usefully written out
5488 @subsubsection Function Slots and Property Lists
5490 In traditional Lisp dialects, symbols are often understood as having
5491 three kinds of value at once:
5495 a @dfn{variable} value, which is used when the symbol appears in
5496 code in a variable reference context
5499 a @dfn{function} value, which is used when the symbol appears in
5500 code in a function name position (i.e.@: as the first element in an
5504 a @dfn{property list} value, which is used when the symbol is given as
5505 the first argument to Lisp's @code{put} or @code{get} functions.
5508 Although Scheme (as one of its simplifications with respect to Lisp)
5509 does away with the distinction between variable and function namespaces,
5510 Guile currently retains some elements of the traditional structure in
5511 case they turn out to be useful when implementing translators for other
5512 languages, in particular Emacs Lisp.
5514 Specifically, Guile symbols have two extra slots, one for a symbol's
5515 property list, and one for its ``function value.'' The following procedures
5516 are provided to access these slots.
5518 @deffn {Scheme Procedure} symbol-fref symbol
5519 @deffnx {C Function} scm_symbol_fref (symbol)
5520 Return the contents of @var{symbol}'s @dfn{function slot}.
5523 @deffn {Scheme Procedure} symbol-fset! symbol value
5524 @deffnx {C Function} scm_symbol_fset_x (symbol, value)
5525 Set the contents of @var{symbol}'s function slot to @var{value}.
5528 @deffn {Scheme Procedure} symbol-pref symbol
5529 @deffnx {C Function} scm_symbol_pref (symbol)
5530 Return the @dfn{property list} currently associated with @var{symbol}.
5533 @deffn {Scheme Procedure} symbol-pset! symbol value
5534 @deffnx {C Function} scm_symbol_pset_x (symbol, value)
5535 Set @var{symbol}'s property list to @var{value}.
5538 @deffn {Scheme Procedure} symbol-property sym prop
5539 From @var{sym}'s property list, return the value for property
5540 @var{prop}. The assumption is that @var{sym}'s property list is an
5541 association list whose keys are distinguished from each other using
5542 @code{equal?}; @var{prop} should be one of the keys in that list. If
5543 the property list has no entry for @var{prop}, @code{symbol-property}
5547 @deffn {Scheme Procedure} set-symbol-property! sym prop val
5548 In @var{sym}'s property list, set the value for property @var{prop} to
5549 @var{val}, or add a new entry for @var{prop}, with value @var{val}, if
5550 none already exists. For the structure of the property list, see
5551 @code{symbol-property}.
5554 @deffn {Scheme Procedure} symbol-property-remove! sym prop
5555 From @var{sym}'s property list, remove the entry for property
5556 @var{prop}, if there is one. For the structure of the property list,
5557 see @code{symbol-property}.
5560 Support for these extra slots may be removed in a future release, and it
5561 is probably better to avoid using them. For a more modern and Schemely
5562 approach to properties, see @ref{Object Properties}.
5565 @node Symbol Read Syntax
5566 @subsubsection Extended Read Syntax for Symbols
5568 @cindex r7rs-symbols
5570 The read syntax for a symbol is a sequence of letters, digits, and
5571 @dfn{extended alphabetic characters}, beginning with a character that
5572 cannot begin a number. In addition, the special cases of @code{+},
5573 @code{-}, and @code{...} are read as symbols even though numbers can
5574 begin with @code{+}, @code{-} or @code{.}.
5576 Extended alphabetic characters may be used within identifiers as if
5577 they were letters. The set of extended alphabetic characters is:
5580 ! $ % & * + - . / : < = > ? @@ ^ _ ~
5583 In addition to the standard read syntax defined above (which is taken
5584 from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
5585 Scheme})), Guile provides an extended symbol read syntax that allows the
5586 inclusion of unusual characters such as space characters, newlines and
5587 parentheses. If (for whatever reason) you need to write a symbol
5588 containing characters not mentioned above, you can do so as follows.
5592 Begin the symbol with the characters @code{#@{},
5595 write the characters of the symbol and
5598 finish the symbol with the characters @code{@}#}.
5601 Here are a few examples of this form of read syntax. The first symbol
5602 needs to use extended syntax because it contains a space character, the
5603 second because it contains a line break, and the last because it looks
5615 Although Guile provides this extended read syntax for symbols,
5616 widespread usage of it is discouraged because it is not portable and not
5619 Alternatively, if you enable the @code{r7rs-symbols} read option (see
5620 @pxref{Scheme Read}), you can write arbitrary symbols using the same
5621 notation used for strings, except delimited by vertical bars instead of
5626 |\x3BB; is a greek lambda|
5627 |\| is a vertical bar|
5630 Note that there's also an @code{r7rs-symbols} print option
5631 (@pxref{Scheme Write}). To enable the use of this notation, evaluate
5632 one or both of the following expressions:
5635 (read-enable 'r7rs-symbols)
5636 (print-enable 'r7rs-symbols)
5640 @node Symbol Uninterned
5641 @subsubsection Uninterned Symbols
5643 What makes symbols useful is that they are automatically kept unique.
5644 There are no two symbols that are distinct objects but have the same
5645 name. But of course, there is no rule without exception. In addition
5646 to the normal symbols that have been discussed up to now, you can also
5647 create special @dfn{uninterned} symbols that behave slightly
5650 To understand what is different about them and why they might be useful,
5651 we look at how normal symbols are actually kept unique.
5653 Whenever Guile wants to find the symbol with a specific name, for
5654 example during @code{read} or when executing @code{string->symbol}, it
5655 first looks into a table of all existing symbols to find out whether a
5656 symbol with the given name already exists. When this is the case, Guile
5657 just returns that symbol. When not, a new symbol with the name is
5658 created and entered into the table so that it can be found later.
5660 Sometimes you might want to create a symbol that is guaranteed `fresh',
5661 i.e.@: a symbol that did not exist previously. You might also want to
5662 somehow guarantee that no one else will ever unintentionally stumble
5663 across your symbol in the future. These properties of a symbol are
5664 often needed when generating code during macro expansion. When
5665 introducing new temporary variables, you want to guarantee that they
5666 don't conflict with variables in other people's code.
5668 The simplest way to arrange for this is to create a new symbol but
5669 not enter it into the global table of all symbols. That way, no one
5670 will ever get access to your symbol by chance. Symbols that are not in
5671 the table are called @dfn{uninterned}. Of course, symbols that
5672 @emph{are} in the table are called @dfn{interned}.
5674 You create new uninterned symbols with the function @code{make-symbol}.
5675 You can test whether a symbol is interned or not with
5676 @code{symbol-interned?}.
5678 Uninterned symbols break the rule that the name of a symbol uniquely
5679 identifies the symbol object. Because of this, they can not be written
5680 out and read back in like interned symbols. Currently, Guile has no
5681 support for reading uninterned symbols. Note that the function
5682 @code{gensym} does not return uninterned symbols for this reason.
5684 @deffn {Scheme Procedure} make-symbol name
5685 @deffnx {C Function} scm_make_symbol (name)
5686 Return a new uninterned symbol with the name @var{name}. The returned
5687 symbol is guaranteed to be unique and future calls to
5688 @code{string->symbol} will not return it.
5691 @deffn {Scheme Procedure} symbol-interned? symbol
5692 @deffnx {C Function} scm_symbol_interned_p (symbol)
5693 Return @code{#t} if @var{symbol} is interned, otherwise return
5700 (define foo-1 (string->symbol "foo"))
5701 (define foo-2 (string->symbol "foo"))
5702 (define foo-3 (make-symbol "foo"))
5703 (define foo-4 (make-symbol "foo"))
5707 ; Two interned symbols with the same name are the same object,
5711 ; but a call to make-symbol with the same name returns a
5716 ; A call to make-symbol always returns a new object, even for
5720 @result{} #<uninterned-symbol foo 8085290>
5721 ; Uninterned symbols print differently from interned symbols,
5725 ; but they are still symbols,
5727 (symbol-interned? foo-3)
5729 ; just not interned.
5734 @subsection Keywords
5737 Keywords are self-evaluating objects with a convenient read syntax that
5738 makes them easy to type.
5740 Guile's keyword support conforms to R5RS, and adds a (switchable) read
5741 syntax extension to permit keywords to begin with @code{:} as well as
5742 @code{#:}, or to end with @code{:}.
5745 * Why Use Keywords?:: Motivation for keyword usage.
5746 * Coding With Keywords:: How to use keywords.
5747 * Keyword Read Syntax:: Read syntax for keywords.
5748 * Keyword Procedures:: Procedures for dealing with keywords.
5751 @node Why Use Keywords?
5752 @subsubsection Why Use Keywords?
5754 Keywords are useful in contexts where a program or procedure wants to be
5755 able to accept a large number of optional arguments without making its
5756 interface unmanageable.
5758 To illustrate this, consider a hypothetical @code{make-window}
5759 procedure, which creates a new window on the screen for drawing into
5760 using some graphical toolkit. There are many parameters that the caller
5761 might like to specify, but which could also be sensibly defaulted, for
5766 color depth -- Default: the color depth for the screen
5769 background color -- Default: white
5772 width -- Default: 600
5775 height -- Default: 400
5778 If @code{make-window} did not use keywords, the caller would have to
5779 pass in a value for each possible argument, remembering the correct
5780 argument order and using a special value to indicate the default value
5784 (make-window 'default ;; Color depth
5785 'default ;; Background color
5788 @dots{}) ;; More make-window arguments
5791 With keywords, on the other hand, defaulted arguments are omitted, and
5792 non-default arguments are clearly tagged by the appropriate keyword. As
5793 a result, the invocation becomes much clearer:
5796 (make-window #:width 800 #:height 100)
5799 On the other hand, for a simpler procedure with few arguments, the use
5800 of keywords would be a hindrance rather than a help. The primitive
5801 procedure @code{cons}, for example, would not be improved if it had to
5805 (cons #:car x #:cdr y)
5808 So the decision whether to use keywords or not is purely pragmatic: use
5809 them if they will clarify the procedure invocation at point of call.
5811 @node Coding With Keywords
5812 @subsubsection Coding With Keywords
5814 If a procedure wants to support keywords, it should take a rest argument
5815 and then use whatever means is convenient to extract keywords and their
5816 corresponding arguments from the contents of that rest argument.
5818 The following example illustrates the principle: the code for
5819 @code{make-window} uses a helper procedure called
5820 @code{get-keyword-value} to extract individual keyword arguments from
5824 (define (get-keyword-value args keyword default)
5825 (let ((kv (memq keyword args)))
5826 (if (and kv (>= (length kv) 2))
5830 (define (make-window . args)
5831 (let ((depth (get-keyword-value args #:depth screen-depth))
5832 (bg (get-keyword-value args #:bg "white"))
5833 (width (get-keyword-value args #:width 800))
5834 (height (get-keyword-value args #:height 100))
5839 But you don't need to write @code{get-keyword-value}. The @code{(ice-9
5840 optargs)} module provides a set of powerful macros that you can use to
5841 implement keyword-supporting procedures like this:
5844 (use-modules (ice-9 optargs))
5846 (define (make-window . args)
5847 (let-keywords args #f ((depth screen-depth)
5855 Or, even more economically, like this:
5858 (use-modules (ice-9 optargs))
5860 (define* (make-window #:key (depth screen-depth)
5867 For further details on @code{let-keywords}, @code{define*} and other
5868 facilities provided by the @code{(ice-9 optargs)} module, see
5869 @ref{Optional Arguments}.
5871 To handle keyword arguments from procedures implemented in C,
5872 use @code{scm_c_bind_keyword_arguments} (@pxref{Keyword Procedures}).
5874 @node Keyword Read Syntax
5875 @subsubsection Keyword Read Syntax
5877 Guile, by default, only recognizes a keyword syntax that is compatible
5878 with R5RS. A token of the form @code{#:NAME}, where @code{NAME} has the
5879 same syntax as a Scheme symbol (@pxref{Symbol Read Syntax}), is the
5880 external representation of the keyword named @code{NAME}. Keyword
5881 objects print using this syntax as well, so values containing keyword
5882 objects can be read back into Guile. When used in an expression,
5883 keywords are self-quoting objects.
5885 If the @code{keyword} read option is set to @code{'prefix}, Guile also
5886 recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
5887 of the form @code{:NAME} are read as symbols, as required by R5RS.
5889 @cindex SRFI-88 keyword syntax
5891 If the @code{keyword} read option is set to @code{'postfix}, Guile
5892 recognizes the SRFI-88 read syntax @code{NAME:} (@pxref{SRFI-88}).
5893 Otherwise, tokens of this form are read as symbols.
5895 To enable and disable the alternative non-R5RS keyword syntax, you use
5896 the @code{read-set!} procedure documented @ref{Scheme Read}. Note that
5897 the @code{prefix} and @code{postfix} syntax are mutually exclusive.
5900 (read-set! keywords 'prefix)
5910 (read-set! keywords 'postfix)
5920 (read-set! keywords #f)
5928 ERROR: In expression :type:
5929 ERROR: Unbound variable: :type
5930 ABORT: (unbound-variable)
5933 @node Keyword Procedures
5934 @subsubsection Keyword Procedures
5936 @deffn {Scheme Procedure} keyword? obj
5937 @deffnx {C Function} scm_keyword_p (obj)
5938 Return @code{#t} if the argument @var{obj} is a keyword, else
5942 @deffn {Scheme Procedure} keyword->symbol keyword
5943 @deffnx {C Function} scm_keyword_to_symbol (keyword)
5944 Return the symbol with the same name as @var{keyword}.
5947 @deffn {Scheme Procedure} symbol->keyword symbol
5948 @deffnx {C Function} scm_symbol_to_keyword (symbol)
5949 Return the keyword with the same name as @var{symbol}.
5952 @deftypefn {C Function} int scm_is_keyword (SCM obj)
5953 Equivalent to @code{scm_is_true (scm_keyword_p (@var{obj}))}.
5956 @deftypefn {C Function} SCM scm_from_locale_keyword (const char *name)
5957 @deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *name, size_t len)
5958 Equivalent to @code{scm_symbol_to_keyword (scm_from_locale_symbol
5959 (@var{name}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln
5960 (@var{name}, @var{len}))}, respectively.
5962 Note that these functions should @emph{not} be used when @var{name} is a
5963 C string constant, because there is no guarantee that the current locale
5964 will match that of the execution character set, used for string and
5965 character constants. Most modern C compilers use UTF-8 by default, so
5966 in such cases we recommend @code{scm_from_utf8_keyword}.
5969 @deftypefn {C Function} SCM scm_from_latin1_keyword (const char *name)
5970 @deftypefnx {C Function} SCM scm_from_utf8_keyword (const char *name)
5971 Equivalent to @code{scm_symbol_to_keyword (scm_from_latin1_symbol
5972 (@var{name}))} and @code{scm_symbol_to_keyword (scm_from_utf8_symbol
5973 (@var{name}))}, respectively.
5976 @deftypefn {C Function} void scm_c_bind_keyword_arguments (const char *subr, @
5977 SCM rest, scm_t_keyword_arguments_flags flags, @
5978 SCM keyword1, SCM *argp1, @
5980 SCM keywordN, SCM *argpN, @
5981 @nicode{SCM_UNDEFINED})
5983 Extract the specified keyword arguments from @var{rest}, which is not
5984 modified. If the keyword argument @var{keyword1} is present in
5985 @var{rest} with an associated value, that value is stored in the
5986 variable pointed to by @var{argp1}, otherwise the variable is left
5987 unchanged. Similarly for the other keywords and argument pointers up to
5988 @var{keywordN} and @var{argpN}. The argument list to
5989 @code{scm_c_bind_keyword_arguments} must be terminated by
5990 @code{SCM_UNDEFINED}.
5992 Note that since the variables pointed to by @var{argp1} through
5993 @var{argpN} are left unchanged if the associated keyword argument is not
5994 present, they should be initialized to their default values before
5995 calling @code{scm_c_bind_keyword_arguments}. Alternatively, you can
5996 initialize them to @code{SCM_UNDEFINED} before the call, and then use
5997 @code{SCM_UNBNDP} after the call to see which ones were provided.
5999 If an unrecognized keyword argument is present in @var{rest} and
6000 @var{flags} does not contain @code{SCM_ALLOW_OTHER_KEYS}, or if
6001 non-keyword arguments are present and @var{flags} does not contain
6002 @code{SCM_ALLOW_NON_KEYWORD_ARGUMENTS}, an exception is raised.
6003 @var{subr} should be the name of the procedure receiving the keyword
6004 arguments, for purposes of error reporting.
6013 SCM my_string_join (SCM strings, SCM rest)
6015 SCM delimiter = SCM_UNDEFINED;
6016 SCM grammar = sym_infix;
6018 scm_c_bind_keyword_arguments ("my-string-join", rest, 0,
6019 k_delimiter, &delimiter,
6020 k_grammar, &grammar,
6023 if (SCM_UNBNDP (delimiter))
6024 delimiter = scm_from_utf8_string (" ");
6026 return scm_string_join (strings, delimiter, grammar);
6031 k_delimiter = scm_from_utf8_keyword ("delimiter");
6032 k_grammar = scm_from_utf8_keyword ("grammar");
6033 sym_infix = scm_from_utf8_symbol ("infix");
6034 scm_c_define_gsubr ("my-string-join", 1, 0, 1, my_string_join);
6041 @subsection ``Functionality-Centric'' Data Types
6043 Procedures and macros are documented in their own sections: see
6044 @ref{Procedures} and @ref{Macros}.
6046 Variable objects are documented as part of the description of Guile's
6047 module system: see @ref{Variables}.
6049 Asyncs, dynamic roots and fluids are described in the section on
6050 scheduling: see @ref{Scheduling}.
6052 Hooks are documented in the section on general utility functions: see
6055 Ports are described in the section on I/O: see @ref{Input and Output}.
6057 Regular expressions are described in their own section: see @ref{Regular
6061 @c TeX-master: "guile.texi"