2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007,
4 @c 2008, 2009, 2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Simple Data Types
8 @section Simple Generic Data Types
10 This chapter describes those of Guile's simple data types which are
11 primarily used for their role as items of generic data. By
12 @dfn{simple} we mean data types that are not primarily used as
13 containers to hold other data --- i.e.@: pairs, lists, vectors and so on.
14 For the documentation of such @dfn{compound} data types, see
15 @ref{Compound Data Types}.
17 @c One of the great strengths of Scheme is that there is no straightforward
18 @c distinction between ``data'' and ``functionality''. For example,
19 @c Guile's support for dynamic linking could be described:
23 @c either in a ``data-centric'' way, as the behaviour and properties of the
24 @c ``dynamically linked object'' data type, and the operations that may be
25 @c applied to instances of this type
28 @c or in a ``functionality-centric'' way, as the set of procedures that
29 @c constitute Guile's support for dynamic linking, in the context of the
33 @c The contents of this chapter are, therefore, a matter of judgment. By
34 @c @dfn{generic}, we mean to select those data types whose typical use as
35 @c @emph{data} in a wide variety of programming contexts is more important
36 @c than their use in the implementation of a particular piece of
37 @c @emph{functionality}. The last section of this chapter provides
38 @c references for all the data types that are documented not here but in a
39 @c ``functionality-centric'' way elsewhere in the manual.
42 * Booleans:: True/false values.
43 * Numbers:: Numerical data types.
44 * Characters:: Single characters.
45 * Character Sets:: Sets of characters.
46 * Strings:: Sequences of characters.
47 * Bytevectors:: Sequences of bytes.
49 * Keywords:: Self-quoting, customizable display keywords.
50 * Other Types:: "Functionality-centric" data types.
58 The two boolean values are @code{#t} for true and @code{#f} for false.
60 Boolean values are returned by predicate procedures, such as the general
61 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
62 (@pxref{Equality}) and numerical and string comparison operators like
63 @code{string=?} (@pxref{String Comparison}) and @code{<=}
73 (equal? "house" "houses")
81 In test condition contexts like @code{if} and @code{cond}
82 (@pxref{Conditionals}), where a group of subexpressions will be
83 evaluated only if a @var{condition} expression evaluates to ``true'',
84 ``true'' means any value at all except @code{#f}.
97 A result of this asymmetry is that typical Scheme source code more often
98 uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
99 represent an @code{if} or @code{cond} false value, whereas @code{#t} is
100 not necessary to represent an @code{if} or @code{cond} true value.
102 It is important to note that @code{#f} is @strong{not} equivalent to any
103 other Scheme value. In particular, @code{#f} is not the same as the
104 number 0 (like in C and C++), and not the same as the ``empty list''
105 (like in some Lisp dialects).
107 In C, the two Scheme boolean values are available as the two constants
108 @code{SCM_BOOL_T} for @code{#t} and @code{SCM_BOOL_F} for @code{#f}.
109 Care must be taken with the false value @code{SCM_BOOL_F}: it is not
110 false when used in C conditionals. In order to test for it, use
111 @code{scm_is_false} or @code{scm_is_true}.
114 @deffn {Scheme Procedure} not x
115 @deffnx {C Function} scm_not (x)
116 Return @code{#t} if @var{x} is @code{#f}, else return @code{#f}.
120 @deffn {Scheme Procedure} boolean? obj
121 @deffnx {C Function} scm_boolean_p (obj)
122 Return @code{#t} if @var{obj} is either @code{#t} or @code{#f}, else
126 @deftypevr {C Macro} SCM SCM_BOOL_T
127 The @code{SCM} representation of the Scheme object @code{#t}.
130 @deftypevr {C Macro} SCM SCM_BOOL_F
131 The @code{SCM} representation of the Scheme object @code{#f}.
134 @deftypefn {C Function} int scm_is_true (SCM obj)
135 Return @code{0} if @var{obj} is @code{#f}, else return @code{1}.
138 @deftypefn {C Function} int scm_is_false (SCM obj)
139 Return @code{1} if @var{obj} is @code{#f}, else return @code{0}.
142 @deftypefn {C Function} int scm_is_bool (SCM obj)
143 Return @code{1} if @var{obj} is either @code{#t} or @code{#f}, else
147 @deftypefn {C Function} SCM scm_from_bool (int val)
148 Return @code{#f} if @var{val} is @code{0}, else return @code{#t}.
151 @deftypefn {C Function} int scm_to_bool (SCM val)
152 Return @code{1} if @var{val} is @code{SCM_BOOL_T}, return @code{0}
153 when @var{val} is @code{SCM_BOOL_F}, else signal a `wrong type' error.
155 You should probably use @code{scm_is_true} instead of this function
156 when you just want to test a @code{SCM} value for trueness.
160 @subsection Numerical data types
163 Guile supports a rich ``tower'' of numerical types --- integer,
164 rational, real and complex --- and provides an extensive set of
165 mathematical and scientific functions for operating on numerical
166 data. This section of the manual documents those types and functions.
168 You may also find it illuminating to read R5RS's presentation of numbers
169 in Scheme, which is particularly clear and accessible: see
170 @ref{Numbers,,,r5rs,R5RS}.
173 * Numerical Tower:: Scheme's numerical "tower".
174 * Integers:: Whole numbers.
175 * Reals and Rationals:: Real and rational numbers.
176 * Complex Numbers:: Complex numbers.
177 * Exactness:: Exactness and inexactness.
178 * Number Syntax:: Read syntax for numerical data.
179 * Integer Operations:: Operations on integer values.
180 * Comparison:: Comparison predicates.
181 * Conversion:: Converting numbers to and from strings.
182 * Complex:: Complex number operations.
183 * Arithmetic:: Arithmetic functions.
184 * Scientific:: Scientific functions.
185 * Bitwise Operations:: Logical AND, OR, NOT, and so on.
186 * Random:: Random number generation.
190 @node Numerical Tower
191 @subsubsection Scheme's Numerical ``Tower''
194 Scheme's numerical ``tower'' consists of the following categories of
199 Whole numbers, positive or negative; e.g.@: --5, 0, 18.
202 The set of numbers that can be expressed as @math{@var{p}/@var{q}}
203 where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
204 pi (an irrational number) doesn't. These include integers
208 The set of numbers that describes all possible positions along a
209 one-dimensional line. This includes rationals as well as irrational
212 @item complex numbers
213 The set of numbers that describes all possible positions in a two
214 dimensional space. This includes real as well as imaginary numbers
215 (@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
216 @var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
220 It is called a tower because each category ``sits on'' the one that
221 follows it, in the sense that every integer is also a rational, every
222 rational is also real, and every real number is also a complex number
223 (but with zero imaginary part).
225 In addition to the classification into integers, rationals, reals and
226 complex numbers, Scheme also distinguishes between whether a number is
227 represented exactly or not. For example, the result of
228 @m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)}, but Guile
229 can represent neither @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
230 Instead, it stores an inexact approximation, using the C type
233 Guile can represent exact rationals of any magnitude, inexact
234 rationals that fit into a C @code{double}, and inexact complex numbers
235 with @code{double} real and imaginary parts.
237 The @code{number?} predicate may be applied to any Scheme value to
238 discover whether the value is any of the supported numerical types.
240 @deffn {Scheme Procedure} number? obj
241 @deffnx {C Function} scm_number_p (obj)
242 Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
251 (number? "hello there!")
254 (define pi 3.141592654)
259 @deftypefn {C Function} int scm_is_number (SCM obj)
260 This is equivalent to @code{scm_is_true (scm_number_p (obj))}.
263 The next few subsections document each of Guile's numerical data types
267 @subsubsection Integers
269 @tpindex Integer numbers
273 Integers are whole numbers, that is numbers with no fractional part,
274 such as 2, 83, and @minus{}3789.
276 Integers in Guile can be arbitrarily big, as shown by the following
280 (define (factorial n)
281 (let loop ((n n) (product 1))
284 (loop (- n 1) (* product n)))))
290 @result{} 2432902008176640000
293 @result{} -119622220865480194561963161495657715064383733760000000000
296 Readers whose background is in programming languages where integers are
297 limited by the need to fit into just 4 or 8 bytes of memory may find
298 this surprising, or suspect that Guile's representation of integers is
299 inefficient. In fact, Guile achieves a near optimal balance of
300 convenience and efficiency by using the host computer's native
301 representation of integers where possible, and a more general
302 representation where the required number does not fit in the native
303 form. Conversion between these two representations is automatic and
304 completely invisible to the Scheme level programmer.
306 C has a host of different integer types, and Guile offers a host of
307 functions to convert between them and the @code{SCM} representation.
308 For example, a C @code{int} can be handled with @code{scm_to_int} and
309 @code{scm_from_int}. Guile also defines a few C integer types of its
310 own, to help with differences between systems.
312 C integer types that are not covered can be handled with the generic
313 @code{scm_to_signed_integer} and @code{scm_from_signed_integer} for
314 signed types, or with @code{scm_to_unsigned_integer} and
315 @code{scm_from_unsigned_integer} for unsigned types.
317 Scheme integers can be exact and inexact. For example, a number
318 written as @code{3.0} with an explicit decimal-point is inexact, but
319 it is also an integer. The functions @code{integer?} and
320 @code{scm_is_integer} report true for such a number, but the functions
321 @code{exact-integer?}, @code{scm_is_exact_integer},
322 @code{scm_is_signed_integer}, and @code{scm_is_unsigned_integer} only
323 allow exact integers and thus report false. Likewise, the conversion
324 functions like @code{scm_to_signed_integer} only accept exact
327 The motivation for this behavior is that the inexactness of a number
328 should not be lost silently. If you want to allow inexact integers,
329 you can explicitly insert a call to @code{inexact->exact} or to its C
330 equivalent @code{scm_inexact_to_exact}. (Only inexact integers will
331 be converted by this call into exact integers; inexact non-integers
332 will become exact fractions.)
334 @deffn {Scheme Procedure} integer? x
335 @deffnx {C Function} scm_integer_p (x)
336 Return @code{#t} if @var{x} is an exact or inexact integer number, else
354 @deftypefn {C Function} int scm_is_integer (SCM x)
355 This is equivalent to @code{scm_is_true (scm_integer_p (x))}.
358 @deffn {Scheme Procedure} exact-integer? x
359 @deffnx {C Function} scm_exact_integer_p (x)
360 Return @code{#t} if @var{x} is an exact integer number, else
372 @deftypefn {C Function} int scm_is_exact_integer (SCM x)
373 This is equivalent to @code{scm_is_true (scm_exact_integer_p (x))}.
376 @defvr {C Type} scm_t_int8
377 @defvrx {C Type} scm_t_uint8
378 @defvrx {C Type} scm_t_int16
379 @defvrx {C Type} scm_t_uint16
380 @defvrx {C Type} scm_t_int32
381 @defvrx {C Type} scm_t_uint32
382 @defvrx {C Type} scm_t_int64
383 @defvrx {C Type} scm_t_uint64
384 @defvrx {C Type} scm_t_intmax
385 @defvrx {C Type} scm_t_uintmax
386 The C types are equivalent to the corresponding ISO C types but are
387 defined on all platforms, with the exception of @code{scm_t_int64} and
388 @code{scm_t_uint64}, which are only defined when a 64-bit type is
389 available. For example, @code{scm_t_int8} is equivalent to
392 You can regard these definitions as a stop-gap measure until all
393 platforms provide these types. If you know that all the platforms
394 that you are interested in already provide these types, it is better
395 to use them directly instead of the types provided by Guile.
398 @deftypefn {C Function} int scm_is_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
399 @deftypefnx {C Function} int scm_is_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
400 Return @code{1} when @var{x} represents an exact integer that is
401 between @var{min} and @var{max}, inclusive.
403 These functions can be used to check whether a @code{SCM} value will
404 fit into a given range, such as the range of a given C integer type.
405 If you just want to convert a @code{SCM} value to a given C integer
406 type, use one of the conversion functions directly.
409 @deftypefn {C Function} scm_t_intmax scm_to_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
410 @deftypefnx {C Function} scm_t_uintmax scm_to_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
411 When @var{x} represents an exact integer that is between @var{min} and
412 @var{max} inclusive, return that integer. Else signal an error,
413 either a `wrong-type' error when @var{x} is not an exact integer, or
414 an `out-of-range' error when it doesn't fit the given range.
417 @deftypefn {C Function} SCM scm_from_signed_integer (scm_t_intmax x)
418 @deftypefnx {C Function} SCM scm_from_unsigned_integer (scm_t_uintmax x)
419 Return the @code{SCM} value that represents the integer @var{x}. This
420 function will always succeed and will always return an exact number.
423 @deftypefn {C Function} char scm_to_char (SCM x)
424 @deftypefnx {C Function} {signed char} scm_to_schar (SCM x)
425 @deftypefnx {C Function} {unsigned char} scm_to_uchar (SCM x)
426 @deftypefnx {C Function} short scm_to_short (SCM x)
427 @deftypefnx {C Function} {unsigned short} scm_to_ushort (SCM x)
428 @deftypefnx {C Function} int scm_to_int (SCM x)
429 @deftypefnx {C Function} {unsigned int} scm_to_uint (SCM x)
430 @deftypefnx {C Function} long scm_to_long (SCM x)
431 @deftypefnx {C Function} {unsigned long} scm_to_ulong (SCM x)
432 @deftypefnx {C Function} {long long} scm_to_long_long (SCM x)
433 @deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x)
434 @deftypefnx {C Function} size_t scm_to_size_t (SCM x)
435 @deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x)
436 @deftypefnx {C Function} scm_t_ptrdiff scm_to_ptrdiff_t (SCM x)
437 @deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x)
438 @deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x)
439 @deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x)
440 @deftypefnx {C Function} scm_t_uint16 scm_to_uint16 (SCM x)
441 @deftypefnx {C Function} scm_t_int32 scm_to_int32 (SCM x)
442 @deftypefnx {C Function} scm_t_uint32 scm_to_uint32 (SCM x)
443 @deftypefnx {C Function} scm_t_int64 scm_to_int64 (SCM x)
444 @deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x)
445 @deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x)
446 @deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x)
447 When @var{x} represents an exact integer that fits into the indicated
448 C type, return that integer. Else signal an error, either a
449 `wrong-type' error when @var{x} is not an exact integer, or an
450 `out-of-range' error when it doesn't fit the given range.
452 The functions @code{scm_to_long_long}, @code{scm_to_ulong_long},
453 @code{scm_to_int64}, and @code{scm_to_uint64} are only available when
454 the corresponding types are.
457 @deftypefn {C Function} SCM scm_from_char (char x)
458 @deftypefnx {C Function} SCM scm_from_schar (signed char x)
459 @deftypefnx {C Function} SCM scm_from_uchar (unsigned char x)
460 @deftypefnx {C Function} SCM scm_from_short (short x)
461 @deftypefnx {C Function} SCM scm_from_ushort (unsigned short x)
462 @deftypefnx {C Function} SCM scm_from_int (int x)
463 @deftypefnx {C Function} SCM scm_from_uint (unsigned int x)
464 @deftypefnx {C Function} SCM scm_from_long (long x)
465 @deftypefnx {C Function} SCM scm_from_ulong (unsigned long x)
466 @deftypefnx {C Function} SCM scm_from_long_long (long long x)
467 @deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x)
468 @deftypefnx {C Function} SCM scm_from_size_t (size_t x)
469 @deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x)
470 @deftypefnx {C Function} SCM scm_from_ptrdiff_t (scm_t_ptrdiff x)
471 @deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x)
472 @deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x)
473 @deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x)
474 @deftypefnx {C Function} SCM scm_from_uint16 (scm_t_uint16 x)
475 @deftypefnx {C Function} SCM scm_from_int32 (scm_t_int32 x)
476 @deftypefnx {C Function} SCM scm_from_uint32 (scm_t_uint32 x)
477 @deftypefnx {C Function} SCM scm_from_int64 (scm_t_int64 x)
478 @deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x)
479 @deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x)
480 @deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x)
481 Return the @code{SCM} value that represents the integer @var{x}.
482 These functions will always succeed and will always return an exact
486 @deftypefn {C Function} void scm_to_mpz (SCM val, mpz_t rop)
487 Assign @var{val} to the multiple precision integer @var{rop}.
488 @var{val} must be an exact integer, otherwise an error will be
489 signalled. @var{rop} must have been initialized with @code{mpz_init}
490 before this function is called. When @var{rop} is no longer needed
491 the occupied space must be freed with @code{mpz_clear}.
492 @xref{Initializing Integers,,, gmp, GNU MP Manual}, for details.
495 @deftypefn {C Function} SCM scm_from_mpz (mpz_t val)
496 Return the @code{SCM} value that represents @var{val}.
499 @node Reals and Rationals
500 @subsubsection Real and Rational Numbers
501 @tpindex Real numbers
502 @tpindex Rational numbers
507 Mathematically, the real numbers are the set of numbers that describe
508 all possible points along a continuous, infinite, one-dimensional line.
509 The rational numbers are the set of all numbers that can be written as
510 fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
511 All rational numbers are also real, but there are real numbers that
512 are not rational, for example @m{\sqrt{2}, the square root of 2}, and
515 Guile can represent both exact and inexact rational numbers, but it
516 cannot represent precise finite irrational numbers. Exact rationals are
517 represented by storing the numerator and denominator as two exact
518 integers. Inexact rationals are stored as floating point numbers using
519 the C type @code{double}.
521 Exact rationals are written as a fraction of integers. There must be
522 no whitespace around the slash:
529 Even though the actual encoding of inexact rationals is in binary, it
530 may be helpful to think of it as a decimal number with a limited
531 number of significant figures and a decimal point somewhere, since
532 this corresponds to the standard notation for non-whole numbers. For
538 -5648394822220000000000.0
542 The limited precision of Guile's encoding means that any finite ``real''
543 number in Guile can be written in a rational form, by multiplying and
544 then dividing by sufficient powers of 10 (or in fact, 2). For example,
545 @samp{-0.00000142857931198} is the same as @minus{}142857931198 divided
546 by 100000000000000000. In Guile's current incarnation, therefore, the
547 @code{rational?} and @code{real?} predicates are equivalent for finite
551 Dividing by an exact zero leads to a error message, as one might expect.
552 However, dividing by an inexact zero does not produce an error.
553 Instead, the result of the division is either plus or minus infinity,
554 depending on the sign of the divided number and the sign of the zero
555 divisor (some platforms support signed zeroes @samp{-0.0} and
556 @samp{+0.0}; @samp{0.0} is the same as @samp{+0.0}).
558 Dividing zero by an inexact zero yields a @acronym{NaN} (`not a number')
559 value, although they are actually considered numbers by Scheme.
560 Attempts to compare a @acronym{NaN} value with any number (including
561 itself) using @code{=}, @code{<}, @code{>}, @code{<=} or @code{>=}
562 always returns @code{#f}. Although a @acronym{NaN} value is not
563 @code{=} to itself, it is both @code{eqv?} and @code{equal?} to itself
564 and other @acronym{NaN} values. However, the preferred way to test for
565 them is by using @code{nan?}.
567 The real @acronym{NaN} values and infinities are written @samp{+nan.0},
568 @samp{+inf.0} and @samp{-inf.0}. This syntax is also recognized by
569 @code{read} as an extension to the usual Scheme syntax. These special
570 values are considered by Scheme to be inexact real numbers but not
571 rational. Note that non-real complex numbers may also contain
572 infinities or @acronym{NaN} values in their real or imaginary parts. To
573 test a real number to see if it is infinite, a @acronym{NaN} value, or
574 neither, use @code{inf?}, @code{nan?}, or @code{finite?}, respectively.
575 Every real number in Scheme belongs to precisely one of those three
578 On platforms that follow @acronym{IEEE} 754 for their floating point
579 arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
580 are implemented using the corresponding @acronym{IEEE} 754 values.
581 They behave in arithmetic operations like @acronym{IEEE} 754 describes
582 it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
584 @deffn {Scheme Procedure} real? obj
585 @deffnx {C Function} scm_real_p (obj)
586 Return @code{#t} if @var{obj} is a real number, else @code{#f}. Note
587 that the sets of integer and rational values form subsets of the set
588 of real numbers, so the predicate will also be fulfilled if @var{obj}
589 is an integer number or a rational number.
592 @deffn {Scheme Procedure} rational? x
593 @deffnx {C Function} scm_rational_p (x)
594 Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise.
595 Note that the set of integer values forms a subset of the set of
596 rational numbers, i.e.@: the predicate will also be fulfilled if
597 @var{x} is an integer number.
600 @deffn {Scheme Procedure} rationalize x eps
601 @deffnx {C Function} scm_rationalize (x, eps)
602 Returns the @emph{simplest} rational number differing
603 from @var{x} by no more than @var{eps}.
605 As required by @acronym{R5RS}, @code{rationalize} only returns an
606 exact result when both its arguments are exact. Thus, you might need
607 to use @code{inexact->exact} on the arguments.
610 (rationalize (inexact->exact 1.2) 1/100)
616 @deffn {Scheme Procedure} inf? x
617 @deffnx {C Function} scm_inf_p (x)
618 Return @code{#t} if the real number @var{x} is @samp{+inf.0} or
619 @samp{-inf.0}. Otherwise return @code{#f}.
622 @deffn {Scheme Procedure} nan? x
623 @deffnx {C Function} scm_nan_p (x)
624 Return @code{#t} if the real number @var{x} is @samp{+nan.0}, or
628 @deffn {Scheme Procedure} finite? x
629 @deffnx {C Function} scm_finite_p (x)
630 Return @code{#t} if the real number @var{x} is neither infinite nor a
631 NaN, @code{#f} otherwise.
634 @deffn {Scheme Procedure} nan
635 @deffnx {C Function} scm_nan ()
636 Return @samp{+nan.0}, a @acronym{NaN} value.
639 @deffn {Scheme Procedure} inf
640 @deffnx {C Function} scm_inf ()
641 Return @samp{+inf.0}, positive infinity.
644 @deffn {Scheme Procedure} numerator x
645 @deffnx {C Function} scm_numerator (x)
646 Return the numerator of the rational number @var{x}.
649 @deffn {Scheme Procedure} denominator x
650 @deffnx {C Function} scm_denominator (x)
651 Return the denominator of the rational number @var{x}.
654 @deftypefn {C Function} int scm_is_real (SCM val)
655 @deftypefnx {C Function} int scm_is_rational (SCM val)
656 Equivalent to @code{scm_is_true (scm_real_p (val))} and
657 @code{scm_is_true (scm_rational_p (val))}, respectively.
660 @deftypefn {C Function} double scm_to_double (SCM val)
661 Returns the number closest to @var{val} that is representable as a
662 @code{double}. Returns infinity for a @var{val} that is too large in
663 magnitude. The argument @var{val} must be a real number.
666 @deftypefn {C Function} SCM scm_from_double (double val)
667 Return the @code{SCM} value that represents @var{val}. The returned
668 value is inexact according to the predicate @code{inexact?}, but it
669 will be exactly equal to @var{val}.
672 @node Complex Numbers
673 @subsubsection Complex Numbers
674 @tpindex Complex numbers
678 Complex numbers are the set of numbers that describe all possible points
679 in a two-dimensional space. The two coordinates of a particular point
680 in this space are known as the @dfn{real} and @dfn{imaginary} parts of
681 the complex number that describes that point.
683 In Guile, complex numbers are written in rectangular form as the sum of
684 their real and imaginary parts, using the symbol @code{i} to indicate
699 Polar form can also be used, with an @samp{@@} between magnitude and
703 1@@3.141592 @result{} -1.0 (approx)
704 -1@@1.57079 @result{} 0.0-1.0i (approx)
707 Guile represents a complex number as a pair of inexact reals, so the
708 real and imaginary parts of a complex number have the same properties of
709 inexactness and limited precision as single inexact real numbers.
711 Note that each part of a complex number may contain any inexact real
712 value, including the special values @samp{+nan.0}, @samp{+inf.0} and
713 @samp{-inf.0}, as well as either of the signed zeroes @samp{0.0} or
717 @deffn {Scheme Procedure} complex? z
718 @deffnx {C Function} scm_complex_p (z)
719 Return @code{#t} if @var{z} is a complex number, @code{#f}
720 otherwise. Note that the sets of real, rational and integer
721 values form subsets of the set of complex numbers, i.e.@: the
722 predicate will also be fulfilled if @var{z} is a real,
723 rational or integer number.
726 @deftypefn {C Function} int scm_is_complex (SCM val)
727 Equivalent to @code{scm_is_true (scm_complex_p (val))}.
731 @subsubsection Exact and Inexact Numbers
732 @tpindex Exact numbers
733 @tpindex Inexact numbers
737 @rnindex exact->inexact
738 @rnindex inexact->exact
740 R5RS requires that, with few exceptions, a calculation involving inexact
741 numbers always produces an inexact result. To meet this requirement,
742 Guile distinguishes between an exact integer value such as @samp{5} and
743 the corresponding inexact integer value which, to the limited precision
744 available, has no fractional part, and is printed as @samp{5.0}. Guile
745 will only convert the latter value to the former when forced to do so by
746 an invocation of the @code{inexact->exact} procedure.
748 The only exception to the above requirement is when the values of the
749 inexact numbers do not affect the result. For example @code{(expt n 0)}
750 is @samp{1} for any value of @code{n}, therefore @code{(expt 5.0 0)} is
751 permitted to return an exact @samp{1}.
753 @deffn {Scheme Procedure} exact? z
754 @deffnx {C Function} scm_exact_p (z)
755 Return @code{#t} if the number @var{z} is exact, @code{#f}
771 @deftypefn {C Function} int scm_is_exact (SCM z)
772 Return a @code{1} if the number @var{z} is exact, and @code{0}
773 otherwise. This is equivalent to @code{scm_is_true (scm_exact_p (z))}.
775 An alternate approch to testing the exactness of a number is to
776 use @code{scm_is_signed_integer} or @code{scm_is_unsigned_integer}.
779 @deffn {Scheme Procedure} inexact? z
780 @deffnx {C Function} scm_inexact_p (z)
781 Return @code{#t} if the number @var{z} is inexact, @code{#f}
785 @deftypefn {C Function} int scm_is_inexact (SCM z)
786 Return a @code{1} if the number @var{z} is inexact, and @code{0}
787 otherwise. This is equivalent to @code{scm_is_true (scm_inexact_p (z))}.
790 @deffn {Scheme Procedure} inexact->exact z
791 @deffnx {C Function} scm_inexact_to_exact (z)
792 Return an exact number that is numerically closest to @var{z}, when
793 there is one. For inexact rationals, Guile returns the exact rational
794 that is numerically equal to the inexact rational. Inexact complex
795 numbers with a non-zero imaginary part can not be made exact.
802 The following happens because 12/10 is not exactly representable as a
803 @code{double} (on most platforms). However, when reading a decimal
804 number that has been marked exact with the ``#e'' prefix, Guile is
805 able to represent it correctly.
809 @result{} 5404319552844595/4503599627370496
817 @c begin (texi-doc-string "guile" "exact->inexact")
818 @deffn {Scheme Procedure} exact->inexact z
819 @deffnx {C Function} scm_exact_to_inexact (z)
820 Convert the number @var{z} to its inexact representation.
825 @subsubsection Read Syntax for Numerical Data
827 The read syntax for integers is a string of digits, optionally
828 preceded by a minus or plus character, a code indicating the
829 base in which the integer is encoded, and a code indicating whether
830 the number is exact or inexact. The supported base codes are:
835 the integer is written in binary (base 2)
839 the integer is written in octal (base 8)
843 the integer is written in decimal (base 10)
847 the integer is written in hexadecimal (base 16)
850 If the base code is omitted, the integer is assumed to be decimal. The
851 following examples show how these base codes are used.
870 The codes for indicating exactness (which can, incidentally, be applied
871 to all numerical values) are:
880 the number is inexact.
883 If the exactness indicator is omitted, the number is exact unless it
884 contains a radix point. Since Guile can not represent exact complex
885 numbers, an error is signalled when asking for them.
895 ERROR: Wrong type argument
898 Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
899 plus and minus infinity, respectively. The value must be written
900 exactly as shown, that is, they always must have a sign and exactly
901 one zero digit after the decimal point. It also understands
902 @samp{+nan.0} and @samp{-nan.0} for the special `not-a-number' value.
903 The sign is ignored for `not-a-number' and the value is always printed
906 @node Integer Operations
907 @subsubsection Operations on Integer Values
916 @deffn {Scheme Procedure} odd? n
917 @deffnx {C Function} scm_odd_p (n)
918 Return @code{#t} if @var{n} is an odd number, @code{#f}
922 @deffn {Scheme Procedure} even? n
923 @deffnx {C Function} scm_even_p (n)
924 Return @code{#t} if @var{n} is an even number, @code{#f}
928 @c begin (texi-doc-string "guile" "quotient")
929 @c begin (texi-doc-string "guile" "remainder")
930 @deffn {Scheme Procedure} quotient n d
931 @deffnx {Scheme Procedure} remainder n d
932 @deffnx {C Function} scm_quotient (n, d)
933 @deffnx {C Function} scm_remainder (n, d)
934 Return the quotient or remainder from @var{n} divided by @var{d}. The
935 quotient is rounded towards zero, and the remainder will have the same
936 sign as @var{n}. In all cases quotient and remainder satisfy
937 @math{@var{n} = @var{q}*@var{d} + @var{r}}.
940 (remainder 13 4) @result{} 1
941 (remainder -13 4) @result{} -1
944 See also @code{truncate-quotient}, @code{truncate-remainder} and
945 related operations in @ref{Arithmetic}.
948 @c begin (texi-doc-string "guile" "modulo")
949 @deffn {Scheme Procedure} modulo n d
950 @deffnx {C Function} scm_modulo (n, d)
951 Return the remainder from @var{n} divided by @var{d}, with the same
955 (modulo 13 4) @result{} 1
956 (modulo -13 4) @result{} 3
957 (modulo 13 -4) @result{} -3
958 (modulo -13 -4) @result{} -1
961 See also @code{floor-quotient}, @code{floor-remainder} and
962 related operations in @ref{Arithmetic}.
965 @c begin (texi-doc-string "guile" "gcd")
966 @deffn {Scheme Procedure} gcd x@dots{}
967 @deffnx {C Function} scm_gcd (x, y)
968 Return the greatest common divisor of all arguments.
969 If called without arguments, 0 is returned.
971 The C function @code{scm_gcd} always takes two arguments, while the
972 Scheme function can take an arbitrary number.
975 @c begin (texi-doc-string "guile" "lcm")
976 @deffn {Scheme Procedure} lcm x@dots{}
977 @deffnx {C Function} scm_lcm (x, y)
978 Return the least common multiple of the arguments.
979 If called without arguments, 1 is returned.
981 The C function @code{scm_lcm} always takes two arguments, while the
982 Scheme function can take an arbitrary number.
985 @deffn {Scheme Procedure} modulo-expt n k m
986 @deffnx {C Function} scm_modulo_expt (n, k, m)
987 Return @var{n} raised to the integer exponent
988 @var{k}, modulo @var{m}.
996 @deftypefn {Scheme Procedure} {} exact-integer-sqrt @var{k}
997 @deftypefnx {C Function} void scm_exact_integer_sqrt (SCM @var{k}, SCM *@var{s}, SCM *@var{r})
998 Return two exact non-negative integers @var{s} and @var{r}
999 such that @math{@var{k} = @var{s}^2 + @var{r}} and
1000 @math{@var{s}^2 <= @var{k} < (@var{s} + 1)^2}.
1001 An error is raised if @var{k} is not an exact non-negative integer.
1004 (exact-integer-sqrt 10) @result{} 3 and 1
1009 @subsubsection Comparison Predicates
1014 The C comparison functions below always takes two arguments, while the
1015 Scheme functions can take an arbitrary number. Also keep in mind that
1016 the C functions return one of the Scheme boolean values
1017 @code{SCM_BOOL_T} or @code{SCM_BOOL_F} which are both true as far as C
1018 is concerned. Thus, always write @code{scm_is_true (scm_num_eq_p (x,
1019 y))} when testing the two Scheme numbers @code{x} and @code{y} for
1020 equality, for example.
1022 @c begin (texi-doc-string "guile" "=")
1023 @deffn {Scheme Procedure} =
1024 @deffnx {C Function} scm_num_eq_p (x, y)
1025 Return @code{#t} if all parameters are numerically equal.
1028 @c begin (texi-doc-string "guile" "<")
1029 @deffn {Scheme Procedure} <
1030 @deffnx {C Function} scm_less_p (x, y)
1031 Return @code{#t} if the list of parameters is monotonically
1035 @c begin (texi-doc-string "guile" ">")
1036 @deffn {Scheme Procedure} >
1037 @deffnx {C Function} scm_gr_p (x, y)
1038 Return @code{#t} if the list of parameters is monotonically
1042 @c begin (texi-doc-string "guile" "<=")
1043 @deffn {Scheme Procedure} <=
1044 @deffnx {C Function} scm_leq_p (x, y)
1045 Return @code{#t} if the list of parameters is monotonically
1049 @c begin (texi-doc-string "guile" ">=")
1050 @deffn {Scheme Procedure} >=
1051 @deffnx {C Function} scm_geq_p (x, y)
1052 Return @code{#t} if the list of parameters is monotonically
1056 @c begin (texi-doc-string "guile" "zero?")
1057 @deffn {Scheme Procedure} zero? z
1058 @deffnx {C Function} scm_zero_p (z)
1059 Return @code{#t} if @var{z} is an exact or inexact number equal to
1063 @c begin (texi-doc-string "guile" "positive?")
1064 @deffn {Scheme Procedure} positive? x
1065 @deffnx {C Function} scm_positive_p (x)
1066 Return @code{#t} if @var{x} is an exact or inexact number greater than
1070 @c begin (texi-doc-string "guile" "negative?")
1071 @deffn {Scheme Procedure} negative? x
1072 @deffnx {C Function} scm_negative_p (x)
1073 Return @code{#t} if @var{x} is an exact or inexact number less than
1079 @subsubsection Converting Numbers To and From Strings
1080 @rnindex number->string
1081 @rnindex string->number
1083 The following procedures read and write numbers according to their
1084 external representation as defined by R5RS (@pxref{Lexical structure,
1085 R5RS Lexical Structure,, r5rs, The Revised^5 Report on the Algorithmic
1086 Language Scheme}). @xref{Number Input and Output, the @code{(ice-9
1087 i18n)} module}, for locale-dependent number parsing.
1089 @deffn {Scheme Procedure} number->string n [radix]
1090 @deffnx {C Function} scm_number_to_string (n, radix)
1091 Return a string holding the external representation of the
1092 number @var{n} in the given @var{radix}. If @var{n} is
1093 inexact, a radix of 10 will be used.
1096 @deffn {Scheme Procedure} string->number string [radix]
1097 @deffnx {C Function} scm_string_to_number (string, radix)
1098 Return a number of the maximally precise representation
1099 expressed by the given @var{string}. @var{radix} must be an
1100 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
1101 is a default radix that may be overridden by an explicit radix
1102 prefix in @var{string} (e.g.@: "#o177"). If @var{radix} is not
1103 supplied, then the default radix is 10. If string is not a
1104 syntactically valid notation for a number, then
1105 @code{string->number} returns @code{#f}.
1108 @deftypefn {C Function} SCM scm_c_locale_stringn_to_number (const char *string, size_t len, unsigned radix)
1109 As per @code{string->number} above, but taking a C string, as pointer
1110 and length. The string characters should be in the current locale
1111 encoding (@code{locale} in the name refers only to that, there's no
1112 locale-dependent parsing).
1117 @subsubsection Complex Number Operations
1118 @rnindex make-rectangular
1125 @deffn {Scheme Procedure} make-rectangular real_part imaginary_part
1126 @deffnx {C Function} scm_make_rectangular (real_part, imaginary_part)
1127 Return a complex number constructed of the given @var{real-part} and @var{imaginary-part} parts.
1130 @deffn {Scheme Procedure} make-polar mag ang
1131 @deffnx {C Function} scm_make_polar (mag, ang)
1133 Return the complex number @var{mag} * e^(i * @var{ang}).
1136 @c begin (texi-doc-string "guile" "real-part")
1137 @deffn {Scheme Procedure} real-part z
1138 @deffnx {C Function} scm_real_part (z)
1139 Return the real part of the number @var{z}.
1142 @c begin (texi-doc-string "guile" "imag-part")
1143 @deffn {Scheme Procedure} imag-part z
1144 @deffnx {C Function} scm_imag_part (z)
1145 Return the imaginary part of the number @var{z}.
1148 @c begin (texi-doc-string "guile" "magnitude")
1149 @deffn {Scheme Procedure} magnitude z
1150 @deffnx {C Function} scm_magnitude (z)
1151 Return the magnitude of the number @var{z}. This is the same as
1152 @code{abs} for real arguments, but also allows complex numbers.
1155 @c begin (texi-doc-string "guile" "angle")
1156 @deffn {Scheme Procedure} angle z
1157 @deffnx {C Function} scm_angle (z)
1158 Return the angle of the complex number @var{z}.
1161 @deftypefn {C Function} SCM scm_c_make_rectangular (double re, double im)
1162 @deftypefnx {C Function} SCM scm_c_make_polar (double x, double y)
1163 Like @code{scm_make_rectangular} or @code{scm_make_polar},
1164 respectively, but these functions take @code{double}s as their
1168 @deftypefn {C Function} double scm_c_real_part (z)
1169 @deftypefnx {C Function} double scm_c_imag_part (z)
1170 Returns the real or imaginary part of @var{z} as a @code{double}.
1173 @deftypefn {C Function} double scm_c_magnitude (z)
1174 @deftypefnx {C Function} double scm_c_angle (z)
1175 Returns the magnitude or angle of @var{z} as a @code{double}.
1180 @subsubsection Arithmetic Functions
1195 @rnindex euclidean-quotient
1196 @rnindex euclidean-remainder
1198 @rnindex floor-quotient
1199 @rnindex floor-remainder
1201 @rnindex ceiling-quotient
1202 @rnindex ceiling-remainder
1204 @rnindex truncate-quotient
1205 @rnindex truncate-remainder
1207 @rnindex centered-quotient
1208 @rnindex centered-remainder
1210 @rnindex round-quotient
1211 @rnindex round-remainder
1213 The C arithmetic functions below always takes two arguments, while the
1214 Scheme functions can take an arbitrary number. When you need to
1215 invoke them with just one argument, for example to compute the
1216 equivalent of @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
1217 one: @code{scm_difference (x, SCM_UNDEFINED)}.
1219 @c begin (texi-doc-string "guile" "+")
1220 @deffn {Scheme Procedure} + z1 @dots{}
1221 @deffnx {C Function} scm_sum (z1, z2)
1222 Return the sum of all parameter values. Return 0 if called without any
1226 @c begin (texi-doc-string "guile" "-")
1227 @deffn {Scheme Procedure} - z1 z2 @dots{}
1228 @deffnx {C Function} scm_difference (z1, z2)
1229 If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
1230 the sum of all but the first argument are subtracted from the first
1234 @c begin (texi-doc-string "guile" "*")
1235 @deffn {Scheme Procedure} * z1 @dots{}
1236 @deffnx {C Function} scm_product (z1, z2)
1237 Return the product of all arguments. If called without arguments, 1 is
1241 @c begin (texi-doc-string "guile" "/")
1242 @deffn {Scheme Procedure} / z1 z2 @dots{}
1243 @deffnx {C Function} scm_divide (z1, z2)
1244 Divide the first argument by the product of the remaining arguments. If
1245 called with one argument @var{z1}, 1/@var{z1} is returned.
1248 @deffn {Scheme Procedure} 1+ z
1249 @deffnx {C Function} scm_oneplus (z)
1250 Return @math{@var{z} + 1}.
1253 @deffn {Scheme Procedure} 1- z
1254 @deffnx {C function} scm_oneminus (z)
1255 Return @math{@var{z} - 1}.
1258 @c begin (texi-doc-string "guile" "abs")
1259 @deffn {Scheme Procedure} abs x
1260 @deffnx {C Function} scm_abs (x)
1261 Return the absolute value of @var{x}.
1263 @var{x} must be a number with zero imaginary part. To calculate the
1264 magnitude of a complex number, use @code{magnitude} instead.
1267 @c begin (texi-doc-string "guile" "max")
1268 @deffn {Scheme Procedure} max x1 x2 @dots{}
1269 @deffnx {C Function} scm_max (x1, x2)
1270 Return the maximum of all parameter values.
1273 @c begin (texi-doc-string "guile" "min")
1274 @deffn {Scheme Procedure} min x1 x2 @dots{}
1275 @deffnx {C Function} scm_min (x1, x2)
1276 Return the minimum of all parameter values.
1279 @c begin (texi-doc-string "guile" "truncate")
1280 @deffn {Scheme Procedure} truncate x
1281 @deffnx {C Function} scm_truncate_number (x)
1282 Round the inexact number @var{x} towards zero.
1285 @c begin (texi-doc-string "guile" "round")
1286 @deffn {Scheme Procedure} round x
1287 @deffnx {C Function} scm_round_number (x)
1288 Round the inexact number @var{x} to the nearest integer. When exactly
1289 halfway between two integers, round to the even one.
1292 @c begin (texi-doc-string "guile" "floor")
1293 @deffn {Scheme Procedure} floor x
1294 @deffnx {C Function} scm_floor (x)
1295 Round the number @var{x} towards minus infinity.
1298 @c begin (texi-doc-string "guile" "ceiling")
1299 @deffn {Scheme Procedure} ceiling x
1300 @deffnx {C Function} scm_ceiling (x)
1301 Round the number @var{x} towards infinity.
1304 @deftypefn {C Function} double scm_c_truncate (double x)
1305 @deftypefnx {C Function} double scm_c_round (double x)
1306 Like @code{scm_truncate_number} or @code{scm_round_number},
1307 respectively, but these functions take and return @code{double}
1311 @deftypefn {Scheme Procedure} {} euclidean/ @var{x} @var{y}
1312 @deftypefnx {Scheme Procedure} {} euclidean-quotient @var{x} @var{y}
1313 @deftypefnx {Scheme Procedure} {} euclidean-remainder @var{x} @var{y}
1314 @deftypefnx {C Function} void scm_euclidean_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1315 @deftypefnx {C Function} SCM scm_euclidean_quotient (SCM @var{x}, SCM @var{y})
1316 @deftypefnx {C Function} SCM scm_euclidean_remainder (SCM @var{x}, SCM @var{y})
1317 These procedures accept two real numbers @var{x} and @var{y}, where the
1318 divisor @var{y} must be non-zero. @code{euclidean-quotient} returns the
1319 integer @var{q} and @code{euclidean-remainder} returns the real number
1320 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
1321 @math{0 <= @var{r} < |@var{y}|}. @code{euclidean/} returns both @var{q} and
1322 @var{r}, and is more efficient than computing each separately. Note
1323 that when @math{@var{y} > 0}, @code{euclidean-quotient} returns
1324 @math{floor(@var{x}/@var{y})}, otherwise it returns
1325 @math{ceiling(@var{x}/@var{y})}.
1327 Note that these operators are equivalent to the R6RS operators
1328 @code{div}, @code{mod}, and @code{div-and-mod}.
1331 (euclidean-quotient 123 10) @result{} 12
1332 (euclidean-remainder 123 10) @result{} 3
1333 (euclidean/ 123 10) @result{} 12 and 3
1334 (euclidean/ 123 -10) @result{} -12 and 3
1335 (euclidean/ -123 10) @result{} -13 and 7
1336 (euclidean/ -123 -10) @result{} 13 and 7
1337 (euclidean/ -123.2 -63.5) @result{} 2.0 and 3.8
1338 (euclidean/ 16/3 -10/7) @result{} -3 and 22/21
1342 @deftypefn {Scheme Procedure} {} floor/ @var{x} @var{y}
1343 @deftypefnx {Scheme Procedure} {} floor-quotient @var{x} @var{y}
1344 @deftypefnx {Scheme Procedure} {} floor-remainder @var{x} @var{y}
1345 @deftypefnx {C Function} void scm_floor_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1346 @deftypefnx {C Function} SCM scm_floor_quotient (@var{x}, @var{y})
1347 @deftypefnx {C Function} SCM scm_floor_remainder (@var{x}, @var{y})
1348 These procedures accept two real numbers @var{x} and @var{y}, where the
1349 divisor @var{y} must be non-zero. @code{floor-quotient} returns the
1350 integer @var{q} and @code{floor-remainder} returns the real number
1351 @var{r} such that @math{@var{q} = floor(@var{x}/@var{y})} and
1352 @math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{floor/} returns
1353 both @var{q} and @var{r}, and is more efficient than computing each
1354 separately. Note that @var{r}, if non-zero, will have the same sign
1357 When @var{x} and @var{y} are integers, @code{floor-remainder} is
1358 equivalent to the R5RS integer-only operator @code{modulo}.
1361 (floor-quotient 123 10) @result{} 12
1362 (floor-remainder 123 10) @result{} 3
1363 (floor/ 123 10) @result{} 12 and 3
1364 (floor/ 123 -10) @result{} -13 and -7
1365 (floor/ -123 10) @result{} -13 and 7
1366 (floor/ -123 -10) @result{} 12 and -3
1367 (floor/ -123.2 -63.5) @result{} 1.0 and -59.7
1368 (floor/ 16/3 -10/7) @result{} -4 and -8/21
1372 @deftypefn {Scheme Procedure} {} ceiling/ @var{x} @var{y}
1373 @deftypefnx {Scheme Procedure} {} ceiling-quotient @var{x} @var{y}
1374 @deftypefnx {Scheme Procedure} {} ceiling-remainder @var{x} @var{y}
1375 @deftypefnx {C Function} void scm_ceiling_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1376 @deftypefnx {C Function} SCM scm_ceiling_quotient (@var{x}, @var{y})
1377 @deftypefnx {C Function} SCM scm_ceiling_remainder (@var{x}, @var{y})
1378 These procedures accept two real numbers @var{x} and @var{y}, where the
1379 divisor @var{y} must be non-zero. @code{ceiling-quotient} returns the
1380 integer @var{q} and @code{ceiling-remainder} returns the real number
1381 @var{r} such that @math{@var{q} = ceiling(@var{x}/@var{y})} and
1382 @math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{ceiling/} returns
1383 both @var{q} and @var{r}, and is more efficient than computing each
1384 separately. Note that @var{r}, if non-zero, will have the opposite sign
1388 (ceiling-quotient 123 10) @result{} 13
1389 (ceiling-remainder 123 10) @result{} -7
1390 (ceiling/ 123 10) @result{} 13 and -7
1391 (ceiling/ 123 -10) @result{} -12 and 3
1392 (ceiling/ -123 10) @result{} -12 and -3
1393 (ceiling/ -123 -10) @result{} 13 and 7
1394 (ceiling/ -123.2 -63.5) @result{} 2.0 and 3.8
1395 (ceiling/ 16/3 -10/7) @result{} -3 and 22/21
1399 @deftypefn {Scheme Procedure} {} truncate/ @var{x} @var{y}
1400 @deftypefnx {Scheme Procedure} {} truncate-quotient @var{x} @var{y}
1401 @deftypefnx {Scheme Procedure} {} truncate-remainder @var{x} @var{y}
1402 @deftypefnx {C Function} void scm_truncate_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1403 @deftypefnx {C Function} SCM scm_truncate_quotient (@var{x}, @var{y})
1404 @deftypefnx {C Function} SCM scm_truncate_remainder (@var{x}, @var{y})
1405 These procedures accept two real numbers @var{x} and @var{y}, where the
1406 divisor @var{y} must be non-zero. @code{truncate-quotient} returns the
1407 integer @var{q} and @code{truncate-remainder} returns the real number
1408 @var{r} such that @var{q} is @math{@var{x}/@var{y}} rounded toward zero,
1409 and @math{@var{x} = @var{q}*@var{y} + @var{r}}. @code{truncate/} returns
1410 both @var{q} and @var{r}, and is more efficient than computing each
1411 separately. Note that @var{r}, if non-zero, will have the same sign
1414 When @var{x} and @var{y} are integers, these operators are
1415 equivalent to the R5RS integer-only operators @code{quotient} and
1419 (truncate-quotient 123 10) @result{} 12
1420 (truncate-remainder 123 10) @result{} 3
1421 (truncate/ 123 10) @result{} 12 and 3
1422 (truncate/ 123 -10) @result{} -12 and 3
1423 (truncate/ -123 10) @result{} -12 and -3
1424 (truncate/ -123 -10) @result{} 12 and -3
1425 (truncate/ -123.2 -63.5) @result{} 1.0 and -59.7
1426 (truncate/ 16/3 -10/7) @result{} -3 and 22/21
1430 @deftypefn {Scheme Procedure} {} centered/ @var{x} @var{y}
1431 @deftypefnx {Scheme Procedure} {} centered-quotient @var{x} @var{y}
1432 @deftypefnx {Scheme Procedure} {} centered-remainder @var{x} @var{y}
1433 @deftypefnx {C Function} void scm_centered_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1434 @deftypefnx {C Function} SCM scm_centered_quotient (SCM @var{x}, SCM @var{y})
1435 @deftypefnx {C Function} SCM scm_centered_remainder (SCM @var{x}, SCM @var{y})
1436 These procedures accept two real numbers @var{x} and @var{y}, where the
1437 divisor @var{y} must be non-zero. @code{centered-quotient} returns the
1438 integer @var{q} and @code{centered-remainder} returns the real number
1439 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
1440 @math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}. @code{centered/}
1441 returns both @var{q} and @var{r}, and is more efficient than computing
1444 Note that @code{centered-quotient} returns @math{@var{x}/@var{y}}
1445 rounded to the nearest integer. When @math{@var{x}/@var{y}} lies
1446 exactly half-way between two integers, the tie is broken according to
1447 the sign of @var{y}. If @math{@var{y} > 0}, ties are rounded toward
1448 positive infinity, otherwise they are rounded toward negative infinity.
1449 This is a consequence of the requirement that
1450 @math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}.
1452 Note that these operators are equivalent to the R6RS operators
1453 @code{div0}, @code{mod0}, and @code{div0-and-mod0}.
1456 (centered-quotient 123 10) @result{} 12
1457 (centered-remainder 123 10) @result{} 3
1458 (centered/ 123 10) @result{} 12 and 3
1459 (centered/ 123 -10) @result{} -12 and 3
1460 (centered/ -123 10) @result{} -12 and -3
1461 (centered/ -123 -10) @result{} 12 and -3
1462 (centered/ 125 10) @result{} 13 and -5
1463 (centered/ 127 10) @result{} 13 and -3
1464 (centered/ 135 10) @result{} 14 and -5
1465 (centered/ -123.2 -63.5) @result{} 2.0 and 3.8
1466 (centered/ 16/3 -10/7) @result{} -4 and -8/21
1470 @deftypefn {Scheme Procedure} {} round/ @var{x} @var{y}
1471 @deftypefnx {Scheme Procedure} {} round-quotient @var{x} @var{y}
1472 @deftypefnx {Scheme Procedure} {} round-remainder @var{x} @var{y}
1473 @deftypefnx {C Function} void scm_round_divide (SCM @var{x}, SCM @var{y}, SCM *@var{q}, SCM *@var{r})
1474 @deftypefnx {C Function} SCM scm_round_quotient (@var{x}, @var{y})
1475 @deftypefnx {C Function} SCM scm_round_remainder (@var{x}, @var{y})
1476 These procedures accept two real numbers @var{x} and @var{y}, where the
1477 divisor @var{y} must be non-zero. @code{round-quotient} returns the
1478 integer @var{q} and @code{round-remainder} returns the real number
1479 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
1480 @var{q} is @math{@var{x}/@var{y}} rounded to the nearest integer,
1481 with ties going to the nearest even integer. @code{round/}
1482 returns both @var{q} and @var{r}, and is more efficient than computing
1485 Note that @code{round/} and @code{centered/} are almost equivalent, but
1486 their behavior differs when @math{@var{x}/@var{y}} lies exactly half-way
1487 between two integers. In this case, @code{round/} chooses the nearest
1488 even integer, whereas @code{centered/} chooses in such a way to satisfy
1489 the constraint @math{-|@var{y}/2| <= @var{r} < |@var{y}/2|}, which
1490 is stronger than the corresponding constraint for @code{round/},
1491 @math{-|@var{y}/2| <= @var{r} <= |@var{y}/2|}. In particular,
1492 when @var{x} and @var{y} are integers, the number of possible remainders
1493 returned by @code{centered/} is @math{|@var{y}|}, whereas the number of
1494 possible remainders returned by @code{round/} is @math{|@var{y}|+1} when
1498 (round-quotient 123 10) @result{} 12
1499 (round-remainder 123 10) @result{} 3
1500 (round/ 123 10) @result{} 12 and 3
1501 (round/ 123 -10) @result{} -12 and 3
1502 (round/ -123 10) @result{} -12 and -3
1503 (round/ -123 -10) @result{} 12 and -3
1504 (round/ 125 10) @result{} 12 and 5
1505 (round/ 127 10) @result{} 13 and -3
1506 (round/ 135 10) @result{} 14 and -5
1507 (round/ -123.2 -63.5) @result{} 2.0 and 3.8
1508 (round/ 16/3 -10/7) @result{} -4 and -8/21
1513 @subsubsection Scientific Functions
1515 The following procedures accept any kind of number as arguments,
1516 including complex numbers.
1519 @c begin (texi-doc-string "guile" "sqrt")
1520 @deffn {Scheme Procedure} sqrt z
1521 Return the square root of @var{z}. Of the two possible roots
1522 (positive and negative), the one with a positive real part is
1523 returned, or if that's zero then a positive imaginary part. Thus,
1526 (sqrt 9.0) @result{} 3.0
1527 (sqrt -9.0) @result{} 0.0+3.0i
1528 (sqrt 1.0+1.0i) @result{} 1.09868411346781+0.455089860562227i
1529 (sqrt -1.0-1.0i) @result{} 0.455089860562227-1.09868411346781i
1534 @c begin (texi-doc-string "guile" "expt")
1535 @deffn {Scheme Procedure} expt z1 z2
1536 Return @var{z1} raised to the power of @var{z2}.
1540 @c begin (texi-doc-string "guile" "sin")
1541 @deffn {Scheme Procedure} sin z
1542 Return the sine of @var{z}.
1546 @c begin (texi-doc-string "guile" "cos")
1547 @deffn {Scheme Procedure} cos z
1548 Return the cosine of @var{z}.
1552 @c begin (texi-doc-string "guile" "tan")
1553 @deffn {Scheme Procedure} tan z
1554 Return the tangent of @var{z}.
1558 @c begin (texi-doc-string "guile" "asin")
1559 @deffn {Scheme Procedure} asin z
1560 Return the arcsine of @var{z}.
1564 @c begin (texi-doc-string "guile" "acos")
1565 @deffn {Scheme Procedure} acos z
1566 Return the arccosine of @var{z}.
1570 @c begin (texi-doc-string "guile" "atan")
1571 @deffn {Scheme Procedure} atan z
1572 @deffnx {Scheme Procedure} atan y x
1573 Return the arctangent of @var{z}, or of @math{@var{y}/@var{x}}.
1577 @c begin (texi-doc-string "guile" "exp")
1578 @deffn {Scheme Procedure} exp z
1579 Return e to the power of @var{z}, where e is the base of natural
1580 logarithms (2.71828@dots{}).
1584 @c begin (texi-doc-string "guile" "log")
1585 @deffn {Scheme Procedure} log z
1586 Return the natural logarithm of @var{z}.
1589 @c begin (texi-doc-string "guile" "log10")
1590 @deffn {Scheme Procedure} log10 z
1591 Return the base 10 logarithm of @var{z}.
1594 @c begin (texi-doc-string "guile" "sinh")
1595 @deffn {Scheme Procedure} sinh z
1596 Return the hyperbolic sine of @var{z}.
1599 @c begin (texi-doc-string "guile" "cosh")
1600 @deffn {Scheme Procedure} cosh z
1601 Return the hyperbolic cosine of @var{z}.
1604 @c begin (texi-doc-string "guile" "tanh")
1605 @deffn {Scheme Procedure} tanh z
1606 Return the hyperbolic tangent of @var{z}.
1609 @c begin (texi-doc-string "guile" "asinh")
1610 @deffn {Scheme Procedure} asinh z
1611 Return the hyperbolic arcsine of @var{z}.
1614 @c begin (texi-doc-string "guile" "acosh")
1615 @deffn {Scheme Procedure} acosh z
1616 Return the hyperbolic arccosine of @var{z}.
1619 @c begin (texi-doc-string "guile" "atanh")
1620 @deffn {Scheme Procedure} atanh z
1621 Return the hyperbolic arctangent of @var{z}.
1625 @node Bitwise Operations
1626 @subsubsection Bitwise Operations
1628 For the following bitwise functions, negative numbers are treated as
1629 infinite precision twos-complements. For instance @math{-6} is bits
1630 @math{@dots{}111010}, with infinitely many ones on the left. It can
1631 be seen that adding 6 (binary 110) to such a bit pattern gives all
1634 @deffn {Scheme Procedure} logand n1 n2 @dots{}
1635 @deffnx {C Function} scm_logand (n1, n2)
1636 Return the bitwise @sc{and} of the integer arguments.
1639 (logand) @result{} -1
1640 (logand 7) @result{} 7
1641 (logand #b111 #b011 #b001) @result{} 1
1645 @deffn {Scheme Procedure} logior n1 n2 @dots{}
1646 @deffnx {C Function} scm_logior (n1, n2)
1647 Return the bitwise @sc{or} of the integer arguments.
1650 (logior) @result{} 0
1651 (logior 7) @result{} 7
1652 (logior #b000 #b001 #b011) @result{} 3
1656 @deffn {Scheme Procedure} logxor n1 n2 @dots{}
1657 @deffnx {C Function} scm_loxor (n1, n2)
1658 Return the bitwise @sc{xor} of the integer arguments. A bit is
1659 set in the result if it is set in an odd number of arguments.
1662 (logxor) @result{} 0
1663 (logxor 7) @result{} 7
1664 (logxor #b000 #b001 #b011) @result{} 2
1665 (logxor #b000 #b001 #b011 #b011) @result{} 1
1669 @deffn {Scheme Procedure} lognot n
1670 @deffnx {C Function} scm_lognot (n)
1671 Return the integer which is the ones-complement of the integer
1672 argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
1675 (number->string (lognot #b10000000) 2)
1676 @result{} "-10000001"
1677 (number->string (lognot #b0) 2)
1682 @deffn {Scheme Procedure} logtest j k
1683 @deffnx {C Function} scm_logtest (j, k)
1684 Test whether @var{j} and @var{k} have any 1 bits in common. This is
1685 equivalent to @code{(not (zero? (logand j k)))}, but without actually
1686 calculating the @code{logand}, just testing for non-zero.
1689 (logtest #b0100 #b1011) @result{} #f
1690 (logtest #b0100 #b0111) @result{} #t
1694 @deffn {Scheme Procedure} logbit? index j
1695 @deffnx {C Function} scm_logbit_p (index, j)
1696 Test whether bit number @var{index} in @var{j} is set. @var{index}
1697 starts from 0 for the least significant bit.
1700 (logbit? 0 #b1101) @result{} #t
1701 (logbit? 1 #b1101) @result{} #f
1702 (logbit? 2 #b1101) @result{} #t
1703 (logbit? 3 #b1101) @result{} #t
1704 (logbit? 4 #b1101) @result{} #f
1708 @deffn {Scheme Procedure} ash n count
1709 @deffnx {C Function} scm_ash (n, count)
1710 Return @math{floor(n * 2^count)}.
1711 @var{n} and @var{count} must be exact integers.
1713 With @var{n} viewed as an infinite-precision twos-complement
1714 integer, @code{ash} means a left shift introducing zero bits
1715 when @var{count} is positive, or a right shift dropping bits
1716 when @var{count} is negative. This is an ``arithmetic'' shift.
1719 (number->string (ash #b1 3) 2) @result{} "1000"
1720 (number->string (ash #b1010 -1) 2) @result{} "101"
1722 ;; -23 is bits ...11101001, -6 is bits ...111010
1723 (ash -23 -2) @result{} -6
1727 @deffn {Scheme Procedure} round-ash n count
1728 @deffnx {C Function} scm_round_ash (n, count)
1729 Return @math{round(n * 2^count)}.
1730 @var{n} and @var{count} must be exact integers.
1732 With @var{n} viewed as an infinite-precision twos-complement
1733 integer, @code{round-ash} means a left shift introducing zero
1734 bits when @var{count} is positive, or a right shift rounding
1735 to the nearest integer (with ties going to the nearest even
1736 integer) when @var{count} is negative. This is a rounded
1737 ``arithmetic'' shift.
1740 (number->string (round-ash #b1 3) 2) @result{} \"1000\"
1741 (number->string (round-ash #b1010 -1) 2) @result{} \"101\"
1742 (number->string (round-ash #b1010 -2) 2) @result{} \"10\"
1743 (number->string (round-ash #b1011 -2) 2) @result{} \"11\"
1744 (number->string (round-ash #b1101 -2) 2) @result{} \"11\"
1745 (number->string (round-ash #b1110 -2) 2) @result{} \"100\"
1749 @deffn {Scheme Procedure} logcount n
1750 @deffnx {C Function} scm_logcount (n)
1751 Return the number of bits in integer @var{n}. If @var{n} is
1752 positive, the 1-bits in its binary representation are counted.
1753 If negative, the 0-bits in its two's-complement binary
1754 representation are counted. If zero, 0 is returned.
1757 (logcount #b10101010)
1766 @deffn {Scheme Procedure} integer-length n
1767 @deffnx {C Function} scm_integer_length (n)
1768 Return the number of bits necessary to represent @var{n}.
1770 For positive @var{n} this is how many bits to the most significant one
1771 bit. For negative @var{n} it's how many bits to the most significant
1772 zero bit in twos complement form.
1775 (integer-length #b10101010) @result{} 8
1776 (integer-length #b1111) @result{} 4
1777 (integer-length 0) @result{} 0
1778 (integer-length -1) @result{} 0
1779 (integer-length -256) @result{} 8
1780 (integer-length -257) @result{} 9
1784 @deffn {Scheme Procedure} integer-expt n k
1785 @deffnx {C Function} scm_integer_expt (n, k)
1786 Return @var{n} raised to the power @var{k}. @var{k} must be an exact
1787 integer, @var{n} can be any number.
1789 Negative @var{k} is supported, and results in @m{1/n^|k|, 1/n^abs(k)}
1790 in the usual way. @math{@var{n}^0} is 1, as usual, and that includes
1794 (integer-expt 2 5) @result{} 32
1795 (integer-expt -3 3) @result{} -27
1796 (integer-expt 5 -3) @result{} 1/125
1797 (integer-expt 0 0) @result{} 1
1801 @deffn {Scheme Procedure} bit-extract n start end
1802 @deffnx {C Function} scm_bit_extract (n, start, end)
1803 Return the integer composed of the @var{start} (inclusive)
1804 through @var{end} (exclusive) bits of @var{n}. The
1805 @var{start}th bit becomes the 0-th bit in the result.
1808 (number->string (bit-extract #b1101101010 0 4) 2)
1810 (number->string (bit-extract #b1101101010 4 9) 2)
1817 @subsubsection Random Number Generation
1819 Pseudo-random numbers are generated from a random state object, which
1820 can be created with @code{seed->random-state} or
1821 @code{datum->random-state}. An external representation (i.e.@: one
1822 which can written with @code{write} and read with @code{read}) of a
1823 random state object can be obtained via
1824 @code{random-state->datum}. The @var{state} parameter to the
1825 various functions below is optional, it defaults to the state object
1826 in the @code{*random-state*} variable.
1828 @deffn {Scheme Procedure} copy-random-state [state]
1829 @deffnx {C Function} scm_copy_random_state (state)
1830 Return a copy of the random state @var{state}.
1833 @deffn {Scheme Procedure} random n [state]
1834 @deffnx {C Function} scm_random (n, state)
1835 Return a number in [0, @var{n}).
1837 Accepts a positive integer or real n and returns a
1838 number of the same type between zero (inclusive) and
1839 @var{n} (exclusive). The values returned have a uniform
1843 @deffn {Scheme Procedure} random:exp [state]
1844 @deffnx {C Function} scm_random_exp (state)
1845 Return an inexact real in an exponential distribution with mean
1846 1. For an exponential distribution with mean @var{u} use @code{(*
1847 @var{u} (random:exp))}.
1850 @deffn {Scheme Procedure} random:hollow-sphere! vect [state]
1851 @deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
1852 Fills @var{vect} with inexact real random numbers the sum of whose
1853 squares is equal to 1.0. Thinking of @var{vect} as coordinates in
1854 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1855 the coordinates are uniformly distributed over the surface of the unit
1859 @deffn {Scheme Procedure} random:normal [state]
1860 @deffnx {C Function} scm_random_normal (state)
1861 Return an inexact real in a normal distribution. The distribution
1862 used has mean 0 and standard deviation 1. For a normal distribution
1863 with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
1864 (* @var{d} (random:normal)))}.
1867 @deffn {Scheme Procedure} random:normal-vector! vect [state]
1868 @deffnx {C Function} scm_random_normal_vector_x (vect, state)
1869 Fills @var{vect} with inexact real random numbers that are
1870 independent and standard normally distributed
1871 (i.e., with mean 0 and variance 1).
1874 @deffn {Scheme Procedure} random:solid-sphere! vect [state]
1875 @deffnx {C Function} scm_random_solid_sphere_x (vect, state)
1876 Fills @var{vect} with inexact real random numbers the sum of whose
1877 squares is less than 1.0. Thinking of @var{vect} as coordinates in
1878 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1879 the coordinates are uniformly distributed within the unit
1881 @c FIXME: What does this mean, particularly the n-sphere part?
1884 @deffn {Scheme Procedure} random:uniform [state]
1885 @deffnx {C Function} scm_random_uniform (state)
1886 Return a uniformly distributed inexact real random number in
1890 @deffn {Scheme Procedure} seed->random-state seed
1891 @deffnx {C Function} scm_seed_to_random_state (seed)
1892 Return a new random state using @var{seed}.
1895 @deffn {Scheme Procedure} datum->random-state datum
1896 @deffnx {C Function} scm_datum_to_random_state (datum)
1897 Return a new random state from @var{datum}, which should have been
1898 obtained by @code{random-state->datum}.
1901 @deffn {Scheme Procedure} random-state->datum state
1902 @deffnx {C Function} scm_random_state_to_datum (state)
1903 Return a datum representation of @var{state} that may be written out and
1904 read back with the Scheme reader.
1907 @deffn {Scheme Procedure} random-state-from-platform
1908 @deffnx {C Function} scm_random_state_from_platform ()
1909 Construct a new random state seeded from a platform-specific source of
1910 entropy, appropriate for use in non-security-critical applications.
1911 Currently @file{/dev/urandom} is tried first, or else the seed is based
1912 on the time, date, process ID, an address from a freshly allocated heap
1913 cell, an address from the local stack frame, and a high-resolution timer
1917 @defvar *random-state*
1918 The global random state used by the above functions when the
1919 @var{state} parameter is not given.
1922 Note that the initial value of @code{*random-state*} is the same every
1923 time Guile starts up. Therefore, if you don't pass a @var{state}
1924 parameter to the above procedures, and you don't set
1925 @code{*random-state*} to @code{(seed->random-state your-seed)}, where
1926 @code{your-seed} is something that @emph{isn't} the same every time,
1927 you'll get the same sequence of ``random'' numbers on every run.
1929 For example, unless the relevant source code has changed, @code{(map
1930 random (cdr (iota 30)))}, if the first use of random numbers since
1931 Guile started up, will always give:
1934 (map random (cdr (iota 19)))
1936 (0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12)
1939 To seed the random state in a sensible way for non-security-critical
1940 applications, do this during initialization of your program:
1943 (set! *random-state* (random-state-from-platform))
1948 @subsection Characters
1951 In Scheme, there is a data type to describe a single character.
1953 Defining what exactly a character @emph{is} can be more complicated
1954 than it seems. Guile follows the advice of R6RS and uses The Unicode
1955 Standard to help define what a character is. So, for Guile, a
1956 character is anything in the Unicode Character Database.
1959 @cindex Unicode code point
1961 The Unicode Character Database is basically a table of characters
1962 indexed using integers called 'code points'. Valid code points are in
1963 the ranges 0 to @code{#xD7FF} inclusive or @code{#xE000} to
1964 @code{#x10FFFF} inclusive, which is about 1.1 million code points.
1966 @cindex designated code point
1967 @cindex code point, designated
1969 Any code point that has been assigned to a character or that has
1970 otherwise been given a meaning by Unicode is called a 'designated code
1971 point'. Most of the designated code points, about 200,000 of them,
1972 indicate characters, accents or other combining marks that modify
1973 other characters, symbols, whitespace, and control characters. Some
1974 are not characters but indicators that suggest how to format or
1975 display neighboring characters.
1977 @cindex reserved code point
1978 @cindex code point, reserved
1980 If a code point is not a designated code point -- if it has not been
1981 assigned to a character by The Unicode Standard -- it is a 'reserved
1982 code point', meaning that they are reserved for future use. Most of
1983 the code points, about 800,000, are 'reserved code points'.
1985 By convention, a Unicode code point is written as
1986 ``U+XXXX'' where ``XXXX'' is a hexadecimal number. Please note that
1987 this convenient notation is not valid code. Guile does not interpret
1988 ``U+XXXX'' as a character.
1990 In Scheme, a character literal is written as @code{#\@var{name}} where
1991 @var{name} is the name of the character that you want. Printable
1992 characters have their usual single character name; for example,
1993 @code{#\a} is a lower case @code{a}.
1995 Some of the code points are 'combining characters' that are not meant
1996 to be printed by themselves but are instead meant to modify the
1997 appearance of the previous character. For combining characters, an
1998 alternate form of the character literal is @code{#\} followed by
1999 U+25CC (a small, dotted circle), followed by the combining character.
2000 This allows the combining character to be drawn on the circle, not on
2001 the backslash of @code{#\}.
2003 Many of the non-printing characters, such as whitespace characters and
2004 control characters, also have names.
2006 The most commonly used non-printing characters have long character
2007 names, described in the table below.
2009 @multitable {@code{#\backspace}} {Preferred}
2010 @item Character Name @tab Codepoint
2011 @item @code{#\nul} @tab U+0000
2012 @item @code{#\alarm} @tab u+0007
2013 @item @code{#\backspace} @tab U+0008
2014 @item @code{#\tab} @tab U+0009
2015 @item @code{#\linefeed} @tab U+000A
2016 @item @code{#\newline} @tab U+000A
2017 @item @code{#\vtab} @tab U+000B
2018 @item @code{#\page} @tab U+000C
2019 @item @code{#\return} @tab U+000D
2020 @item @code{#\esc} @tab U+001B
2021 @item @code{#\space} @tab U+0020
2022 @item @code{#\delete} @tab U+007F
2025 There are also short names for all of the ``C0 control characters''
2026 (those with code points below 32). The following table lists the short
2027 name for each character.
2029 @multitable @columnfractions .25 .25 .25 .25
2030 @item 0 = @code{#\nul}
2031 @tab 1 = @code{#\soh}
2032 @tab 2 = @code{#\stx}
2033 @tab 3 = @code{#\etx}
2034 @item 4 = @code{#\eot}
2035 @tab 5 = @code{#\enq}
2036 @tab 6 = @code{#\ack}
2037 @tab 7 = @code{#\bel}
2038 @item 8 = @code{#\bs}
2039 @tab 9 = @code{#\ht}
2040 @tab 10 = @code{#\lf}
2041 @tab 11 = @code{#\vt}
2042 @item 12 = @code{#\ff}
2043 @tab 13 = @code{#\cr}
2044 @tab 14 = @code{#\so}
2045 @tab 15 = @code{#\si}
2046 @item 16 = @code{#\dle}
2047 @tab 17 = @code{#\dc1}
2048 @tab 18 = @code{#\dc2}
2049 @tab 19 = @code{#\dc3}
2050 @item 20 = @code{#\dc4}
2051 @tab 21 = @code{#\nak}
2052 @tab 22 = @code{#\syn}
2053 @tab 23 = @code{#\etb}
2054 @item 24 = @code{#\can}
2055 @tab 25 = @code{#\em}
2056 @tab 26 = @code{#\sub}
2057 @tab 27 = @code{#\esc}
2058 @item 28 = @code{#\fs}
2059 @tab 29 = @code{#\gs}
2060 @tab 30 = @code{#\rs}
2061 @tab 31 = @code{#\us}
2062 @item 32 = @code{#\sp}
2065 The short name for the ``delete'' character (code point U+007F) is
2068 There are also a few alternative names left over for compatibility with
2069 previous versions of Guile.
2071 @multitable {@code{#\backspace}} {Preferred}
2072 @item Alternate @tab Standard
2073 @item @code{#\nl} @tab @code{#\newline}
2074 @item @code{#\np} @tab @code{#\page}
2075 @item @code{#\null} @tab @code{#\nul}
2078 Characters may also be written using their code point values. They can
2079 be written with as an octal number, such as @code{#\10} for
2080 @code{#\bs} or @code{#\177} for @code{#\del}.
2082 If one prefers hex to octal, there is an additional syntax for character
2083 escapes: @code{#\xHHHH} -- the letter 'x' followed by a hexadecimal
2084 number of one to eight digits.
2087 @deffn {Scheme Procedure} char? x
2088 @deffnx {C Function} scm_char_p (x)
2089 Return @code{#t} if @var{x} is a character, else @code{#f}.
2092 Fundamentally, the character comparison operations below are
2093 numeric comparisons of the character's code points.
2096 @deffn {Scheme Procedure} char=? x y
2097 Return @code{#t} if code point of @var{x} is equal to the code point
2098 of @var{y}, else @code{#f}.
2102 @deffn {Scheme Procedure} char<? x y
2103 Return @code{#t} if the code point of @var{x} is less than the code
2104 point of @var{y}, else @code{#f}.
2108 @deffn {Scheme Procedure} char<=? x y
2109 Return @code{#t} if the code point of @var{x} is less than or equal
2110 to the code point of @var{y}, else @code{#f}.
2114 @deffn {Scheme Procedure} char>? x y
2115 Return @code{#t} if the code point of @var{x} is greater than the
2116 code point of @var{y}, else @code{#f}.
2120 @deffn {Scheme Procedure} char>=? x y
2121 Return @code{#t} if the code point of @var{x} is greater than or
2122 equal to the code point of @var{y}, else @code{#f}.
2125 @cindex case folding
2127 Case-insensitive character comparisons use @emph{Unicode case
2128 folding}. In case folding comparisons, if a character is lowercase
2129 and has an uppercase form that can be expressed as a single character,
2130 it is converted to uppercase before comparison. All other characters
2131 undergo no conversion before the comparison occurs. This includes the
2132 German sharp S (Eszett) which is not uppercased before conversion
2133 because its uppercase form has two characters. Unicode case folding
2134 is language independent: it uses rules that are generally true, but,
2135 it cannot cover all cases for all languages.
2138 @deffn {Scheme Procedure} char-ci=? x y
2139 Return @code{#t} if the case-folded code point of @var{x} is the same
2140 as the case-folded code point of @var{y}, else @code{#f}.
2144 @deffn {Scheme Procedure} char-ci<? x y
2145 Return @code{#t} if the case-folded code point of @var{x} is less
2146 than the case-folded code point of @var{y}, else @code{#f}.
2150 @deffn {Scheme Procedure} char-ci<=? x y
2151 Return @code{#t} if the case-folded code point of @var{x} is less
2152 than or equal to the case-folded code point of @var{y}, else
2157 @deffn {Scheme Procedure} char-ci>? x y
2158 Return @code{#t} if the case-folded code point of @var{x} is greater
2159 than the case-folded code point of @var{y}, else @code{#f}.
2163 @deffn {Scheme Procedure} char-ci>=? x y
2164 Return @code{#t} if the case-folded code point of @var{x} is greater
2165 than or equal to the case-folded code point of @var{y}, else
2169 @rnindex char-alphabetic?
2170 @deffn {Scheme Procedure} char-alphabetic? chr
2171 @deffnx {C Function} scm_char_alphabetic_p (chr)
2172 Return @code{#t} if @var{chr} is alphabetic, else @code{#f}.
2175 @rnindex char-numeric?
2176 @deffn {Scheme Procedure} char-numeric? chr
2177 @deffnx {C Function} scm_char_numeric_p (chr)
2178 Return @code{#t} if @var{chr} is numeric, else @code{#f}.
2181 @rnindex char-whitespace?
2182 @deffn {Scheme Procedure} char-whitespace? chr
2183 @deffnx {C Function} scm_char_whitespace_p (chr)
2184 Return @code{#t} if @var{chr} is whitespace, else @code{#f}.
2187 @rnindex char-upper-case?
2188 @deffn {Scheme Procedure} char-upper-case? chr
2189 @deffnx {C Function} scm_char_upper_case_p (chr)
2190 Return @code{#t} if @var{chr} is uppercase, else @code{#f}.
2193 @rnindex char-lower-case?
2194 @deffn {Scheme Procedure} char-lower-case? chr
2195 @deffnx {C Function} scm_char_lower_case_p (chr)
2196 Return @code{#t} if @var{chr} is lowercase, else @code{#f}.
2199 @deffn {Scheme Procedure} char-is-both? chr
2200 @deffnx {C Function} scm_char_is_both_p (chr)
2201 Return @code{#t} if @var{chr} is either uppercase or lowercase, else
2205 @deffn {Scheme Procedure} char-general-category chr
2206 @deffnx {C Function} scm_char_general_category (chr)
2207 Return a symbol giving the two-letter name of the Unicode general
2208 category assigned to @var{chr} or @code{#f} if no named category is
2209 assigned. The following table provides a list of category names along
2210 with their meanings.
2212 @multitable @columnfractions .1 .4 .1 .4
2214 @tab Uppercase letter
2216 @tab Final quote punctuation
2218 @tab Lowercase letter
2220 @tab Other punctuation
2222 @tab Titlecase letter
2226 @tab Modifier letter
2228 @tab Currency symbol
2232 @tab Modifier symbol
2234 @tab Non-spacing mark
2238 @tab Combining spacing mark
2240 @tab Space separator
2246 @tab Decimal digit number
2248 @tab Paragraph separator
2258 @tab Connector punctuation
2262 @tab Dash punctuation
2266 @tab Open punctuation
2270 @tab Close punctuation
2274 @tab Initial quote punctuation
2280 @rnindex char->integer
2281 @deffn {Scheme Procedure} char->integer chr
2282 @deffnx {C Function} scm_char_to_integer (chr)
2283 Return the code point of @var{chr}.
2286 @rnindex integer->char
2287 @deffn {Scheme Procedure} integer->char n
2288 @deffnx {C Function} scm_integer_to_char (n)
2289 Return the character that has code point @var{n}. The integer @var{n}
2290 must be a valid code point. Valid code points are in the ranges 0 to
2291 @code{#xD7FF} inclusive or @code{#xE000} to @code{#x10FFFF} inclusive.
2294 @rnindex char-upcase
2295 @deffn {Scheme Procedure} char-upcase chr
2296 @deffnx {C Function} scm_char_upcase (chr)
2297 Return the uppercase character version of @var{chr}.
2300 @rnindex char-downcase
2301 @deffn {Scheme Procedure} char-downcase chr
2302 @deffnx {C Function} scm_char_downcase (chr)
2303 Return the lowercase character version of @var{chr}.
2306 @rnindex char-titlecase
2307 @deffn {Scheme Procedure} char-titlecase chr
2308 @deffnx {C Function} scm_char_titlecase (chr)
2309 Return the titlecase character version of @var{chr} if one exists;
2310 otherwise return the uppercase version.
2312 For most characters these will be the same, but the Unicode Standard
2313 includes certain digraph compatibility characters, such as @code{U+01F3}
2314 ``dz'', for which the uppercase and titlecase characters are different
2315 (@code{U+01F1} ``DZ'' and @code{U+01F2} ``Dz'' in this case,
2320 @deftypefn {C Function} scm_t_wchar scm_c_upcase (scm_t_wchar @var{c})
2321 @deftypefnx {C Function} scm_t_wchar scm_c_downcase (scm_t_wchar @var{c})
2322 @deftypefnx {C Function} scm_t_wchar scm_c_titlecase (scm_t_wchar @var{c})
2324 These C functions take an integer representation of a Unicode
2325 codepoint and return the codepoint corresponding to its uppercase,
2326 lowercase, and titlecase forms respectively. The type
2327 @code{scm_t_wchar} is a signed, 32-bit integer.
2330 @node Character Sets
2331 @subsection Character Sets
2333 The features described in this section correspond directly to SRFI-14.
2335 The data type @dfn{charset} implements sets of characters
2336 (@pxref{Characters}). Because the internal representation of
2337 character sets is not visible to the user, a lot of procedures for
2338 handling them are provided.
2340 Character sets can be created, extended, tested for the membership of a
2341 characters and be compared to other character sets.
2344 * Character Set Predicates/Comparison::
2345 * Iterating Over Character Sets:: Enumerate charset elements.
2346 * Creating Character Sets:: Making new charsets.
2347 * Querying Character Sets:: Test charsets for membership etc.
2348 * Character-Set Algebra:: Calculating new charsets.
2349 * Standard Character Sets:: Variables containing predefined charsets.
2352 @node Character Set Predicates/Comparison
2353 @subsubsection Character Set Predicates/Comparison
2355 Use these procedures for testing whether an object is a character set,
2356 or whether several character sets are equal or subsets of each other.
2357 @code{char-set-hash} can be used for calculating a hash value, maybe for
2358 usage in fast lookup procedures.
2360 @deffn {Scheme Procedure} char-set? obj
2361 @deffnx {C Function} scm_char_set_p (obj)
2362 Return @code{#t} if @var{obj} is a character set, @code{#f}
2366 @deffn {Scheme Procedure} char-set= char_set @dots{}
2367 @deffnx {C Function} scm_char_set_eq (char_sets)
2368 Return @code{#t} if all given character sets are equal.
2371 @deffn {Scheme Procedure} char-set<= char_set @dots{}
2372 @deffnx {C Function} scm_char_set_leq (char_sets)
2373 Return @code{#t} if every character set @var{char_set}i is a subset
2374 of character set @var{char_set}i+1.
2377 @deffn {Scheme Procedure} char-set-hash cs [bound]
2378 @deffnx {C Function} scm_char_set_hash (cs, bound)
2379 Compute a hash value for the character set @var{cs}. If
2380 @var{bound} is given and non-zero, it restricts the
2381 returned value to the range 0 @dots{} @var{bound} - 1.
2384 @c ===================================================================
2386 @node Iterating Over Character Sets
2387 @subsubsection Iterating Over Character Sets
2389 Character set cursors are a means for iterating over the members of a
2390 character sets. After creating a character set cursor with
2391 @code{char-set-cursor}, a cursor can be dereferenced with
2392 @code{char-set-ref}, advanced to the next member with
2393 @code{char-set-cursor-next}. Whether a cursor has passed past the last
2394 element of the set can be checked with @code{end-of-char-set?}.
2396 Additionally, mapping and (un-)folding procedures for character sets are
2399 @deffn {Scheme Procedure} char-set-cursor cs
2400 @deffnx {C Function} scm_char_set_cursor (cs)
2401 Return a cursor into the character set @var{cs}.
2404 @deffn {Scheme Procedure} char-set-ref cs cursor
2405 @deffnx {C Function} scm_char_set_ref (cs, cursor)
2406 Return the character at the current cursor position
2407 @var{cursor} in the character set @var{cs}. It is an error to
2408 pass a cursor for which @code{end-of-char-set?} returns true.
2411 @deffn {Scheme Procedure} char-set-cursor-next cs cursor
2412 @deffnx {C Function} scm_char_set_cursor_next (cs, cursor)
2413 Advance the character set cursor @var{cursor} to the next
2414 character in the character set @var{cs}. It is an error if the
2415 cursor given satisfies @code{end-of-char-set?}.
2418 @deffn {Scheme Procedure} end-of-char-set? cursor
2419 @deffnx {C Function} scm_end_of_char_set_p (cursor)
2420 Return @code{#t} if @var{cursor} has reached the end of a
2421 character set, @code{#f} otherwise.
2424 @deffn {Scheme Procedure} char-set-fold kons knil cs
2425 @deffnx {C Function} scm_char_set_fold (kons, knil, cs)
2426 Fold the procedure @var{kons} over the character set @var{cs},
2427 initializing it with @var{knil}.
2430 @deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
2431 @deffnx {C Function} scm_char_set_unfold (p, f, g, seed, base_cs)
2432 This is a fundamental constructor for character sets.
2434 @item @var{g} is used to generate a series of ``seed'' values
2435 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2436 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2437 @item @var{p} tells us when to stop -- when it returns true
2438 when applied to one of the seed values.
2439 @item @var{f} maps each seed value to a character. These
2440 characters are added to the base character set @var{base_cs} to
2441 form the result; @var{base_cs} defaults to the empty set.
2445 @deffn {Scheme Procedure} char-set-unfold! p f g seed base_cs
2446 @deffnx {C Function} scm_char_set_unfold_x (p, f, g, seed, base_cs)
2447 This is a fundamental constructor for character sets.
2449 @item @var{g} is used to generate a series of ``seed'' values
2450 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2451 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2452 @item @var{p} tells us when to stop -- when it returns true
2453 when applied to one of the seed values.
2454 @item @var{f} maps each seed value to a character. These
2455 characters are added to the base character set @var{base_cs} to
2456 form the result; @var{base_cs} defaults to the empty set.
2460 @deffn {Scheme Procedure} char-set-for-each proc cs
2461 @deffnx {C Function} scm_char_set_for_each (proc, cs)
2462 Apply @var{proc} to every character in the character set
2463 @var{cs}. The return value is not specified.
2466 @deffn {Scheme Procedure} char-set-map proc cs
2467 @deffnx {C Function} scm_char_set_map (proc, cs)
2468 Map the procedure @var{proc} over every character in @var{cs}.
2469 @var{proc} must be a character -> character procedure.
2472 @c ===================================================================
2474 @node Creating Character Sets
2475 @subsubsection Creating Character Sets
2477 New character sets are produced with these procedures.
2479 @deffn {Scheme Procedure} char-set-copy cs
2480 @deffnx {C Function} scm_char_set_copy (cs)
2481 Return a newly allocated character set containing all
2482 characters in @var{cs}.
2485 @deffn {Scheme Procedure} char-set chr @dots{}
2486 @deffnx {C Function} scm_char_set (chrs)
2487 Return a character set containing all given characters.
2490 @deffn {Scheme Procedure} list->char-set list [base_cs]
2491 @deffnx {C Function} scm_list_to_char_set (list, base_cs)
2492 Convert the character list @var{list} to a character set. If
2493 the character set @var{base_cs} is given, the character in this
2494 set are also included in the result.
2497 @deffn {Scheme Procedure} list->char-set! list base_cs
2498 @deffnx {C Function} scm_list_to_char_set_x (list, base_cs)
2499 Convert the character list @var{list} to a character set. The
2500 characters are added to @var{base_cs} and @var{base_cs} is
2504 @deffn {Scheme Procedure} string->char-set str [base_cs]
2505 @deffnx {C Function} scm_string_to_char_set (str, base_cs)
2506 Convert the string @var{str} to a character set. If the
2507 character set @var{base_cs} is given, the characters in this
2508 set are also included in the result.
2511 @deffn {Scheme Procedure} string->char-set! str base_cs
2512 @deffnx {C Function} scm_string_to_char_set_x (str, base_cs)
2513 Convert the string @var{str} to a character set. The
2514 characters from the string are added to @var{base_cs}, and
2515 @var{base_cs} is returned.
2518 @deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
2519 @deffnx {C Function} scm_char_set_filter (pred, cs, base_cs)
2520 Return a character set containing every character from @var{cs}
2521 so that it satisfies @var{pred}. If provided, the characters
2522 from @var{base_cs} are added to the result.
2525 @deffn {Scheme Procedure} char-set-filter! pred cs base_cs
2526 @deffnx {C Function} scm_char_set_filter_x (pred, cs, base_cs)
2527 Return a character set containing every character from @var{cs}
2528 so that it satisfies @var{pred}. The characters are added to
2529 @var{base_cs} and @var{base_cs} is returned.
2532 @deffn {Scheme Procedure} ucs-range->char-set lower upper [error [base_cs]]
2533 @deffnx {C Function} scm_ucs_range_to_char_set (lower, upper, error, base_cs)
2534 Return a character set containing all characters whose
2535 character codes lie in the half-open range
2536 [@var{lower},@var{upper}).
2538 If @var{error} is a true value, an error is signalled if the
2539 specified range contains characters which are not contained in
2540 the implemented character range. If @var{error} is @code{#f},
2541 these characters are silently left out of the resulting
2544 The characters in @var{base_cs} are added to the result, if
2548 @deffn {Scheme Procedure} ucs-range->char-set! lower upper error base_cs
2549 @deffnx {C Function} scm_ucs_range_to_char_set_x (lower, upper, error, base_cs)
2550 Return a character set containing all characters whose
2551 character codes lie in the half-open range
2552 [@var{lower},@var{upper}).
2554 If @var{error} is a true value, an error is signalled if the
2555 specified range contains characters which are not contained in
2556 the implemented character range. If @var{error} is @code{#f},
2557 these characters are silently left out of the resulting
2560 The characters are added to @var{base_cs} and @var{base_cs} is
2564 @deffn {Scheme Procedure} ->char-set x
2565 @deffnx {C Function} scm_to_char_set (x)
2566 Coerces x into a char-set. @var{x} may be a string, character or
2567 char-set. A string is converted to the set of its constituent
2568 characters; a character is converted to a singleton set; a char-set is
2572 @c ===================================================================
2574 @node Querying Character Sets
2575 @subsubsection Querying Character Sets
2577 Access the elements and other information of a character set with these
2580 @deffn {Scheme Procedure} %char-set-dump cs
2581 Returns an association list containing debugging information
2582 for @var{cs}. The association list has the following entries.
2587 The number of groups of contiguous code points the char-set
2590 A list of lists where each sublist is a range of code points
2591 and their associated characters
2593 The return value of this function cannot be relied upon to be
2594 consistent between versions of Guile and should not be used in code.
2597 @deffn {Scheme Procedure} char-set-size cs
2598 @deffnx {C Function} scm_char_set_size (cs)
2599 Return the number of elements in character set @var{cs}.
2602 @deffn {Scheme Procedure} char-set-count pred cs
2603 @deffnx {C Function} scm_char_set_count (pred, cs)
2604 Return the number of the elements int the character set
2605 @var{cs} which satisfy the predicate @var{pred}.
2608 @deffn {Scheme Procedure} char-set->list cs
2609 @deffnx {C Function} scm_char_set_to_list (cs)
2610 Return a list containing the elements of the character set
2614 @deffn {Scheme Procedure} char-set->string cs
2615 @deffnx {C Function} scm_char_set_to_string (cs)
2616 Return a string containing the elements of the character set
2617 @var{cs}. The order in which the characters are placed in the
2618 string is not defined.
2621 @deffn {Scheme Procedure} char-set-contains? cs ch
2622 @deffnx {C Function} scm_char_set_contains_p (cs, ch)
2623 Return @code{#t} if the character @var{ch} is contained in the
2624 character set @var{cs}, or @code{#f} otherwise.
2627 @deffn {Scheme Procedure} char-set-every pred cs
2628 @deffnx {C Function} scm_char_set_every (pred, cs)
2629 Return a true value if every character in the character set
2630 @var{cs} satisfies the predicate @var{pred}.
2633 @deffn {Scheme Procedure} char-set-any pred cs
2634 @deffnx {C Function} scm_char_set_any (pred, cs)
2635 Return a true value if any character in the character set
2636 @var{cs} satisfies the predicate @var{pred}.
2639 @c ===================================================================
2641 @node Character-Set Algebra
2642 @subsubsection Character-Set Algebra
2644 Character sets can be manipulated with the common set algebra operation,
2645 such as union, complement, intersection etc. All of these procedures
2646 provide side-effecting variants, which modify their character set
2649 @deffn {Scheme Procedure} char-set-adjoin cs chr @dots{}
2650 @deffnx {C Function} scm_char_set_adjoin (cs, chrs)
2651 Add all character arguments to the first argument, which must
2655 @deffn {Scheme Procedure} char-set-delete cs chr @dots{}
2656 @deffnx {C Function} scm_char_set_delete (cs, chrs)
2657 Delete all character arguments from the first argument, which
2658 must be a character set.
2661 @deffn {Scheme Procedure} char-set-adjoin! cs chr @dots{}
2662 @deffnx {C Function} scm_char_set_adjoin_x (cs, chrs)
2663 Add all character arguments to the first argument, which must
2667 @deffn {Scheme Procedure} char-set-delete! cs chr @dots{}
2668 @deffnx {C Function} scm_char_set_delete_x (cs, chrs)
2669 Delete all character arguments from the first argument, which
2670 must be a character set.
2673 @deffn {Scheme Procedure} char-set-complement cs
2674 @deffnx {C Function} scm_char_set_complement (cs)
2675 Return the complement of the character set @var{cs}.
2678 Note that the complement of a character set is likely to contain many
2679 reserved code points (code points that are not associated with
2680 characters). It may be helpful to modify the output of
2681 @code{char-set-complement} by computing its intersection with the set
2682 of designated code points, @code{char-set:designated}.
2684 @deffn {Scheme Procedure} char-set-union cs @dots{}
2685 @deffnx {C Function} scm_char_set_union (char_sets)
2686 Return the union of all argument character sets.
2689 @deffn {Scheme Procedure} char-set-intersection cs @dots{}
2690 @deffnx {C Function} scm_char_set_intersection (char_sets)
2691 Return the intersection of all argument character sets.
2694 @deffn {Scheme Procedure} char-set-difference cs1 cs @dots{}
2695 @deffnx {C Function} scm_char_set_difference (cs1, char_sets)
2696 Return the difference of all argument character sets.
2699 @deffn {Scheme Procedure} char-set-xor cs @dots{}
2700 @deffnx {C Function} scm_char_set_xor (char_sets)
2701 Return the exclusive-or of all argument character sets.
2704 @deffn {Scheme Procedure} char-set-diff+intersection cs1 cs @dots{}
2705 @deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, char_sets)
2706 Return the difference and the intersection of all argument
2710 @deffn {Scheme Procedure} char-set-complement! cs
2711 @deffnx {C Function} scm_char_set_complement_x (cs)
2712 Return the complement of the character set @var{cs}.
2715 @deffn {Scheme Procedure} char-set-union! cs1 cs @dots{}
2716 @deffnx {C Function} scm_char_set_union_x (cs1, char_sets)
2717 Return the union of all argument character sets.
2720 @deffn {Scheme Procedure} char-set-intersection! cs1 cs @dots{}
2721 @deffnx {C Function} scm_char_set_intersection_x (cs1, char_sets)
2722 Return the intersection of all argument character sets.
2725 @deffn {Scheme Procedure} char-set-difference! cs1 cs @dots{}
2726 @deffnx {C Function} scm_char_set_difference_x (cs1, char_sets)
2727 Return the difference of all argument character sets.
2730 @deffn {Scheme Procedure} char-set-xor! cs1 cs @dots{}
2731 @deffnx {C Function} scm_char_set_xor_x (cs1, char_sets)
2732 Return the exclusive-or of all argument character sets.
2735 @deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 cs @dots{}
2736 @deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, char_sets)
2737 Return the difference and the intersection of all argument
2741 @c ===================================================================
2743 @node Standard Character Sets
2744 @subsubsection Standard Character Sets
2746 In order to make the use of the character set data type and procedures
2747 useful, several predefined character set variables exist.
2753 These character sets are locale independent and are not recomputed
2754 upon a @code{setlocale} call. They contain characters from the whole
2755 range of Unicode code points. For instance, @code{char-set:letter}
2756 contains about 100,000 characters.
2758 @defvr {Scheme Variable} char-set:lower-case
2759 @defvrx {C Variable} scm_char_set_lower_case
2760 All lower-case characters.
2763 @defvr {Scheme Variable} char-set:upper-case
2764 @defvrx {C Variable} scm_char_set_upper_case
2765 All upper-case characters.
2768 @defvr {Scheme Variable} char-set:title-case
2769 @defvrx {C Variable} scm_char_set_title_case
2770 All single characters that function as if they were an upper-case
2771 letter followed by a lower-case letter.
2774 @defvr {Scheme Variable} char-set:letter
2775 @defvrx {C Variable} scm_char_set_letter
2776 All letters. This includes @code{char-set:lower-case},
2777 @code{char-set:upper-case}, @code{char-set:title-case}, and many
2778 letters that have no case at all. For example, Chinese and Japanese
2779 characters typically have no concept of case.
2782 @defvr {Scheme Variable} char-set:digit
2783 @defvrx {C Variable} scm_char_set_digit
2787 @defvr {Scheme Variable} char-set:letter+digit
2788 @defvrx {C Variable} scm_char_set_letter_and_digit
2789 The union of @code{char-set:letter} and @code{char-set:digit}.
2792 @defvr {Scheme Variable} char-set:graphic
2793 @defvrx {C Variable} scm_char_set_graphic
2794 All characters which would put ink on the paper.
2797 @defvr {Scheme Variable} char-set:printing
2798 @defvrx {C Variable} scm_char_set_printing
2799 The union of @code{char-set:graphic} and @code{char-set:whitespace}.
2802 @defvr {Scheme Variable} char-set:whitespace
2803 @defvrx {C Variable} scm_char_set_whitespace
2804 All whitespace characters.
2807 @defvr {Scheme Variable} char-set:blank
2808 @defvrx {C Variable} scm_char_set_blank
2809 All horizontal whitespace characters, which notably includes
2810 @code{#\space} and @code{#\tab}.
2813 @defvr {Scheme Variable} char-set:iso-control
2814 @defvrx {C Variable} scm_char_set_iso_control
2815 The ISO control characters are the C0 control characters (U+0000 to
2816 U+001F), delete (U+007F), and the C1 control characters (U+0080 to
2820 @defvr {Scheme Variable} char-set:punctuation
2821 @defvrx {C Variable} scm_char_set_punctuation
2822 All punctuation characters, such as the characters
2823 @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
2826 @defvr {Scheme Variable} char-set:symbol
2827 @defvrx {C Variable} scm_char_set_symbol
2828 All symbol characters, such as the characters @code{$+<=>^`|~}.
2831 @defvr {Scheme Variable} char-set:hex-digit
2832 @defvrx {C Variable} scm_char_set_hex_digit
2833 The hexadecimal digits @code{0123456789abcdefABCDEF}.
2836 @defvr {Scheme Variable} char-set:ascii
2837 @defvrx {C Variable} scm_char_set_ascii
2838 All ASCII characters.
2841 @defvr {Scheme Variable} char-set:empty
2842 @defvrx {C Variable} scm_char_set_empty
2843 The empty character set.
2846 @defvr {Scheme Variable} char-set:designated
2847 @defvrx {C Variable} scm_char_set_designated
2848 This character set contains all designated code points. This includes
2849 all the code points to which Unicode has assigned a character or other
2853 @defvr {Scheme Variable} char-set:full
2854 @defvrx {C Variable} scm_char_set_full
2855 This character set contains all possible code points. This includes
2856 both designated and reserved code points.
2863 Strings are fixed-length sequences of characters. They can be created
2864 by calling constructor procedures, but they can also literally get
2865 entered at the @acronym{REPL} or in Scheme source files.
2867 @c Guile provides a rich set of string processing procedures, because text
2868 @c handling is very important when Guile is used as a scripting language.
2870 Strings always carry the information about how many characters they are
2871 composed of with them, so there is no special end-of-string character,
2872 like in C. That means that Scheme strings can contain any character,
2873 even the @samp{#\nul} character @samp{\0}.
2875 To use strings efficiently, you need to know a bit about how Guile
2876 implements them. In Guile, a string consists of two parts, a head and
2877 the actual memory where the characters are stored. When a string (or
2878 a substring of it) is copied, only a new head gets created, the memory
2879 is usually not copied. The two heads start out pointing to the same
2882 When one of these two strings is modified, as with @code{string-set!},
2883 their common memory does get copied so that each string has its own
2884 memory and modifying one does not accidentally modify the other as well.
2885 Thus, Guile's strings are `copy on write'; the actual copying of their
2886 memory is delayed until one string is written to.
2888 This implementation makes functions like @code{substring} very
2889 efficient in the common case that no modifications are done to the
2892 If you do know that your strings are getting modified right away, you
2893 can use @code{substring/copy} instead of @code{substring}. This
2894 function performs the copy immediately at the time of creation. This
2895 is more efficient, especially in a multi-threaded program. Also,
2896 @code{substring/copy} can avoid the problem that a short substring
2897 holds on to the memory of a very large original string that could
2898 otherwise be recycled.
2900 If you want to avoid the copy altogether, so that modifications of one
2901 string show up in the other, you can use @code{substring/shared}. The
2902 strings created by this procedure are called @dfn{mutation sharing
2903 substrings} since the substring and the original string share
2904 modifications to each other.
2906 If you want to prevent modifications, use @code{substring/read-only}.
2908 Guile provides all procedures of SRFI-13 and a few more.
2911 * String Syntax:: Read syntax for strings.
2912 * String Predicates:: Testing strings for certain properties.
2913 * String Constructors:: Creating new string objects.
2914 * List/String Conversion:: Converting from/to lists of characters.
2915 * String Selection:: Select portions from strings.
2916 * String Modification:: Modify parts or whole strings.
2917 * String Comparison:: Lexicographic ordering predicates.
2918 * String Searching:: Searching in strings.
2919 * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
2920 * Reversing and Appending Strings:: Appending strings to form a new string.
2921 * Mapping Folding and Unfolding:: Iterating over strings.
2922 * Miscellaneous String Operations:: Replicating, insertion, parsing, ...
2923 * Representing Strings as Bytes:: Encoding and decoding strings.
2924 * Conversion to/from C::
2925 * String Internals:: The storage strategy for strings.
2929 @subsubsection String Read Syntax
2931 @c In the following @code is used to get a good font in TeX etc, but
2932 @c is omitted for Info format, so as not to risk any confusion over
2933 @c whether surrounding ` ' quotes are part of the escape or are
2934 @c special in a string (they're not).
2936 The read syntax for strings is an arbitrarily long sequence of
2937 characters enclosed in double quotes (@nicode{"}).
2939 Backslash is an escape character and can be used to insert the following
2940 special characters. @nicode{\"} and @nicode{\\} are R5RS standard, the
2941 next seven are R6RS standard --- notice they follow C syntax --- and the
2942 remaining four are Guile extensions.
2946 Backslash character.
2949 Double quote character (an unescaped @nicode{"} is otherwise the end
2953 Bell character (ASCII 7).
2956 Formfeed character (ASCII 12).
2959 Newline character (ASCII 10).
2962 Carriage return character (ASCII 13).
2965 Tab character (ASCII 9).
2968 Vertical tab character (ASCII 11).
2971 Backspace character (ASCII 8).
2974 NUL character (ASCII 0).
2976 @item @nicode{\} followed by newline (ASCII 10)
2977 Nothing. This way if @nicode{\} is the last character in a line, the
2978 string will continue with the first character from the next line,
2979 without a line break.
2981 If the @code{hungry-eol-escapes} reader option is enabled, which is not
2982 the case by default, leading whitespace on the next line is discarded.
2988 (read-enable 'hungry-eol-escapes)
2994 Character code given by two hexadecimal digits. For example
2995 @nicode{\x7f} for an ASCII DEL (127).
2997 @item @nicode{\uHHHH}
2998 Character code given by four hexadecimal digits. For example
2999 @nicode{\u0100} for a capital A with macron (U+0100).
3001 @item @nicode{\UHHHHHH}
3002 Character code given by six hexadecimal digits. For example
3007 The following are examples of string literals:
3016 The three escape sequences @code{\xHH}, @code{\uHHHH} and @code{\UHHHHHH} were
3017 chosen to not break compatibility with code written for previous versions of
3018 Guile. The R6RS specification suggests a different, incompatible syntax for hex
3019 escapes: @code{\xHHHH;} -- a character code followed by one to eight hexadecimal
3020 digits terminated with a semicolon. If this escape format is desired instead,
3021 it can be enabled with the reader option @code{r6rs-hex-escapes}.
3024 (read-enable 'r6rs-hex-escapes)
3027 For more on reader options, @xref{Scheme Read}.
3029 @node String Predicates
3030 @subsubsection String Predicates
3032 The following procedures can be used to check whether a given string
3033 fulfills some specified property.
3036 @deffn {Scheme Procedure} string? obj
3037 @deffnx {C Function} scm_string_p (obj)
3038 Return @code{#t} if @var{obj} is a string, else @code{#f}.
3041 @deftypefn {C Function} int scm_is_string (SCM obj)
3042 Returns @code{1} if @var{obj} is a string, @code{0} otherwise.
3045 @deffn {Scheme Procedure} string-null? str
3046 @deffnx {C Function} scm_string_null_p (str)
3047 Return @code{#t} if @var{str}'s length is zero, and
3048 @code{#f} otherwise.
3050 (string-null? "") @result{} #t
3052 (string-null? y) @result{} #f
3056 @deffn {Scheme Procedure} string-any char_pred s [start [end]]
3057 @deffnx {C Function} scm_string_any (char_pred, s, start, end)
3058 Check if @var{char_pred} is true for any character in string @var{s}.
3060 @var{char_pred} can be a character to check for any equal to that, or
3061 a character set (@pxref{Character Sets}) to check for any in that set,
3062 or a predicate procedure to call.
3064 For a procedure, calls @code{(@var{char_pred} c)} are made
3065 successively on the characters from @var{start} to @var{end}. If
3066 @var{char_pred} returns true (ie.@: non-@code{#f}), @code{string-any}
3067 stops and that return value is the return from @code{string-any}. The
3068 call on the last character (ie.@: at @math{@var{end}-1}), if that
3069 point is reached, is a tail call.
3071 If there are no characters in @var{s} (ie.@: @var{start} equals
3072 @var{end}) then the return is @code{#f}.
3075 @deffn {Scheme Procedure} string-every char_pred s [start [end]]
3076 @deffnx {C Function} scm_string_every (char_pred, s, start, end)
3077 Check if @var{char_pred} is true for every character in string
3080 @var{char_pred} can be a character to check for every character equal
3081 to that, or a character set (@pxref{Character Sets}) to check for
3082 every character being in that set, or a predicate procedure to call.
3084 For a procedure, calls @code{(@var{char_pred} c)} are made
3085 successively on the characters from @var{start} to @var{end}. If
3086 @var{char_pred} returns @code{#f}, @code{string-every} stops and
3087 returns @code{#f}. The call on the last character (ie.@: at
3088 @math{@var{end}-1}), if that point is reached, is a tail call and the
3089 return from that call is the return from @code{string-every}.
3091 If there are no characters in @var{s} (ie.@: @var{start} equals
3092 @var{end}) then the return is @code{#t}.
3095 @node String Constructors
3096 @subsubsection String Constructors
3098 The string constructor procedures create new string objects, possibly
3099 initializing them with some specified character data. See also
3100 @xref{String Selection}, for ways to create strings from existing
3103 @c FIXME::martin: list->string belongs into `List/String Conversion'
3105 @deffn {Scheme Procedure} string char@dots{}
3107 Return a newly allocated string made from the given character
3111 (string #\x #\y #\z) @result{} "xyz"
3112 (string) @result{} ""
3116 @deffn {Scheme Procedure} list->string lst
3117 @deffnx {C Function} scm_string (lst)
3118 @rnindex list->string
3119 Return a newly allocated string made from a list of characters.
3122 (list->string '(#\a #\b #\c)) @result{} "abc"
3126 @deffn {Scheme Procedure} reverse-list->string lst
3127 @deffnx {C Function} scm_reverse_list_to_string (lst)
3128 Return a newly allocated string made from a list of characters, in
3132 (reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
3136 @rnindex make-string
3137 @deffn {Scheme Procedure} make-string k [chr]
3138 @deffnx {C Function} scm_make_string (k, chr)
3139 Return a newly allocated string of
3140 length @var{k}. If @var{chr} is given, then all elements of
3141 the string are initialized to @var{chr}, otherwise the contents
3142 of the string are unspecified.
3145 @deftypefn {C Function} SCM scm_c_make_string (size_t len, SCM chr)
3146 Like @code{scm_make_string}, but expects the length as a
3150 @deffn {Scheme Procedure} string-tabulate proc len
3151 @deffnx {C Function} scm_string_tabulate (proc, len)
3152 @var{proc} is an integer->char procedure. Construct a string
3153 of size @var{len} by applying @var{proc} to each index to
3154 produce the corresponding string element. The order in which
3155 @var{proc} is applied to the indices is not specified.
3158 @deffn {Scheme Procedure} string-join ls [delimiter [grammar]]
3159 @deffnx {C Function} scm_string_join (ls, delimiter, grammar)
3160 Append the string in the string list @var{ls}, using the string
3161 @var{delimiter} as a delimiter between the elements of @var{ls}.
3162 @var{grammar} is a symbol which specifies how the delimiter is
3163 placed between the strings, and defaults to the symbol
3168 Insert the separator between list elements. An empty string
3169 will produce an empty list.
3171 Like @code{infix}, but will raise an error if given the empty
3174 Insert the separator after every list element.
3176 Insert the separator before each list element.
3180 @node List/String Conversion
3181 @subsubsection List/String conversion
3183 When processing strings, it is often convenient to first convert them
3184 into a list representation by using the procedure @code{string->list},
3185 work with the resulting list, and then convert it back into a string.
3186 These procedures are useful for similar tasks.
3188 @rnindex string->list
3189 @deffn {Scheme Procedure} string->list str [start [end]]
3190 @deffnx {C Function} scm_substring_to_list (str, start, end)
3191 @deffnx {C Function} scm_string_to_list (str)
3192 Convert the string @var{str} into a list of characters.
3195 @deffn {Scheme Procedure} string-split str char_pred
3196 @deffnx {C Function} scm_string_split (str, char_pred)
3197 Split the string @var{str} into a list of substrings delimited
3198 by appearances of characters that
3202 equal @var{char_pred}, if it is a character,
3205 satisfy the predicate @var{char_pred}, if it is a procedure,
3208 are in the set @var{char_pred}, if it is a character set.
3211 Note that an empty substring between separator characters will result in
3212 an empty string in the result list.
3215 (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
3217 ("root" "x" "0" "0" "root" "/root" "/bin/bash")
3219 (string-split "::" #\:)
3223 (string-split "" #\:)
3230 @node String Selection
3231 @subsubsection String Selection
3233 Portions of strings can be extracted by these procedures.
3234 @code{string-ref} delivers individual characters whereas
3235 @code{substring} can be used to extract substrings from longer strings.
3237 @rnindex string-length
3238 @deffn {Scheme Procedure} string-length string
3239 @deffnx {C Function} scm_string_length (string)
3240 Return the number of characters in @var{string}.
3243 @deftypefn {C Function} size_t scm_c_string_length (SCM str)
3244 Return the number of characters in @var{str} as a @code{size_t}.
3248 @deffn {Scheme Procedure} string-ref str k
3249 @deffnx {C Function} scm_string_ref (str, k)
3250 Return character @var{k} of @var{str} using zero-origin
3251 indexing. @var{k} must be a valid index of @var{str}.
3254 @deftypefn {C Function} SCM scm_c_string_ref (SCM str, size_t k)
3255 Return character @var{k} of @var{str} using zero-origin
3256 indexing. @var{k} must be a valid index of @var{str}.
3259 @rnindex string-copy
3260 @deffn {Scheme Procedure} string-copy str [start [end]]
3261 @deffnx {C Function} scm_substring_copy (str, start, end)
3262 @deffnx {C Function} scm_string_copy (str)
3263 Return a copy of the given string @var{str}.
3265 The returned string shares storage with @var{str} initially, but it is
3266 copied as soon as one of the two strings is modified.
3270 @deffn {Scheme Procedure} substring str start [end]
3271 @deffnx {C Function} scm_substring (str, start, end)
3272 Return a new string formed from the characters
3273 of @var{str} beginning with index @var{start} (inclusive) and
3274 ending with index @var{end} (exclusive).
3275 @var{str} must be a string, @var{start} and @var{end} must be
3276 exact integers satisfying:
3278 0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
3280 The returned string shares storage with @var{str} initially, but it is
3281 copied as soon as one of the two strings is modified.
3284 @deffn {Scheme Procedure} substring/shared str start [end]
3285 @deffnx {C Function} scm_substring_shared (str, start, end)
3286 Like @code{substring}, but the strings continue to share their storage
3287 even if they are modified. Thus, modifications to @var{str} show up
3288 in the new string, and vice versa.
3291 @deffn {Scheme Procedure} substring/copy str start [end]
3292 @deffnx {C Function} scm_substring_copy (str, start, end)
3293 Like @code{substring}, but the storage for the new string is copied
3297 @deffn {Scheme Procedure} substring/read-only str start [end]
3298 @deffnx {C Function} scm_substring_read_only (str, start, end)
3299 Like @code{substring}, but the resulting string can not be modified.
3302 @deftypefn {C Function} SCM scm_c_substring (SCM str, size_t start, size_t end)
3303 @deftypefnx {C Function} SCM scm_c_substring_shared (SCM str, size_t start, size_t end)
3304 @deftypefnx {C Function} SCM scm_c_substring_copy (SCM str, size_t start, size_t end)
3305 @deftypefnx {C Function} SCM scm_c_substring_read_only (SCM str, size_t start, size_t end)
3306 Like @code{scm_substring}, etc. but the bounds are given as a @code{size_t}.
3309 @deffn {Scheme Procedure} string-take s n
3310 @deffnx {C Function} scm_string_take (s, n)
3311 Return the @var{n} first characters of @var{s}.
3314 @deffn {Scheme Procedure} string-drop s n
3315 @deffnx {C Function} scm_string_drop (s, n)
3316 Return all but the first @var{n} characters of @var{s}.
3319 @deffn {Scheme Procedure} string-take-right s n
3320 @deffnx {C Function} scm_string_take_right (s, n)
3321 Return the @var{n} last characters of @var{s}.
3324 @deffn {Scheme Procedure} string-drop-right s n
3325 @deffnx {C Function} scm_string_drop_right (s, n)
3326 Return all but the last @var{n} characters of @var{s}.
3329 @deffn {Scheme Procedure} string-pad s len [chr [start [end]]]
3330 @deffnx {Scheme Procedure} string-pad-right s len [chr [start [end]]]
3331 @deffnx {C Function} scm_string_pad (s, len, chr, start, end)
3332 @deffnx {C Function} scm_string_pad_right (s, len, chr, start, end)
3333 Take characters @var{start} to @var{end} from the string @var{s} and
3334 either pad with @var{chr} or truncate them to give @var{len}
3337 @code{string-pad} pads or truncates on the left, so for example
3340 (string-pad "x" 3) @result{} " x"
3341 (string-pad "abcde" 3) @result{} "cde"
3344 @code{string-pad-right} pads or truncates on the right, so for example
3347 (string-pad-right "x" 3) @result{} "x "
3348 (string-pad-right "abcde" 3) @result{} "abc"
3352 @deffn {Scheme Procedure} string-trim s [char_pred [start [end]]]
3353 @deffnx {Scheme Procedure} string-trim-right s [char_pred [start [end]]]
3354 @deffnx {Scheme Procedure} string-trim-both s [char_pred [start [end]]]
3355 @deffnx {C Function} scm_string_trim (s, char_pred, start, end)
3356 @deffnx {C Function} scm_string_trim_right (s, char_pred, start, end)
3357 @deffnx {C Function} scm_string_trim_both (s, char_pred, start, end)
3358 Trim occurrences of @var{char_pred} from the ends of @var{s}.
3360 @code{string-trim} trims @var{char_pred} characters from the left
3361 (start) of the string, @code{string-trim-right} trims them from the
3362 right (end) of the string, @code{string-trim-both} trims from both
3365 @var{char_pred} can be a character, a character set, or a predicate
3366 procedure to call on each character. If @var{char_pred} is not given
3367 the default is whitespace as per @code{char-set:whitespace}
3368 (@pxref{Standard Character Sets}).
3371 (string-trim " x ") @result{} "x "
3372 (string-trim-right "banana" #\a) @result{} "banan"
3373 (string-trim-both ".,xy:;" char-set:punctuation)
3375 (string-trim-both "xyzzy" (lambda (c)
3382 @node String Modification
3383 @subsubsection String Modification
3385 These procedures are for modifying strings in-place. This means that the
3386 result of the operation is not a new string; instead, the original string's
3387 memory representation is modified.
3389 @rnindex string-set!
3390 @deffn {Scheme Procedure} string-set! str k chr
3391 @deffnx {C Function} scm_string_set_x (str, k, chr)
3392 Store @var{chr} in element @var{k} of @var{str} and return
3393 an unspecified value. @var{k} must be a valid index of
3397 @deftypefn {C Function} void scm_c_string_set_x (SCM str, size_t k, SCM chr)
3398 Like @code{scm_string_set_x}, but the index is given as a @code{size_t}.
3401 @rnindex string-fill!
3402 @deffn {Scheme Procedure} string-fill! str chr [start [end]]
3403 @deffnx {C Function} scm_substring_fill_x (str, chr, start, end)
3404 @deffnx {C Function} scm_string_fill_x (str, chr)
3405 Stores @var{chr} in every element of the given @var{str} and
3406 returns an unspecified value.
3409 @deffn {Scheme Procedure} substring-fill! str start end fill
3410 @deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
3411 Change every character in @var{str} between @var{start} and
3412 @var{end} to @var{fill}.
3415 (define y (string-copy "abcdefg"))
3416 (substring-fill! y 1 3 #\r)
3422 @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
3423 @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
3424 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
3425 into @var{str2} beginning at position @var{start2}.
3426 @var{str1} and @var{str2} can be the same string.
3429 @deffn {Scheme Procedure} string-copy! target tstart s [start [end]]
3430 @deffnx {C Function} scm_string_copy_x (target, tstart, s, start, end)
3431 Copy the sequence of characters from index range [@var{start},
3432 @var{end}) in string @var{s} to string @var{target}, beginning
3433 at index @var{tstart}. The characters are copied left-to-right
3434 or right-to-left as needed -- the copy is guaranteed to work,
3435 even if @var{target} and @var{s} are the same string. It is an
3436 error if the copy operation runs off the end of the target
3441 @node String Comparison
3442 @subsubsection String Comparison
3444 The procedures in this section are similar to the character ordering
3445 predicates (@pxref{Characters}), but are defined on character sequences.
3447 The first set is specified in R5RS and has names that end in @code{?}.
3448 The second set is specified in SRFI-13 and the names have not ending
3451 The predicates ending in @code{-ci} ignore the character case
3452 when comparing strings. For now, case-insensitive comparison is done
3453 using the R5RS rules, where every lower-case character that has a
3454 single character upper-case form is converted to uppercase before
3455 comparison. See @xref{Text Collation, the @code{(ice-9
3456 i18n)} module}, for locale-dependent string comparison.
3459 @deffn {Scheme Procedure} string=? s1 s2 s3 @dots{}
3460 Lexicographic equality predicate; return @code{#t} if all strings are
3461 the same length and contain the same characters in the same positions,
3462 otherwise return @code{#f}.
3464 The procedure @code{string-ci=?} treats upper and lower case
3465 letters as though they were the same character, but
3466 @code{string=?} treats upper and lower case as distinct
3471 @deffn {Scheme Procedure} string<? s1 s2 s3 @dots{}
3472 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3473 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3474 lexicographically less than @var{str_i+1}.
3478 @deffn {Scheme Procedure} string<=? s1 s2 s3 @dots{}
3479 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3480 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3481 lexicographically less than or equal to @var{str_i+1}.
3485 @deffn {Scheme Procedure} string>? s1 s2 s3 @dots{}
3486 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3487 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3488 lexicographically greater than @var{str_i+1}.
3492 @deffn {Scheme Procedure} string>=? s1 s2 s3 @dots{}
3493 Lexicographic ordering predicate; return @code{#t} if, for every pair of
3494 consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is
3495 lexicographically greater than or equal to @var{str_i+1}.
3498 @rnindex string-ci=?
3499 @deffn {Scheme Procedure} string-ci=? s1 s2 s3 @dots{}
3500 Case-insensitive string equality predicate; return @code{#t} if
3501 all strings are the same length and their component
3502 characters match (ignoring case) at each position; otherwise
3506 @rnindex string-ci<?
3507 @deffn {Scheme Procedure} string-ci<? s1 s2 s3 @dots{}
3508 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3509 for every pair of consecutive string arguments @var{str_i} and
3510 @var{str_i+1}, @var{str_i} is lexicographically less than @var{str_i+1}
3515 @deffn {Scheme Procedure} string-ci<=? s1 s2 s3 @dots{}
3516 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3517 for every pair of consecutive string arguments @var{str_i} and
3518 @var{str_i+1}, @var{str_i} is lexicographically less than or equal to
3519 @var{str_i+1} regardless of case.
3522 @rnindex string-ci>?
3523 @deffn {Scheme Procedure} string-ci>? s1 s2 s3 @dots{}
3524 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3525 for every pair of consecutive string arguments @var{str_i} and
3526 @var{str_i+1}, @var{str_i} is lexicographically greater than
3527 @var{str_i+1} regardless of case.
3530 @rnindex string-ci>=?
3531 @deffn {Scheme Procedure} string-ci>=? s1 s2 s3 @dots{}
3532 Case insensitive lexicographic ordering predicate; return @code{#t} if,
3533 for every pair of consecutive string arguments @var{str_i} and
3534 @var{str_i+1}, @var{str_i} is lexicographically greater than or equal to
3535 @var{str_i+1} regardless of case.
3538 @deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3539 @deffnx {C Function} scm_string_compare (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3540 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3541 mismatch index, depending upon whether @var{s1} is less than,
3542 equal to, or greater than @var{s2}. The mismatch index is the
3543 largest index @var{i} such that for every 0 <= @var{j} <
3544 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3545 @var{i} is the first position that does not match.
3548 @deffn {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3549 @deffnx {C Function} scm_string_compare_ci (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3550 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3551 mismatch index, depending upon whether @var{s1} is less than,
3552 equal to, or greater than @var{s2}. The mismatch index is the
3553 largest index @var{i} such that for every 0 <= @var{j} <
3554 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3555 @var{i} is the first position where the lowercased letters
3560 @deffn {Scheme Procedure} string= s1 s2 [start1 [end1 [start2 [end2]]]]
3561 @deffnx {C Function} scm_string_eq (s1, s2, start1, end1, start2, end2)
3562 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3566 @deffn {Scheme Procedure} string<> s1 s2 [start1 [end1 [start2 [end2]]]]
3567 @deffnx {C Function} scm_string_neq (s1, s2, start1, end1, start2, end2)
3568 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3572 @deffn {Scheme Procedure} string< s1 s2 [start1 [end1 [start2 [end2]]]]
3573 @deffnx {C Function} scm_string_lt (s1, s2, start1, end1, start2, end2)
3574 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3575 true value otherwise.
3578 @deffn {Scheme Procedure} string> s1 s2 [start1 [end1 [start2 [end2]]]]
3579 @deffnx {C Function} scm_string_gt (s1, s2, start1, end1, start2, end2)
3580 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3581 true value otherwise.
3584 @deffn {Scheme Procedure} string<= s1 s2 [start1 [end1 [start2 [end2]]]]
3585 @deffnx {C Function} scm_string_le (s1, s2, start1, end1, start2, end2)
3586 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3590 @deffn {Scheme Procedure} string>= s1 s2 [start1 [end1 [start2 [end2]]]]
3591 @deffnx {C Function} scm_string_ge (s1, s2, start1, end1, start2, end2)
3592 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3596 @deffn {Scheme Procedure} string-ci= s1 s2 [start1 [end1 [start2 [end2]]]]
3597 @deffnx {C Function} scm_string_ci_eq (s1, s2, start1, end1, start2, end2)
3598 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3599 value otherwise. The character comparison is done
3603 @deffn {Scheme Procedure} string-ci<> s1 s2 [start1 [end1 [start2 [end2]]]]
3604 @deffnx {C Function} scm_string_ci_neq (s1, s2, start1, end1, start2, end2)
3605 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3606 value otherwise. The character comparison is done
3610 @deffn {Scheme Procedure} string-ci< s1 s2 [start1 [end1 [start2 [end2]]]]
3611 @deffnx {C Function} scm_string_ci_lt (s1, s2, start1, end1, start2, end2)
3612 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3613 true value otherwise. The character comparison is done
3617 @deffn {Scheme Procedure} string-ci> s1 s2 [start1 [end1 [start2 [end2]]]]
3618 @deffnx {C Function} scm_string_ci_gt (s1, s2, start1, end1, start2, end2)
3619 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3620 true value otherwise. The character comparison is done
3624 @deffn {Scheme Procedure} string-ci<= s1 s2 [start1 [end1 [start2 [end2]]]]
3625 @deffnx {C Function} scm_string_ci_le (s1, s2, start1, end1, start2, end2)
3626 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3627 value otherwise. The character comparison is done
3631 @deffn {Scheme Procedure} string-ci>= s1 s2 [start1 [end1 [start2 [end2]]]]
3632 @deffnx {C Function} scm_string_ci_ge (s1, s2, start1, end1, start2, end2)
3633 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3634 otherwise. The character comparison is done
3638 @deffn {Scheme Procedure} string-hash s [bound [start [end]]]
3639 @deffnx {C Function} scm_substring_hash (s, bound, start, end)
3640 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).
3643 @deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
3644 @deffnx {C Function} scm_substring_hash_ci (s, bound, start, end)
3645 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).
3648 Because the same visual appearance of an abstract Unicode character can
3649 be obtained via multiple sequences of Unicode characters, even the
3650 case-insensitive string comparison functions described above may return
3651 @code{#f} when presented with strings containing different
3652 representations of the same character. For example, the Unicode
3653 character ``LATIN SMALL LETTER S WITH DOT BELOW AND DOT ABOVE'' can be
3654 represented with a single character (U+1E69) or by the character ``LATIN
3655 SMALL LETTER S'' (U+0073) followed by the combining marks ``COMBINING
3656 DOT BELOW'' (U+0323) and ``COMBINING DOT ABOVE'' (U+0307).
3658 For this reason, it is often desirable to ensure that the strings
3659 to be compared are using a mutually consistent representation for every
3660 character. The Unicode standard defines two methods of normalizing the
3661 contents of strings: Decomposition, which breaks composite characters
3662 into a set of constituent characters with an ordering defined by the
3663 Unicode Standard; and composition, which performs the converse.
3665 There are two decomposition operations. ``Canonical decomposition''
3666 produces character sequences that share the same visual appearance as
3667 the original characters, while ``compatibility decomposition'' produces
3668 ones whose visual appearances may differ from the originals but which
3669 represent the same abstract character.
3671 These operations are encapsulated in the following set of normalization
3676 Characters are decomposed to their canonical forms.
3679 Characters are decomposed to their compatibility forms.
3682 Characters are decomposed to their canonical forms, then composed.
3685 Characters are decomposed to their compatibility forms, then composed.
3689 The functions below put their arguments into one of the forms described
3692 @deffn {Scheme Procedure} string-normalize-nfd s
3693 @deffnx {C Function} scm_string_normalize_nfd (s)
3694 Return the @code{NFD} normalized form of @var{s}.
3697 @deffn {Scheme Procedure} string-normalize-nfkd s
3698 @deffnx {C Function} scm_string_normalize_nfkd (s)
3699 Return the @code{NFKD} normalized form of @var{s}.
3702 @deffn {Scheme Procedure} string-normalize-nfc s
3703 @deffnx {C Function} scm_string_normalize_nfc (s)
3704 Return the @code{NFC} normalized form of @var{s}.
3707 @deffn {Scheme Procedure} string-normalize-nfkc s
3708 @deffnx {C Function} scm_string_normalize_nfkc (s)
3709 Return the @code{NFKC} normalized form of @var{s}.
3712 @node String Searching
3713 @subsubsection String Searching
3715 @deffn {Scheme Procedure} string-index s char_pred [start [end]]
3716 @deffnx {C Function} scm_string_index (s, char_pred, start, end)
3717 Search through the string @var{s} from left to right, returning
3718 the index of the first occurrence of a character which
3722 equals @var{char_pred}, if it is character,
3725 satisfies the predicate @var{char_pred}, if it is a procedure,
3728 is in the set @var{char_pred}, if it is a character set.
3731 Return @code{#f} if no match is found.
3734 @deffn {Scheme Procedure} string-rindex s char_pred [start [end]]
3735 @deffnx {C Function} scm_string_rindex (s, char_pred, start, end)
3736 Search through the string @var{s} from right to left, returning
3737 the index of the last occurrence of a character which
3741 equals @var{char_pred}, if it is character,
3744 satisfies the predicate @var{char_pred}, if it is a procedure,
3747 is in the set if @var{char_pred} is a character set.
3750 Return @code{#f} if no match is found.
3753 @deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3754 @deffnx {C Function} scm_string_prefix_length (s1, s2, start1, end1, start2, end2)
3755 Return the length of the longest common prefix of the two
3759 @deffn {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3760 @deffnx {C Function} scm_string_prefix_length_ci (s1, s2, start1, end1, start2, end2)
3761 Return the length of the longest common prefix of the two
3762 strings, ignoring character case.
3765 @deffn {Scheme Procedure} string-suffix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3766 @deffnx {C Function} scm_string_suffix_length (s1, s2, start1, end1, start2, end2)
3767 Return the length of the longest common suffix of the two
3771 @deffn {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3772 @deffnx {C Function} scm_string_suffix_length_ci (s1, s2, start1, end1, start2, end2)
3773 Return the length of the longest common suffix of the two
3774 strings, ignoring character case.
3777 @deffn {Scheme Procedure} string-prefix? s1 s2 [start1 [end1 [start2 [end2]]]]
3778 @deffnx {C Function} scm_string_prefix_p (s1, s2, start1, end1, start2, end2)
3779 Is @var{s1} a prefix of @var{s2}?
3782 @deffn {Scheme Procedure} string-prefix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3783 @deffnx {C Function} scm_string_prefix_ci_p (s1, s2, start1, end1, start2, end2)
3784 Is @var{s1} a prefix of @var{s2}, ignoring character case?
3787 @deffn {Scheme Procedure} string-suffix? s1 s2 [start1 [end1 [start2 [end2]]]]
3788 @deffnx {C Function} scm_string_suffix_p (s1, s2, start1, end1, start2, end2)
3789 Is @var{s1} a suffix of @var{s2}?
3792 @deffn {Scheme Procedure} string-suffix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3793 @deffnx {C Function} scm_string_suffix_ci_p (s1, s2, start1, end1, start2, end2)
3794 Is @var{s1} a suffix of @var{s2}, ignoring character case?
3797 @deffn {Scheme Procedure} string-index-right s char_pred [start [end]]
3798 @deffnx {C Function} scm_string_index_right (s, char_pred, start, end)
3799 Search through the string @var{s} from right to left, returning
3800 the index of the last occurrence of a character which
3804 equals @var{char_pred}, if it is character,
3807 satisfies the predicate @var{char_pred}, if it is a procedure,
3810 is in the set if @var{char_pred} is a character set.
3813 Return @code{#f} if no match is found.
3816 @deffn {Scheme Procedure} string-skip s char_pred [start [end]]
3817 @deffnx {C Function} scm_string_skip (s, char_pred, start, end)
3818 Search through the string @var{s} from left to right, returning
3819 the index of the first occurrence of a character which
3823 does not equal @var{char_pred}, if it is character,
3826 does not satisfy the predicate @var{char_pred}, if it is a
3830 is not in the set if @var{char_pred} is a character set.
3834 @deffn {Scheme Procedure} string-skip-right s char_pred [start [end]]
3835 @deffnx {C Function} scm_string_skip_right (s, char_pred, start, end)
3836 Search through the string @var{s} from right to left, returning
3837 the index of the last occurrence of a character which
3841 does not equal @var{char_pred}, if it is character,
3844 does not satisfy the predicate @var{char_pred}, if it is a
3848 is not in the set if @var{char_pred} is a character set.
3852 @deffn {Scheme Procedure} string-count s char_pred [start [end]]
3853 @deffnx {C Function} scm_string_count (s, char_pred, start, end)
3854 Return the count of the number of characters in the string
3859 equals @var{char_pred}, if it is character,
3862 satisfies the predicate @var{char_pred}, if it is a procedure.
3865 is in the set @var{char_pred}, if it is a character set.
3869 @deffn {Scheme Procedure} string-contains s1 s2 [start1 [end1 [start2 [end2]]]]
3870 @deffnx {C Function} scm_string_contains (s1, s2, start1, end1, start2, end2)
3871 Does string @var{s1} contain string @var{s2}? Return the index
3872 in @var{s1} where @var{s2} occurs as a substring, or false.
3873 The optional start/end indices restrict the operation to the
3874 indicated substrings.
3877 @deffn {Scheme Procedure} string-contains-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3878 @deffnx {C Function} scm_string_contains_ci (s1, s2, start1, end1, start2, end2)
3879 Does string @var{s1} contain string @var{s2}? Return the index
3880 in @var{s1} where @var{s2} occurs as a substring, or false.
3881 The optional start/end indices restrict the operation to the
3882 indicated substrings. Character comparison is done
3886 @node Alphabetic Case Mapping
3887 @subsubsection Alphabetic Case Mapping
3889 These are procedures for mapping strings to their upper- or lower-case
3890 equivalents, respectively, or for capitalizing strings.
3892 They use the basic case mapping rules for Unicode characters. No
3893 special language or context rules are considered. The resulting strings
3894 are guaranteed to be the same length as the input strings.
3896 @xref{Character Case Mapping, the @code{(ice-9
3897 i18n)} module}, for locale-dependent case conversions.
3899 @deffn {Scheme Procedure} string-upcase str [start [end]]
3900 @deffnx {C Function} scm_substring_upcase (str, start, end)
3901 @deffnx {C Function} scm_string_upcase (str)
3902 Upcase every character in @code{str}.
3905 @deffn {Scheme Procedure} string-upcase! str [start [end]]
3906 @deffnx {C Function} scm_substring_upcase_x (str, start, end)
3907 @deffnx {C Function} scm_string_upcase_x (str)
3908 Destructively upcase every character in @code{str}.
3918 @deffn {Scheme Procedure} string-downcase str [start [end]]
3919 @deffnx {C Function} scm_substring_downcase (str, start, end)
3920 @deffnx {C Function} scm_string_downcase (str)
3921 Downcase every character in @var{str}.
3924 @deffn {Scheme Procedure} string-downcase! str [start [end]]
3925 @deffnx {C Function} scm_substring_downcase_x (str, start, end)
3926 @deffnx {C Function} scm_string_downcase_x (str)
3927 Destructively downcase every character in @var{str}.
3932 (string-downcase! y)
3939 @deffn {Scheme Procedure} string-capitalize str
3940 @deffnx {C Function} scm_string_capitalize (str)
3941 Return a freshly allocated string with the characters in
3942 @var{str}, where the first character of every word is
3946 @deffn {Scheme Procedure} string-capitalize! str
3947 @deffnx {C Function} scm_string_capitalize_x (str)
3948 Upcase the first character of every word in @var{str}
3949 destructively and return @var{str}.
3952 y @result{} "hello world"
3953 (string-capitalize! y) @result{} "Hello World"
3954 y @result{} "Hello World"
3958 @deffn {Scheme Procedure} string-titlecase str [start [end]]
3959 @deffnx {C Function} scm_string_titlecase (str, start, end)
3960 Titlecase every first character in a word in @var{str}.
3963 @deffn {Scheme Procedure} string-titlecase! str [start [end]]
3964 @deffnx {C Function} scm_string_titlecase_x (str, start, end)
3965 Destructively titlecase every first character in a word in
3969 @node Reversing and Appending Strings
3970 @subsubsection Reversing and Appending Strings
3972 @deffn {Scheme Procedure} string-reverse str [start [end]]
3973 @deffnx {C Function} scm_string_reverse (str, start, end)
3974 Reverse the string @var{str}. The optional arguments
3975 @var{start} and @var{end} delimit the region of @var{str} to
3979 @deffn {Scheme Procedure} string-reverse! str [start [end]]
3980 @deffnx {C Function} scm_string_reverse_x (str, start, end)
3981 Reverse the string @var{str} in-place. The optional arguments
3982 @var{start} and @var{end} delimit the region of @var{str} to
3983 operate on. The return value is unspecified.
3986 @rnindex string-append
3987 @deffn {Scheme Procedure} string-append arg @dots{}
3988 @deffnx {C Function} scm_string_append (args)
3989 Return a newly allocated string whose characters form the
3990 concatenation of the given strings, @var{arg} @enddots{}.
3994 (string-append h "world"))
3995 @result{} "hello world"
3999 @deffn {Scheme Procedure} string-append/shared arg @dots{}
4000 @deffnx {C Function} scm_string_append_shared (args)
4001 Like @code{string-append}, but the result may share memory
4002 with the argument strings.
4005 @deffn {Scheme Procedure} string-concatenate ls
4006 @deffnx {C Function} scm_string_concatenate (ls)
4007 Append the elements (which must be strings) of @var{ls} together into a
4008 single string. Guaranteed to return a freshly allocated string.
4011 @deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]]
4012 @deffnx {C Function} scm_string_concatenate_reverse (ls, final_string, end)
4013 Without optional arguments, this procedure is equivalent to
4016 (string-concatenate (reverse ls))
4019 If the optional argument @var{final_string} is specified, it is
4020 consed onto the beginning to @var{ls} before performing the
4021 list-reverse and string-concatenate operations. If @var{end}
4022 is given, only the characters of @var{final_string} up to index
4025 Guaranteed to return a freshly allocated string.
4028 @deffn {Scheme Procedure} string-concatenate/shared ls
4029 @deffnx {C Function} scm_string_concatenate_shared (ls)
4030 Like @code{string-concatenate}, but the result may share memory
4031 with the strings in the list @var{ls}.
4034 @deffn {Scheme Procedure} string-concatenate-reverse/shared ls [final_string [end]]
4035 @deffnx {C Function} scm_string_concatenate_reverse_shared (ls, final_string, end)
4036 Like @code{string-concatenate-reverse}, but the result may
4037 share memory with the strings in the @var{ls} arguments.
4040 @node Mapping Folding and Unfolding
4041 @subsubsection Mapping, Folding, and Unfolding
4043 @deffn {Scheme Procedure} string-map proc s [start [end]]
4044 @deffnx {C Function} scm_string_map (proc, s, start, end)
4045 @var{proc} is a char->char procedure, it is mapped over
4046 @var{s}. The order in which the procedure is applied to the
4047 string elements is not specified.
4050 @deffn {Scheme Procedure} string-map! proc s [start [end]]
4051 @deffnx {C Function} scm_string_map_x (proc, s, start, end)
4052 @var{proc} is a char->char procedure, it is mapped over
4053 @var{s}. The order in which the procedure is applied to the
4054 string elements is not specified. The string @var{s} is
4055 modified in-place, the return value is not specified.
4058 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
4059 @deffnx {C Function} scm_string_for_each (proc, s, start, end)
4060 @var{proc} is mapped over @var{s} in left-to-right order. The
4061 return value is not specified.
4064 @deffn {Scheme Procedure} string-for-each-index proc s [start [end]]
4065 @deffnx {C Function} scm_string_for_each_index (proc, s, start, end)
4066 Call @code{(@var{proc} i)} for each index i in @var{s}, from left to
4069 For example, to change characters to alternately upper and lower case,
4072 (define str (string-copy "studly"))
4073 (string-for-each-index
4076 ((if (even? i) char-upcase char-downcase)
4077 (string-ref str i))))
4079 str @result{} "StUdLy"
4083 @deffn {Scheme Procedure} string-fold kons knil s [start [end]]
4084 @deffnx {C Function} scm_string_fold (kons, knil, s, start, end)
4085 Fold @var{kons} over the characters of @var{s}, with @var{knil}
4086 as the terminating element, from left to right. @var{kons}
4087 must expect two arguments: The actual character and the last
4088 result of @var{kons}' application.
4091 @deffn {Scheme Procedure} string-fold-right kons knil s [start [end]]
4092 @deffnx {C Function} scm_string_fold_right (kons, knil, s, start, end)
4093 Fold @var{kons} over the characters of @var{s}, with @var{knil}
4094 as the terminating element, from right to left. @var{kons}
4095 must expect two arguments: The actual character and the last
4096 result of @var{kons}' application.
4099 @deffn {Scheme Procedure} string-unfold p f g seed [base [make_final]]
4100 @deffnx {C Function} scm_string_unfold (p, f, g, seed, base, make_final)
4102 @item @var{g} is used to generate a series of @emph{seed}
4103 values from the initial @var{seed}: @var{seed}, (@var{g}
4104 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
4106 @item @var{p} tells us when to stop -- when it returns true
4107 when applied to one of these seed values.
4108 @item @var{f} maps each seed value to the corresponding
4109 character in the result string. These chars are assembled
4110 into the string in a left-to-right order.
4111 @item @var{base} is the optional initial/leftmost portion
4112 of the constructed string; it default to the empty
4114 @item @var{make_final} is applied to the terminal seed
4115 value (on which @var{p} returns true) to produce
4116 the final/rightmost portion of the constructed string.
4117 The default is nothing extra.
4121 @deffn {Scheme Procedure} string-unfold-right p f g seed [base [make_final]]
4122 @deffnx {C Function} scm_string_unfold_right (p, f, g, seed, base, make_final)
4124 @item @var{g} is used to generate a series of @emph{seed}
4125 values from the initial @var{seed}: @var{seed}, (@var{g}
4126 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
4128 @item @var{p} tells us when to stop -- when it returns true
4129 when applied to one of these seed values.
4130 @item @var{f} maps each seed value to the corresponding
4131 character in the result string. These chars are assembled
4132 into the string in a right-to-left order.
4133 @item @var{base} is the optional initial/rightmost portion
4134 of the constructed string; it default to the empty
4136 @item @var{make_final} is applied to the terminal seed
4137 value (on which @var{p} returns true) to produce
4138 the final/leftmost portion of the constructed string.
4139 It defaults to @code{(lambda (x) )}.
4143 @node Miscellaneous String Operations
4144 @subsubsection Miscellaneous String Operations
4146 @deffn {Scheme Procedure} xsubstring s from [to [start [end]]]
4147 @deffnx {C Function} scm_xsubstring (s, from, to, start, end)
4148 This is the @emph{extended substring} procedure that implements
4149 replicated copying of a substring of some string.
4151 @var{s} is a string, @var{start} and @var{end} are optional
4152 arguments that demarcate a substring of @var{s}, defaulting to
4153 0 and the length of @var{s}. Replicate this substring up and
4154 down index space, in both the positive and negative directions.
4155 @code{xsubstring} returns the substring of this string
4156 beginning at index @var{from}, and ending at @var{to}, which
4157 defaults to @var{from} + (@var{end} - @var{start}).
4160 @deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto [start [end]]]
4161 @deffnx {C Function} scm_string_xcopy_x (target, tstart, s, sfrom, sto, start, end)
4162 Exactly the same as @code{xsubstring}, but the extracted text
4163 is written into the string @var{target} starting at index
4164 @var{tstart}. The operation is not defined if @code{(eq?
4165 @var{target} @var{s})} or these arguments share storage -- you
4166 cannot copy a string on top of itself.
4169 @deffn {Scheme Procedure} string-replace s1 s2 [start1 [end1 [start2 [end2]]]]
4170 @deffnx {C Function} scm_string_replace (s1, s2, start1, end1, start2, end2)
4171 Return the string @var{s1}, but with the characters
4172 @var{start1} @dots{} @var{end1} replaced by the characters
4173 @var{start2} @dots{} @var{end2} from @var{s2}.
4176 @deffn {Scheme Procedure} string-tokenize s [token_set [start [end]]]
4177 @deffnx {C Function} scm_string_tokenize (s, token_set, start, end)
4178 Split the string @var{s} into a list of substrings, where each
4179 substring is a maximal non-empty contiguous sequence of
4180 characters from the character set @var{token_set}, which
4181 defaults to @code{char-set:graphic}.
4182 If @var{start} or @var{end} indices are provided, they restrict
4183 @code{string-tokenize} to operating on the indicated substring
4187 @deffn {Scheme Procedure} string-filter char_pred s [start [end]]
4188 @deffnx {C Function} scm_string_filter (char_pred, s, start, end)
4189 Filter the string @var{s}, retaining only those characters which
4190 satisfy @var{char_pred}.
4192 If @var{char_pred} is a procedure, it is applied to each character as
4193 a predicate, if it is a character, it is tested for equality and if it
4194 is a character set, it is tested for membership.
4197 @deffn {Scheme Procedure} string-delete char_pred s [start [end]]
4198 @deffnx {C Function} scm_string_delete (char_pred, s, start, end)
4199 Delete characters satisfying @var{char_pred} from @var{s}.
4201 If @var{char_pred} is a procedure, it is applied to each character as
4202 a predicate, if it is a character, it is tested for equality and if it
4203 is a character set, it is tested for membership.
4206 @node Representing Strings as Bytes
4207 @subsubsection Representing Strings as Bytes
4209 Out in the cold world outside of Guile, not all strings are treated in
4210 the same way. Out there there are only bytes, and there are many ways
4211 of representing a strings (sequences of characters) as binary data
4212 (sequences of bytes).
4214 As a user, usually you don't have to think about this very much. When
4215 you type on your keyboard, your system encodes your keystrokes as bytes
4216 according to the locale that you have configured on your computer.
4217 Guile uses the locale to decode those bytes back into characters --
4218 hopefully the same characters that you typed in.
4220 All is not so clear when dealing with a system with multiple users, such
4221 as a web server. Your web server might get a request from one user for
4222 data encoded in the ISO-8859-1 character set, and then another request
4223 from a different user for UTF-8 data.
4226 @cindex character encoding
4227 Guile provides an @dfn{iconv} module for converting between strings and
4228 sequences of bytes. @xref{Bytevectors}, for more on how Guile
4229 represents raw byte sequences. This module gets its name from the
4230 common @sc{unix} command of the same name.
4232 Note that often it is sufficient to just read and write strings from
4233 ports instead of using these functions. To do this, specify the port
4234 encoding using @code{set-port-encoding!}. @xref{Ports}, for more on
4235 ports and character encodings.
4237 Unlike the rest of the procedures in this section, you have to load the
4238 @code{iconv} module before having access to these procedures:
4241 (use-modules (ice-9 iconv))
4244 @deffn {Scheme Procedure} string->bytevector string encoding [conversion-strategy]
4245 Encode @var{string} as a sequence of bytes.
4247 The string will be encoded in the character set specified by the
4248 @var{encoding} string. If the string has characters that cannot be
4249 represented in the encoding, by default this procedure raises an
4250 @code{encoding-error}. Pass a @var{conversion-strategy} argument to
4251 specify other behaviors.
4253 The return value is a bytevector. @xref{Bytevectors}, for more on
4254 bytevectors. @xref{Ports}, for more on character encodings and
4255 conversion strategies.
4258 @deffn {Scheme Procedure} bytevector->string bytevector encoding [conversion-strategy]
4259 Decode @var{bytevector} into a string.
4261 The bytes will be decoded from the character set by the @var{encoding}
4262 string. If the bytes do not form a valid encoding, by default this
4263 procedure raises an @code{decoding-error}. As with
4264 @code{string->bytevector}, pass the optional @var{conversion-strategy}
4265 argument to modify this behavior. @xref{Ports}, for more on character
4266 encodings and conversion strategies.
4269 @deffn {Scheme Procedure} call-with-output-encoded-string encoding proc [conversion-strategy]
4270 Like @code{call-with-output-string}, but instead of returning a string,
4271 returns a encoding of the string according to @var{encoding}, as a
4272 bytevector. This procedure can be more efficient than collecting a
4273 string and then converting it via @code{string->bytevector}.
4276 @node Conversion to/from C
4277 @subsubsection Conversion to/from C
4279 When creating a Scheme string from a C string or when converting a
4280 Scheme string to a C string, the concept of character encoding becomes
4283 In C, a string is just a sequence of bytes, and the character encoding
4284 describes the relation between these bytes and the actual characters
4285 that make up the string. For Scheme strings, character encoding is not
4286 an issue (most of the time), since in Scheme you usually treat strings
4287 as character sequences, not byte sequences.
4289 Converting to C and converting from C each have their own challenges.
4291 When converting from C to Scheme, it is important that the sequence of
4292 bytes in the C string be valid with respect to its encoding. ASCII
4293 strings, for example, can't have any bytes greater than 127. An ASCII
4294 byte greater than 127 is considered @emph{ill-formed} and cannot be
4295 converted into a Scheme character.
4297 Problems can occur in the reverse operation as well. Not all character
4298 encodings can hold all possible Scheme characters. Some encodings, like
4299 ASCII for example, can only describe a small subset of all possible
4300 characters. So, when converting to C, one must first decide what to do
4301 with Scheme characters that can't be represented in the C string.
4303 Converting a Scheme string to a C string will often allocate fresh
4304 memory to hold the result. You must take care that this memory is
4305 properly freed eventually. In many cases, this can be achieved by
4306 using @code{scm_dynwind_free} inside an appropriate dynwind context,
4307 @xref{Dynamic Wind}.
4309 @deftypefn {C Function} SCM scm_from_locale_string (const char *str)
4310 @deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
4311 Creates a new Scheme string that has the same contents as @var{str} when
4312 interpreted in the character encoding of the current locale.
4314 For @code{scm_from_locale_string}, @var{str} must be null-terminated.
4316 For @code{scm_from_locale_stringn}, @var{len} specifies the length of
4317 @var{str} in bytes, and @var{str} does not need to be null-terminated.
4318 If @var{len} is @code{(size_t)-1}, then @var{str} does need to be
4319 null-terminated and the real length will be found with @code{strlen}.
4321 If the C string is ill-formed, an error will be raised.
4323 Note that these functions should @emph{not} be used to convert C string
4324 constants, because there is no guarantee that the current locale will
4325 match that of the execution character set, used for string and character
4326 constants. Most modern C compilers use UTF-8 by default, so to convert
4327 C string constants we recommend @code{scm_from_utf8_string}.
4330 @deftypefn {C Function} SCM scm_take_locale_string (char *str)
4331 @deftypefnx {C Function} SCM scm_take_locale_stringn (char *str, size_t len)
4332 Like @code{scm_from_locale_string} and @code{scm_from_locale_stringn},
4333 respectively, but also frees @var{str} with @code{free} eventually.
4334 Thus, you can use this function when you would free @var{str} anyway
4335 immediately after creating the Scheme string. In certain cases, Guile
4336 can then use @var{str} directly as its internal representation.
4339 @deftypefn {C Function} {char *} scm_to_locale_string (SCM str)
4340 @deftypefnx {C Function} {char *} scm_to_locale_stringn (SCM str, size_t *lenp)
4341 Returns a C string with the same contents as @var{str} in the character
4342 encoding of the current locale. The C string must be freed with
4343 @code{free} eventually, maybe by using @code{scm_dynwind_free},
4344 @xref{Dynamic Wind}.
4346 For @code{scm_to_locale_string}, the returned string is
4347 null-terminated and an error is signalled when @var{str} contains
4348 @code{#\nul} characters.
4350 For @code{scm_to_locale_stringn} and @var{lenp} not @code{NULL},
4351 @var{str} might contain @code{#\nul} characters and the length of the
4352 returned string in bytes is stored in @code{*@var{lenp}}. The
4353 returned string will not be null-terminated in this case. If
4354 @var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
4355 @code{scm_to_locale_string}.
4357 If a character in @var{str} cannot be represented in the character
4358 encoding of the current locale, the default port conversion strategy is
4359 used. @xref{Ports}, for more on conversion strategies.
4361 If the conversion strategy is @code{error}, an error will be raised. If
4362 it is @code{substitute}, a replacement character, such as a question
4363 mark, will be inserted in its place. If it is @code{escape}, a hex
4364 escape will be inserted in its place.
4367 @deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
4368 Puts @var{str} as a C string in the current locale encoding into the
4369 memory pointed to by @var{buf}. The buffer at @var{buf} has room for
4370 @var{max_len} bytes and @code{scm_to_local_stringbuf} will never store
4371 more than that. No terminating @code{'\0'} will be stored.
4373 The return value of @code{scm_to_locale_stringbuf} is the number of
4374 bytes that are needed for all of @var{str}, regardless of whether
4375 @var{buf} was large enough to hold them. Thus, when the return value
4376 is larger than @var{max_len}, only @var{max_len} bytes have been
4377 stored and you probably need to try again with a larger buffer.
4380 For most situations, string conversion should occur using the current
4381 locale, such as with the functions above. But there may be cases where
4382 one wants to convert strings from a character encoding other than the
4383 locale's character encoding. For these cases, the lower-level functions
4384 @code{scm_to_stringn} and @code{scm_from_stringn} are provided. These
4385 functions should seldom be necessary if one is properly using locales.
4387 @deftp {C Type} scm_t_string_failed_conversion_handler
4388 This is an enumerated type that can take one of three values:
4389 @code{SCM_FAILED_CONVERSION_ERROR},
4390 @code{SCM_FAILED_CONVERSION_QUESTION_MARK}, and
4391 @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE}. They are used to indicate
4392 a strategy for handling characters that cannot be converted to or from a
4393 given character encoding. @code{SCM_FAILED_CONVERSION_ERROR} indicates
4394 that a conversion should throw an error if some characters cannot be
4395 converted. @code{SCM_FAILED_CONVERSION_QUESTION_MARK} indicates that a
4396 conversion should replace unconvertable characters with the question
4397 mark character. And, @code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE}
4398 requests that a conversion should replace an unconvertable character
4399 with an escape sequence.
4401 While all three strategies apply when converting Scheme strings to C,
4402 only @code{SCM_FAILED_CONVERSION_ERROR} and
4403 @code{SCM_FAILED_CONVERSION_QUESTION_MARK} can be used when converting C
4407 @deftypefn {C Function} char *scm_to_stringn (SCM str, size_t *lenp, const char *encoding, scm_t_string_failed_conversion_handler handler)
4408 This function returns a newly allocated C string from the Guile string
4409 @var{str}. The length of the returned string in bytes will be returned in
4410 @var{lenp}. The character encoding of the C string is passed as the ASCII,
4411 null-terminated C string @var{encoding}. The @var{handler} parameter
4412 gives a strategy for dealing with characters that cannot be converted
4413 into @var{encoding}.
4415 If @var{lenp} is @code{NULL}, this function will return a null-terminated C
4416 string. It will throw an error if the string contains a null
4419 The Scheme interface to this function is @code{string->bytevector}, from the
4420 @code{ice-9 iconv} module. @xref{Representing Strings as Bytes}.
4423 @deftypefn {C Function} SCM scm_from_stringn (const char *str, size_t len, const char *encoding, scm_t_string_failed_conversion_handler handler)
4424 This function returns a scheme string from the C string @var{str}. The
4425 length in bytes of the C string is input as @var{len}. The encoding of the C
4426 string is passed as the ASCII, null-terminated C string @code{encoding}.
4427 The @var{handler} parameters suggests a strategy for dealing with
4428 unconvertable characters.
4430 The Scheme interface to this function is @code{bytevector->string}.
4431 @xref{Representing Strings as Bytes}.
4434 The following conversion functions are provided as a convenience for the
4435 most commonly used encodings.
4437 @deftypefn {C Function} SCM scm_from_latin1_string (const char *str)
4438 @deftypefnx {C Function} SCM scm_from_utf8_string (const char *str)
4439 @deftypefnx {C Function} SCM scm_from_utf32_string (const scm_t_wchar *str)
4440 Return a scheme string from the null-terminated C string @var{str},
4441 which is ISO-8859-1-, UTF-8-, or UTF-32-encoded. These functions should
4442 be used to convert hard-coded C string constants into Scheme strings.
4445 @deftypefn {C Function} SCM scm_from_latin1_stringn (const char *str, size_t len)
4446 @deftypefnx {C Function} SCM scm_from_utf8_stringn (const char *str, size_t len)
4447 @deftypefnx {C Function} SCM scm_from_utf32_stringn (const scm_t_wchar *str, size_t len)
4448 Return a scheme string from C string @var{str}, which is ISO-8859-1-,
4449 UTF-8-, or UTF-32-encoded, of length @var{len}. @var{len} is the number
4450 of bytes pointed to by @var{str} for @code{scm_from_latin1_stringn} and
4451 @code{scm_from_utf8_stringn}; it is the number of elements (code points)
4452 in @var{str} in the case of @code{scm_from_utf32_stringn}.
4455 @deftypefn {C function} char *scm_to_latin1_stringn (SCM str, size_t *lenp)
4456 @deftypefnx {C function} char *scm_to_utf8_stringn (SCM str, size_t *lenp)
4457 @deftypefnx {C function} scm_t_wchar *scm_to_utf32_stringn (SCM str, size_t *lenp)
4458 Return a newly allocated, ISO-8859-1-, UTF-8-, or UTF-32-encoded C string
4459 from Scheme string @var{str}. An error is thrown when @var{str}
4460 cannot be converted to the specified encoding. If @var{lenp} is
4461 @code{NULL}, the returned C string will be null terminated, and an error
4462 will be thrown if the C string would otherwise contain null
4463 characters. If @var{lenp} is not @code{NULL}, the string is not null terminated,
4464 and the length of the returned string is returned in @var{lenp}. The length
4465 returned is the number of bytes for @code{scm_to_latin1_stringn} and
4466 @code{scm_to_utf8_stringn}; it is the number of elements (code points)
4467 for @code{scm_to_utf32_stringn}.
4470 It is not often the case, but sometimes when you are dealing with the
4471 implementation details of a port, you need to encode and decode strings
4472 according to the encoding and conversion strategy of the port. There
4473 are some convenience functions for that purpose as well.
4475 @deftypefn {C Function} SCM scm_from_port_string (const char *str, SCM port)
4476 @deftypefnx {C Function} SCM scm_from_port_stringn (const char *str, size_t len, SCM port)
4477 @deftypefnx {C Function} char* scm_to_port_string (SCM str, SCM port)
4478 @deftypefnx {C Function} char* scm_to_port_stringn (SCM str, size_t *lenp, SCM port)
4479 Like @code{scm_from_stringn} and friends, except they take their
4480 encoding and conversion strategy from a given port object.
4483 @node String Internals
4484 @subsubsection String Internals
4486 Guile stores each string in memory as a contiguous array of Unicode code
4487 points along with an associated set of attributes. If all of the code
4488 points of a string have an integer range between 0 and 255 inclusive,
4489 the code point array is stored as one byte per code point: it is stored
4490 as an ISO-8859-1 (aka Latin-1) string. If any of the code points of the
4491 string has an integer value greater that 255, the code point array is
4492 stored as four bytes per code point: it is stored as a UTF-32 string.
4494 Conversion between the one-byte-per-code-point and
4495 four-bytes-per-code-point representations happens automatically as
4498 No API is provided to set the internal representation of strings;
4499 however, there are pair of procedures available to query it. These are
4500 debugging procedures. Using them in production code is discouraged,
4501 since the details of Guile's internal representation of strings may
4502 change from release to release.
4504 @deffn {Scheme Procedure} string-bytes-per-char str
4505 @deffnx {C Function} scm_string_bytes_per_char (str)
4506 Return the number of bytes used to encode a Unicode code point in string
4507 @var{str}. The result is one or four.
4510 @deffn {Scheme Procedure} %string-dump str
4511 @deffnx {C Function} scm_sys_string_dump (str)
4512 Returns an association list containing debugging information for
4513 @var{str}. The association list has the following entries.
4520 The start index of the string into its stringbuf
4523 The length of the string
4526 If this string is a substring, it returns its
4527 parent string. Otherwise, it returns @code{#f}
4530 @code{#t} if the string is read-only
4532 @item stringbuf-chars
4533 A new string containing this string's stringbuf's characters
4535 @item stringbuf-length
4536 The number of characters in this stringbuf
4538 @item stringbuf-shared
4539 @code{#t} if this stringbuf is shared
4541 @item stringbuf-wide
4542 @code{#t} if this stringbuf's characters are stored in a 32-bit buffer,
4543 or @code{#f} if they are stored in an 8-bit buffer
4549 @subsection Bytevectors
4554 A @dfn{bytevector} is a raw bit string. The @code{(rnrs bytevectors)}
4555 module provides the programming interface specified by the
4556 @uref{http://www.r6rs.org/, Revised^6 Report on the Algorithmic Language
4557 Scheme (R6RS)}. It contains procedures to manipulate bytevectors and
4558 interpret their contents in a number of ways: bytevector contents can be
4559 accessed as signed or unsigned integer of various sizes and endianness,
4560 as IEEE-754 floating point numbers, or as strings. It is a useful tool
4561 to encode and decode binary data.
4563 The R6RS (Section 4.3.4) specifies an external representation for
4564 bytevectors, whereby the octets (integers in the range 0--255) contained
4565 in the bytevector are represented as a list prefixed by @code{#vu8}:
4571 denotes a 3-byte bytevector containing the octets 1, 53, and 204. Like
4572 string literals, booleans, etc., bytevectors are ``self-quoting'', i.e.,
4573 they do not need to be quoted:
4577 @result{} #vu8(1 53 204)
4580 Bytevectors can be used with the binary input/output primitives of the
4581 R6RS (@pxref{R6RS I/O Ports}).
4584 * Bytevector Endianness:: Dealing with byte order.
4585 * Bytevector Manipulation:: Creating, copying, manipulating bytevectors.
4586 * Bytevectors as Integers:: Interpreting bytes as integers.
4587 * Bytevectors and Integer Lists:: Converting to/from an integer list.
4588 * Bytevectors as Floats:: Interpreting bytes as real numbers.
4589 * Bytevectors as Strings:: Interpreting bytes as Unicode strings.
4590 * Bytevectors as Arrays:: Guile extension to the bytevector API.
4591 * Bytevectors as Uniform Vectors:: Bytevectors and SRFI-4.
4594 @node Bytevector Endianness
4595 @subsubsection Endianness
4601 Some of the following procedures take an @var{endianness} parameter.
4602 The @dfn{endianness} is defined as the order of bytes in multi-byte
4603 numbers: numbers encoded in @dfn{big endian} have their most
4604 significant bytes written first, whereas numbers encoded in
4605 @dfn{little endian} have their least significant bytes
4606 first@footnote{Big-endian and little-endian are the most common
4607 ``endiannesses'', but others do exist. For instance, the GNU MP
4608 library allows @dfn{word order} to be specified independently of
4609 @dfn{byte order} (@pxref{Integer Import and Export,,, gmp, The GNU
4610 Multiple Precision Arithmetic Library Manual}).}.
4612 Little-endian is the native endianness of the IA32 architecture and
4613 its derivatives, while big-endian is native to SPARC and PowerPC,
4614 among others. The @code{native-endianness} procedure returns the
4615 native endianness of the machine it runs on.
4617 @deffn {Scheme Procedure} native-endianness
4618 @deffnx {C Function} scm_native_endianness ()
4619 Return a value denoting the native endianness of the host machine.
4622 @deffn {Scheme Macro} endianness symbol
4623 Return an object denoting the endianness specified by @var{symbol}. If
4624 @var{symbol} is neither @code{big} nor @code{little} then an error is
4625 raised at expand-time.
4628 @defvr {C Variable} scm_endianness_big
4629 @defvrx {C Variable} scm_endianness_little
4630 The objects denoting big- and little-endianness, respectively.
4634 @node Bytevector Manipulation
4635 @subsubsection Manipulating Bytevectors
4637 Bytevectors can be created, copied, and analyzed with the following
4638 procedures and C functions.
4640 @deffn {Scheme Procedure} make-bytevector len [fill]
4641 @deffnx {C Function} scm_make_bytevector (len, fill)
4642 @deffnx {C Function} scm_c_make_bytevector (size_t len)
4643 Return a new bytevector of @var{len} bytes. Optionally, if @var{fill}
4644 is given, fill it with @var{fill}; @var{fill} must be in the range
4648 @deffn {Scheme Procedure} bytevector? obj
4649 @deffnx {C Function} scm_bytevector_p (obj)
4650 Return true if @var{obj} is a bytevector.
4653 @deftypefn {C Function} int scm_is_bytevector (SCM obj)
4654 Equivalent to @code{scm_is_true (scm_bytevector_p (obj))}.
4657 @deffn {Scheme Procedure} bytevector-length bv
4658 @deffnx {C Function} scm_bytevector_length (bv)
4659 Return the length in bytes of bytevector @var{bv}.
4662 @deftypefn {C Function} size_t scm_c_bytevector_length (SCM bv)
4663 Likewise, return the length in bytes of bytevector @var{bv}.
4666 @deffn {Scheme Procedure} bytevector=? bv1 bv2
4667 @deffnx {C Function} scm_bytevector_eq_p (bv1, bv2)
4668 Return is @var{bv1} equals to @var{bv2}---i.e., if they have the same
4669 length and contents.
4672 @deffn {Scheme Procedure} bytevector-fill! bv fill
4673 @deffnx {C Function} scm_bytevector_fill_x (bv, fill)
4674 Fill bytevector @var{bv} with @var{fill}, a byte.
4677 @deffn {Scheme Procedure} bytevector-copy! source source-start target target-start len
4678 @deffnx {C Function} scm_bytevector_copy_x (source, source_start, target, target_start, len)
4679 Copy @var{len} bytes from @var{source} into @var{target}, starting
4680 reading from @var{source-start} (a positive index within @var{source})
4681 and start writing at @var{target-start}. It is permitted for the
4682 @var{source} and @var{target} regions to overlap.
4685 @deffn {Scheme Procedure} bytevector-copy bv
4686 @deffnx {C Function} scm_bytevector_copy (bv)
4687 Return a newly allocated copy of @var{bv}.
4690 @deftypefn {C Function} scm_t_uint8 scm_c_bytevector_ref (SCM bv, size_t index)
4691 Return the byte at @var{index} in bytevector @var{bv}.
4694 @deftypefn {C Function} void scm_c_bytevector_set_x (SCM bv, size_t index, scm_t_uint8 value)
4695 Set the byte at @var{index} in @var{bv} to @var{value}.
4698 Low-level C macros are available. They do not perform any
4699 type-checking; as such they should be used with care.
4701 @deftypefn {C Macro} size_t SCM_BYTEVECTOR_LENGTH (bv)
4702 Return the length in bytes of bytevector @var{bv}.
4705 @deftypefn {C Macro} {signed char *} SCM_BYTEVECTOR_CONTENTS (bv)
4706 Return a pointer to the contents of bytevector @var{bv}.
4710 @node Bytevectors as Integers
4711 @subsubsection Interpreting Bytevector Contents as Integers
4713 The contents of a bytevector can be interpreted as a sequence of
4714 integers of any given size, sign, and endianness.
4717 (let ((bv (make-bytevector 4)))
4718 (bytevector-u8-set! bv 0 #x12)
4719 (bytevector-u8-set! bv 1 #x34)
4720 (bytevector-u8-set! bv 2 #x56)
4721 (bytevector-u8-set! bv 3 #x78)
4723 (map (lambda (number)
4724 (number->string number 16))
4725 (list (bytevector-u8-ref bv 0)
4726 (bytevector-u16-ref bv 0 (endianness big))
4727 (bytevector-u32-ref bv 0 (endianness little)))))
4729 @result{} ("12" "1234" "78563412")
4732 The most generic procedures to interpret bytevector contents as integers
4733 are described below.
4735 @deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
4736 @deffnx {C Function} scm_bytevector_uint_ref (bv, index, endianness, size)
4737 Return the @var{size}-byte long unsigned integer at index @var{index} in
4738 @var{bv}, decoded according to @var{endianness}.
4741 @deffn {Scheme Procedure} bytevector-sint-ref bv index endianness size
4742 @deffnx {C Function} scm_bytevector_sint_ref (bv, index, endianness, size)
4743 Return the @var{size}-byte long signed integer at index @var{index} in
4744 @var{bv}, decoded according to @var{endianness}.
4747 @deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
4748 @deffnx {C Function} scm_bytevector_uint_set_x (bv, index, value, endianness, size)
4749 Set the @var{size}-byte long unsigned integer at @var{index} to
4750 @var{value}, encoded according to @var{endianness}.
4753 @deffn {Scheme Procedure} bytevector-sint-set! bv index value endianness size
4754 @deffnx {C Function} scm_bytevector_sint_set_x (bv, index, value, endianness, size)
4755 Set the @var{size}-byte long signed integer at @var{index} to
4756 @var{value}, encoded according to @var{endianness}.
4759 The following procedures are similar to the ones above, but specialized
4760 to a given integer size:
4762 @deffn {Scheme Procedure} bytevector-u8-ref bv index
4763 @deffnx {Scheme Procedure} bytevector-s8-ref bv index
4764 @deffnx {Scheme Procedure} bytevector-u16-ref bv index endianness
4765 @deffnx {Scheme Procedure} bytevector-s16-ref bv index endianness
4766 @deffnx {Scheme Procedure} bytevector-u32-ref bv index endianness
4767 @deffnx {Scheme Procedure} bytevector-s32-ref bv index endianness
4768 @deffnx {Scheme Procedure} bytevector-u64-ref bv index endianness
4769 @deffnx {Scheme Procedure} bytevector-s64-ref bv index endianness
4770 @deffnx {C Function} scm_bytevector_u8_ref (bv, index)
4771 @deffnx {C Function} scm_bytevector_s8_ref (bv, index)
4772 @deffnx {C Function} scm_bytevector_u16_ref (bv, index, endianness)
4773 @deffnx {C Function} scm_bytevector_s16_ref (bv, index, endianness)
4774 @deffnx {C Function} scm_bytevector_u32_ref (bv, index, endianness)
4775 @deffnx {C Function} scm_bytevector_s32_ref (bv, index, endianness)
4776 @deffnx {C Function} scm_bytevector_u64_ref (bv, index, endianness)
4777 @deffnx {C Function} scm_bytevector_s64_ref (bv, index, endianness)
4778 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
4779 16, 32 or 64) from @var{bv} at @var{index}, decoded according to
4783 @deffn {Scheme Procedure} bytevector-u8-set! bv index value
4784 @deffnx {Scheme Procedure} bytevector-s8-set! bv index value
4785 @deffnx {Scheme Procedure} bytevector-u16-set! bv index value endianness
4786 @deffnx {Scheme Procedure} bytevector-s16-set! bv index value endianness
4787 @deffnx {Scheme Procedure} bytevector-u32-set! bv index value endianness
4788 @deffnx {Scheme Procedure} bytevector-s32-set! bv index value endianness
4789 @deffnx {Scheme Procedure} bytevector-u64-set! bv index value endianness
4790 @deffnx {Scheme Procedure} bytevector-s64-set! bv index value endianness
4791 @deffnx {C Function} scm_bytevector_u8_set_x (bv, index, value)
4792 @deffnx {C Function} scm_bytevector_s8_set_x (bv, index, value)
4793 @deffnx {C Function} scm_bytevector_u16_set_x (bv, index, value, endianness)
4794 @deffnx {C Function} scm_bytevector_s16_set_x (bv, index, value, endianness)
4795 @deffnx {C Function} scm_bytevector_u32_set_x (bv, index, value, endianness)
4796 @deffnx {C Function} scm_bytevector_s32_set_x (bv, index, value, endianness)
4797 @deffnx {C Function} scm_bytevector_u64_set_x (bv, index, value, endianness)
4798 @deffnx {C Function} scm_bytevector_s64_set_x (bv, index, value, endianness)
4799 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
4800 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to
4804 Finally, a variant specialized for the host's endianness is available
4805 for each of these functions (with the exception of the @code{u8}
4806 accessors, for obvious reasons):
4808 @deffn {Scheme Procedure} bytevector-u16-native-ref bv index
4809 @deffnx {Scheme Procedure} bytevector-s16-native-ref bv index
4810 @deffnx {Scheme Procedure} bytevector-u32-native-ref bv index
4811 @deffnx {Scheme Procedure} bytevector-s32-native-ref bv index
4812 @deffnx {Scheme Procedure} bytevector-u64-native-ref bv index
4813 @deffnx {Scheme Procedure} bytevector-s64-native-ref bv index
4814 @deffnx {C Function} scm_bytevector_u16_native_ref (bv, index)
4815 @deffnx {C Function} scm_bytevector_s16_native_ref (bv, index)
4816 @deffnx {C Function} scm_bytevector_u32_native_ref (bv, index)
4817 @deffnx {C Function} scm_bytevector_s32_native_ref (bv, index)
4818 @deffnx {C Function} scm_bytevector_u64_native_ref (bv, index)
4819 @deffnx {C Function} scm_bytevector_s64_native_ref (bv, index)
4820 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
4821 16, 32 or 64) from @var{bv} at @var{index}, decoded according to the
4822 host's native endianness.
4825 @deffn {Scheme Procedure} bytevector-u16-native-set! bv index value
4826 @deffnx {Scheme Procedure} bytevector-s16-native-set! bv index value
4827 @deffnx {Scheme Procedure} bytevector-u32-native-set! bv index value
4828 @deffnx {Scheme Procedure} bytevector-s32-native-set! bv index value
4829 @deffnx {Scheme Procedure} bytevector-u64-native-set! bv index value
4830 @deffnx {Scheme Procedure} bytevector-s64-native-set! bv index value
4831 @deffnx {C Function} scm_bytevector_u16_native_set_x (bv, index, value)
4832 @deffnx {C Function} scm_bytevector_s16_native_set_x (bv, index, value)
4833 @deffnx {C Function} scm_bytevector_u32_native_set_x (bv, index, value)
4834 @deffnx {C Function} scm_bytevector_s32_native_set_x (bv, index, value)
4835 @deffnx {C Function} scm_bytevector_u64_native_set_x (bv, index, value)
4836 @deffnx {C Function} scm_bytevector_s64_native_set_x (bv, index, value)
4837 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
4838 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to the
4839 host's native endianness.
4843 @node Bytevectors and Integer Lists
4844 @subsubsection Converting Bytevectors to/from Integer Lists
4846 Bytevector contents can readily be converted to/from lists of signed or
4850 (bytevector->sint-list (u8-list->bytevector (make-list 4 255))
4851 (endianness little) 2)
4855 @deffn {Scheme Procedure} bytevector->u8-list bv
4856 @deffnx {C Function} scm_bytevector_to_u8_list (bv)
4857 Return a newly allocated list of unsigned 8-bit integers from the
4858 contents of @var{bv}.
4861 @deffn {Scheme Procedure} u8-list->bytevector lst
4862 @deffnx {C Function} scm_u8_list_to_bytevector (lst)
4863 Return a newly allocated bytevector consisting of the unsigned 8-bit
4864 integers listed in @var{lst}.
4867 @deffn {Scheme Procedure} bytevector->uint-list bv endianness size
4868 @deffnx {C Function} scm_bytevector_to_uint_list (bv, endianness, size)
4869 Return a list of unsigned integers of @var{size} bytes representing the
4870 contents of @var{bv}, decoded according to @var{endianness}.
4873 @deffn {Scheme Procedure} bytevector->sint-list bv endianness size
4874 @deffnx {C Function} scm_bytevector_to_sint_list (bv, endianness, size)
4875 Return a list of signed integers of @var{size} bytes representing the
4876 contents of @var{bv}, decoded according to @var{endianness}.
4879 @deffn {Scheme Procedure} uint-list->bytevector lst endianness size
4880 @deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
4881 Return a new bytevector containing the unsigned integers listed in
4882 @var{lst} and encoded on @var{size} bytes according to @var{endianness}.
4885 @deffn {Scheme Procedure} sint-list->bytevector lst endianness size
4886 @deffnx {C Function} scm_sint_list_to_bytevector (lst, endianness, size)
4887 Return a new bytevector containing the signed integers listed in
4888 @var{lst} and encoded on @var{size} bytes according to @var{endianness}.
4891 @node Bytevectors as Floats
4892 @subsubsection Interpreting Bytevector Contents as Floating Point Numbers
4894 @cindex IEEE-754 floating point numbers
4896 Bytevector contents can also be accessed as IEEE-754 single- or
4897 double-precision floating point numbers (respectively 32 and 64-bit
4898 long) using the procedures described here.
4900 @deffn {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
4901 @deffnx {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
4902 @deffnx {C Function} scm_bytevector_ieee_single_ref (bv, index, endianness)
4903 @deffnx {C Function} scm_bytevector_ieee_double_ref (bv, index, endianness)
4904 Return the IEEE-754 single-precision floating point number from @var{bv}
4905 at @var{index} according to @var{endianness}.
4908 @deffn {Scheme Procedure} bytevector-ieee-single-set! bv index value endianness
4909 @deffnx {Scheme Procedure} bytevector-ieee-double-set! bv index value endianness
4910 @deffnx {C Function} scm_bytevector_ieee_single_set_x (bv, index, value, endianness)
4911 @deffnx {C Function} scm_bytevector_ieee_double_set_x (bv, index, value, endianness)
4912 Store real number @var{value} in @var{bv} at @var{index} according to
4916 Specialized procedures are also available:
4918 @deffn {Scheme Procedure} bytevector-ieee-single-native-ref bv index
4919 @deffnx {Scheme Procedure} bytevector-ieee-double-native-ref bv index
4920 @deffnx {C Function} scm_bytevector_ieee_single_native_ref (bv, index)
4921 @deffnx {C Function} scm_bytevector_ieee_double_native_ref (bv, index)
4922 Return the IEEE-754 single-precision floating point number from @var{bv}
4923 at @var{index} according to the host's native endianness.
4926 @deffn {Scheme Procedure} bytevector-ieee-single-native-set! bv index value
4927 @deffnx {Scheme Procedure} bytevector-ieee-double-native-set! bv index value
4928 @deffnx {C Function} scm_bytevector_ieee_single_native_set_x (bv, index, value)
4929 @deffnx {C Function} scm_bytevector_ieee_double_native_set_x (bv, index, value)
4930 Store real number @var{value} in @var{bv} at @var{index} according to
4931 the host's native endianness.
4935 @node Bytevectors as Strings
4936 @subsubsection Interpreting Bytevector Contents as Unicode Strings
4938 @cindex Unicode string encoding
4940 Bytevector contents can also be interpreted as Unicode strings encoded
4941 in one of the most commonly available encoding formats.
4942 @xref{Representing Strings as Bytes}, for a more generic interface.
4945 (utf8->string (u8-list->bytevector '(99 97 102 101)))
4948 (string->utf8 "caf@'e") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT
4949 @result{} #vu8(99 97 102 195 169)
4952 @deffn {Scheme Procedure} string->utf8 str
4953 @deffnx {Scheme Procedure} string->utf16 str [endianness]
4954 @deffnx {Scheme Procedure} string->utf32 str [endianness]
4955 @deffnx {C Function} scm_string_to_utf8 (str)
4956 @deffnx {C Function} scm_string_to_utf16 (str, endianness)
4957 @deffnx {C Function} scm_string_to_utf32 (str, endianness)
4958 Return a newly allocated bytevector that contains the UTF-8, UTF-16, or
4959 UTF-32 (aka. UCS-4) encoding of @var{str}. For UTF-16 and UTF-32,
4960 @var{endianness} should be the symbol @code{big} or @code{little}; when omitted,
4961 it defaults to big endian.
4964 @deffn {Scheme Procedure} utf8->string utf
4965 @deffnx {Scheme Procedure} utf16->string utf [endianness]
4966 @deffnx {Scheme Procedure} utf32->string utf [endianness]
4967 @deffnx {C Function} scm_utf8_to_string (utf)
4968 @deffnx {C Function} scm_utf16_to_string (utf, endianness)
4969 @deffnx {C Function} scm_utf32_to_string (utf, endianness)
4970 Return a newly allocated string that contains from the UTF-8-, UTF-16-,
4971 or UTF-32-decoded contents of bytevector @var{utf}. For UTF-16 and UTF-32,
4972 @var{endianness} should be the symbol @code{big} or @code{little}; when omitted,
4973 it defaults to big endian.
4976 @node Bytevectors as Arrays
4977 @subsubsection Accessing Bytevectors with the Array API
4979 As an extension to the R6RS, Guile allows bytevectors to be manipulated
4980 with the @dfn{array} procedures (@pxref{Arrays}). When using these
4981 APIs, bytes are accessed one at a time as 8-bit unsigned integers:
4984 (define bv #vu8(0 1 2 3))
4995 ;; Note the different argument order on array-set!.
4996 (array-set! bv 77 2)
5005 @node Bytevectors as Uniform Vectors
5006 @subsubsection Accessing Bytevectors with the SRFI-4 API
5008 Bytevectors may also be accessed with the SRFI-4 API. @xref{SRFI-4 and
5009 Bytevectors}, for more information.
5016 Symbols in Scheme are widely used in three ways: as items of discrete
5017 data, as lookup keys for alists and hash tables, and to denote variable
5020 A @dfn{symbol} is similar to a string in that it is defined by a
5021 sequence of characters. The sequence of characters is known as the
5022 symbol's @dfn{name}. In the usual case --- that is, where the symbol's
5023 name doesn't include any characters that could be confused with other
5024 elements of Scheme syntax --- a symbol is written in a Scheme program by
5025 writing the sequence of characters that make up the name, @emph{without}
5026 any quotation marks or other special syntax. For example, the symbol
5027 whose name is ``multiply-by-2'' is written, simply:
5033 Notice how this differs from a @emph{string} with contents
5034 ``multiply-by-2'', which is written with double quotation marks, like
5041 Looking beyond how they are written, symbols are different from strings
5042 in two important respects.
5044 The first important difference is uniqueness. If the same-looking
5045 string is read twice from two different places in a program, the result
5046 is two @emph{different} string objects whose contents just happen to be
5047 the same. If, on the other hand, the same-looking symbol is read twice
5048 from two different places in a program, the result is the @emph{same}
5049 symbol object both times.
5051 Given two read symbols, you can use @code{eq?} to test whether they are
5052 the same (that is, have the same name). @code{eq?} is the most
5053 efficient comparison operator in Scheme, and comparing two symbols like
5054 this is as fast as comparing, for example, two numbers. Given two
5055 strings, on the other hand, you must use @code{equal?} or
5056 @code{string=?}, which are much slower comparison operators, to
5057 determine whether the strings have the same contents.
5060 (define sym1 (quote hello))
5061 (define sym2 (quote hello))
5062 (eq? sym1 sym2) @result{} #t
5064 (define str1 "hello")
5065 (define str2 "hello")
5066 (eq? str1 str2) @result{} #f
5067 (equal? str1 str2) @result{} #t
5070 The second important difference is that symbols, unlike strings, are not
5071 self-evaluating. This is why we need the @code{(quote @dots{})}s in the
5072 example above: @code{(quote hello)} evaluates to the symbol named
5073 "hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
5074 symbol named "hello" and evaluated as a variable reference @dots{} about
5075 which more below (@pxref{Symbol Variables}).
5078 * Symbol Data:: Symbols as discrete data.
5079 * Symbol Keys:: Symbols as lookup keys.
5080 * Symbol Variables:: Symbols as denoting variables.
5081 * Symbol Primitives:: Operations related to symbols.
5082 * Symbol Props:: Function slots and property lists.
5083 * Symbol Read Syntax:: Extended read syntax for symbols.
5084 * Symbol Uninterned:: Uninterned symbols.
5089 @subsubsection Symbols as Discrete Data
5091 Numbers and symbols are similar to the extent that they both lend
5092 themselves to @code{eq?} comparison. But symbols are more descriptive
5093 than numbers, because a symbol's name can be used directly to describe
5094 the concept for which that symbol stands.
5096 For example, imagine that you need to represent some colours in a
5097 computer program. Using numbers, you would have to choose arbitrarily
5098 some mapping between numbers and colours, and then take care to use that
5099 mapping consistently:
5102 ;; 1=red, 2=green, 3=purple
5104 (if (eq? (colour-of car) 1)
5109 You can make the mapping more explicit and the code more readable by
5117 (if (eq? (colour-of car) red)
5122 But the simplest and clearest approach is not to use numbers at all, but
5123 symbols whose names specify the colours that they refer to:
5126 (if (eq? (colour-of car) 'red)
5130 The descriptive advantages of symbols over numbers increase as the set
5131 of concepts that you want to describe grows. Suppose that a car object
5132 can have other properties as well, such as whether it has or uses:
5136 automatic or manual transmission
5138 leaded or unleaded fuel
5140 power steering (or not).
5144 Then a car's combined property set could be naturally represented and
5145 manipulated as a list of symbols:
5148 (properties-of car1)
5150 (red manual unleaded power-steering)
5152 (if (memq 'power-steering (properties-of car1))
5153 (display "Unfit people can drive this car.\n")
5154 (display "You'll need strong arms to drive this car!\n"))
5156 Unfit people can drive this car.
5159 Remember, the fundamental property of symbols that we are relying on
5160 here is that an occurrence of @code{'red} in one part of a program is an
5161 @emph{indistinguishable} symbol from an occurrence of @code{'red} in
5162 another part of a program; this means that symbols can usefully be
5163 compared using @code{eq?}. At the same time, symbols have naturally
5164 descriptive names. This combination of efficiency and descriptive power
5165 makes them ideal for use as discrete data.
5169 @subsubsection Symbols as Lookup Keys
5171 Given their efficiency and descriptive power, it is natural to use
5172 symbols as the keys in an association list or hash table.
5174 To illustrate this, consider a more structured representation of the car
5175 properties example from the preceding subsection. Rather than
5176 mixing all the properties up together in a flat list, we could use an
5177 association list like this:
5180 (define car1-properties '((colour . red)
5181 (transmission . manual)
5183 (steering . power-assisted)))
5186 Notice how this structure is more explicit and extensible than the flat
5187 list. For example it makes clear that @code{manual} refers to the
5188 transmission rather than, say, the windows or the locking of the car.
5189 It also allows further properties to use the same symbols among their
5190 possible values without becoming ambiguous:
5193 (define car1-properties '((colour . red)
5194 (transmission . manual)
5196 (steering . power-assisted)
5198 (locking . manual)))
5201 With a representation like this, it is easy to use the efficient
5202 @code{assq-XXX} family of procedures (@pxref{Association Lists}) to
5203 extract or change individual pieces of information:
5206 (assq-ref car1-properties 'fuel) @result{} unleaded
5207 (assq-ref car1-properties 'transmission) @result{} manual
5209 (assq-set! car1-properties 'seat-colour 'black)
5212 (transmission . manual)
5214 (steering . power-assisted)
5215 (seat-colour . black)
5216 (locking . manual)))
5219 Hash tables also have keys, and exactly the same arguments apply to the
5220 use of symbols in hash tables as in association lists. The hash value
5221 that Guile uses to decide where to add a symbol-keyed entry to a hash
5222 table can be obtained by calling the @code{symbol-hash} procedure:
5224 @deffn {Scheme Procedure} symbol-hash symbol
5225 @deffnx {C Function} scm_symbol_hash (symbol)
5226 Return a hash value for @var{symbol}.
5229 See @ref{Hash Tables} for information about hash tables in general, and
5230 for why you might choose to use a hash table rather than an association
5234 @node Symbol Variables
5235 @subsubsection Symbols as Denoting Variables
5237 When an unquoted symbol in a Scheme program is evaluated, it is
5238 interpreted as a variable reference, and the result of the evaluation is
5239 the appropriate variable's value.
5241 For example, when the expression @code{(string-length "abcd")} is read
5242 and evaluated, the sequence of characters @code{string-length} is read
5243 as the symbol whose name is "string-length". This symbol is associated
5244 with a variable whose value is the procedure that implements string
5245 length calculation. Therefore evaluation of the @code{string-length}
5246 symbol results in that procedure.
5248 The details of the connection between an unquoted symbol and the
5249 variable to which it refers are explained elsewhere. See @ref{Binding
5250 Constructs}, for how associations between symbols and variables are
5251 created, and @ref{Modules}, for how those associations are affected by
5252 Guile's module system.
5255 @node Symbol Primitives
5256 @subsubsection Operations Related to Symbols
5258 Given any Scheme value, you can determine whether it is a symbol using
5259 the @code{symbol?} primitive:
5262 @deffn {Scheme Procedure} symbol? obj
5263 @deffnx {C Function} scm_symbol_p (obj)
5264 Return @code{#t} if @var{obj} is a symbol, otherwise return
5268 @deftypefn {C Function} int scm_is_symbol (SCM val)
5269 Equivalent to @code{scm_is_true (scm_symbol_p (val))}.
5272 Once you know that you have a symbol, you can obtain its name as a
5273 string by calling @code{symbol->string}. Note that Guile differs by
5274 default from R5RS on the details of @code{symbol->string} as regards
5277 @rnindex symbol->string
5278 @deffn {Scheme Procedure} symbol->string s
5279 @deffnx {C Function} scm_symbol_to_string (s)
5280 Return the name of symbol @var{s} as a string. By default, Guile reads
5281 symbols case-sensitively, so the string returned will have the same case
5282 variation as the sequence of characters that caused @var{s} to be
5285 If Guile is set to read symbols case-insensitively (as specified by
5286 R5RS), and @var{s} comes into being as part of a literal expression
5287 (@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
5288 by a call to the @code{read} or @code{string-ci->symbol} procedures,
5289 Guile converts any alphabetic characters in the symbol's name to
5290 lower case before creating the symbol object, so the string returned
5291 here will be in lower case.
5293 If @var{s} was created by @code{string->symbol}, the case of characters
5294 in the string returned will be the same as that in the string that was
5295 passed to @code{string->symbol}, regardless of Guile's case-sensitivity
5296 setting at the time @var{s} was created.
5298 It is an error to apply mutation procedures like @code{string-set!} to
5299 strings returned by this procedure.
5302 Most symbols are created by writing them literally in code. However it
5303 is also possible to create symbols programmatically using the following
5306 @deffn {Scheme Procedure} symbol char@dots{}
5308 Return a newly allocated symbol made from the given character arguments.
5311 (symbol #\x #\y #\z) @result{} xyz
5315 @deffn {Scheme Procedure} list->symbol lst
5316 @rnindex list->symbol
5317 Return a newly allocated symbol made from a list of characters.
5320 (list->symbol '(#\a #\b #\c)) @result{} abc
5324 @rnindex symbol-append
5325 @deffn {Scheme Procedure} symbol-append arg @dots{}
5326 Return a newly allocated symbol whose characters form the
5327 concatenation of the given symbols, @var{arg} @enddots{}.
5331 (symbol-append h 'world))
5332 @result{} helloworld
5336 @rnindex string->symbol
5337 @deffn {Scheme Procedure} string->symbol string
5338 @deffnx {C Function} scm_string_to_symbol (string)
5339 Return the symbol whose name is @var{string}. This procedure can create
5340 symbols with names containing special characters or letters in the
5341 non-standard case, but it is usually a bad idea to create such symbols
5342 because in some implementations of Scheme they cannot be read as
5346 @deffn {Scheme Procedure} string-ci->symbol str
5347 @deffnx {C Function} scm_string_ci_to_symbol (str)
5348 Return the symbol whose name is @var{str}. If Guile is currently
5349 reading symbols case-insensitively, @var{str} is converted to lowercase
5350 before the returned symbol is looked up or created.
5353 The following examples illustrate Guile's detailed behaviour as regards
5354 the case-sensitivity of symbols:
5357 (read-enable 'case-insensitive) ; R5RS compliant behaviour
5359 (symbol->string 'flying-fish) @result{} "flying-fish"
5360 (symbol->string 'Martin) @result{} "martin"
5362 (string->symbol "Malvina")) @result{} "Malvina"
5364 (eq? 'mISSISSIppi 'mississippi) @result{} #t
5365 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
5366 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
5368 (string->symbol (symbol->string 'LolliPop))) @result{} #t
5369 (string=? "K. Harper, M.D."
5371 (string->symbol "K. Harper, M.D."))) @result{} #t
5373 (read-disable 'case-insensitive) ; Guile default behaviour
5375 (symbol->string 'flying-fish) @result{} "flying-fish"
5376 (symbol->string 'Martin) @result{} "Martin"
5378 (string->symbol "Malvina")) @result{} "Malvina"
5380 (eq? 'mISSISSIppi 'mississippi) @result{} #f
5381 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
5382 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
5384 (string->symbol (symbol->string 'LolliPop))) @result{} #t
5385 (string=? "K. Harper, M.D."
5387 (string->symbol "K. Harper, M.D."))) @result{} #t
5390 From C, there are lower level functions that construct a Scheme symbol
5391 from a C string in the current locale encoding.
5393 When you want to do more from C, you should convert between symbols
5394 and strings using @code{scm_symbol_to_string} and
5395 @code{scm_string_to_symbol} and work with the strings.
5397 @deftypefn {C Function} SCM scm_from_latin1_symbol (const char *name)
5398 @deftypefnx {C Function} SCM scm_from_utf8_symbol (const char *name)
5399 Construct and return a Scheme symbol whose name is specified by the
5400 null-terminated C string @var{name}. These are appropriate when
5401 the C string is hard-coded in the source code.
5404 @deftypefn {C Function} SCM scm_from_locale_symbol (const char *name)
5405 @deftypefnx {C Function} SCM scm_from_locale_symboln (const char *name, size_t len)
5406 Construct and return a Scheme symbol whose name is specified by
5407 @var{name}. For @code{scm_from_locale_symbol}, @var{name} must be null
5408 terminated; for @code{scm_from_locale_symboln} the length of @var{name} is
5409 specified explicitly by @var{len}.
5411 Note that these functions should @emph{not} be used when @var{name} is a
5412 C string constant, because there is no guarantee that the current locale
5413 will match that of the execution character set, used for string and
5414 character constants. Most modern C compilers use UTF-8 by default, so
5415 in such cases we recommend @code{scm_from_utf8_symbol}.
5418 @deftypefn {C Function} SCM scm_take_locale_symbol (char *str)
5419 @deftypefnx {C Function} SCM scm_take_locale_symboln (char *str, size_t len)
5420 Like @code{scm_from_locale_symbol} and @code{scm_from_locale_symboln},
5421 respectively, but also frees @var{str} with @code{free} eventually.
5422 Thus, you can use this function when you would free @var{str} anyway
5423 immediately after creating the Scheme string. In certain cases, Guile
5424 can then use @var{str} directly as its internal representation.
5427 The size of a symbol can also be obtained from C:
5429 @deftypefn {C Function} size_t scm_c_symbol_length (SCM sym)
5430 Return the number of characters in @var{sym}.
5433 Finally, some applications, especially those that generate new Scheme
5434 code dynamically, need to generate symbols for use in the generated
5435 code. The @code{gensym} primitive meets this need:
5437 @deffn {Scheme Procedure} gensym [prefix]
5438 @deffnx {C Function} scm_gensym (prefix)
5439 Create a new symbol with a name constructed from a prefix and a counter
5440 value. The string @var{prefix} can be specified as an optional
5441 argument. Default prefix is @samp{@w{ g}}. The counter is increased by 1
5442 at each call. There is no provision for resetting the counter.
5445 The symbols generated by @code{gensym} are @emph{likely} to be unique,
5446 since their names begin with a space and it is only otherwise possible
5447 to generate such symbols if a programmer goes out of their way to do
5448 so. Uniqueness can be guaranteed by instead using uninterned symbols
5449 (@pxref{Symbol Uninterned}), though they can't be usefully written out
5454 @subsubsection Function Slots and Property Lists
5456 In traditional Lisp dialects, symbols are often understood as having
5457 three kinds of value at once:
5461 a @dfn{variable} value, which is used when the symbol appears in
5462 code in a variable reference context
5465 a @dfn{function} value, which is used when the symbol appears in
5466 code in a function name position (i.e.@: as the first element in an
5470 a @dfn{property list} value, which is used when the symbol is given as
5471 the first argument to Lisp's @code{put} or @code{get} functions.
5474 Although Scheme (as one of its simplifications with respect to Lisp)
5475 does away with the distinction between variable and function namespaces,
5476 Guile currently retains some elements of the traditional structure in
5477 case they turn out to be useful when implementing translators for other
5478 languages, in particular Emacs Lisp.
5480 Specifically, Guile symbols have two extra slots, one for a symbol's
5481 property list, and one for its ``function value.'' The following procedures
5482 are provided to access these slots.
5484 @deffn {Scheme Procedure} symbol-fref symbol
5485 @deffnx {C Function} scm_symbol_fref (symbol)
5486 Return the contents of @var{symbol}'s @dfn{function slot}.
5489 @deffn {Scheme Procedure} symbol-fset! symbol value
5490 @deffnx {C Function} scm_symbol_fset_x (symbol, value)
5491 Set the contents of @var{symbol}'s function slot to @var{value}.
5494 @deffn {Scheme Procedure} symbol-pref symbol
5495 @deffnx {C Function} scm_symbol_pref (symbol)
5496 Return the @dfn{property list} currently associated with @var{symbol}.
5499 @deffn {Scheme Procedure} symbol-pset! symbol value
5500 @deffnx {C Function} scm_symbol_pset_x (symbol, value)
5501 Set @var{symbol}'s property list to @var{value}.
5504 @deffn {Scheme Procedure} symbol-property sym prop
5505 From @var{sym}'s property list, return the value for property
5506 @var{prop}. The assumption is that @var{sym}'s property list is an
5507 association list whose keys are distinguished from each other using
5508 @code{equal?}; @var{prop} should be one of the keys in that list. If
5509 the property list has no entry for @var{prop}, @code{symbol-property}
5513 @deffn {Scheme Procedure} set-symbol-property! sym prop val
5514 In @var{sym}'s property list, set the value for property @var{prop} to
5515 @var{val}, or add a new entry for @var{prop}, with value @var{val}, if
5516 none already exists. For the structure of the property list, see
5517 @code{symbol-property}.
5520 @deffn {Scheme Procedure} symbol-property-remove! sym prop
5521 From @var{sym}'s property list, remove the entry for property
5522 @var{prop}, if there is one. For the structure of the property list,
5523 see @code{symbol-property}.
5526 Support for these extra slots may be removed in a future release, and it
5527 is probably better to avoid using them. For a more modern and Schemely
5528 approach to properties, see @ref{Object Properties}.
5531 @node Symbol Read Syntax
5532 @subsubsection Extended Read Syntax for Symbols
5534 The read syntax for a symbol is a sequence of letters, digits, and
5535 @dfn{extended alphabetic characters}, beginning with a character that
5536 cannot begin a number. In addition, the special cases of @code{+},
5537 @code{-}, and @code{...} are read as symbols even though numbers can
5538 begin with @code{+}, @code{-} or @code{.}.
5540 Extended alphabetic characters may be used within identifiers as if
5541 they were letters. The set of extended alphabetic characters is:
5544 ! $ % & * + - . / : < = > ? @@ ^ _ ~
5547 In addition to the standard read syntax defined above (which is taken
5548 from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
5549 Scheme})), Guile provides an extended symbol read syntax that allows the
5550 inclusion of unusual characters such as space characters, newlines and
5551 parentheses. If (for whatever reason) you need to write a symbol
5552 containing characters not mentioned above, you can do so as follows.
5556 Begin the symbol with the characters @code{#@{},
5559 write the characters of the symbol and
5562 finish the symbol with the characters @code{@}#}.
5565 Here are a few examples of this form of read syntax. The first symbol
5566 needs to use extended syntax because it contains a space character, the
5567 second because it contains a line break, and the last because it looks
5579 Although Guile provides this extended read syntax for symbols,
5580 widespread usage of it is discouraged because it is not portable and not
5584 @node Symbol Uninterned
5585 @subsubsection Uninterned Symbols
5587 What makes symbols useful is that they are automatically kept unique.
5588 There are no two symbols that are distinct objects but have the same
5589 name. But of course, there is no rule without exception. In addition
5590 to the normal symbols that have been discussed up to now, you can also
5591 create special @dfn{uninterned} symbols that behave slightly
5594 To understand what is different about them and why they might be useful,
5595 we look at how normal symbols are actually kept unique.
5597 Whenever Guile wants to find the symbol with a specific name, for
5598 example during @code{read} or when executing @code{string->symbol}, it
5599 first looks into a table of all existing symbols to find out whether a
5600 symbol with the given name already exists. When this is the case, Guile
5601 just returns that symbol. When not, a new symbol with the name is
5602 created and entered into the table so that it can be found later.
5604 Sometimes you might want to create a symbol that is guaranteed `fresh',
5605 i.e.@: a symbol that did not exist previously. You might also want to
5606 somehow guarantee that no one else will ever unintentionally stumble
5607 across your symbol in the future. These properties of a symbol are
5608 often needed when generating code during macro expansion. When
5609 introducing new temporary variables, you want to guarantee that they
5610 don't conflict with variables in other people's code.
5612 The simplest way to arrange for this is to create a new symbol but
5613 not enter it into the global table of all symbols. That way, no one
5614 will ever get access to your symbol by chance. Symbols that are not in
5615 the table are called @dfn{uninterned}. Of course, symbols that
5616 @emph{are} in the table are called @dfn{interned}.
5618 You create new uninterned symbols with the function @code{make-symbol}.
5619 You can test whether a symbol is interned or not with
5620 @code{symbol-interned?}.
5622 Uninterned symbols break the rule that the name of a symbol uniquely
5623 identifies the symbol object. Because of this, they can not be written
5624 out and read back in like interned symbols. Currently, Guile has no
5625 support for reading uninterned symbols. Note that the function
5626 @code{gensym} does not return uninterned symbols for this reason.
5628 @deffn {Scheme Procedure} make-symbol name
5629 @deffnx {C Function} scm_make_symbol (name)
5630 Return a new uninterned symbol with the name @var{name}. The returned
5631 symbol is guaranteed to be unique and future calls to
5632 @code{string->symbol} will not return it.
5635 @deffn {Scheme Procedure} symbol-interned? symbol
5636 @deffnx {C Function} scm_symbol_interned_p (symbol)
5637 Return @code{#t} if @var{symbol} is interned, otherwise return
5644 (define foo-1 (string->symbol "foo"))
5645 (define foo-2 (string->symbol "foo"))
5646 (define foo-3 (make-symbol "foo"))
5647 (define foo-4 (make-symbol "foo"))
5651 ; Two interned symbols with the same name are the same object,
5655 ; but a call to make-symbol with the same name returns a
5660 ; A call to make-symbol always returns a new object, even for
5664 @result{} #<uninterned-symbol foo 8085290>
5665 ; Uninterned symbols print differently from interned symbols,
5669 ; but they are still symbols,
5671 (symbol-interned? foo-3)
5673 ; just not interned.
5678 @subsection Keywords
5681 Keywords are self-evaluating objects with a convenient read syntax that
5682 makes them easy to type.
5684 Guile's keyword support conforms to R5RS, and adds a (switchable) read
5685 syntax extension to permit keywords to begin with @code{:} as well as
5686 @code{#:}, or to end with @code{:}.
5689 * Why Use Keywords?:: Motivation for keyword usage.
5690 * Coding With Keywords:: How to use keywords.
5691 * Keyword Read Syntax:: Read syntax for keywords.
5692 * Keyword Procedures:: Procedures for dealing with keywords.
5695 @node Why Use Keywords?
5696 @subsubsection Why Use Keywords?
5698 Keywords are useful in contexts where a program or procedure wants to be
5699 able to accept a large number of optional arguments without making its
5700 interface unmanageable.
5702 To illustrate this, consider a hypothetical @code{make-window}
5703 procedure, which creates a new window on the screen for drawing into
5704 using some graphical toolkit. There are many parameters that the caller
5705 might like to specify, but which could also be sensibly defaulted, for
5710 color depth -- Default: the color depth for the screen
5713 background color -- Default: white
5716 width -- Default: 600
5719 height -- Default: 400
5722 If @code{make-window} did not use keywords, the caller would have to
5723 pass in a value for each possible argument, remembering the correct
5724 argument order and using a special value to indicate the default value
5728 (make-window 'default ;; Color depth
5729 'default ;; Background color
5732 @dots{}) ;; More make-window arguments
5735 With keywords, on the other hand, defaulted arguments are omitted, and
5736 non-default arguments are clearly tagged by the appropriate keyword. As
5737 a result, the invocation becomes much clearer:
5740 (make-window #:width 800 #:height 100)
5743 On the other hand, for a simpler procedure with few arguments, the use
5744 of keywords would be a hindrance rather than a help. The primitive
5745 procedure @code{cons}, for example, would not be improved if it had to
5749 (cons #:car x #:cdr y)
5752 So the decision whether to use keywords or not is purely pragmatic: use
5753 them if they will clarify the procedure invocation at point of call.
5755 @node Coding With Keywords
5756 @subsubsection Coding With Keywords
5758 If a procedure wants to support keywords, it should take a rest argument
5759 and then use whatever means is convenient to extract keywords and their
5760 corresponding arguments from the contents of that rest argument.
5762 The following example illustrates the principle: the code for
5763 @code{make-window} uses a helper procedure called
5764 @code{get-keyword-value} to extract individual keyword arguments from
5768 (define (get-keyword-value args keyword default)
5769 (let ((kv (memq keyword args)))
5770 (if (and kv (>= (length kv) 2))
5774 (define (make-window . args)
5775 (let ((depth (get-keyword-value args #:depth screen-depth))
5776 (bg (get-keyword-value args #:bg "white"))
5777 (width (get-keyword-value args #:width 800))
5778 (height (get-keyword-value args #:height 100))
5783 But you don't need to write @code{get-keyword-value}. The @code{(ice-9
5784 optargs)} module provides a set of powerful macros that you can use to
5785 implement keyword-supporting procedures like this:
5788 (use-modules (ice-9 optargs))
5790 (define (make-window . args)
5791 (let-keywords args #f ((depth screen-depth)
5799 Or, even more economically, like this:
5802 (use-modules (ice-9 optargs))
5804 (define* (make-window #:key (depth screen-depth)
5811 For further details on @code{let-keywords}, @code{define*} and other
5812 facilities provided by the @code{(ice-9 optargs)} module, see
5813 @ref{Optional Arguments}.
5815 To handle keyword arguments from procedures implemented in C,
5816 use @code{scm_c_bind_keyword_arguments} (@pxref{Keyword Procedures}).
5818 @node Keyword Read Syntax
5819 @subsubsection Keyword Read Syntax
5821 Guile, by default, only recognizes a keyword syntax that is compatible
5822 with R5RS. A token of the form @code{#:NAME}, where @code{NAME} has the
5823 same syntax as a Scheme symbol (@pxref{Symbol Read Syntax}), is the
5824 external representation of the keyword named @code{NAME}. Keyword
5825 objects print using this syntax as well, so values containing keyword
5826 objects can be read back into Guile. When used in an expression,
5827 keywords are self-quoting objects.
5829 If the @code{keyword} read option is set to @code{'prefix}, Guile also
5830 recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
5831 of the form @code{:NAME} are read as symbols, as required by R5RS.
5833 @cindex SRFI-88 keyword syntax
5835 If the @code{keyword} read option is set to @code{'postfix}, Guile
5836 recognizes the SRFI-88 read syntax @code{NAME:} (@pxref{SRFI-88}).
5837 Otherwise, tokens of this form are read as symbols.
5839 To enable and disable the alternative non-R5RS keyword syntax, you use
5840 the @code{read-set!} procedure documented @ref{Scheme Read}. Note that
5841 the @code{prefix} and @code{postfix} syntax are mutually exclusive.
5844 (read-set! keywords 'prefix)
5854 (read-set! keywords 'postfix)
5864 (read-set! keywords #f)
5872 ERROR: In expression :type:
5873 ERROR: Unbound variable: :type
5874 ABORT: (unbound-variable)
5877 @node Keyword Procedures
5878 @subsubsection Keyword Procedures
5880 @deffn {Scheme Procedure} keyword? obj
5881 @deffnx {C Function} scm_keyword_p (obj)
5882 Return @code{#t} if the argument @var{obj} is a keyword, else
5886 @deffn {Scheme Procedure} keyword->symbol keyword
5887 @deffnx {C Function} scm_keyword_to_symbol (keyword)
5888 Return the symbol with the same name as @var{keyword}.
5891 @deffn {Scheme Procedure} symbol->keyword symbol
5892 @deffnx {C Function} scm_symbol_to_keyword (symbol)
5893 Return the keyword with the same name as @var{symbol}.
5896 @deftypefn {C Function} int scm_is_keyword (SCM obj)
5897 Equivalent to @code{scm_is_true (scm_keyword_p (@var{obj}))}.
5900 @deftypefn {C Function} SCM scm_from_locale_keyword (const char *name)
5901 @deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *name, size_t len)
5902 Equivalent to @code{scm_symbol_to_keyword (scm_from_locale_symbol
5903 (@var{name}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln
5904 (@var{name}, @var{len}))}, respectively.
5906 Note that these functions should @emph{not} be used when @var{name} is a
5907 C string constant, because there is no guarantee that the current locale
5908 will match that of the execution character set, used for string and
5909 character constants. Most modern C compilers use UTF-8 by default, so
5910 in such cases we recommend @code{scm_from_utf8_keyword}.
5913 @deftypefn {C Function} SCM scm_from_latin1_keyword (const char *name)
5914 @deftypefnx {C Function} SCM scm_from_utf8_keyword (const char *name)
5915 Equivalent to @code{scm_symbol_to_keyword (scm_from_latin1_symbol
5916 (@var{name}))} and @code{scm_symbol_to_keyword (scm_from_utf8_symbol
5917 (@var{name}))}, respectively.
5920 @deftypefn {C Function} void scm_c_bind_keyword_arguments (const char *subr, @
5921 SCM rest, scm_t_keyword_arguments_flags flags, @
5922 SCM keyword1, SCM *argp1, @
5924 SCM keywordN, SCM *argpN, @
5925 @nicode{SCM_UNDEFINED})
5927 Extract the specified keyword arguments from @var{rest}, which is not
5928 modified. If the keyword argument @var{keyword1} is present in
5929 @var{rest} with an associated value, that value is stored in the
5930 variable pointed to by @var{argp1}, otherwise the variable is left
5931 unchanged. Similarly for the other keywords and argument pointers up to
5932 @var{keywordN} and @var{argpN}. The argument list to
5933 @code{scm_c_bind_keyword_arguments} must be terminated by
5934 @code{SCM_UNDEFINED}.
5936 Note that since the variables pointed to by @var{argp1} through
5937 @var{argpN} are left unchanged if the associated keyword argument is not
5938 present, they should be initialized to their default values before
5939 calling @code{scm_c_bind_keyword_arguments}. Alternatively, you can
5940 initialize them to @code{SCM_UNDEFINED} before the call, and then use
5941 @code{SCM_UNBNDP} after the call to see which ones were provided.
5943 If an unrecognized keyword argument is present in @var{rest} and
5944 @var{flags} does not contain @code{SCM_ALLOW_OTHER_KEYS}, or if
5945 non-keyword arguments are present and @var{flags} does not contain
5946 @code{SCM_ALLOW_NON_KEYWORD_ARGUMENTS}, an exception is raised.
5947 @var{subr} should be the name of the procedure receiving the keyword
5948 arguments, for purposes of error reporting.
5957 SCM my_string_join (SCM strings, SCM rest)
5959 SCM delimiter = SCM_UNDEFINED;
5960 SCM grammar = sym_infix;
5962 scm_c_bind_keyword_arguments ("my-string-join", rest, 0,
5963 k_delimiter, &delimiter,
5964 k_grammar, &grammar,
5967 if (SCM_UNBNDP (delimiter))
5968 delimiter = scm_from_utf8_string (" ");
5970 return scm_string_join (strings, delimiter, grammar);
5975 k_delimiter = scm_from_utf8_keyword ("delimiter");
5976 k_grammar = scm_from_utf8_keyword ("grammar");
5977 sym_infix = scm_from_utf8_symbol ("infix");
5978 scm_c_define_gsubr ("my-string-join", 1, 0, 1, my_string_join);
5985 @subsection ``Functionality-Centric'' Data Types
5987 Procedures and macros are documented in their own sections: see
5988 @ref{Procedures} and @ref{Macros}.
5990 Variable objects are documented as part of the description of Guile's
5991 module system: see @ref{Variables}.
5993 Asyncs, dynamic roots and fluids are described in the section on
5994 scheduling: see @ref{Scheduling}.
5996 Hooks are documented in the section on general utility functions: see
5999 Ports are described in the section on I/O: see @ref{Input and Output}.
6001 Regular expressions are described in their own section: see @ref{Regular
6005 @c TeX-master: "guile.texi"