2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @node Simple Data Types
9 @section Simple Generic Data Types
11 This chapter describes those of Guile's simple data types which are
12 primarily used for their role as items of generic data. By
13 @dfn{simple} we mean data types that are not primarily used as
14 containers to hold other data --- i.e.@: pairs, lists, vectors and so on.
15 For the documentation of such @dfn{compound} data types, see
16 @ref{Compound Data Types}.
18 @c One of the great strengths of Scheme is that there is no straightforward
19 @c distinction between ``data'' and ``functionality''. For example,
20 @c Guile's support for dynamic linking could be described:
24 @c either in a ``data-centric'' way, as the behaviour and properties of the
25 @c ``dynamically linked object'' data type, and the operations that may be
26 @c applied to instances of this type
29 @c or in a ``functionality-centric'' way, as the set of procedures that
30 @c constitute Guile's support for dynamic linking, in the context of the
34 @c The contents of this chapter are, therefore, a matter of judgment. By
35 @c @dfn{generic}, we mean to select those data types whose typical use as
36 @c @emph{data} in a wide variety of programming contexts is more important
37 @c than their use in the implementation of a particular piece of
38 @c @emph{functionality}. The last section of this chapter provides
39 @c references for all the data types that are documented not here but in a
40 @c ``functionality-centric'' way elsewhere in the manual.
43 * Booleans:: True/false values.
44 * Numbers:: Numerical data types.
45 * Characters:: Single characters.
46 * Character Sets:: Sets of characters.
47 * Strings:: Sequences of characters.
48 * Bytevectors:: Sequences of bytes.
49 * Regular Expressions:: Pattern matching and substitution.
51 * Keywords:: Self-quoting, customizable display keywords.
52 * Other Types:: "Functionality-centric" data types.
60 The two boolean values are @code{#t} for true and @code{#f} for false.
62 Boolean values are returned by predicate procedures, such as the general
63 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
64 (@pxref{Equality}) and numerical and string comparison operators like
65 @code{string=?} (@pxref{String Comparison}) and @code{<=}
75 (equal? "house" "houses")
83 In test condition contexts like @code{if} and @code{cond} (@pxref{if
84 cond case}), where a group of subexpressions will be evaluated only if a
85 @var{condition} expression evaluates to ``true'', ``true'' means any
86 value at all except @code{#f}.
99 A result of this asymmetry is that typical Scheme source code more often
100 uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
101 represent an @code{if} or @code{cond} false value, whereas @code{#t} is
102 not necessary to represent an @code{if} or @code{cond} true value.
104 It is important to note that @code{#f} is @strong{not} equivalent to any
105 other Scheme value. In particular, @code{#f} is not the same as the
106 number 0 (like in C and C++), and not the same as the ``empty list''
107 (like in some Lisp dialects).
109 In C, the two Scheme boolean values are available as the two constants
110 @code{SCM_BOOL_T} for @code{#t} and @code{SCM_BOOL_F} for @code{#f}.
111 Care must be taken with the false value @code{SCM_BOOL_F}: it is not
112 false when used in C conditionals. In order to test for it, use
113 @code{scm_is_false} or @code{scm_is_true}.
116 @deffn {Scheme Procedure} not x
117 @deffnx {C Function} scm_not (x)
118 Return @code{#t} if @var{x} is @code{#f}, else return @code{#f}.
122 @deffn {Scheme Procedure} boolean? obj
123 @deffnx {C Function} scm_boolean_p (obj)
124 Return @code{#t} if @var{obj} is either @code{#t} or @code{#f}, else
128 @deftypevr {C Macro} SCM SCM_BOOL_T
129 The @code{SCM} representation of the Scheme object @code{#t}.
132 @deftypevr {C Macro} SCM SCM_BOOL_F
133 The @code{SCM} representation of the Scheme object @code{#f}.
136 @deftypefn {C Function} int scm_is_true (SCM obj)
137 Return @code{0} if @var{obj} is @code{#f}, else return @code{1}.
140 @deftypefn {C Function} int scm_is_false (SCM obj)
141 Return @code{1} if @var{obj} is @code{#f}, else return @code{0}.
144 @deftypefn {C Function} int scm_is_bool (SCM obj)
145 Return @code{1} if @var{obj} is either @code{#t} or @code{#f}, else
149 @deftypefn {C Function} SCM scm_from_bool (int val)
150 Return @code{#f} if @var{val} is @code{0}, else return @code{#t}.
153 @deftypefn {C Function} int scm_to_bool (SCM val)
154 Return @code{1} if @var{val} is @code{SCM_BOOL_T}, return @code{0}
155 when @var{val} is @code{SCM_BOOL_F}, else signal a `wrong type' error.
157 You should probably use @code{scm_is_true} instead of this function
158 when you just want to test a @code{SCM} value for trueness.
162 @subsection Numerical data types
165 Guile supports a rich ``tower'' of numerical types --- integer,
166 rational, real and complex --- and provides an extensive set of
167 mathematical and scientific functions for operating on numerical
168 data. This section of the manual documents those types and functions.
170 You may also find it illuminating to read R5RS's presentation of numbers
171 in Scheme, which is particularly clear and accessible: see
172 @ref{Numbers,,,r5rs,R5RS}.
175 * Numerical Tower:: Scheme's numerical "tower".
176 * Integers:: Whole numbers.
177 * Reals and Rationals:: Real and rational numbers.
178 * Complex Numbers:: Complex numbers.
179 * Exactness:: Exactness and inexactness.
180 * Number Syntax:: Read syntax for numerical data.
181 * Integer Operations:: Operations on integer values.
182 * Comparison:: Comparison predicates.
183 * Conversion:: Converting numbers to and from strings.
184 * Complex:: Complex number operations.
185 * Arithmetic:: Arithmetic functions.
186 * Scientific:: Scientific functions.
187 * Bitwise Operations:: Logical AND, OR, NOT, and so on.
188 * Random:: Random number generation.
192 @node Numerical Tower
193 @subsubsection Scheme's Numerical ``Tower''
196 Scheme's numerical ``tower'' consists of the following categories of
201 Whole numbers, positive or negative; e.g.@: --5, 0, 18.
204 The set of numbers that can be expressed as @math{@var{p}/@var{q}}
205 where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
206 pi (an irrational number) doesn't. These include integers
210 The set of numbers that describes all possible positions along a
211 one-dimensional line. This includes rationals as well as irrational
214 @item complex numbers
215 The set of numbers that describes all possible positions in a two
216 dimensional space. This includes real as well as imaginary numbers
217 (@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
218 @var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
222 It is called a tower because each category ``sits on'' the one that
223 follows it, in the sense that every integer is also a rational, every
224 rational is also real, and every real number is also a complex number
225 (but with zero imaginary part).
227 In addition to the classification into integers, rationals, reals and
228 complex numbers, Scheme also distinguishes between whether a number is
229 represented exactly or not. For example, the result of
230 @m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)}, but Guile
231 can represent neither @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
232 Instead, it stores an inexact approximation, using the C type
235 Guile can represent exact rationals of any magnitude, inexact
236 rationals that fit into a C @code{double}, and inexact complex numbers
237 with @code{double} real and imaginary parts.
239 The @code{number?} predicate may be applied to any Scheme value to
240 discover whether the value is any of the supported numerical types.
242 @deffn {Scheme Procedure} number? obj
243 @deffnx {C Function} scm_number_p (obj)
244 Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
253 (number? "hello there!")
256 (define pi 3.141592654)
261 @deftypefn {C Function} int scm_is_number (SCM obj)
262 This is equivalent to @code{scm_is_true (scm_number_p (obj))}.
265 The next few subsections document each of Guile's numerical data types
269 @subsubsection Integers
271 @tpindex Integer numbers
275 Integers are whole numbers, that is numbers with no fractional part,
276 such as 2, 83, and @minus{}3789.
278 Integers in Guile can be arbitrarily big, as shown by the following
282 (define (factorial n)
283 (let loop ((n n) (product 1))
286 (loop (- n 1) (* product n)))))
292 @result{} 2432902008176640000
295 @result{} -119622220865480194561963161495657715064383733760000000000
298 Readers whose background is in programming languages where integers are
299 limited by the need to fit into just 4 or 8 bytes of memory may find
300 this surprising, or suspect that Guile's representation of integers is
301 inefficient. In fact, Guile achieves a near optimal balance of
302 convenience and efficiency by using the host computer's native
303 representation of integers where possible, and a more general
304 representation where the required number does not fit in the native
305 form. Conversion between these two representations is automatic and
306 completely invisible to the Scheme level programmer.
308 The infinities @samp{+inf.0} and @samp{-inf.0} are considered to be
309 inexact integers. They are explained in detail in the next section,
310 together with reals and rationals.
312 C has a host of different integer types, and Guile offers a host of
313 functions to convert between them and the @code{SCM} representation.
314 For example, a C @code{int} can be handled with @code{scm_to_int} and
315 @code{scm_from_int}. Guile also defines a few C integer types of its
316 own, to help with differences between systems.
318 C integer types that are not covered can be handled with the generic
319 @code{scm_to_signed_integer} and @code{scm_from_signed_integer} for
320 signed types, or with @code{scm_to_unsigned_integer} and
321 @code{scm_from_unsigned_integer} for unsigned types.
323 Scheme integers can be exact and inexact. For example, a number
324 written as @code{3.0} with an explicit decimal-point is inexact, but
325 it is also an integer. The functions @code{integer?} and
326 @code{scm_is_integer} report true for such a number, but the functions
327 @code{scm_is_signed_integer} and @code{scm_is_unsigned_integer} only
328 allow exact integers and thus report false. Likewise, the conversion
329 functions like @code{scm_to_signed_integer} only accept exact
332 The motivation for this behavior is that the inexactness of a number
333 should not be lost silently. If you want to allow inexact integers,
334 you can explicitly insert a call to @code{inexact->exact} or to its C
335 equivalent @code{scm_inexact_to_exact}. (Only inexact integers will
336 be converted by this call into exact integers; inexact non-integers
337 will become exact fractions.)
339 @deffn {Scheme Procedure} integer? x
340 @deffnx {C Function} scm_integer_p (x)
341 Return @code{#t} if @var{x} is an exact or inexact integer number, else
359 @deftypefn {C Function} int scm_is_integer (SCM x)
360 This is equivalent to @code{scm_is_true (scm_integer_p (x))}.
363 @defvr {C Type} scm_t_int8
364 @defvrx {C Type} scm_t_uint8
365 @defvrx {C Type} scm_t_int16
366 @defvrx {C Type} scm_t_uint16
367 @defvrx {C Type} scm_t_int32
368 @defvrx {C Type} scm_t_uint32
369 @defvrx {C Type} scm_t_int64
370 @defvrx {C Type} scm_t_uint64
371 @defvrx {C Type} scm_t_intmax
372 @defvrx {C Type} scm_t_uintmax
373 The C types are equivalent to the corresponding ISO C types but are
374 defined on all platforms, with the exception of @code{scm_t_int64} and
375 @code{scm_t_uint64}, which are only defined when a 64-bit type is
376 available. For example, @code{scm_t_int8} is equivalent to
379 You can regard these definitions as a stop-gap measure until all
380 platforms provide these types. If you know that all the platforms
381 that you are interested in already provide these types, it is better
382 to use them directly instead of the types provided by Guile.
385 @deftypefn {C Function} int scm_is_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
386 @deftypefnx {C Function} int scm_is_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
387 Return @code{1} when @var{x} represents an exact integer that is
388 between @var{min} and @var{max}, inclusive.
390 These functions can be used to check whether a @code{SCM} value will
391 fit into a given range, such as the range of a given C integer type.
392 If you just want to convert a @code{SCM} value to a given C integer
393 type, use one of the conversion functions directly.
396 @deftypefn {C Function} scm_t_intmax scm_to_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
397 @deftypefnx {C Function} scm_t_uintmax scm_to_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
398 When @var{x} represents an exact integer that is between @var{min} and
399 @var{max} inclusive, return that integer. Else signal an error,
400 either a `wrong-type' error when @var{x} is not an exact integer, or
401 an `out-of-range' error when it doesn't fit the given range.
404 @deftypefn {C Function} SCM scm_from_signed_integer (scm_t_intmax x)
405 @deftypefnx {C Function} SCM scm_from_unsigned_integer (scm_t_uintmax x)
406 Return the @code{SCM} value that represents the integer @var{x}. This
407 function will always succeed and will always return an exact number.
410 @deftypefn {C Function} char scm_to_char (SCM x)
411 @deftypefnx {C Function} {signed char} scm_to_schar (SCM x)
412 @deftypefnx {C Function} {unsigned char} scm_to_uchar (SCM x)
413 @deftypefnx {C Function} short scm_to_short (SCM x)
414 @deftypefnx {C Function} {unsigned short} scm_to_ushort (SCM x)
415 @deftypefnx {C Function} int scm_to_int (SCM x)
416 @deftypefnx {C Function} {unsigned int} scm_to_uint (SCM x)
417 @deftypefnx {C Function} long scm_to_long (SCM x)
418 @deftypefnx {C Function} {unsigned long} scm_to_ulong (SCM x)
419 @deftypefnx {C Function} {long long} scm_to_long_long (SCM x)
420 @deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x)
421 @deftypefnx {C Function} size_t scm_to_size_t (SCM x)
422 @deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x)
423 @deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x)
424 @deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x)
425 @deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x)
426 @deftypefnx {C Function} scm_t_uint16 scm_to_uint16 (SCM x)
427 @deftypefnx {C Function} scm_t_int32 scm_to_int32 (SCM x)
428 @deftypefnx {C Function} scm_t_uint32 scm_to_uint32 (SCM x)
429 @deftypefnx {C Function} scm_t_int64 scm_to_int64 (SCM x)
430 @deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x)
431 @deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x)
432 @deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x)
433 When @var{x} represents an exact integer that fits into the indicated
434 C type, return that integer. Else signal an error, either a
435 `wrong-type' error when @var{x} is not an exact integer, or an
436 `out-of-range' error when it doesn't fit the given range.
438 The functions @code{scm_to_long_long}, @code{scm_to_ulong_long},
439 @code{scm_to_int64}, and @code{scm_to_uint64} are only available when
440 the corresponding types are.
443 @deftypefn {C Function} SCM scm_from_char (char x)
444 @deftypefnx {C Function} SCM scm_from_schar (signed char x)
445 @deftypefnx {C Function} SCM scm_from_uchar (unsigned char x)
446 @deftypefnx {C Function} SCM scm_from_short (short x)
447 @deftypefnx {C Function} SCM scm_from_ushort (unsigned short x)
448 @deftypefnx {C Function} SCM scm_from_int (int x)
449 @deftypefnx {C Function} SCM scm_from_uint (unsigned int x)
450 @deftypefnx {C Function} SCM scm_from_long (long x)
451 @deftypefnx {C Function} SCM scm_from_ulong (unsigned long x)
452 @deftypefnx {C Function} SCM scm_from_long_long (long long x)
453 @deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x)
454 @deftypefnx {C Function} SCM scm_from_size_t (size_t x)
455 @deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x)
456 @deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x)
457 @deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x)
458 @deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x)
459 @deftypefnx {C Function} SCM scm_from_uint16 (scm_t_uint16 x)
460 @deftypefnx {C Function} SCM scm_from_int32 (scm_t_int32 x)
461 @deftypefnx {C Function} SCM scm_from_uint32 (scm_t_uint32 x)
462 @deftypefnx {C Function} SCM scm_from_int64 (scm_t_int64 x)
463 @deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x)
464 @deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x)
465 @deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x)
466 Return the @code{SCM} value that represents the integer @var{x}.
467 These functions will always succeed and will always return an exact
471 @deftypefn {C Function} void scm_to_mpz (SCM val, mpz_t rop)
472 Assign @var{val} to the multiple precision integer @var{rop}.
473 @var{val} must be an exact integer, otherwise an error will be
474 signalled. @var{rop} must have been initialized with @code{mpz_init}
475 before this function is called. When @var{rop} is no longer needed
476 the occupied space must be freed with @code{mpz_clear}.
477 @xref{Initializing Integers,,, gmp, GNU MP Manual}, for details.
480 @deftypefn {C Function} SCM scm_from_mpz (mpz_t val)
481 Return the @code{SCM} value that represents @var{val}.
484 @node Reals and Rationals
485 @subsubsection Real and Rational Numbers
486 @tpindex Real numbers
487 @tpindex Rational numbers
492 Mathematically, the real numbers are the set of numbers that describe
493 all possible points along a continuous, infinite, one-dimensional line.
494 The rational numbers are the set of all numbers that can be written as
495 fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
496 All rational numbers are also real, but there are real numbers that
497 are not rational, for example @m{\sqrt2, the square root of 2}, and
500 Guile can represent both exact and inexact rational numbers, but it
501 can not represent irrational numbers. Exact rationals are represented
502 by storing the numerator and denominator as two exact integers.
503 Inexact rationals are stored as floating point numbers using the C
506 Exact rationals are written as a fraction of integers. There must be
507 no whitespace around the slash:
514 Even though the actual encoding of inexact rationals is in binary, it
515 may be helpful to think of it as a decimal number with a limited
516 number of significant figures and a decimal point somewhere, since
517 this corresponds to the standard notation for non-whole numbers. For
523 -5648394822220000000000.0
527 The limited precision of Guile's encoding means that any ``real'' number
528 in Guile can be written in a rational form, by multiplying and then dividing
529 by sufficient powers of 10 (or in fact, 2). For example,
530 @samp{-0.00000142857931198} is the same as @minus{}142857931198 divided by
531 100000000000000000. In Guile's current incarnation, therefore, the
532 @code{rational?} and @code{real?} predicates are equivalent.
535 Dividing by an exact zero leads to a error message, as one might
536 expect. However, dividing by an inexact zero does not produce an
537 error. Instead, the result of the division is either plus or minus
538 infinity, depending on the sign of the divided number.
540 The infinities are written @samp{+inf.0} and @samp{-inf.0},
541 respectively. This syntax is also recognized by @code{read} as an
542 extension to the usual Scheme syntax.
544 Dividing zero by zero yields something that is not a number at all:
545 @samp{+nan.0}. This is the special `not a number' value.
547 On platforms that follow @acronym{IEEE} 754 for their floating point
548 arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
549 are implemented using the corresponding @acronym{IEEE} 754 values.
550 They behave in arithmetic operations like @acronym{IEEE} 754 describes
551 it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
553 The infinities are inexact integers and are considered to be both even
554 and odd. While @samp{+nan.0} is not @code{=} to itself, it is
555 @code{eqv?} to itself.
557 To test for the special values, use the functions @code{inf?} and
560 @deffn {Scheme Procedure} real? obj
561 @deffnx {C Function} scm_real_p (obj)
562 Return @code{#t} if @var{obj} is a real number, else @code{#f}. Note
563 that the sets of integer and rational values form subsets of the set
564 of real numbers, so the predicate will also be fulfilled if @var{obj}
565 is an integer number or a rational number.
568 @deffn {Scheme Procedure} rational? x
569 @deffnx {C Function} scm_rational_p (x)
570 Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise.
571 Note that the set of integer values forms a subset of the set of
572 rational numbers, i. e. the predicate will also be fulfilled if
573 @var{x} is an integer number.
575 Since Guile can not represent irrational numbers, every number
576 satisfying @code{real?} also satisfies @code{rational?} in Guile.
579 @deffn {Scheme Procedure} rationalize x eps
580 @deffnx {C Function} scm_rationalize (x, eps)
581 Returns the @emph{simplest} rational number differing
582 from @var{x} by no more than @var{eps}.
584 As required by @acronym{R5RS}, @code{rationalize} only returns an
585 exact result when both its arguments are exact. Thus, you might need
586 to use @code{inexact->exact} on the arguments.
589 (rationalize (inexact->exact 1.2) 1/100)
595 @deffn {Scheme Procedure} inf? x
596 @deffnx {C Function} scm_inf_p (x)
597 Return @code{#t} if @var{x} is either @samp{+inf.0} or @samp{-inf.0},
601 @deffn {Scheme Procedure} nan? x
602 @deffnx {C Function} scm_nan_p (x)
603 Return @code{#t} if @var{x} is @samp{+nan.0}, @code{#f} otherwise.
606 @deffn {Scheme Procedure} nan
607 @deffnx {C Function} scm_nan ()
611 @deffn {Scheme Procedure} inf
612 @deffnx {C Function} scm_inf ()
616 @deffn {Scheme Procedure} numerator x
617 @deffnx {C Function} scm_numerator (x)
618 Return the numerator of the rational number @var{x}.
621 @deffn {Scheme Procedure} denominator x
622 @deffnx {C Function} scm_denominator (x)
623 Return the denominator of the rational number @var{x}.
626 @deftypefn {C Function} int scm_is_real (SCM val)
627 @deftypefnx {C Function} int scm_is_rational (SCM val)
628 Equivalent to @code{scm_is_true (scm_real_p (val))} and
629 @code{scm_is_true (scm_rational_p (val))}, respectively.
632 @deftypefn {C Function} double scm_to_double (SCM val)
633 Returns the number closest to @var{val} that is representable as a
634 @code{double}. Returns infinity for a @var{val} that is too large in
635 magnitude. The argument @var{val} must be a real number.
638 @deftypefn {C Function} SCM scm_from_double (double val)
639 Return the @code{SCM} value that represents @var{val}. The returned
640 value is inexact according to the predicate @code{inexact?}, but it
641 will be exactly equal to @var{val}.
644 @node Complex Numbers
645 @subsubsection Complex Numbers
646 @tpindex Complex numbers
650 Complex numbers are the set of numbers that describe all possible points
651 in a two-dimensional space. The two coordinates of a particular point
652 in this space are known as the @dfn{real} and @dfn{imaginary} parts of
653 the complex number that describes that point.
655 In Guile, complex numbers are written in rectangular form as the sum of
656 their real and imaginary parts, using the symbol @code{i} to indicate
671 Polar form can also be used, with an @samp{@@} between magnitude and
675 1@@3.141592 @result{} -1.0 (approx)
676 -1@@1.57079 @result{} 0.0-1.0i (approx)
679 Guile represents a complex number with a non-zero imaginary part as a
680 pair of inexact rationals, so the real and imaginary parts of a
681 complex number have the same properties of inexactness and limited
682 precision as single inexact rational numbers. Guile can not represent
683 exact complex numbers with non-zero imaginary parts.
685 @deffn {Scheme Procedure} complex? z
686 @deffnx {C Function} scm_complex_p (z)
687 Return @code{#t} if @var{x} is a complex number, @code{#f}
688 otherwise. Note that the sets of real, rational and integer
689 values form subsets of the set of complex numbers, i. e. the
690 predicate will also be fulfilled if @var{x} is a real,
691 rational or integer number.
694 @deftypefn {C Function} int scm_is_complex (SCM val)
695 Equivalent to @code{scm_is_true (scm_complex_p (val))}.
699 @subsubsection Exact and Inexact Numbers
700 @tpindex Exact numbers
701 @tpindex Inexact numbers
705 @rnindex exact->inexact
706 @rnindex inexact->exact
708 R5RS requires that a calculation involving inexact numbers always
709 produces an inexact result. To meet this requirement, Guile
710 distinguishes between an exact integer value such as @samp{5} and the
711 corresponding inexact real value which, to the limited precision
712 available, has no fractional part, and is printed as @samp{5.0}. Guile
713 will only convert the latter value to the former when forced to do so by
714 an invocation of the @code{inexact->exact} procedure.
716 @deffn {Scheme Procedure} exact? z
717 @deffnx {C Function} scm_exact_p (z)
718 Return @code{#t} if the number @var{z} is exact, @code{#f}
734 @deffn {Scheme Procedure} inexact? z
735 @deffnx {C Function} scm_inexact_p (z)
736 Return @code{#t} if the number @var{z} is inexact, @code{#f}
740 @deffn {Scheme Procedure} inexact->exact z
741 @deffnx {C Function} scm_inexact_to_exact (z)
742 Return an exact number that is numerically closest to @var{z}, when
743 there is one. For inexact rationals, Guile returns the exact rational
744 that is numerically equal to the inexact rational. Inexact complex
745 numbers with a non-zero imaginary part can not be made exact.
752 The following happens because 12/10 is not exactly representable as a
753 @code{double} (on most platforms). However, when reading a decimal
754 number that has been marked exact with the ``#e'' prefix, Guile is
755 able to represent it correctly.
759 @result{} 5404319552844595/4503599627370496
767 @c begin (texi-doc-string "guile" "exact->inexact")
768 @deffn {Scheme Procedure} exact->inexact z
769 @deffnx {C Function} scm_exact_to_inexact (z)
770 Convert the number @var{z} to its inexact representation.
775 @subsubsection Read Syntax for Numerical Data
777 The read syntax for integers is a string of digits, optionally
778 preceded by a minus or plus character, a code indicating the
779 base in which the integer is encoded, and a code indicating whether
780 the number is exact or inexact. The supported base codes are:
785 the integer is written in binary (base 2)
789 the integer is written in octal (base 8)
793 the integer is written in decimal (base 10)
797 the integer is written in hexadecimal (base 16)
800 If the base code is omitted, the integer is assumed to be decimal. The
801 following examples show how these base codes are used.
820 The codes for indicating exactness (which can, incidentally, be applied
821 to all numerical values) are:
830 the number is inexact.
833 If the exactness indicator is omitted, the number is exact unless it
834 contains a radix point. Since Guile can not represent exact complex
835 numbers, an error is signalled when asking for them.
845 ERROR: Wrong type argument
848 Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
849 plus and minus infinity, respectively. The value must be written
850 exactly as shown, that is, they always must have a sign and exactly
851 one zero digit after the decimal point. It also understands
852 @samp{+nan.0} and @samp{-nan.0} for the special `not-a-number' value.
853 The sign is ignored for `not-a-number' and the value is always printed
856 @node Integer Operations
857 @subsubsection Operations on Integer Values
866 @deffn {Scheme Procedure} odd? n
867 @deffnx {C Function} scm_odd_p (n)
868 Return @code{#t} if @var{n} is an odd number, @code{#f}
872 @deffn {Scheme Procedure} even? n
873 @deffnx {C Function} scm_even_p (n)
874 Return @code{#t} if @var{n} is an even number, @code{#f}
878 @c begin (texi-doc-string "guile" "quotient")
879 @c begin (texi-doc-string "guile" "remainder")
880 @deffn {Scheme Procedure} quotient n d
881 @deffnx {Scheme Procedure} remainder n d
882 @deffnx {C Function} scm_quotient (n, d)
883 @deffnx {C Function} scm_remainder (n, d)
884 Return the quotient or remainder from @var{n} divided by @var{d}. The
885 quotient is rounded towards zero, and the remainder will have the same
886 sign as @var{n}. In all cases quotient and remainder satisfy
887 @math{@var{n} = @var{q}*@var{d} + @var{r}}.
890 (remainder 13 4) @result{} 1
891 (remainder -13 4) @result{} -1
895 @c begin (texi-doc-string "guile" "modulo")
896 @deffn {Scheme Procedure} modulo n d
897 @deffnx {C Function} scm_modulo (n, d)
898 Return the remainder from @var{n} divided by @var{d}, with the same
902 (modulo 13 4) @result{} 1
903 (modulo -13 4) @result{} 3
904 (modulo 13 -4) @result{} -3
905 (modulo -13 -4) @result{} -1
909 @c begin (texi-doc-string "guile" "gcd")
910 @deffn {Scheme Procedure} gcd x@dots{}
911 @deffnx {C Function} scm_gcd (x, y)
912 Return the greatest common divisor of all arguments.
913 If called without arguments, 0 is returned.
915 The C function @code{scm_gcd} always takes two arguments, while the
916 Scheme function can take an arbitrary number.
919 @c begin (texi-doc-string "guile" "lcm")
920 @deffn {Scheme Procedure} lcm x@dots{}
921 @deffnx {C Function} scm_lcm (x, y)
922 Return the least common multiple of the arguments.
923 If called without arguments, 1 is returned.
925 The C function @code{scm_lcm} always takes two arguments, while the
926 Scheme function can take an arbitrary number.
929 @deffn {Scheme Procedure} modulo-expt n k m
930 @deffnx {C Function} scm_modulo_expt (n, k, m)
931 Return @var{n} raised to the integer exponent
932 @var{k}, modulo @var{m}.
941 @subsubsection Comparison Predicates
946 The C comparison functions below always takes two arguments, while the
947 Scheme functions can take an arbitrary number. Also keep in mind that
948 the C functions return one of the Scheme boolean values
949 @code{SCM_BOOL_T} or @code{SCM_BOOL_F} which are both true as far as C
950 is concerned. Thus, always write @code{scm_is_true (scm_num_eq_p (x,
951 y))} when testing the two Scheme numbers @code{x} and @code{y} for
952 equality, for example.
954 @c begin (texi-doc-string "guile" "=")
955 @deffn {Scheme Procedure} =
956 @deffnx {C Function} scm_num_eq_p (x, y)
957 Return @code{#t} if all parameters are numerically equal.
960 @c begin (texi-doc-string "guile" "<")
961 @deffn {Scheme Procedure} <
962 @deffnx {C Function} scm_less_p (x, y)
963 Return @code{#t} if the list of parameters is monotonically
967 @c begin (texi-doc-string "guile" ">")
968 @deffn {Scheme Procedure} >
969 @deffnx {C Function} scm_gr_p (x, y)
970 Return @code{#t} if the list of parameters is monotonically
974 @c begin (texi-doc-string "guile" "<=")
975 @deffn {Scheme Procedure} <=
976 @deffnx {C Function} scm_leq_p (x, y)
977 Return @code{#t} if the list of parameters is monotonically
981 @c begin (texi-doc-string "guile" ">=")
982 @deffn {Scheme Procedure} >=
983 @deffnx {C Function} scm_geq_p (x, y)
984 Return @code{#t} if the list of parameters is monotonically
988 @c begin (texi-doc-string "guile" "zero?")
989 @deffn {Scheme Procedure} zero? z
990 @deffnx {C Function} scm_zero_p (z)
991 Return @code{#t} if @var{z} is an exact or inexact number equal to
995 @c begin (texi-doc-string "guile" "positive?")
996 @deffn {Scheme Procedure} positive? x
997 @deffnx {C Function} scm_positive_p (x)
998 Return @code{#t} if @var{x} is an exact or inexact number greater than
1002 @c begin (texi-doc-string "guile" "negative?")
1003 @deffn {Scheme Procedure} negative? x
1004 @deffnx {C Function} scm_negative_p (x)
1005 Return @code{#t} if @var{x} is an exact or inexact number less than
1011 @subsubsection Converting Numbers To and From Strings
1012 @rnindex number->string
1013 @rnindex string->number
1015 The following procedures read and write numbers according to their
1016 external representation as defined by R5RS (@pxref{Lexical structure,
1017 R5RS Lexical Structure,, r5rs, The Revised^5 Report on the Algorithmic
1018 Language Scheme}). @xref{Number Input and Output, the @code{(ice-9
1019 i18n)} module}, for locale-dependent number parsing.
1021 @deffn {Scheme Procedure} number->string n [radix]
1022 @deffnx {C Function} scm_number_to_string (n, radix)
1023 Return a string holding the external representation of the
1024 number @var{n} in the given @var{radix}. If @var{n} is
1025 inexact, a radix of 10 will be used.
1028 @deffn {Scheme Procedure} string->number string [radix]
1029 @deffnx {C Function} scm_string_to_number (string, radix)
1030 Return a number of the maximally precise representation
1031 expressed by the given @var{string}. @var{radix} must be an
1032 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
1033 is a default radix that may be overridden by an explicit radix
1034 prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
1035 supplied, then the default radix is 10. If string is not a
1036 syntactically valid notation for a number, then
1037 @code{string->number} returns @code{#f}.
1040 @deftypefn {C Function} SCM scm_c_locale_stringn_to_number (const char *string, size_t len, unsigned radix)
1041 As per @code{string->number} above, but taking a C string, as pointer
1042 and length. The string characters should be in the current locale
1043 encoding (@code{locale} in the name refers only to that, there's no
1044 locale-dependent parsing).
1049 @subsubsection Complex Number Operations
1050 @rnindex make-rectangular
1057 @deffn {Scheme Procedure} make-rectangular real_part imaginary_part
1058 @deffnx {C Function} scm_make_rectangular (real_part, imaginary_part)
1059 Return a complex number constructed of the given @var{real-part} and @var{imaginary-part} parts.
1062 @deffn {Scheme Procedure} make-polar x y
1063 @deffnx {C Function} scm_make_polar (x, y)
1065 Return the complex number @var{x} * e^(i * @var{y}).
1068 @c begin (texi-doc-string "guile" "real-part")
1069 @deffn {Scheme Procedure} real-part z
1070 @deffnx {C Function} scm_real_part (z)
1071 Return the real part of the number @var{z}.
1074 @c begin (texi-doc-string "guile" "imag-part")
1075 @deffn {Scheme Procedure} imag-part z
1076 @deffnx {C Function} scm_imag_part (z)
1077 Return the imaginary part of the number @var{z}.
1080 @c begin (texi-doc-string "guile" "magnitude")
1081 @deffn {Scheme Procedure} magnitude z
1082 @deffnx {C Function} scm_magnitude (z)
1083 Return the magnitude of the number @var{z}. This is the same as
1084 @code{abs} for real arguments, but also allows complex numbers.
1087 @c begin (texi-doc-string "guile" "angle")
1088 @deffn {Scheme Procedure} angle z
1089 @deffnx {C Function} scm_angle (z)
1090 Return the angle of the complex number @var{z}.
1093 @deftypefn {C Function} SCM scm_c_make_rectangular (double re, double im)
1094 @deftypefnx {C Function} SCM scm_c_make_polar (double x, double y)
1095 Like @code{scm_make_rectangular} or @code{scm_make_polar},
1096 respectively, but these functions take @code{double}s as their
1100 @deftypefn {C Function} double scm_c_real_part (z)
1101 @deftypefnx {C Function} double scm_c_imag_part (z)
1102 Returns the real or imaginary part of @var{z} as a @code{double}.
1105 @deftypefn {C Function} double scm_c_magnitude (z)
1106 @deftypefnx {C Function} double scm_c_angle (z)
1107 Returns the magnitude or angle of @var{z} as a @code{double}.
1112 @subsubsection Arithmetic Functions
1127 The C arithmetic functions below always takes two arguments, while the
1128 Scheme functions can take an arbitrary number. When you need to
1129 invoke them with just one argument, for example to compute the
1130 equivalent od @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
1131 one: @code{scm_difference (x, SCM_UNDEFINED)}.
1133 @c begin (texi-doc-string "guile" "+")
1134 @deffn {Scheme Procedure} + z1 @dots{}
1135 @deffnx {C Function} scm_sum (z1, z2)
1136 Return the sum of all parameter values. Return 0 if called without any
1140 @c begin (texi-doc-string "guile" "-")
1141 @deffn {Scheme Procedure} - z1 z2 @dots{}
1142 @deffnx {C Function} scm_difference (z1, z2)
1143 If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
1144 the sum of all but the first argument are subtracted from the first
1148 @c begin (texi-doc-string "guile" "*")
1149 @deffn {Scheme Procedure} * z1 @dots{}
1150 @deffnx {C Function} scm_product (z1, z2)
1151 Return the product of all arguments. If called without arguments, 1 is
1155 @c begin (texi-doc-string "guile" "/")
1156 @deffn {Scheme Procedure} / z1 z2 @dots{}
1157 @deffnx {C Function} scm_divide (z1, z2)
1158 Divide the first argument by the product of the remaining arguments. If
1159 called with one argument @var{z1}, 1/@var{z1} is returned.
1162 @deffn {Scheme Procedure} 1+ z
1163 @deffnx {C Function} scm_oneplus (z)
1164 Return @math{@var{z} + 1}.
1167 @deffn {Scheme Procedure} 1- z
1168 @deffnx {C function} scm_oneminus (z)
1169 Return @math{@var{z} - 1}.
1172 @c begin (texi-doc-string "guile" "abs")
1173 @deffn {Scheme Procedure} abs x
1174 @deffnx {C Function} scm_abs (x)
1175 Return the absolute value of @var{x}.
1177 @var{x} must be a number with zero imaginary part. To calculate the
1178 magnitude of a complex number, use @code{magnitude} instead.
1181 @c begin (texi-doc-string "guile" "max")
1182 @deffn {Scheme Procedure} max x1 x2 @dots{}
1183 @deffnx {C Function} scm_max (x1, x2)
1184 Return the maximum of all parameter values.
1187 @c begin (texi-doc-string "guile" "min")
1188 @deffn {Scheme Procedure} min x1 x2 @dots{}
1189 @deffnx {C Function} scm_min (x1, x2)
1190 Return the minimum of all parameter values.
1193 @c begin (texi-doc-string "guile" "truncate")
1194 @deffn {Scheme Procedure} truncate x
1195 @deffnx {C Function} scm_truncate_number (x)
1196 Round the inexact number @var{x} towards zero.
1199 @c begin (texi-doc-string "guile" "round")
1200 @deffn {Scheme Procedure} round x
1201 @deffnx {C Function} scm_round_number (x)
1202 Round the inexact number @var{x} to the nearest integer. When exactly
1203 halfway between two integers, round to the even one.
1206 @c begin (texi-doc-string "guile" "floor")
1207 @deffn {Scheme Procedure} floor x
1208 @deffnx {C Function} scm_floor (x)
1209 Round the number @var{x} towards minus infinity.
1212 @c begin (texi-doc-string "guile" "ceiling")
1213 @deffn {Scheme Procedure} ceiling x
1214 @deffnx {C Function} scm_ceiling (x)
1215 Round the number @var{x} towards infinity.
1218 @deftypefn {C Function} double scm_c_truncate (double x)
1219 @deftypefnx {C Function} double scm_c_round (double x)
1220 Like @code{scm_truncate_number} or @code{scm_round_number},
1221 respectively, but these functions take and return @code{double}
1226 @subsubsection Scientific Functions
1228 The following procedures accept any kind of number as arguments,
1229 including complex numbers.
1232 @c begin (texi-doc-string "guile" "sqrt")
1233 @deffn {Scheme Procedure} sqrt z
1234 Return the square root of @var{z}. Of the two possible roots
1235 (positive and negative), the one with the a positive real part is
1236 returned, or if that's zero then a positive imaginary part. Thus,
1239 (sqrt 9.0) @result{} 3.0
1240 (sqrt -9.0) @result{} 0.0+3.0i
1241 (sqrt 1.0+1.0i) @result{} 1.09868411346781+0.455089860562227i
1242 (sqrt -1.0-1.0i) @result{} 0.455089860562227-1.09868411346781i
1247 @c begin (texi-doc-string "guile" "expt")
1248 @deffn {Scheme Procedure} expt z1 z2
1249 Return @var{z1} raised to the power of @var{z2}.
1253 @c begin (texi-doc-string "guile" "sin")
1254 @deffn {Scheme Procedure} sin z
1255 Return the sine of @var{z}.
1259 @c begin (texi-doc-string "guile" "cos")
1260 @deffn {Scheme Procedure} cos z
1261 Return the cosine of @var{z}.
1265 @c begin (texi-doc-string "guile" "tan")
1266 @deffn {Scheme Procedure} tan z
1267 Return the tangent of @var{z}.
1271 @c begin (texi-doc-string "guile" "asin")
1272 @deffn {Scheme Procedure} asin z
1273 Return the arcsine of @var{z}.
1277 @c begin (texi-doc-string "guile" "acos")
1278 @deffn {Scheme Procedure} acos z
1279 Return the arccosine of @var{z}.
1283 @c begin (texi-doc-string "guile" "atan")
1284 @deffn {Scheme Procedure} atan z
1285 @deffnx {Scheme Procedure} atan y x
1286 Return the arctangent of @var{z}, or of @math{@var{y}/@var{x}}.
1290 @c begin (texi-doc-string "guile" "exp")
1291 @deffn {Scheme Procedure} exp z
1292 Return e to the power of @var{z}, where e is the base of natural
1293 logarithms (2.71828@dots{}).
1297 @c begin (texi-doc-string "guile" "log")
1298 @deffn {Scheme Procedure} log z
1299 Return the natural logarithm of @var{z}.
1302 @c begin (texi-doc-string "guile" "log10")
1303 @deffn {Scheme Procedure} log10 z
1304 Return the base 10 logarithm of @var{z}.
1307 @c begin (texi-doc-string "guile" "sinh")
1308 @deffn {Scheme Procedure} sinh z
1309 Return the hyperbolic sine of @var{z}.
1312 @c begin (texi-doc-string "guile" "cosh")
1313 @deffn {Scheme Procedure} cosh z
1314 Return the hyperbolic cosine of @var{z}.
1317 @c begin (texi-doc-string "guile" "tanh")
1318 @deffn {Scheme Procedure} tanh z
1319 Return the hyperbolic tangent of @var{z}.
1322 @c begin (texi-doc-string "guile" "asinh")
1323 @deffn {Scheme Procedure} asinh z
1324 Return the hyperbolic arcsine of @var{z}.
1327 @c begin (texi-doc-string "guile" "acosh")
1328 @deffn {Scheme Procedure} acosh z
1329 Return the hyperbolic arccosine of @var{z}.
1332 @c begin (texi-doc-string "guile" "atanh")
1333 @deffn {Scheme Procedure} atanh z
1334 Return the hyperbolic arctangent of @var{z}.
1338 @node Bitwise Operations
1339 @subsubsection Bitwise Operations
1341 For the following bitwise functions, negative numbers are treated as
1342 infinite precision twos-complements. For instance @math{-6} is bits
1343 @math{@dots{}111010}, with infinitely many ones on the left. It can
1344 be seen that adding 6 (binary 110) to such a bit pattern gives all
1347 @deffn {Scheme Procedure} logand n1 n2 @dots{}
1348 @deffnx {C Function} scm_logand (n1, n2)
1349 Return the bitwise @sc{and} of the integer arguments.
1352 (logand) @result{} -1
1353 (logand 7) @result{} 7
1354 (logand #b111 #b011 #b001) @result{} 1
1358 @deffn {Scheme Procedure} logior n1 n2 @dots{}
1359 @deffnx {C Function} scm_logior (n1, n2)
1360 Return the bitwise @sc{or} of the integer arguments.
1363 (logior) @result{} 0
1364 (logior 7) @result{} 7
1365 (logior #b000 #b001 #b011) @result{} 3
1369 @deffn {Scheme Procedure} logxor n1 n2 @dots{}
1370 @deffnx {C Function} scm_loxor (n1, n2)
1371 Return the bitwise @sc{xor} of the integer arguments. A bit is
1372 set in the result if it is set in an odd number of arguments.
1375 (logxor) @result{} 0
1376 (logxor 7) @result{} 7
1377 (logxor #b000 #b001 #b011) @result{} 2
1378 (logxor #b000 #b001 #b011 #b011) @result{} 1
1382 @deffn {Scheme Procedure} lognot n
1383 @deffnx {C Function} scm_lognot (n)
1384 Return the integer which is the ones-complement of the integer
1385 argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
1388 (number->string (lognot #b10000000) 2)
1389 @result{} "-10000001"
1390 (number->string (lognot #b0) 2)
1395 @deffn {Scheme Procedure} logtest j k
1396 @deffnx {C Function} scm_logtest (j, k)
1397 Test whether @var{j} and @var{k} have any 1 bits in common. This is
1398 equivalent to @code{(not (zero? (logand j k)))}, but without actually
1399 calculating the @code{logand}, just testing for non-zero.
1402 (logtest #b0100 #b1011) @result{} #f
1403 (logtest #b0100 #b0111) @result{} #t
1407 @deffn {Scheme Procedure} logbit? index j
1408 @deffnx {C Function} scm_logbit_p (index, j)
1409 Test whether bit number @var{index} in @var{j} is set. @var{index}
1410 starts from 0 for the least significant bit.
1413 (logbit? 0 #b1101) @result{} #t
1414 (logbit? 1 #b1101) @result{} #f
1415 (logbit? 2 #b1101) @result{} #t
1416 (logbit? 3 #b1101) @result{} #t
1417 (logbit? 4 #b1101) @result{} #f
1421 @deffn {Scheme Procedure} ash n cnt
1422 @deffnx {C Function} scm_ash (n, cnt)
1423 Return @var{n} shifted left by @var{cnt} bits, or shifted right if
1424 @var{cnt} is negative. This is an ``arithmetic'' shift.
1426 This is effectively a multiplication by @m{2^{cnt}, 2^@var{cnt}}, and
1427 when @var{cnt} is negative it's a division, rounded towards negative
1428 infinity. (Note that this is not the same rounding as @code{quotient}
1431 With @var{n} viewed as an infinite precision twos complement,
1432 @code{ash} means a left shift introducing zero bits, or a right shift
1436 (number->string (ash #b1 3) 2) @result{} "1000"
1437 (number->string (ash #b1010 -1) 2) @result{} "101"
1439 ;; -23 is bits ...11101001, -6 is bits ...111010
1440 (ash -23 -2) @result{} -6
1444 @deffn {Scheme Procedure} logcount n
1445 @deffnx {C Function} scm_logcount (n)
1446 Return the number of bits in integer @var{n}. If @var{n} is
1447 positive, the 1-bits in its binary representation are counted.
1448 If negative, the 0-bits in its two's-complement binary
1449 representation are counted. If zero, 0 is returned.
1452 (logcount #b10101010)
1461 @deffn {Scheme Procedure} integer-length n
1462 @deffnx {C Function} scm_integer_length (n)
1463 Return the number of bits necessary to represent @var{n}.
1465 For positive @var{n} this is how many bits to the most significant one
1466 bit. For negative @var{n} it's how many bits to the most significant
1467 zero bit in twos complement form.
1470 (integer-length #b10101010) @result{} 8
1471 (integer-length #b1111) @result{} 4
1472 (integer-length 0) @result{} 0
1473 (integer-length -1) @result{} 0
1474 (integer-length -256) @result{} 8
1475 (integer-length -257) @result{} 9
1479 @deffn {Scheme Procedure} integer-expt n k
1480 @deffnx {C Function} scm_integer_expt (n, k)
1481 Return @var{n} raised to the power @var{k}. @var{k} must be an exact
1482 integer, @var{n} can be any number.
1484 Negative @var{k} is supported, and results in @m{1/n^|k|, 1/n^abs(k)}
1485 in the usual way. @math{@var{n}^0} is 1, as usual, and that includes
1489 (integer-expt 2 5) @result{} 32
1490 (integer-expt -3 3) @result{} -27
1491 (integer-expt 5 -3) @result{} 1/125
1492 (integer-expt 0 0) @result{} 1
1496 @deffn {Scheme Procedure} bit-extract n start end
1497 @deffnx {C Function} scm_bit_extract (n, start, end)
1498 Return the integer composed of the @var{start} (inclusive)
1499 through @var{end} (exclusive) bits of @var{n}. The
1500 @var{start}th bit becomes the 0-th bit in the result.
1503 (number->string (bit-extract #b1101101010 0 4) 2)
1505 (number->string (bit-extract #b1101101010 4 9) 2)
1512 @subsubsection Random Number Generation
1514 Pseudo-random numbers are generated from a random state object, which
1515 can be created with @code{seed->random-state}. The @var{state}
1516 parameter to the various functions below is optional, it defaults to
1517 the state object in the @code{*random-state*} variable.
1519 @deffn {Scheme Procedure} copy-random-state [state]
1520 @deffnx {C Function} scm_copy_random_state (state)
1521 Return a copy of the random state @var{state}.
1524 @deffn {Scheme Procedure} random n [state]
1525 @deffnx {C Function} scm_random (n, state)
1526 Return a number in [0, @var{n}).
1528 Accepts a positive integer or real n and returns a
1529 number of the same type between zero (inclusive) and
1530 @var{n} (exclusive). The values returned have a uniform
1534 @deffn {Scheme Procedure} random:exp [state]
1535 @deffnx {C Function} scm_random_exp (state)
1536 Return an inexact real in an exponential distribution with mean
1537 1. For an exponential distribution with mean @var{u} use @code{(*
1538 @var{u} (random:exp))}.
1541 @deffn {Scheme Procedure} random:hollow-sphere! vect [state]
1542 @deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
1543 Fills @var{vect} with inexact real random numbers the sum of whose
1544 squares is equal to 1.0. Thinking of @var{vect} as coordinates in
1545 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1546 the coordinates are uniformly distributed over the surface of the unit
1550 @deffn {Scheme Procedure} random:normal [state]
1551 @deffnx {C Function} scm_random_normal (state)
1552 Return an inexact real in a normal distribution. The distribution
1553 used has mean 0 and standard deviation 1. For a normal distribution
1554 with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
1555 (* @var{d} (random:normal)))}.
1558 @deffn {Scheme Procedure} random:normal-vector! vect [state]
1559 @deffnx {C Function} scm_random_normal_vector_x (vect, state)
1560 Fills @var{vect} with inexact real random numbers that are
1561 independent and standard normally distributed
1562 (i.e., with mean 0 and variance 1).
1565 @deffn {Scheme Procedure} random:solid-sphere! vect [state]
1566 @deffnx {C Function} scm_random_solid_sphere_x (vect, state)
1567 Fills @var{vect} with inexact real random numbers the sum of whose
1568 squares is less than 1.0. Thinking of @var{vect} as coordinates in
1569 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1570 the coordinates are uniformly distributed within the unit
1572 @c FIXME: What does this mean, particularly the n-sphere part?
1575 @deffn {Scheme Procedure} random:uniform [state]
1576 @deffnx {C Function} scm_random_uniform (state)
1577 Return a uniformly distributed inexact real random number in
1581 @deffn {Scheme Procedure} seed->random-state seed
1582 @deffnx {C Function} scm_seed_to_random_state (seed)
1583 Return a new random state using @var{seed}.
1586 @defvar *random-state*
1587 The global random state used by the above functions when the
1588 @var{state} parameter is not given.
1591 Note that the initial value of @code{*random-state*} is the same every
1592 time Guile starts up. Therefore, if you don't pass a @var{state}
1593 parameter to the above procedures, and you don't set
1594 @code{*random-state*} to @code{(seed->random-state your-seed)}, where
1595 @code{your-seed} is something that @emph{isn't} the same every time,
1596 you'll get the same sequence of ``random'' numbers on every run.
1598 For example, unless the relevant source code has changed, @code{(map
1599 random (cdr (iota 30)))}, if the first use of random numbers since
1600 Guile started up, will always give:
1603 (map random (cdr (iota 19)))
1605 (0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12)
1608 To use the time of day as the random seed, you can use code like this:
1611 (let ((time (gettimeofday)))
1612 (set! *random-state*
1613 (seed->random-state (+ (car time)
1618 And then (depending on the time of day, of course):
1621 (map random (cdr (iota 19)))
1623 (0 0 1 0 2 4 5 4 5 5 9 3 10 1 8 3 14 17)
1626 For security applications, such as password generation, you should use
1627 more bits of seed. Otherwise an open source password generator could
1628 be attacked by guessing the seed@dots{} but that's a subject for
1633 @subsection Characters
1636 In Scheme, there is a data type to describe a single character.
1638 Defining what exactly a character @emph{is} can be more complicated
1639 than it seems. Guile follows the advice of R6RS and uses The Unicode
1640 Standard to help define what a character is. So, for Guile, a
1641 character is anything in the Unicode Character Database.
1644 @cindex Unicode code point
1646 The Unicode Character Database is basically a table of characters
1647 indexed using integers called 'code points'. Valid code points are in
1648 the ranges 0 to @code{#xD7FF} inclusive or @code{#xE000} to
1649 @code{#x10FFFF} inclusive, which is about 1.1 million code points.
1651 @cindex designated code point
1652 @cindex code point, designated
1654 Any code point that has been assigned to a character or that has
1655 otherwise been given a meaning by Unicode is called a 'designated code
1656 point'. Most of the designated code points, about 200,000 of them,
1657 indicate characters, accents or other combining marks that modify
1658 other characters, symbols, whitespace, and control characters. Some
1659 are not characters but indicators that suggest how to format or
1660 display neighboring characters.
1662 @cindex reserved code point
1663 @cindex code point, reserved
1665 If a code point is not a designated code point -- if it has not been
1666 assigned to a character by The Unicode Standard -- it is a 'reserved
1667 code point', meaning that they are reserved for future use. Most of
1668 the code points, about 800,000, are 'reserved code points'.
1670 By convention, a Unicode code point is written as
1671 ``U+XXXX'' where ``XXXX'' is a hexadecimal number. Please note that
1672 this convenient notation is not valid code. Guile does not interpret
1673 ``U+XXXX'' as a character.
1675 In Scheme, a character literal is written as @code{#\@var{name}} where
1676 @var{name} is the name of the character that you want. Printable
1677 characters have their usual single character name; for example,
1678 @code{#\a} is a lower case @code{a}.
1680 Some of the code points are 'combining characters' that are not meant
1681 to be printed by themselves but are instead meant to modify the
1682 appearance of the previous character. For combining characters, an
1683 alternate form of the character literal is @code{#\} followed by
1684 U+25CC (a small, dotted circle), followed by the combining character.
1685 This allows the combining character to be drawn on the circle, not on
1686 the backslash of @code{#\}.
1688 Many of the non-printing characters, such as whitespace characters and
1689 control characters, also have names.
1691 The most commonly used non-printing characters have long character
1692 names, described in the table below.
1694 @multitable {@code{#\backspace}} {Preferred}
1695 @item Character Name @tab Codepoint
1696 @item @code{#\nul} @tab U+0000
1697 @item @code{#\alarm} @tab u+0007
1698 @item @code{#\backspace} @tab U+0008
1699 @item @code{#\tab} @tab U+0009
1700 @item @code{#\linefeed} @tab U+000A
1701 @item @code{#\newline} @tab U+000A
1702 @item @code{#\vtab} @tab U+000B
1703 @item @code{#\page} @tab U+000C
1704 @item @code{#\return} @tab U+000D
1705 @item @code{#\esc} @tab U+001B
1706 @item @code{#\space} @tab U+0020
1707 @item @code{#\delete} @tab U+007F
1710 There are also short names for all of the ``C0 control characters''
1711 (those with code points below 32). The following table lists the short
1712 name for each character.
1714 @multitable @columnfractions .25 .25 .25 .25
1715 @item 0 = @code{#\nul}
1716 @tab 1 = @code{#\soh}
1717 @tab 2 = @code{#\stx}
1718 @tab 3 = @code{#\etx}
1719 @item 4 = @code{#\eot}
1720 @tab 5 = @code{#\enq}
1721 @tab 6 = @code{#\ack}
1722 @tab 7 = @code{#\bel}
1723 @item 8 = @code{#\bs}
1724 @tab 9 = @code{#\ht}
1725 @tab 10 = @code{#\lf}
1726 @tab 11 = @code{#\vt}
1727 @item 12 = @code{#\ff}
1728 @tab 13 = @code{#\cr}
1729 @tab 14 = @code{#\so}
1730 @tab 15 = @code{#\si}
1731 @item 16 = @code{#\dle}
1732 @tab 17 = @code{#\dc1}
1733 @tab 18 = @code{#\dc2}
1734 @tab 19 = @code{#\dc3}
1735 @item 20 = @code{#\dc4}
1736 @tab 21 = @code{#\nak}
1737 @tab 22 = @code{#\syn}
1738 @tab 23 = @code{#\etb}
1739 @item 24 = @code{#\can}
1740 @tab 25 = @code{#\em}
1741 @tab 26 = @code{#\sub}
1742 @tab 27 = @code{#\esc}
1743 @item 28 = @code{#\fs}
1744 @tab 29 = @code{#\gs}
1745 @tab 30 = @code{#\rs}
1746 @tab 31 = @code{#\us}
1747 @item 32 = @code{#\sp}
1750 The short name for the ``delete'' character (code point U+007F) is
1753 There are also a few alternative names left over for compatibility with
1754 previous versions of Guile.
1756 @multitable {@code{#\backspace}} {Preferred}
1757 @item Alternate @tab Standard
1758 @item @code{#\nl} @tab @code{#\newline}
1759 @item @code{#\np} @tab @code{#\page}
1760 @item @code{#\null} @tab @code{#\nul}
1763 Characters may also be written using their code point values. They can
1764 be written with as an octal number, such as @code{#\10} for
1765 @code{#\bs} or @code{#\177} for @code{#\del}.
1767 When the @code{r6rs-hex-escapes} reader option is enabled, there is an
1768 additional syntax for character escapes: @code{#\xHHHH} -- the letter 'x'
1769 followed by a hexadecimal number of one to eight digits.
1772 (read-enable 'r6rs-hex-escapes)
1775 Enabling this option will also change the hex escape format for strings. More
1776 on string escapes can be found at (@pxref{String Syntax}). More on reader
1777 options in general can be found at (@pxref{Reader options}).
1780 @deffn {Scheme Procedure} char? x
1781 @deffnx {C Function} scm_char_p (x)
1782 Return @code{#t} iff @var{x} is a character, else @code{#f}.
1785 Fundamentally, the character comparison operations below are
1786 numeric comparisons of the character's code points.
1789 @deffn {Scheme Procedure} char=? x y
1790 Return @code{#t} iff code point of @var{x} is equal to the code point
1791 of @var{y}, else @code{#f}.
1795 @deffn {Scheme Procedure} char<? x y
1796 Return @code{#t} iff the code point of @var{x} is less than the code
1797 point of @var{y}, else @code{#f}.
1801 @deffn {Scheme Procedure} char<=? x y
1802 Return @code{#t} iff the code point of @var{x} is less than or equal
1803 to the code point of @var{y}, else @code{#f}.
1807 @deffn {Scheme Procedure} char>? x y
1808 Return @code{#t} iff the code point of @var{x} is greater than the
1809 code point of @var{y}, else @code{#f}.
1813 @deffn {Scheme Procedure} char>=? x y
1814 Return @code{#t} iff the code point of @var{x} is greater than or
1815 equal to the code point of @var{y}, else @code{#f}.
1818 @cindex case folding
1820 Case-insensitive character comparisons use @emph{Unicode case
1821 folding}. In case folding comparisons, if a character is lowercase
1822 and has an uppercase form that can be expressed as a single character,
1823 it is converted to uppercase before comparison. All other characters
1824 undergo no conversion before the comparison occurs. This includes the
1825 German sharp S (Eszett) which is not uppercased before conversion
1826 because its uppercase form has two characters. Unicode case folding
1827 is language independent: it uses rules that are generally true, but,
1828 it cannot cover all cases for all languages.
1831 @deffn {Scheme Procedure} char-ci=? x y
1832 Return @code{#t} iff the case-folded code point of @var{x} is the same
1833 as the case-folded code point of @var{y}, else @code{#f}.
1837 @deffn {Scheme Procedure} char-ci<? x y
1838 Return @code{#t} iff the case-folded code point of @var{x} is less
1839 than the case-folded code point of @var{y}, else @code{#f}.
1843 @deffn {Scheme Procedure} char-ci<=? x y
1844 Return @code{#t} iff the case-folded code point of @var{x} is less
1845 than or equal to the case-folded code point of @var{y}, else
1850 @deffn {Scheme Procedure} char-ci>? x y
1851 Return @code{#t} iff the case-folded code point of @var{x} is greater
1852 than the case-folded code point of @var{y}, else @code{#f}.
1856 @deffn {Scheme Procedure} char-ci>=? x y
1857 Return @code{#t} iff the case-folded code point of @var{x} is greater
1858 than or equal to the case-folded code point of @var{y}, else
1862 @rnindex char-alphabetic?
1863 @deffn {Scheme Procedure} char-alphabetic? chr
1864 @deffnx {C Function} scm_char_alphabetic_p (chr)
1865 Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
1868 @rnindex char-numeric?
1869 @deffn {Scheme Procedure} char-numeric? chr
1870 @deffnx {C Function} scm_char_numeric_p (chr)
1871 Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
1874 @rnindex char-whitespace?
1875 @deffn {Scheme Procedure} char-whitespace? chr
1876 @deffnx {C Function} scm_char_whitespace_p (chr)
1877 Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
1880 @rnindex char-upper-case?
1881 @deffn {Scheme Procedure} char-upper-case? chr
1882 @deffnx {C Function} scm_char_upper_case_p (chr)
1883 Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
1886 @rnindex char-lower-case?
1887 @deffn {Scheme Procedure} char-lower-case? chr
1888 @deffnx {C Function} scm_char_lower_case_p (chr)
1889 Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
1892 @deffn {Scheme Procedure} char-is-both? chr
1893 @deffnx {C Function} scm_char_is_both_p (chr)
1894 Return @code{#t} iff @var{chr} is either uppercase or lowercase, else
1898 @deffn {Scheme Procedure} char-general-category chr
1899 @deffnx {C Function} scm_char_general_category (chr)
1900 Return a symbol giving the two-letter name of the Unicode general
1901 category assigned to @var{chr} or @code{#f} if no named category is
1902 assigned. The following table provides a list of category names along
1903 with their meanings.
1905 @multitable @columnfractions .1 .4 .1 .4
1907 @tab Uppercase letter
1909 @tab Final quote punctuation
1911 @tab Lowercase letter
1913 @tab Other punctuation
1915 @tab Titlecase letter
1919 @tab Modifier letter
1921 @tab Currency symbol
1925 @tab Modifier symbol
1927 @tab Non-spacing mark
1931 @tab Combining spacing mark
1933 @tab Space separator
1939 @tab Decimal digit number
1941 @tab Paragraph separator
1951 @tab Connector punctuation
1955 @tab Dash punctuation
1959 @tab Open punctuation
1963 @tab Close punctuation
1967 @tab Initial quote punctuation
1973 @rnindex char->integer
1974 @deffn {Scheme Procedure} char->integer chr
1975 @deffnx {C Function} scm_char_to_integer (chr)
1976 Return the code point of @var{chr}.
1979 @rnindex integer->char
1980 @deffn {Scheme Procedure} integer->char n
1981 @deffnx {C Function} scm_integer_to_char (n)
1982 Return the character that has code point @var{n}. The integer @var{n}
1983 must be a valid code point. Valid code points are in the ranges 0 to
1984 @code{#xD7FF} inclusive or @code{#xE000} to @code{#x10FFFF} inclusive.
1987 @rnindex char-upcase
1988 @deffn {Scheme Procedure} char-upcase chr
1989 @deffnx {C Function} scm_char_upcase (chr)
1990 Return the uppercase character version of @var{chr}.
1993 @rnindex char-downcase
1994 @deffn {Scheme Procedure} char-downcase chr
1995 @deffnx {C Function} scm_char_downcase (chr)
1996 Return the lowercase character version of @var{chr}.
1999 @rnindex char-titlecase
2000 @deffn {Scheme Procedure} char-titlecase chr
2001 @deffnx {C Function} scm_char_titlecase (chr)
2002 Return the titlecase character version of @var{chr} if one exists;
2003 otherwise return the uppercase version.
2005 For most characters these will be the same, but the Unicode Standard
2006 includes certain digraph compatibility characters, such as @code{U+01F3}
2007 ``dz'', for which the uppercase and titlecase characters are different
2008 (@code{U+01F1} ``DZ'' and @code{U+01F2} ``Dz'' in this case,
2013 @deftypefn {C Function} scm_t_wchar scm_c_upcase (scm_t_wchar @var{c})
2014 @deftypefnx {C Function} scm_t_wchar scm_c_downcase (scm_t_wchar @var{c})
2015 @deftypefnx {C Function} scm_t_wchar scm_c_titlecase (scm_t_wchar @var{c})
2017 These C functions take an integer representation of a Unicode
2018 codepoint and return the codepoint corresponding to its uppercase,
2019 lowercase, and titlecase forms respectively. The type
2020 @code{scm_t_wchar} is a signed, 32-bit integer.
2023 @node Character Sets
2024 @subsection Character Sets
2026 The features described in this section correspond directly to SRFI-14.
2028 The data type @dfn{charset} implements sets of characters
2029 (@pxref{Characters}). Because the internal representation of
2030 character sets is not visible to the user, a lot of procedures for
2031 handling them are provided.
2033 Character sets can be created, extended, tested for the membership of a
2034 characters and be compared to other character sets.
2037 * Character Set Predicates/Comparison::
2038 * Iterating Over Character Sets:: Enumerate charset elements.
2039 * Creating Character Sets:: Making new charsets.
2040 * Querying Character Sets:: Test charsets for membership etc.
2041 * Character-Set Algebra:: Calculating new charsets.
2042 * Standard Character Sets:: Variables containing predefined charsets.
2045 @node Character Set Predicates/Comparison
2046 @subsubsection Character Set Predicates/Comparison
2048 Use these procedures for testing whether an object is a character set,
2049 or whether several character sets are equal or subsets of each other.
2050 @code{char-set-hash} can be used for calculating a hash value, maybe for
2051 usage in fast lookup procedures.
2053 @deffn {Scheme Procedure} char-set? obj
2054 @deffnx {C Function} scm_char_set_p (obj)
2055 Return @code{#t} if @var{obj} is a character set, @code{#f}
2059 @deffn {Scheme Procedure} char-set= . char_sets
2060 @deffnx {C Function} scm_char_set_eq (char_sets)
2061 Return @code{#t} if all given character sets are equal.
2064 @deffn {Scheme Procedure} char-set<= . char_sets
2065 @deffnx {C Function} scm_char_set_leq (char_sets)
2066 Return @code{#t} if every character set @var{cs}i is a subset
2067 of character set @var{cs}i+1.
2070 @deffn {Scheme Procedure} char-set-hash cs [bound]
2071 @deffnx {C Function} scm_char_set_hash (cs, bound)
2072 Compute a hash value for the character set @var{cs}. If
2073 @var{bound} is given and non-zero, it restricts the
2074 returned value to the range 0 @dots{} @var{bound - 1}.
2077 @c ===================================================================
2079 @node Iterating Over Character Sets
2080 @subsubsection Iterating Over Character Sets
2082 Character set cursors are a means for iterating over the members of a
2083 character sets. After creating a character set cursor with
2084 @code{char-set-cursor}, a cursor can be dereferenced with
2085 @code{char-set-ref}, advanced to the next member with
2086 @code{char-set-cursor-next}. Whether a cursor has passed past the last
2087 element of the set can be checked with @code{end-of-char-set?}.
2089 Additionally, mapping and (un-)folding procedures for character sets are
2092 @deffn {Scheme Procedure} char-set-cursor cs
2093 @deffnx {C Function} scm_char_set_cursor (cs)
2094 Return a cursor into the character set @var{cs}.
2097 @deffn {Scheme Procedure} char-set-ref cs cursor
2098 @deffnx {C Function} scm_char_set_ref (cs, cursor)
2099 Return the character at the current cursor position
2100 @var{cursor} in the character set @var{cs}. It is an error to
2101 pass a cursor for which @code{end-of-char-set?} returns true.
2104 @deffn {Scheme Procedure} char-set-cursor-next cs cursor
2105 @deffnx {C Function} scm_char_set_cursor_next (cs, cursor)
2106 Advance the character set cursor @var{cursor} to the next
2107 character in the character set @var{cs}. It is an error if the
2108 cursor given satisfies @code{end-of-char-set?}.
2111 @deffn {Scheme Procedure} end-of-char-set? cursor
2112 @deffnx {C Function} scm_end_of_char_set_p (cursor)
2113 Return @code{#t} if @var{cursor} has reached the end of a
2114 character set, @code{#f} otherwise.
2117 @deffn {Scheme Procedure} char-set-fold kons knil cs
2118 @deffnx {C Function} scm_char_set_fold (kons, knil, cs)
2119 Fold the procedure @var{kons} over the character set @var{cs},
2120 initializing it with @var{knil}.
2123 @deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
2124 @deffnx {C Function} scm_char_set_unfold (p, f, g, seed, base_cs)
2125 This is a fundamental constructor for character sets.
2127 @item @var{g} is used to generate a series of ``seed'' values
2128 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2129 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2130 @item @var{p} tells us when to stop -- when it returns true
2131 when applied to one of the seed values.
2132 @item @var{f} maps each seed value to a character. These
2133 characters are added to the base character set @var{base_cs} to
2134 form the result; @var{base_cs} defaults to the empty set.
2138 @deffn {Scheme Procedure} char-set-unfold! p f g seed base_cs
2139 @deffnx {C Function} scm_char_set_unfold_x (p, f, g, seed, base_cs)
2140 This is a fundamental constructor for character sets.
2142 @item @var{g} is used to generate a series of ``seed'' values
2143 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2144 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2145 @item @var{p} tells us when to stop -- when it returns true
2146 when applied to one of the seed values.
2147 @item @var{f} maps each seed value to a character. These
2148 characters are added to the base character set @var{base_cs} to
2149 form the result; @var{base_cs} defaults to the empty set.
2153 @deffn {Scheme Procedure} char-set-for-each proc cs
2154 @deffnx {C Function} scm_char_set_for_each (proc, cs)
2155 Apply @var{proc} to every character in the character set
2156 @var{cs}. The return value is not specified.
2159 @deffn {Scheme Procedure} char-set-map proc cs
2160 @deffnx {C Function} scm_char_set_map (proc, cs)
2161 Map the procedure @var{proc} over every character in @var{cs}.
2162 @var{proc} must be a character -> character procedure.
2165 @c ===================================================================
2167 @node Creating Character Sets
2168 @subsubsection Creating Character Sets
2170 New character sets are produced with these procedures.
2172 @deffn {Scheme Procedure} char-set-copy cs
2173 @deffnx {C Function} scm_char_set_copy (cs)
2174 Return a newly allocated character set containing all
2175 characters in @var{cs}.
2178 @deffn {Scheme Procedure} char-set . rest
2179 @deffnx {C Function} scm_char_set (rest)
2180 Return a character set containing all given characters.
2183 @deffn {Scheme Procedure} list->char-set list [base_cs]
2184 @deffnx {C Function} scm_list_to_char_set (list, base_cs)
2185 Convert the character list @var{list} to a character set. If
2186 the character set @var{base_cs} is given, the character in this
2187 set are also included in the result.
2190 @deffn {Scheme Procedure} list->char-set! list base_cs
2191 @deffnx {C Function} scm_list_to_char_set_x (list, base_cs)
2192 Convert the character list @var{list} to a character set. The
2193 characters are added to @var{base_cs} and @var{base_cs} is
2197 @deffn {Scheme Procedure} string->char-set str [base_cs]
2198 @deffnx {C Function} scm_string_to_char_set (str, base_cs)
2199 Convert the string @var{str} to a character set. If the
2200 character set @var{base_cs} is given, the characters in this
2201 set are also included in the result.
2204 @deffn {Scheme Procedure} string->char-set! str base_cs
2205 @deffnx {C Function} scm_string_to_char_set_x (str, base_cs)
2206 Convert the string @var{str} to a character set. The
2207 characters from the string are added to @var{base_cs}, and
2208 @var{base_cs} is returned.
2211 @deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
2212 @deffnx {C Function} scm_char_set_filter (pred, cs, base_cs)
2213 Return a character set containing every character from @var{cs}
2214 so that it satisfies @var{pred}. If provided, the characters
2215 from @var{base_cs} are added to the result.
2218 @deffn {Scheme Procedure} char-set-filter! pred cs base_cs
2219 @deffnx {C Function} scm_char_set_filter_x (pred, cs, base_cs)
2220 Return a character set containing every character from @var{cs}
2221 so that it satisfies @var{pred}. The characters are added to
2222 @var{base_cs} and @var{base_cs} is returned.
2225 @deffn {Scheme Procedure} ucs-range->char-set lower upper [error [base_cs]]
2226 @deffnx {C Function} scm_ucs_range_to_char_set (lower, upper, error, base_cs)
2227 Return a character set containing all characters whose
2228 character codes lie in the half-open range
2229 [@var{lower},@var{upper}).
2231 If @var{error} is a true value, an error is signalled if the
2232 specified range contains characters which are not contained in
2233 the implemented character range. If @var{error} is @code{#f},
2234 these characters are silently left out of the resulting
2237 The characters in @var{base_cs} are added to the result, if
2241 @deffn {Scheme Procedure} ucs-range->char-set! lower upper error base_cs
2242 @deffnx {C Function} scm_ucs_range_to_char_set_x (lower, upper, error, base_cs)
2243 Return a character set containing all characters whose
2244 character codes lie in the half-open range
2245 [@var{lower},@var{upper}).
2247 If @var{error} is a true value, an error is signalled if the
2248 specified range contains characters which are not contained in
2249 the implemented character range. If @var{error} is @code{#f},
2250 these characters are silently left out of the resulting
2253 The characters are added to @var{base_cs} and @var{base_cs} is
2257 @deffn {Scheme Procedure} ->char-set x
2258 @deffnx {C Function} scm_to_char_set (x)
2259 Coerces x into a char-set. @var{x} may be a string, character or
2260 char-set. A string is converted to the set of its constituent
2261 characters; a character is converted to a singleton set; a char-set is
2265 @c ===================================================================
2267 @node Querying Character Sets
2268 @subsubsection Querying Character Sets
2270 Access the elements and other information of a character set with these
2273 @deffn {Scheme Procedure} %char-set-dump cs
2274 Returns an association list containing debugging information
2275 for @var{cs}. The association list has the following entries.
2280 The number of groups of contiguous code points the char-set
2283 A list of lists where each sublist is a range of code points
2284 and their associated characters
2286 The return value of this function cannot be relied upon to be
2287 consistent between versions of Guile and should not be used in code.
2290 @deffn {Scheme Procedure} char-set-size cs
2291 @deffnx {C Function} scm_char_set_size (cs)
2292 Return the number of elements in character set @var{cs}.
2295 @deffn {Scheme Procedure} char-set-count pred cs
2296 @deffnx {C Function} scm_char_set_count (pred, cs)
2297 Return the number of the elements int the character set
2298 @var{cs} which satisfy the predicate @var{pred}.
2301 @deffn {Scheme Procedure} char-set->list cs
2302 @deffnx {C Function} scm_char_set_to_list (cs)
2303 Return a list containing the elements of the character set
2307 @deffn {Scheme Procedure} char-set->string cs
2308 @deffnx {C Function} scm_char_set_to_string (cs)
2309 Return a string containing the elements of the character set
2310 @var{cs}. The order in which the characters are placed in the
2311 string is not defined.
2314 @deffn {Scheme Procedure} char-set-contains? cs ch
2315 @deffnx {C Function} scm_char_set_contains_p (cs, ch)
2316 Return @code{#t} iff the character @var{ch} is contained in the
2317 character set @var{cs}.
2320 @deffn {Scheme Procedure} char-set-every pred cs
2321 @deffnx {C Function} scm_char_set_every (pred, cs)
2322 Return a true value if every character in the character set
2323 @var{cs} satisfies the predicate @var{pred}.
2326 @deffn {Scheme Procedure} char-set-any pred cs
2327 @deffnx {C Function} scm_char_set_any (pred, cs)
2328 Return a true value if any character in the character set
2329 @var{cs} satisfies the predicate @var{pred}.
2332 @c ===================================================================
2334 @node Character-Set Algebra
2335 @subsubsection Character-Set Algebra
2337 Character sets can be manipulated with the common set algebra operation,
2338 such as union, complement, intersection etc. All of these procedures
2339 provide side-effecting variants, which modify their character set
2342 @deffn {Scheme Procedure} char-set-adjoin cs . rest
2343 @deffnx {C Function} scm_char_set_adjoin (cs, rest)
2344 Add all character arguments to the first argument, which must
2348 @deffn {Scheme Procedure} char-set-delete cs . rest
2349 @deffnx {C Function} scm_char_set_delete (cs, rest)
2350 Delete all character arguments from the first argument, which
2351 must be a character set.
2354 @deffn {Scheme Procedure} char-set-adjoin! cs . rest
2355 @deffnx {C Function} scm_char_set_adjoin_x (cs, rest)
2356 Add all character arguments to the first argument, which must
2360 @deffn {Scheme Procedure} char-set-delete! cs . rest
2361 @deffnx {C Function} scm_char_set_delete_x (cs, rest)
2362 Delete all character arguments from the first argument, which
2363 must be a character set.
2366 @deffn {Scheme Procedure} char-set-complement cs
2367 @deffnx {C Function} scm_char_set_complement (cs)
2368 Return the complement of the character set @var{cs}.
2371 Note that the complement of a character set is likely to contain many
2372 reserved code points (code points that are not associated with
2373 characters). It may be helpful to modify the output of
2374 @code{char-set-complement} by computing its intersection with the set
2375 of designated code points, @code{char-set:designated}.
2377 @deffn {Scheme Procedure} char-set-union . rest
2378 @deffnx {C Function} scm_char_set_union (rest)
2379 Return the union of all argument character sets.
2382 @deffn {Scheme Procedure} char-set-intersection . rest
2383 @deffnx {C Function} scm_char_set_intersection (rest)
2384 Return the intersection of all argument character sets.
2387 @deffn {Scheme Procedure} char-set-difference cs1 . rest
2388 @deffnx {C Function} scm_char_set_difference (cs1, rest)
2389 Return the difference of all argument character sets.
2392 @deffn {Scheme Procedure} char-set-xor . rest
2393 @deffnx {C Function} scm_char_set_xor (rest)
2394 Return the exclusive-or of all argument character sets.
2397 @deffn {Scheme Procedure} char-set-diff+intersection cs1 . rest
2398 @deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, rest)
2399 Return the difference and the intersection of all argument
2403 @deffn {Scheme Procedure} char-set-complement! cs
2404 @deffnx {C Function} scm_char_set_complement_x (cs)
2405 Return the complement of the character set @var{cs}.
2408 @deffn {Scheme Procedure} char-set-union! cs1 . rest
2409 @deffnx {C Function} scm_char_set_union_x (cs1, rest)
2410 Return the union of all argument character sets.
2413 @deffn {Scheme Procedure} char-set-intersection! cs1 . rest
2414 @deffnx {C Function} scm_char_set_intersection_x (cs1, rest)
2415 Return the intersection of all argument character sets.
2418 @deffn {Scheme Procedure} char-set-difference! cs1 . rest
2419 @deffnx {C Function} scm_char_set_difference_x (cs1, rest)
2420 Return the difference of all argument character sets.
2423 @deffn {Scheme Procedure} char-set-xor! cs1 . rest
2424 @deffnx {C Function} scm_char_set_xor_x (cs1, rest)
2425 Return the exclusive-or of all argument character sets.
2428 @deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 . rest
2429 @deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, rest)
2430 Return the difference and the intersection of all argument
2434 @c ===================================================================
2436 @node Standard Character Sets
2437 @subsubsection Standard Character Sets
2439 In order to make the use of the character set data type and procedures
2440 useful, several predefined character set variables exist.
2446 These character sets are locale independent and are not recomputed
2447 upon a @code{setlocale} call. They contain characters from the whole
2448 range of Unicode code points. For instance, @code{char-set:letter}
2449 contains about 94,000 characters.
2451 @defvr {Scheme Variable} char-set:lower-case
2452 @defvrx {C Variable} scm_char_set_lower_case
2453 All lower-case characters.
2456 @defvr {Scheme Variable} char-set:upper-case
2457 @defvrx {C Variable} scm_char_set_upper_case
2458 All upper-case characters.
2461 @defvr {Scheme Variable} char-set:title-case
2462 @defvrx {C Variable} scm_char_set_title_case
2463 All single characters that function as if they were an upper-case
2464 letter followed by a lower-case letter.
2467 @defvr {Scheme Variable} char-set:letter
2468 @defvrx {C Variable} scm_char_set_letter
2469 All letters. This includes @code{char-set:lower-case},
2470 @code{char-set:upper-case}, @code{char-set:title-case}, and many
2471 letters that have no case at all. For example, Chinese and Japanese
2472 characters typically have no concept of case.
2475 @defvr {Scheme Variable} char-set:digit
2476 @defvrx {C Variable} scm_char_set_digit
2480 @defvr {Scheme Variable} char-set:letter+digit
2481 @defvrx {C Variable} scm_char_set_letter_and_digit
2482 The union of @code{char-set:letter} and @code{char-set:digit}.
2485 @defvr {Scheme Variable} char-set:graphic
2486 @defvrx {C Variable} scm_char_set_graphic
2487 All characters which would put ink on the paper.
2490 @defvr {Scheme Variable} char-set:printing
2491 @defvrx {C Variable} scm_char_set_printing
2492 The union of @code{char-set:graphic} and @code{char-set:whitespace}.
2495 @defvr {Scheme Variable} char-set:whitespace
2496 @defvrx {C Variable} scm_char_set_whitespace
2497 All whitespace characters.
2500 @defvr {Scheme Variable} char-set:blank
2501 @defvrx {C Variable} scm_char_set_blank
2502 All horizontal whitespace characters, which notably includes
2503 @code{#\space} and @code{#\tab}.
2506 @defvr {Scheme Variable} char-set:iso-control
2507 @defvrx {C Variable} scm_char_set_iso_control
2508 The ISO control characters are the C0 control characters (U+0000 to
2509 U+001F), delete (U+007F), and the C1 control characters (U+0080 to
2513 @defvr {Scheme Variable} char-set:punctuation
2514 @defvrx {C Variable} scm_char_set_punctuation
2515 All punctuation characters, such as the characters
2516 @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
2519 @defvr {Scheme Variable} char-set:symbol
2520 @defvrx {C Variable} scm_char_set_symbol
2521 All symbol characters, such as the characters @code{$+<=>^`|~}.
2524 @defvr {Scheme Variable} char-set:hex-digit
2525 @defvrx {C Variable} scm_char_set_hex_digit
2526 The hexadecimal digits @code{0123456789abcdefABCDEF}.
2529 @defvr {Scheme Variable} char-set:ascii
2530 @defvrx {C Variable} scm_char_set_ascii
2531 All ASCII characters.
2534 @defvr {Scheme Variable} char-set:empty
2535 @defvrx {C Variable} scm_char_set_empty
2536 The empty character set.
2539 @defvr {Scheme Variable} char-set:designated
2540 @defvrx {C Variable} scm_char_set_designated
2541 This character set contains all designated code points. This includes
2542 all the code points to which Unicode has assigned a character or other
2546 @defvr {Scheme Variable} char-set:full
2547 @defvrx {C Variable} scm_char_set_full
2548 This character set contains all possible code points. This includes
2549 both designated and reserved code points.
2556 Strings are fixed-length sequences of characters. They can be created
2557 by calling constructor procedures, but they can also literally get
2558 entered at the @acronym{REPL} or in Scheme source files.
2560 @c Guile provides a rich set of string processing procedures, because text
2561 @c handling is very important when Guile is used as a scripting language.
2563 Strings always carry the information about how many characters they are
2564 composed of with them, so there is no special end-of-string character,
2565 like in C. That means that Scheme strings can contain any character,
2566 even the @samp{#\nul} character @samp{\0}.
2568 To use strings efficiently, you need to know a bit about how Guile
2569 implements them. In Guile, a string consists of two parts, a head and
2570 the actual memory where the characters are stored. When a string (or
2571 a substring of it) is copied, only a new head gets created, the memory
2572 is usually not copied. The two heads start out pointing to the same
2575 When one of these two strings is modified, as with @code{string-set!},
2576 their common memory does get copied so that each string has its own
2577 memory and modifying one does not accidentally modify the other as well.
2578 Thus, Guile's strings are `copy on write'; the actual copying of their
2579 memory is delayed until one string is written to.
2581 This implementation makes functions like @code{substring} very
2582 efficient in the common case that no modifications are done to the
2585 If you do know that your strings are getting modified right away, you
2586 can use @code{substring/copy} instead of @code{substring}. This
2587 function performs the copy immediately at the time of creation. This
2588 is more efficient, especially in a multi-threaded program. Also,
2589 @code{substring/copy} can avoid the problem that a short substring
2590 holds on to the memory of a very large original string that could
2591 otherwise be recycled.
2593 If you want to avoid the copy altogether, so that modifications of one
2594 string show up in the other, you can use @code{substring/shared}. The
2595 strings created by this procedure are called @dfn{mutation sharing
2596 substrings} since the substring and the original string share
2597 modifications to each other.
2599 If you want to prevent modifications, use @code{substring/read-only}.
2601 Guile provides all procedures of SRFI-13 and a few more.
2604 * String Internals:: The storage strategy for strings.
2605 * String Syntax:: Read syntax for strings.
2606 * String Predicates:: Testing strings for certain properties.
2607 * String Constructors:: Creating new string objects.
2608 * List/String Conversion:: Converting from/to lists of characters.
2609 * String Selection:: Select portions from strings.
2610 * String Modification:: Modify parts or whole strings.
2611 * String Comparison:: Lexicographic ordering predicates.
2612 * String Searching:: Searching in strings.
2613 * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
2614 * Reversing and Appending Strings:: Appending strings to form a new string.
2615 * Mapping Folding and Unfolding:: Iterating over strings.
2616 * Miscellaneous String Operations:: Replicating, insertion, parsing, ...
2617 * Conversion to/from C::
2620 @node String Internals
2621 @subsubsection String Internals
2623 Guile stores each string in memory as a contiguous array of Unicode code
2624 points along with an associated set of attributes. If all of the code
2625 points of a string have an integer range between 0 and 255 inclusive,
2626 the code point array is stored as one byte per code point: it is stored
2627 as an ISO-8859-1 (aka Latin-1) string. If any of the code points of the
2628 string has an integer value greater that 255, the code point array is
2629 stored as four bytes per code point: it is stored as a UTF-32 string.
2631 Conversion between the one-byte-per-code-point and
2632 four-bytes-per-code-point representations happens automatically as
2635 No API is provided to set the internal representation of strings;
2636 however, there are pair of procedures available to query it. These are
2637 debugging procedures. Using them in production code is discouraged,
2638 since the details of Guile's internal representation of strings may
2639 change from release to release.
2641 @deffn {Scheme Procedure} string-bytes-per-char str
2642 @deffnx {C Function} scm_string_bytes_per_char (str)
2643 Return the number of bytes used to encode a Unicode code point in string
2644 @var{str}. The result is one or four.
2647 @deffn {Scheme Procedure} %string-dump str
2648 @deffnx {C Function} scm_sys_string_dump (str)
2649 Returns an association list containing debugging information for
2650 @var{str}. The association list has the following entries.
2657 The start index of the string into its stringbuf
2660 The length of the string
2663 If this string is a substring, it returns its
2664 parent string. Otherwise, it returns @code{#f}
2667 @code{#t} if the string is read-only
2669 @item stringbuf-chars
2670 A new string containing this string's stringbuf's characters
2672 @item stringbuf-length
2673 The number of characters in this stringbuf
2675 @item stringbuf-shared
2676 @code{#t} if this stringbuf is shared
2678 @item stringbuf-wide
2679 @code{#t} if this stringbuf's characters are stored in a 32-bit buffer,
2680 or @code{#f} if they are stored in an 8-bit buffer
2686 @subsubsection String Read Syntax
2688 @c In the following @code is used to get a good font in TeX etc, but
2689 @c is omitted for Info format, so as not to risk any confusion over
2690 @c whether surrounding ` ' quotes are part of the escape or are
2691 @c special in a string (they're not).
2693 The read syntax for strings is an arbitrarily long sequence of
2694 characters enclosed in double quotes (@nicode{"}).
2696 Backslash is an escape character and can be used to insert the following
2697 special characters. @nicode{\"} and @nicode{\\} are R5RS standard, the
2698 next seven are R6RS standard --- notice they follow C syntax --- and the
2699 remaining four are Guile extensions.
2703 Backslash character.
2706 Double quote character (an unescaped @nicode{"} is otherwise the end
2710 Bell character (ASCII 7).
2713 Formfeed character (ASCII 12).
2716 Newline character (ASCII 10).
2719 Carriage return character (ASCII 13).
2722 Tab character (ASCII 9).
2725 Vertical tab character (ASCII 11).
2728 Backspace character (ASCII 8).
2731 NUL character (ASCII 0).
2734 Character code given by two hexadecimal digits. For example
2735 @nicode{\x7f} for an ASCII DEL (127).
2737 @item @nicode{\uHHHH}
2738 Character code given by four hexadecimal digits. For example
2739 @nicode{\u0100} for a capital A with macron (U+0100).
2741 @item @nicode{\UHHHHHH}
2742 Character code given by six hexadecimal digits. For example
2747 The following are examples of string literals:
2756 The three escape sequences @code{\xHH}, @code{\uHHHH} and @code{\UHHHHHH} were
2757 chosen to not break compatibility with code written for previous versions of
2758 Guile. The R6RS specification suggests a different, incompatible syntax for hex
2759 escapes: @code{\xHHHH;} -- a character code followed by one to eight hexadecimal
2760 digits terminated with a semicolon. If this escape format is desired instead,
2761 it can be enabled with the reader option @code{r6rs-hex-escapes}.
2764 (read-enable 'r6rs-hex-escapes)
2767 Enabling this option will also change the hex escape format for characters.
2768 More on character escapes can be found at (@pxref{Characters}). More on
2769 reader options in general can be found at (@pxref{Reader options}).
2771 @node String Predicates
2772 @subsubsection String Predicates
2774 The following procedures can be used to check whether a given string
2775 fulfills some specified property.
2778 @deffn {Scheme Procedure} string? obj
2779 @deffnx {C Function} scm_string_p (obj)
2780 Return @code{#t} if @var{obj} is a string, else @code{#f}.
2783 @deftypefn {C Function} int scm_is_string (SCM obj)
2784 Returns @code{1} if @var{obj} is a string, @code{0} otherwise.
2787 @deffn {Scheme Procedure} string-null? str
2788 @deffnx {C Function} scm_string_null_p (str)
2789 Return @code{#t} if @var{str}'s length is zero, and
2790 @code{#f} otherwise.
2792 (string-null? "") @result{} #t
2794 (string-null? y) @result{} #f
2798 @deffn {Scheme Procedure} string-any char_pred s [start [end]]
2799 @deffnx {C Function} scm_string_any (char_pred, s, start, end)
2800 Check if @var{char_pred} is true for any character in string @var{s}.
2802 @var{char_pred} can be a character to check for any equal to that, or
2803 a character set (@pxref{Character Sets}) to check for any in that set,
2804 or a predicate procedure to call.
2806 For a procedure, calls @code{(@var{char_pred} c)} are made
2807 successively on the characters from @var{start} to @var{end}. If
2808 @var{char_pred} returns true (ie.@: non-@code{#f}), @code{string-any}
2809 stops and that return value is the return from @code{string-any}. The
2810 call on the last character (ie.@: at @math{@var{end}-1}), if that
2811 point is reached, is a tail call.
2813 If there are no characters in @var{s} (ie.@: @var{start} equals
2814 @var{end}) then the return is @code{#f}.
2817 @deffn {Scheme Procedure} string-every char_pred s [start [end]]
2818 @deffnx {C Function} scm_string_every (char_pred, s, start, end)
2819 Check if @var{char_pred} is true for every character in string
2822 @var{char_pred} can be a character to check for every character equal
2823 to that, or a character set (@pxref{Character Sets}) to check for
2824 every character being in that set, or a predicate procedure to call.
2826 For a procedure, calls @code{(@var{char_pred} c)} are made
2827 successively on the characters from @var{start} to @var{end}. If
2828 @var{char_pred} returns @code{#f}, @code{string-every} stops and
2829 returns @code{#f}. The call on the last character (ie.@: at
2830 @math{@var{end}-1}), if that point is reached, is a tail call and the
2831 return from that call is the return from @code{string-every}.
2833 If there are no characters in @var{s} (ie.@: @var{start} equals
2834 @var{end}) then the return is @code{#t}.
2837 @node String Constructors
2838 @subsubsection String Constructors
2840 The string constructor procedures create new string objects, possibly
2841 initializing them with some specified character data. See also
2842 @xref{String Selection}, for ways to create strings from existing
2845 @c FIXME::martin: list->string belongs into `List/String Conversion'
2847 @deffn {Scheme Procedure} string char@dots{}
2849 Return a newly allocated string made from the given character
2853 (string #\x #\y #\z) @result{} "xyz"
2854 (string) @result{} ""
2858 @deffn {Scheme Procedure} list->string lst
2859 @deffnx {C Function} scm_string (lst)
2860 @rnindex list->string
2861 Return a newly allocated string made from a list of characters.
2864 (list->string '(#\a #\b #\c)) @result{} "abc"
2868 @deffn {Scheme Procedure} reverse-list->string lst
2869 @deffnx {C Function} scm_reverse_list_to_string (lst)
2870 Return a newly allocated string made from a list of characters, in
2874 (reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
2878 @rnindex make-string
2879 @deffn {Scheme Procedure} make-string k [chr]
2880 @deffnx {C Function} scm_make_string (k, chr)
2881 Return a newly allocated string of
2882 length @var{k}. If @var{chr} is given, then all elements of
2883 the string are initialized to @var{chr}, otherwise the contents
2884 of the @var{string} are unspecified.
2887 @deftypefn {C Function} SCM scm_c_make_string (size_t len, SCM chr)
2888 Like @code{scm_make_string}, but expects the length as a
2892 @deffn {Scheme Procedure} string-tabulate proc len
2893 @deffnx {C Function} scm_string_tabulate (proc, len)
2894 @var{proc} is an integer->char procedure. Construct a string
2895 of size @var{len} by applying @var{proc} to each index to
2896 produce the corresponding string element. The order in which
2897 @var{proc} is applied to the indices is not specified.
2900 @deffn {Scheme Procedure} string-join ls [delimiter [grammar]]
2901 @deffnx {C Function} scm_string_join (ls, delimiter, grammar)
2902 Append the string in the string list @var{ls}, using the string
2903 @var{delim} as a delimiter between the elements of @var{ls}.
2904 @var{grammar} is a symbol which specifies how the delimiter is
2905 placed between the strings, and defaults to the symbol
2910 Insert the separator between list elements. An empty string
2911 will produce an empty list.
2913 Like @code{infix}, but will raise an error if given the empty
2916 Insert the separator after every list element.
2918 Insert the separator before each list element.
2922 @node List/String Conversion
2923 @subsubsection List/String conversion
2925 When processing strings, it is often convenient to first convert them
2926 into a list representation by using the procedure @code{string->list},
2927 work with the resulting list, and then convert it back into a string.
2928 These procedures are useful for similar tasks.
2930 @rnindex string->list
2931 @deffn {Scheme Procedure} string->list str [start [end]]
2932 @deffnx {C Function} scm_substring_to_list (str, start, end)
2933 @deffnx {C Function} scm_string_to_list (str)
2934 Convert the string @var{str} into a list of characters.
2937 @deffn {Scheme Procedure} string-split str chr
2938 @deffnx {C Function} scm_string_split (str, chr)
2939 Split the string @var{str} into the a list of the substrings delimited
2940 by appearances of the character @var{chr}. Note that an empty substring
2941 between separator characters will result in an empty string in the
2945 (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
2947 ("root" "x" "0" "0" "root" "/root" "/bin/bash")
2949 (string-split "::" #\:)
2953 (string-split "" #\:)
2960 @node String Selection
2961 @subsubsection String Selection
2963 Portions of strings can be extracted by these procedures.
2964 @code{string-ref} delivers individual characters whereas
2965 @code{substring} can be used to extract substrings from longer strings.
2967 @rnindex string-length
2968 @deffn {Scheme Procedure} string-length string
2969 @deffnx {C Function} scm_string_length (string)
2970 Return the number of characters in @var{string}.
2973 @deftypefn {C Function} size_t scm_c_string_length (SCM str)
2974 Return the number of characters in @var{str} as a @code{size_t}.
2978 @deffn {Scheme Procedure} string-ref str k
2979 @deffnx {C Function} scm_string_ref (str, k)
2980 Return character @var{k} of @var{str} using zero-origin
2981 indexing. @var{k} must be a valid index of @var{str}.
2984 @deftypefn {C Function} SCM scm_c_string_ref (SCM str, size_t k)
2985 Return character @var{k} of @var{str} using zero-origin
2986 indexing. @var{k} must be a valid index of @var{str}.
2989 @rnindex string-copy
2990 @deffn {Scheme Procedure} string-copy str [start [end]]
2991 @deffnx {C Function} scm_substring_copy (str, start, end)
2992 @deffnx {C Function} scm_string_copy (str)
2993 Return a copy of the given string @var{str}.
2995 The returned string shares storage with @var{str} initially, but it is
2996 copied as soon as one of the two strings is modified.
3000 @deffn {Scheme Procedure} substring str start [end]
3001 @deffnx {C Function} scm_substring (str, start, end)
3002 Return a new string formed from the characters
3003 of @var{str} beginning with index @var{start} (inclusive) and
3004 ending with index @var{end} (exclusive).
3005 @var{str} must be a string, @var{start} and @var{end} must be
3006 exact integers satisfying:
3008 0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
3010 The returned string shares storage with @var{str} initially, but it is
3011 copied as soon as one of the two strings is modified.
3014 @deffn {Scheme Procedure} substring/shared str start [end]
3015 @deffnx {C Function} scm_substring_shared (str, start, end)
3016 Like @code{substring}, but the strings continue to share their storage
3017 even if they are modified. Thus, modifications to @var{str} show up
3018 in the new string, and vice versa.
3021 @deffn {Scheme Procedure} substring/copy str start [end]
3022 @deffnx {C Function} scm_substring_copy (str, start, end)
3023 Like @code{substring}, but the storage for the new string is copied
3027 @deffn {Scheme Procedure} substring/read-only str start [end]
3028 @deffnx {C Function} scm_substring_read_only (str, start, end)
3029 Like @code{substring}, but the resulting string can not be modified.
3032 @deftypefn {C Function} SCM scm_c_substring (SCM str, size_t start, size_t end)
3033 @deftypefnx {C Function} SCM scm_c_substring_shared (SCM str, size_t start, size_t end)
3034 @deftypefnx {C Function} SCM scm_c_substring_copy (SCM str, size_t start, size_t end)
3035 @deftypefnx {C Function} SCM scm_c_substring_read_only (SCM str, size_t start, size_t end)
3036 Like @code{scm_substring}, etc. but the bounds are given as a @code{size_t}.
3039 @deffn {Scheme Procedure} string-take s n
3040 @deffnx {C Function} scm_string_take (s, n)
3041 Return the @var{n} first characters of @var{s}.
3044 @deffn {Scheme Procedure} string-drop s n
3045 @deffnx {C Function} scm_string_drop (s, n)
3046 Return all but the first @var{n} characters of @var{s}.
3049 @deffn {Scheme Procedure} string-take-right s n
3050 @deffnx {C Function} scm_string_take_right (s, n)
3051 Return the @var{n} last characters of @var{s}.
3054 @deffn {Scheme Procedure} string-drop-right s n
3055 @deffnx {C Function} scm_string_drop_right (s, n)
3056 Return all but the last @var{n} characters of @var{s}.
3059 @deffn {Scheme Procedure} string-pad s len [chr [start [end]]]
3060 @deffnx {Scheme Procedure} string-pad-right s len [chr [start [end]]]
3061 @deffnx {C Function} scm_string_pad (s, len, chr, start, end)
3062 @deffnx {C Function} scm_string_pad_right (s, len, chr, start, end)
3063 Take characters @var{start} to @var{end} from the string @var{s} and
3064 either pad with @var{char} or truncate them to give @var{len}
3067 @code{string-pad} pads or truncates on the left, so for example
3070 (string-pad "x" 3) @result{} " x"
3071 (string-pad "abcde" 3) @result{} "cde"
3074 @code{string-pad-right} pads or truncates on the right, so for example
3077 (string-pad-right "x" 3) @result{} "x "
3078 (string-pad-right "abcde" 3) @result{} "abc"
3082 @deffn {Scheme Procedure} string-trim s [char_pred [start [end]]]
3083 @deffnx {Scheme Procedure} string-trim-right s [char_pred [start [end]]]
3084 @deffnx {Scheme Procedure} string-trim-both s [char_pred [start [end]]]
3085 @deffnx {C Function} scm_string_trim (s, char_pred, start, end)
3086 @deffnx {C Function} scm_string_trim_right (s, char_pred, start, end)
3087 @deffnx {C Function} scm_string_trim_both (s, char_pred, start, end)
3088 Trim occurrences of @var{char_pred} from the ends of @var{s}.
3090 @code{string-trim} trims @var{char_pred} characters from the left
3091 (start) of the string, @code{string-trim-right} trims them from the
3092 right (end) of the string, @code{string-trim-both} trims from both
3095 @var{char_pred} can be a character, a character set, or a predicate
3096 procedure to call on each character. If @var{char_pred} is not given
3097 the default is whitespace as per @code{char-set:whitespace}
3098 (@pxref{Standard Character Sets}).
3101 (string-trim " x ") @result{} "x "
3102 (string-trim-right "banana" #\a) @result{} "banan"
3103 (string-trim-both ".,xy:;" char-set:punctuation)
3105 (string-trim-both "xyzzy" (lambda (c)
3112 @node String Modification
3113 @subsubsection String Modification
3115 These procedures are for modifying strings in-place. This means that the
3116 result of the operation is not a new string; instead, the original string's
3117 memory representation is modified.
3119 @rnindex string-set!
3120 @deffn {Scheme Procedure} string-set! str k chr
3121 @deffnx {C Function} scm_string_set_x (str, k, chr)
3122 Store @var{chr} in element @var{k} of @var{str} and return
3123 an unspecified value. @var{k} must be a valid index of
3127 @deftypefn {C Function} void scm_c_string_set_x (SCM str, size_t k, SCM chr)
3128 Like @code{scm_string_set_x}, but the index is given as a @code{size_t}.
3131 @rnindex string-fill!
3132 @deffn {Scheme Procedure} string-fill! str chr [start [end]]
3133 @deffnx {C Function} scm_substring_fill_x (str, chr, start, end)
3134 @deffnx {C Function} scm_string_fill_x (str, chr)
3135 Stores @var{chr} in every element of the given @var{str} and
3136 returns an unspecified value.
3139 @deffn {Scheme Procedure} substring-fill! str start end fill
3140 @deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
3141 Change every character in @var{str} between @var{start} and
3142 @var{end} to @var{fill}.
3145 (define y "abcdefg")
3146 (substring-fill! y 1 3 #\r)
3152 @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
3153 @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
3154 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
3155 into @var{str2} beginning at position @var{start2}.
3156 @var{str1} and @var{str2} can be the same string.
3159 @deffn {Scheme Procedure} string-copy! target tstart s [start [end]]
3160 @deffnx {C Function} scm_string_copy_x (target, tstart, s, start, end)
3161 Copy the sequence of characters from index range [@var{start},
3162 @var{end}) in string @var{s} to string @var{target}, beginning
3163 at index @var{tstart}. The characters are copied left-to-right
3164 or right-to-left as needed -- the copy is guaranteed to work,
3165 even if @var{target} and @var{s} are the same string. It is an
3166 error if the copy operation runs off the end of the target
3171 @node String Comparison
3172 @subsubsection String Comparison
3174 The procedures in this section are similar to the character ordering
3175 predicates (@pxref{Characters}), but are defined on character sequences.
3177 The first set is specified in R5RS and has names that end in @code{?}.
3178 The second set is specified in SRFI-13 and the names have not ending
3181 The predicates ending in @code{-ci} ignore the character case
3182 when comparing strings. For now, case-insensitive comparison is done
3183 using the R5RS rules, where every lower-case character that has a
3184 single character upper-case form is converted to uppercase before
3185 comparison. See @xref{Text Collation, the @code{(ice-9
3186 i18n)} module}, for locale-dependent string comparison.
3189 @deffn {Scheme Procedure} string=? [s1 [s2 . rest]]
3190 @deffnx {C Function} scm_i_string_equal_p (s1, s2, rest)
3191 Lexicographic equality predicate; return @code{#t} if the two
3192 strings are the same length and contain the same characters in
3193 the same positions, otherwise return @code{#f}.
3195 The procedure @code{string-ci=?} treats upper and lower case
3196 letters as though they were the same character, but
3197 @code{string=?} treats upper and lower case as distinct
3202 @deffn {Scheme Procedure} string<? [s1 [s2 . rest]]
3203 @deffnx {C Function} scm_i_string_less_p (s1, s2, rest)
3204 Lexicographic ordering predicate; return @code{#t} if @var{s1}
3205 is lexicographically less than @var{s2}.
3209 @deffn {Scheme Procedure} string<=? [s1 [s2 . rest]]
3210 @deffnx {C Function} scm_i_string_leq_p (s1, s2, rest)
3211 Lexicographic ordering predicate; return @code{#t} if @var{s1}
3212 is lexicographically less than or equal to @var{s2}.
3216 @deffn {Scheme Procedure} string>? [s1 [s2 . rest]]
3217 @deffnx {C Function} scm_i_string_gr_p (s1, s2, rest)
3218 Lexicographic ordering predicate; return @code{#t} if @var{s1}
3219 is lexicographically greater than @var{s2}.
3223 @deffn {Scheme Procedure} string>=? [s1 [s2 . rest]]
3224 @deffnx {C Function} scm_i_string_geq_p (s1, s2, rest)
3225 Lexicographic ordering predicate; return @code{#t} if @var{s1}
3226 is lexicographically greater than or equal to @var{s2}.
3229 @rnindex string-ci=?
3230 @deffn {Scheme Procedure} string-ci=? [s1 [s2 . rest]]
3231 @deffnx {C Function} scm_i_string_ci_equal_p (s1, s2, rest)
3232 Case-insensitive string equality predicate; return @code{#t} if
3233 the two strings are the same length and their component
3234 characters match (ignoring case) at each position; otherwise
3238 @rnindex string-ci<?
3239 @deffn {Scheme Procedure} string-ci<? [s1 [s2 . rest]]
3240 @deffnx {C Function} scm_i_string_ci_less_p (s1, s2, rest)
3241 Case insensitive lexicographic ordering predicate; return
3242 @code{#t} if @var{s1} is lexicographically less than @var{s2}
3247 @deffn {Scheme Procedure} string-ci<=? [s1 [s2 . rest]]
3248 @deffnx {C Function} scm_i_string_ci_leq_p (s1, s2, rest)
3249 Case insensitive lexicographic ordering predicate; return
3250 @code{#t} if @var{s1} is lexicographically less than or equal
3251 to @var{s2} regardless of case.
3254 @rnindex string-ci>?
3255 @deffn {Scheme Procedure} string-ci>? [s1 [s2 . rest]]
3256 @deffnx {C Function} scm_i_string_ci_gr_p (s1, s2, rest)
3257 Case insensitive lexicographic ordering predicate; return
3258 @code{#t} if @var{s1} is lexicographically greater than
3259 @var{s2} regardless of case.
3262 @rnindex string-ci>=?
3263 @deffn {Scheme Procedure} string-ci>=? [s1 [s2 . rest]]
3264 @deffnx {C Function} scm_i_string_ci_geq_p (s1, s2, rest)
3265 Case insensitive lexicographic ordering predicate; return
3266 @code{#t} if @var{s1} is lexicographically greater than or
3267 equal to @var{s2} regardless of case.
3270 @deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3271 @deffnx {C Function} scm_string_compare (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3272 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3273 mismatch index, depending upon whether @var{s1} is less than,
3274 equal to, or greater than @var{s2}. The mismatch index is the
3275 largest index @var{i} such that for every 0 <= @var{j} <
3276 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3277 @var{i} is the first position that does not match.
3280 @deffn {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3281 @deffnx {C Function} scm_string_compare_ci (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3282 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3283 mismatch index, depending upon whether @var{s1} is less than,
3284 equal to, or greater than @var{s2}. The mismatch index is the
3285 largest index @var{i} such that for every 0 <= @var{j} <
3286 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3287 @var{i} is the first position where the lowercased letters
3292 @deffn {Scheme Procedure} string= s1 s2 [start1 [end1 [start2 [end2]]]]
3293 @deffnx {C Function} scm_string_eq (s1, s2, start1, end1, start2, end2)
3294 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3298 @deffn {Scheme Procedure} string<> s1 s2 [start1 [end1 [start2 [end2]]]]
3299 @deffnx {C Function} scm_string_neq (s1, s2, start1, end1, start2, end2)
3300 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3304 @deffn {Scheme Procedure} string< s1 s2 [start1 [end1 [start2 [end2]]]]
3305 @deffnx {C Function} scm_string_lt (s1, s2, start1, end1, start2, end2)
3306 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3307 true value otherwise.
3310 @deffn {Scheme Procedure} string> s1 s2 [start1 [end1 [start2 [end2]]]]
3311 @deffnx {C Function} scm_string_gt (s1, s2, start1, end1, start2, end2)
3312 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3313 true value otherwise.
3316 @deffn {Scheme Procedure} string<= s1 s2 [start1 [end1 [start2 [end2]]]]
3317 @deffnx {C Function} scm_string_le (s1, s2, start1, end1, start2, end2)
3318 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3322 @deffn {Scheme Procedure} string>= s1 s2 [start1 [end1 [start2 [end2]]]]
3323 @deffnx {C Function} scm_string_ge (s1, s2, start1, end1, start2, end2)
3324 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3328 @deffn {Scheme Procedure} string-ci= s1 s2 [start1 [end1 [start2 [end2]]]]
3329 @deffnx {C Function} scm_string_ci_eq (s1, s2, start1, end1, start2, end2)
3330 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3331 value otherwise. The character comparison is done
3335 @deffn {Scheme Procedure} string-ci<> s1 s2 [start1 [end1 [start2 [end2]]]]
3336 @deffnx {C Function} scm_string_ci_neq (s1, s2, start1, end1, start2, end2)
3337 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3338 value otherwise. The character comparison is done
3342 @deffn {Scheme Procedure} string-ci< s1 s2 [start1 [end1 [start2 [end2]]]]
3343 @deffnx {C Function} scm_string_ci_lt (s1, s2, start1, end1, start2, end2)
3344 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3345 true value otherwise. The character comparison is done
3349 @deffn {Scheme Procedure} string-ci> s1 s2 [start1 [end1 [start2 [end2]]]]
3350 @deffnx {C Function} scm_string_ci_gt (s1, s2, start1, end1, start2, end2)
3351 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3352 true value otherwise. The character comparison is done
3356 @deffn {Scheme Procedure} string-ci<= s1 s2 [start1 [end1 [start2 [end2]]]]
3357 @deffnx {C Function} scm_string_ci_le (s1, s2, start1, end1, start2, end2)
3358 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3359 value otherwise. The character comparison is done
3363 @deffn {Scheme Procedure} string-ci>= s1 s2 [start1 [end1 [start2 [end2]]]]
3364 @deffnx {C Function} scm_string_ci_ge (s1, s2, start1, end1, start2, end2)
3365 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3366 otherwise. The character comparison is done
3370 @deffn {Scheme Procedure} string-hash s [bound [start [end]]]
3371 @deffnx {C Function} scm_substring_hash (s, bound, start, end)
3372 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).
3375 @deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
3376 @deffnx {C Function} scm_substring_hash_ci (s, bound, start, end)
3377 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).
3380 Because the same visual appearance of an abstract Unicode character can
3381 be obtained via multiple sequences of Unicode characters, even the
3382 case-insensitive string comparison functions described above may return
3383 @code{#f} when presented with strings containing different
3384 representations of the same character. For example, the Unicode
3385 character ``LATIN SMALL LETTER S WITH DOT BELOW AND DOT ABOVE'' can be
3386 represented with a single character (U+1E69) or by the character ``LATIN
3387 SMALL LETTER S'' (U+0073) followed by the combining marks ``COMBINING
3388 DOT BELOW'' (U+0323) and ``COMBINING DOT ABOVE'' (U+0307).
3390 For this reason, it is often desirable to ensure that the strings
3391 to be compared are using a mutually consistent representation for every
3392 character. The Unicode standard defines two methods of normalizing the
3393 contents of strings: Decomposition, which breaks composite characters
3394 into a set of constituent characters with an ordering defined by the
3395 Unicode Standard; and composition, which performs the converse.
3397 There are two decomposition operations. ``Canonical decomposition''
3398 produces character sequences that share the same visual appearance as
3399 the original characters, while ``compatiblity decomposition'' produces
3400 ones whose visual appearances may differ from the originals but which
3401 represent the same abstract character.
3403 These operations are encapsulated in the following set of normalization
3408 Characters are decomposed to their canonical forms.
3411 Characters are decomposed to their compatibility forms.
3414 Characters are decomposed to their canonical forms, then composed.
3417 Characters are decomposed to their compatibility forms, then composed.
3421 The functions below put their arguments into one of the forms described
3424 @deffn {Scheme Procedure} string-normalize-nfd s
3425 @deffnx {C Function} scm_string_normalize_nfd (s)
3426 Return the @code{NFD} normalized form of @var{s}.
3429 @deffn {Scheme Procedure} string-normalize-nfkd s
3430 @deffnx {C Function} scm_string_normalize_nfkd (s)
3431 Return the @code{NFKD} normalized form of @var{s}.
3434 @deffn {Scheme Procedure} string-normalize-nfc s
3435 @deffnx {C Function} scm_string_normalize_nfc (s)
3436 Return the @code{NFC} normalized form of @var{s}.
3439 @deffn {Scheme Procedure} string-normalize-nfkc s
3440 @deffnx {C Function} scm_string_normalize_nfkc (s)
3441 Return the @code{NFKC} normalized form of @var{s}.
3444 @node String Searching
3445 @subsubsection String Searching
3447 @deffn {Scheme Procedure} string-index s char_pred [start [end]]
3448 @deffnx {C Function} scm_string_index (s, char_pred, start, end)
3449 Search through the string @var{s} from left to right, returning
3450 the index of the first occurrence of a character which
3454 equals @var{char_pred}, if it is character,
3457 satisfies the predicate @var{char_pred}, if it is a procedure,
3460 is in the set @var{char_pred}, if it is a character set.
3464 @deffn {Scheme Procedure} string-rindex s char_pred [start [end]]
3465 @deffnx {C Function} scm_string_rindex (s, char_pred, start, end)
3466 Search through the string @var{s} from right to left, returning
3467 the index of the last occurrence of a character which
3471 equals @var{char_pred}, if it is character,
3474 satisfies the predicate @var{char_pred}, if it is a procedure,
3477 is in the set if @var{char_pred} is a character set.
3481 @deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3482 @deffnx {C Function} scm_string_prefix_length (s1, s2, start1, end1, start2, end2)
3483 Return the length of the longest common prefix of the two
3487 @deffn {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3488 @deffnx {C Function} scm_string_prefix_length_ci (s1, s2, start1, end1, start2, end2)
3489 Return the length of the longest common prefix of the two
3490 strings, ignoring character case.
3493 @deffn {Scheme Procedure} string-suffix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3494 @deffnx {C Function} scm_string_suffix_length (s1, s2, start1, end1, start2, end2)
3495 Return the length of the longest common suffix of the two
3499 @deffn {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3500 @deffnx {C Function} scm_string_suffix_length_ci (s1, s2, start1, end1, start2, end2)
3501 Return the length of the longest common suffix of the two
3502 strings, ignoring character case.
3505 @deffn {Scheme Procedure} string-prefix? s1 s2 [start1 [end1 [start2 [end2]]]]
3506 @deffnx {C Function} scm_string_prefix_p (s1, s2, start1, end1, start2, end2)
3507 Is @var{s1} a prefix of @var{s2}?
3510 @deffn {Scheme Procedure} string-prefix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3511 @deffnx {C Function} scm_string_prefix_ci_p (s1, s2, start1, end1, start2, end2)
3512 Is @var{s1} a prefix of @var{s2}, ignoring character case?
3515 @deffn {Scheme Procedure} string-suffix? s1 s2 [start1 [end1 [start2 [end2]]]]
3516 @deffnx {C Function} scm_string_suffix_p (s1, s2, start1, end1, start2, end2)
3517 Is @var{s1} a suffix of @var{s2}?
3520 @deffn {Scheme Procedure} string-suffix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3521 @deffnx {C Function} scm_string_suffix_ci_p (s1, s2, start1, end1, start2, end2)
3522 Is @var{s1} a suffix of @var{s2}, ignoring character case?
3525 @deffn {Scheme Procedure} string-index-right s char_pred [start [end]]
3526 @deffnx {C Function} scm_string_index_right (s, char_pred, start, end)
3527 Search through the string @var{s} from right to left, returning
3528 the index of the last occurrence of a character which
3532 equals @var{char_pred}, if it is character,
3535 satisfies the predicate @var{char_pred}, if it is a procedure,
3538 is in the set if @var{char_pred} is a character set.
3542 @deffn {Scheme Procedure} string-skip s char_pred [start [end]]
3543 @deffnx {C Function} scm_string_skip (s, char_pred, start, end)
3544 Search through the string @var{s} from left to right, returning
3545 the index of the first occurrence of a character which
3549 does not equal @var{char_pred}, if it is character,
3552 does not satisfy the predicate @var{char_pred}, if it is a
3556 is not in the set if @var{char_pred} is a character set.
3560 @deffn {Scheme Procedure} string-skip-right s char_pred [start [end]]
3561 @deffnx {C Function} scm_string_skip_right (s, char_pred, start, end)
3562 Search through the string @var{s} from right to left, returning
3563 the index of the last occurrence of a character which
3567 does not equal @var{char_pred}, if it is character,
3570 does not satisfy the predicate @var{char_pred}, if it is a
3574 is not in the set if @var{char_pred} is a character set.
3578 @deffn {Scheme Procedure} string-count s char_pred [start [end]]
3579 @deffnx {C Function} scm_string_count (s, char_pred, start, end)
3580 Return the count of the number of characters in the string
3585 equals @var{char_pred}, if it is character,
3588 satisfies the predicate @var{char_pred}, if it is a procedure.
3591 is in the set @var{char_pred}, if it is a character set.
3595 @deffn {Scheme Procedure} string-contains s1 s2 [start1 [end1 [start2 [end2]]]]
3596 @deffnx {C Function} scm_string_contains (s1, s2, start1, end1, start2, end2)
3597 Does string @var{s1} contain string @var{s2}? Return the index
3598 in @var{s1} where @var{s2} occurs as a substring, or false.
3599 The optional start/end indices restrict the operation to the
3600 indicated substrings.
3603 @deffn {Scheme Procedure} string-contains-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3604 @deffnx {C Function} scm_string_contains_ci (s1, s2, start1, end1, start2, end2)
3605 Does string @var{s1} contain string @var{s2}? Return the index
3606 in @var{s1} where @var{s2} occurs as a substring, or false.
3607 The optional start/end indices restrict the operation to the
3608 indicated substrings. Character comparison is done
3612 @node Alphabetic Case Mapping
3613 @subsubsection Alphabetic Case Mapping
3615 These are procedures for mapping strings to their upper- or lower-case
3616 equivalents, respectively, or for capitalizing strings.
3618 They use the basic case mapping rules for Unicode characters. No
3619 special language or context rules are considered. The resulting strings
3620 are guaranteed to be the same length as the input strings.
3622 @xref{Character Case Mapping, the @code{(ice-9
3623 i18n)} module}, for locale-dependent case conversions.
3625 @deffn {Scheme Procedure} string-upcase str [start [end]]
3626 @deffnx {C Function} scm_substring_upcase (str, start, end)
3627 @deffnx {C Function} scm_string_upcase (str)
3628 Upcase every character in @code{str}.
3631 @deffn {Scheme Procedure} string-upcase! str [start [end]]
3632 @deffnx {C Function} scm_substring_upcase_x (str, start, end)
3633 @deffnx {C Function} scm_string_upcase_x (str)
3634 Destructively upcase every character in @code{str}.
3644 @deffn {Scheme Procedure} string-downcase str [start [end]]
3645 @deffnx {C Function} scm_substring_downcase (str, start, end)
3646 @deffnx {C Function} scm_string_downcase (str)
3647 Downcase every character in @var{str}.
3650 @deffn {Scheme Procedure} string-downcase! str [start [end]]
3651 @deffnx {C Function} scm_substring_downcase_x (str, start, end)
3652 @deffnx {C Function} scm_string_downcase_x (str)
3653 Destructively downcase every character in @var{str}.
3658 (string-downcase! y)
3665 @deffn {Scheme Procedure} string-capitalize str
3666 @deffnx {C Function} scm_string_capitalize (str)
3667 Return a freshly allocated string with the characters in
3668 @var{str}, where the first character of every word is
3672 @deffn {Scheme Procedure} string-capitalize! str
3673 @deffnx {C Function} scm_string_capitalize_x (str)
3674 Upcase the first character of every word in @var{str}
3675 destructively and return @var{str}.
3678 y @result{} "hello world"
3679 (string-capitalize! y) @result{} "Hello World"
3680 y @result{} "Hello World"
3684 @deffn {Scheme Procedure} string-titlecase str [start [end]]
3685 @deffnx {C Function} scm_string_titlecase (str, start, end)
3686 Titlecase every first character in a word in @var{str}.
3689 @deffn {Scheme Procedure} string-titlecase! str [start [end]]
3690 @deffnx {C Function} scm_string_titlecase_x (str, start, end)
3691 Destructively titlecase every first character in a word in
3695 @node Reversing and Appending Strings
3696 @subsubsection Reversing and Appending Strings
3698 @deffn {Scheme Procedure} string-reverse str [start [end]]
3699 @deffnx {C Function} scm_string_reverse (str, start, end)
3700 Reverse the string @var{str}. The optional arguments
3701 @var{start} and @var{end} delimit the region of @var{str} to
3705 @deffn {Scheme Procedure} string-reverse! str [start [end]]
3706 @deffnx {C Function} scm_string_reverse_x (str, start, end)
3707 Reverse the string @var{str} in-place. The optional arguments
3708 @var{start} and @var{end} delimit the region of @var{str} to
3709 operate on. The return value is unspecified.
3712 @rnindex string-append
3713 @deffn {Scheme Procedure} string-append . args
3714 @deffnx {C Function} scm_string_append (args)
3715 Return a newly allocated string whose characters form the
3716 concatenation of the given strings, @var{args}.
3720 (string-append h "world"))
3721 @result{} "hello world"
3725 @deffn {Scheme Procedure} string-append/shared . rest
3726 @deffnx {C Function} scm_string_append_shared (rest)
3727 Like @code{string-append}, but the result may share memory
3728 with the argument strings.
3731 @deffn {Scheme Procedure} string-concatenate ls
3732 @deffnx {C Function} scm_string_concatenate (ls)
3733 Append the elements of @var{ls} (which must be strings)
3734 together into a single string. Guaranteed to return a freshly
3738 @deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]]
3739 @deffnx {C Function} scm_string_concatenate_reverse (ls, final_string, end)
3740 Without optional arguments, this procedure is equivalent to
3743 (string-concatenate (reverse ls))
3746 If the optional argument @var{final_string} is specified, it is
3747 consed onto the beginning to @var{ls} before performing the
3748 list-reverse and string-concatenate operations. If @var{end}
3749 is given, only the characters of @var{final_string} up to index
3752 Guaranteed to return a freshly allocated string.
3755 @deffn {Scheme Procedure} string-concatenate/shared ls
3756 @deffnx {C Function} scm_string_concatenate_shared (ls)
3757 Like @code{string-concatenate}, but the result may share memory
3758 with the strings in the list @var{ls}.
3761 @deffn {Scheme Procedure} string-concatenate-reverse/shared ls [final_string [end]]
3762 @deffnx {C Function} scm_string_concatenate_reverse_shared (ls, final_string, end)
3763 Like @code{string-concatenate-reverse}, but the result may
3764 share memory with the strings in the @var{ls} arguments.
3767 @node Mapping Folding and Unfolding
3768 @subsubsection Mapping, Folding, and Unfolding
3770 @deffn {Scheme Procedure} string-map proc s [start [end]]
3771 @deffnx {C Function} scm_string_map (proc, s, start, end)
3772 @var{proc} is a char->char procedure, it is mapped over
3773 @var{s}. The order in which the procedure is applied to the
3774 string elements is not specified.
3777 @deffn {Scheme Procedure} string-map! proc s [start [end]]
3778 @deffnx {C Function} scm_string_map_x (proc, s, start, end)
3779 @var{proc} is a char->char procedure, it is mapped over
3780 @var{s}. The order in which the procedure is applied to the
3781 string elements is not specified. The string @var{s} is
3782 modified in-place, the return value is not specified.
3785 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
3786 @deffnx {C Function} scm_string_for_each (proc, s, start, end)
3787 @var{proc} is mapped over @var{s} in left-to-right order. The
3788 return value is not specified.
3791 @deffn {Scheme Procedure} string-for-each-index proc s [start [end]]
3792 @deffnx {C Function} scm_string_for_each_index (proc, s, start, end)
3793 Call @code{(@var{proc} i)} for each index i in @var{s}, from left to
3796 For example, to change characters to alternately upper and lower case,
3799 (define str (string-copy "studly"))
3800 (string-for-each-index
3803 ((if (even? i) char-upcase char-downcase)
3804 (string-ref str i))))
3806 str @result{} "StUdLy"
3810 @deffn {Scheme Procedure} string-fold kons knil s [start [end]]
3811 @deffnx {C Function} scm_string_fold (kons, knil, s, start, end)
3812 Fold @var{kons} over the characters of @var{s}, with @var{knil}
3813 as the terminating element, from left to right. @var{kons}
3814 must expect two arguments: The actual character and the last
3815 result of @var{kons}' application.
3818 @deffn {Scheme Procedure} string-fold-right kons knil s [start [end]]
3819 @deffnx {C Function} scm_string_fold_right (kons, knil, s, start, end)
3820 Fold @var{kons} over the characters of @var{s}, with @var{knil}
3821 as the terminating element, from right to left. @var{kons}
3822 must expect two arguments: The actual character and the last
3823 result of @var{kons}' application.
3826 @deffn {Scheme Procedure} string-unfold p f g seed [base [make_final]]
3827 @deffnx {C Function} scm_string_unfold (p, f, g, seed, base, make_final)
3829 @item @var{g} is used to generate a series of @emph{seed}
3830 values from the initial @var{seed}: @var{seed}, (@var{g}
3831 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
3833 @item @var{p} tells us when to stop -- when it returns true
3834 when applied to one of these seed values.
3835 @item @var{f} maps each seed value to the corresponding
3836 character in the result string. These chars are assembled
3837 into the string in a left-to-right order.
3838 @item @var{base} is the optional initial/leftmost portion
3839 of the constructed string; it default to the empty
3841 @item @var{make_final} is applied to the terminal seed
3842 value (on which @var{p} returns true) to produce
3843 the final/rightmost portion of the constructed string.
3844 The default is nothing extra.
3848 @deffn {Scheme Procedure} string-unfold-right p f g seed [base [make_final]]
3849 @deffnx {C Function} scm_string_unfold_right (p, f, g, seed, base, make_final)
3851 @item @var{g} is used to generate a series of @emph{seed}
3852 values from the initial @var{seed}: @var{seed}, (@var{g}
3853 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
3855 @item @var{p} tells us when to stop -- when it returns true
3856 when applied to one of these seed values.
3857 @item @var{f} maps each seed value to the corresponding
3858 character in the result string. These chars are assembled
3859 into the string in a right-to-left order.
3860 @item @var{base} is the optional initial/rightmost portion
3861 of the constructed string; it default to the empty
3863 @item @var{make_final} is applied to the terminal seed
3864 value (on which @var{p} returns true) to produce
3865 the final/leftmost portion of the constructed string.
3866 It defaults to @code{(lambda (x) )}.
3870 @node Miscellaneous String Operations
3871 @subsubsection Miscellaneous String Operations
3873 @deffn {Scheme Procedure} xsubstring s from [to [start [end]]]
3874 @deffnx {C Function} scm_xsubstring (s, from, to, start, end)
3875 This is the @emph{extended substring} procedure that implements
3876 replicated copying of a substring of some string.
3878 @var{s} is a string, @var{start} and @var{end} are optional
3879 arguments that demarcate a substring of @var{s}, defaulting to
3880 0 and the length of @var{s}. Replicate this substring up and
3881 down index space, in both the positive and negative directions.
3882 @code{xsubstring} returns the substring of this string
3883 beginning at index @var{from}, and ending at @var{to}, which
3884 defaults to @var{from} + (@var{end} - @var{start}).
3887 @deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto [start [end]]]
3888 @deffnx {C Function} scm_string_xcopy_x (target, tstart, s, sfrom, sto, start, end)
3889 Exactly the same as @code{xsubstring}, but the extracted text
3890 is written into the string @var{target} starting at index
3891 @var{tstart}. The operation is not defined if @code{(eq?
3892 @var{target} @var{s})} or these arguments share storage -- you
3893 cannot copy a string on top of itself.
3896 @deffn {Scheme Procedure} string-replace s1 s2 [start1 [end1 [start2 [end2]]]]
3897 @deffnx {C Function} scm_string_replace (s1, s2, start1, end1, start2, end2)
3898 Return the string @var{s1}, but with the characters
3899 @var{start1} @dots{} @var{end1} replaced by the characters
3900 @var{start2} @dots{} @var{end2} from @var{s2}.
3903 @deffn {Scheme Procedure} string-tokenize s [token_set [start [end]]]
3904 @deffnx {C Function} scm_string_tokenize (s, token_set, start, end)
3905 Split the string @var{s} into a list of substrings, where each
3906 substring is a maximal non-empty contiguous sequence of
3907 characters from the character set @var{token_set}, which
3908 defaults to @code{char-set:graphic}.
3909 If @var{start} or @var{end} indices are provided, they restrict
3910 @code{string-tokenize} to operating on the indicated substring
3914 @deffn {Scheme Procedure} string-filter s char_pred [start [end]]
3915 @deffnx {C Function} scm_string_filter (s, char_pred, start, end)
3916 Filter the string @var{s}, retaining only those characters which
3917 satisfy @var{char_pred}.
3919 If @var{char_pred} is a procedure, it is applied to each character as
3920 a predicate, if it is a character, it is tested for equality and if it
3921 is a character set, it is tested for membership.
3924 @deffn {Scheme Procedure} string-delete s char_pred [start [end]]
3925 @deffnx {C Function} scm_string_delete (s, char_pred, start, end)
3926 Delete characters satisfying @var{char_pred} from @var{s}.
3928 If @var{char_pred} is a procedure, it is applied to each character as
3929 a predicate, if it is a character, it is tested for equality and if it
3930 is a character set, it is tested for membership.
3933 @node Conversion to/from C
3934 @subsubsection Conversion to/from C
3936 When creating a Scheme string from a C string or when converting a
3937 Scheme string to a C string, the concept of character encoding becomes
3940 In C, a string is just a sequence of bytes, and the character encoding
3941 describes the relation between these bytes and the actual characters
3942 that make up the string. For Scheme strings, character encoding is
3943 not an issue (most of the time), since in Scheme you never get to see
3944 the bytes, only the characters.
3946 Converting to C and converting from C each have their own challenges.
3948 When converting from C to Scheme, it is important that the sequence of
3949 bytes in the C string be valid with respect to its encoding. ASCII
3950 strings, for example, can't have any bytes greater than 127. An ASCII
3951 byte greater than 127 is considered @emph{ill-formed} and cannot be
3952 converted into a Scheme character.
3954 Problems can occur in the reverse operation as well. Not all character
3955 encodings can hold all possible Scheme characters. Some encodings, like
3956 ASCII for example, can only describe a small subset of all possible
3957 characters. So, when converting to C, one must first decide what to do
3958 with Scheme characters that can't be represented in the C string.
3960 Converting a Scheme string to a C string will often allocate fresh
3961 memory to hold the result. You must take care that this memory is
3962 properly freed eventually. In many cases, this can be achieved by
3963 using @code{scm_dynwind_free} inside an appropriate dynwind context,
3964 @xref{Dynamic Wind}.
3966 @deftypefn {C Function} SCM scm_from_locale_string (const char *str)
3967 @deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
3968 Creates a new Scheme string that has the same contents as @var{str} when
3969 interpreted in the locale character encoding of the
3970 @code{current-input-port}.
3972 For @code{scm_from_locale_string}, @var{str} must be null-terminated.
3974 For @code{scm_from_locale_stringn}, @var{len} specifies the length of
3975 @var{str} in bytes, and @var{str} does not need to be null-terminated.
3976 If @var{len} is @code{(size_t)-1}, then @var{str} does need to be
3977 null-terminated and the real length will be found with @code{strlen}.
3979 If the C string is ill-formed, an error will be raised.
3982 @deftypefn {C Function} SCM scm_take_locale_string (char *str)
3983 @deftypefnx {C Function} SCM scm_take_locale_stringn (char *str, size_t len)
3984 Like @code{scm_from_locale_string} and @code{scm_from_locale_stringn},
3985 respectively, but also frees @var{str} with @code{free} eventually.
3986 Thus, you can use this function when you would free @var{str} anyway
3987 immediately after creating the Scheme string. In certain cases, Guile
3988 can then use @var{str} directly as its internal representation.
3991 @deftypefn {C Function} {char *} scm_to_locale_string (SCM str)
3992 @deftypefnx {C Function} {char *} scm_to_locale_stringn (SCM str, size_t *lenp)
3993 Returns a C string with the same contents as @var{str} in the locale
3994 encoding of the @code{current-output-port}. The C string must be freed
3995 with @code{free} eventually, maybe by using @code{scm_dynwind_free},
3996 @xref{Dynamic Wind}.
3998 For @code{scm_to_locale_string}, the returned string is
3999 null-terminated and an error is signalled when @var{str} contains
4000 @code{#\nul} characters.
4002 For @code{scm_to_locale_stringn} and @var{lenp} not @code{NULL},
4003 @var{str} might contain @code{#\nul} characters and the length of the
4004 returned string in bytes is stored in @code{*@var{lenp}}. The
4005 returned string will not be null-terminated in this case. If
4006 @var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
4007 @code{scm_to_locale_string}.
4009 If a character in @var{str} cannot be represented in the locale encoding
4010 of the current output port, the port conversion strategy of the current
4011 output port will determine the result, @xref{Ports}. If output port's
4012 conversion strategy is @code{error}, an error will be raised. If it is
4013 @code{subsitute}, a replacement character, such as a question mark, will
4014 be inserted in its place. If it is @code{escape}, a hex escape will be
4015 inserted in its place.
4018 @deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
4019 Puts @var{str} as a C string in the current locale encoding into the
4020 memory pointed to by @var{buf}. The buffer at @var{buf} has room for
4021 @var{max_len} bytes and @code{scm_to_local_stringbuf} will never store
4022 more than that. No terminating @code{'\0'} will be stored.
4024 The return value of @code{scm_to_locale_stringbuf} is the number of
4025 bytes that are needed for all of @var{str}, regardless of whether
4026 @var{buf} was large enough to hold them. Thus, when the return value
4027 is larger than @var{max_len}, only @var{max_len} bytes have been
4028 stored and you probably need to try again with a larger buffer.
4032 @subsection Bytevectors
4037 A @dfn{bytevector} is a raw bit string. The @code{(rnrs bytevector)}
4038 module provides the programming interface specified by the
4039 @uref{http://www.r6rs.org/, Revised^6 Report on the Algorithmic Language
4040 Scheme (R6RS)}. It contains procedures to manipulate bytevectors and
4041 interpret their contents in a number of ways: bytevector contents can be
4042 accessed as signed or unsigned integer of various sizes and endianness,
4043 as IEEE-754 floating point numbers, or as strings. It is a useful tool
4044 to encode and decode binary data.
4046 The R6RS (Section 4.3.4) specifies an external representation for
4047 bytevectors, whereby the octets (integers in the range 0--255) contained
4048 in the bytevector are represented as a list prefixed by @code{#vu8}:
4054 denotes a 3-byte bytevector containing the octets 1, 53, and 204. Like
4055 string literals, booleans, etc., bytevectors are ``self-quoting'', i.e.,
4056 they do not need to be quoted:
4060 @result{} #vu8(1 53 204)
4063 Bytevectors can be used with the binary input/output primitives of the
4064 R6RS (@pxref{R6RS I/O Ports}).
4067 * Bytevector Endianness:: Dealing with byte order.
4068 * Bytevector Manipulation:: Creating, copying, manipulating bytevectors.
4069 * Bytevectors as Integers:: Interpreting bytes as integers.
4070 * Bytevectors and Integer Lists:: Converting to/from an integer list.
4071 * Bytevectors as Floats:: Interpreting bytes as real numbers.
4072 * Bytevectors as Strings:: Interpreting bytes as Unicode strings.
4073 * Bytevectors as Generalized Vectors:: Guile extension to the bytevector API.
4074 * Bytevectors as Uniform Vectors:: Bytevectors and SRFI-4.
4077 @node Bytevector Endianness
4078 @subsubsection Endianness
4084 Some of the following procedures take an @var{endianness} parameter.
4085 The @dfn{endianness} is defined as the order of bytes in multi-byte
4086 numbers: numbers encoded in @dfn{big endian} have their most
4087 significant bytes written first, whereas numbers encoded in
4088 @dfn{little endian} have their least significant bytes
4089 first@footnote{Big-endian and little-endian are the most common
4090 ``endiannesses'', but others do exist. For instance, the GNU MP
4091 library allows @dfn{word order} to be specified independently of
4092 @dfn{byte order} (@pxref{Integer Import and Export,,, gmp, The GNU
4093 Multiple Precision Arithmetic Library Manual}).}.
4095 Little-endian is the native endianness of the IA32 architecture and
4096 its derivatives, while big-endian is native to SPARC and PowerPC,
4097 among others. The @code{native-endianness} procedure returns the
4098 native endianness of the machine it runs on.
4100 @deffn {Scheme Procedure} native-endianness
4101 @deffnx {C Function} scm_native_endianness ()
4102 Return a value denoting the native endianness of the host machine.
4105 @deffn {Scheme Macro} endianness symbol
4106 Return an object denoting the endianness specified by @var{symbol}. If
4107 @var{symbol} is neither @code{big} nor @code{little} then an error is
4108 raised at expand-time.
4111 @defvr {C Variable} scm_endianness_big
4112 @defvrx {C Variable} scm_endianness_little
4113 The objects denoting big- and little-endianness, respectively.
4117 @node Bytevector Manipulation
4118 @subsubsection Manipulating Bytevectors
4120 Bytevectors can be created, copied, and analyzed with the following
4121 procedures and C functions.
4123 @deffn {Scheme Procedure} make-bytevector len [fill]
4124 @deffnx {C Function} scm_make_bytevector (len, fill)
4125 @deffnx {C Function} scm_c_make_bytevector (size_t len)
4126 Return a new bytevector of @var{len} bytes. Optionally, if @var{fill}
4127 is given, fill it with @var{fill}; @var{fill} must be in the range
4131 @deffn {Scheme Procedure} bytevector? obj
4132 @deffnx {C Function} scm_bytevector_p (obj)
4133 Return true if @var{obj} is a bytevector.
4136 @deftypefn {C Function} int scm_is_bytevector (SCM obj)
4137 Equivalent to @code{scm_is_true (scm_bytevector_p (obj))}.
4140 @deffn {Scheme Procedure} bytevector-length bv
4141 @deffnx {C Function} scm_bytevector_length (bv)
4142 Return the length in bytes of bytevector @var{bv}.
4145 @deftypefn {C Function} size_t scm_c_bytevector_length (SCM bv)
4146 Likewise, return the length in bytes of bytevector @var{bv}.
4149 @deffn {Scheme Procedure} bytevector=? bv1 bv2
4150 @deffnx {C Function} scm_bytevector_eq_p (bv1, bv2)
4151 Return is @var{bv1} equals to @var{bv2}---i.e., if they have the same
4152 length and contents.
4155 @deffn {Scheme Procedure} bytevector-fill! bv fill
4156 @deffnx {C Function} scm_bytevector_fill_x (bv, fill)
4157 Fill bytevector @var{bv} with @var{fill}, a byte.
4160 @deffn {Scheme Procedure} bytevector-copy! source source-start target target-start len
4161 @deffnx {C Function} scm_bytevector_copy_x (source, source_start, target, target_start, len)
4162 Copy @var{len} bytes from @var{source} into @var{target}, starting
4163 reading from @var{source-start} (a positive index within @var{source})
4164 and start writing at @var{target-start}.
4167 @deffn {Scheme Procedure} bytevector-copy bv
4168 @deffnx {C Function} scm_bytevector_copy (bv)
4169 Return a newly allocated copy of @var{bv}.
4172 @deftypefn {C Function} scm_t_uint8 scm_c_bytevector_ref (SCM bv, size_t index)
4173 Return the byte at @var{index} in bytevector @var{bv}.
4176 @deftypefn {C Function} void scm_c_bytevector_set_x (SCM bv, size_t index, scm_t_uint8 value)
4177 Set the byte at @var{index} in @var{bv} to @var{value}.
4180 Low-level C macros are available. They do not perform any
4181 type-checking; as such they should be used with care.
4183 @deftypefn {C Macro} size_t SCM_BYTEVECTOR_LENGTH (bv)
4184 Return the length in bytes of bytevector @var{bv}.
4187 @deftypefn {C Macro} {signed char *} SCM_BYTEVECTOR_CONTENTS (bv)
4188 Return a pointer to the contents of bytevector @var{bv}.
4192 @node Bytevectors as Integers
4193 @subsubsection Interpreting Bytevector Contents as Integers
4195 The contents of a bytevector can be interpreted as a sequence of
4196 integers of any given size, sign, and endianness.
4199 (let ((bv (make-bytevector 4)))
4200 (bytevector-u8-set! bv 0 #x12)
4201 (bytevector-u8-set! bv 1 #x34)
4202 (bytevector-u8-set! bv 2 #x56)
4203 (bytevector-u8-set! bv 3 #x78)
4205 (map (lambda (number)
4206 (number->string number 16))
4207 (list (bytevector-u8-ref bv 0)
4208 (bytevector-u16-ref bv 0 (endianness big))
4209 (bytevector-u32-ref bv 0 (endianness little)))))
4211 @result{} ("12" "1234" "78563412")
4214 The most generic procedures to interpret bytevector contents as integers
4215 are described below.
4217 @deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
4218 @deffnx {Scheme Procedure} bytevector-sint-ref bv index endianness size
4219 @deffnx {C Function} scm_bytevector_uint_ref (bv, index, endianness, size)
4220 @deffnx {C Function} scm_bytevector_sint_ref (bv, index, endianness, size)
4221 Return the @var{size}-byte long unsigned (resp. signed) integer at
4222 index @var{index} in @var{bv}, decoded according to @var{endianness}.
4225 @deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
4226 @deffnx {Scheme Procedure} bytevector-sint-set! bv index value endianness size
4227 @deffnx {C Function} scm_bytevector_uint_set_x (bv, index, value, endianness, size)
4228 @deffnx {C Function} scm_bytevector_sint_set_x (bv, index, value, endianness, size)
4229 Set the @var{size}-byte long unsigned (resp. signed) integer at
4230 @var{index} to @var{value}, encoded according to @var{endianness}.
4233 The following procedures are similar to the ones above, but specialized
4234 to a given integer size:
4236 @deffn {Scheme Procedure} bytevector-u8-ref bv index
4237 @deffnx {Scheme Procedure} bytevector-s8-ref bv index
4238 @deffnx {Scheme Procedure} bytevector-u16-ref bv index endianness
4239 @deffnx {Scheme Procedure} bytevector-s16-ref bv index endianness
4240 @deffnx {Scheme Procedure} bytevector-u32-ref bv index endianness
4241 @deffnx {Scheme Procedure} bytevector-s32-ref bv index endianness
4242 @deffnx {Scheme Procedure} bytevector-u64-ref bv index endianness
4243 @deffnx {Scheme Procedure} bytevector-s64-ref bv index endianness
4244 @deffnx {C Function} scm_bytevector_u8_ref (bv, index)
4245 @deffnx {C Function} scm_bytevector_s8_ref (bv, index)
4246 @deffnx {C Function} scm_bytevector_u16_ref (bv, index, endianness)
4247 @deffnx {C Function} scm_bytevector_s16_ref (bv, index, endianness)
4248 @deffnx {C Function} scm_bytevector_u32_ref (bv, index, endianness)
4249 @deffnx {C Function} scm_bytevector_s32_ref (bv, index, endianness)
4250 @deffnx {C Function} scm_bytevector_u64_ref (bv, index, endianness)
4251 @deffnx {C Function} scm_bytevector_s64_ref (bv, index, endianness)
4252 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
4253 16, 32 or 64) from @var{bv} at @var{index}, decoded according to
4257 @deffn {Scheme Procedure} bytevector-u8-set! bv index value
4258 @deffnx {Scheme Procedure} bytevector-s8-set! bv index value
4259 @deffnx {Scheme Procedure} bytevector-u16-set! bv index value endianness
4260 @deffnx {Scheme Procedure} bytevector-s16-set! bv index value endianness
4261 @deffnx {Scheme Procedure} bytevector-u32-set! bv index value endianness
4262 @deffnx {Scheme Procedure} bytevector-s32-set! bv index value endianness
4263 @deffnx {Scheme Procedure} bytevector-u64-set! bv index value endianness
4264 @deffnx {Scheme Procedure} bytevector-s64-set! bv index value endianness
4265 @deffnx {C Function} scm_bytevector_u8_set_x (bv, index, value)
4266 @deffnx {C Function} scm_bytevector_s8_set_x (bv, index, value)
4267 @deffnx {C Function} scm_bytevector_u16_set_x (bv, index, value, endianness)
4268 @deffnx {C Function} scm_bytevector_s16_set_x (bv, index, value, endianness)
4269 @deffnx {C Function} scm_bytevector_u32_set_x (bv, index, value, endianness)
4270 @deffnx {C Function} scm_bytevector_s32_set_x (bv, index, value, endianness)
4271 @deffnx {C Function} scm_bytevector_u64_set_x (bv, index, value, endianness)
4272 @deffnx {C Function} scm_bytevector_s64_set_x (bv, index, value, endianness)
4273 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
4274 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to
4278 Finally, a variant specialized for the host's endianness is available
4279 for each of these functions (with the exception of the @code{u8}
4280 accessors, for obvious reasons):
4282 @deffn {Scheme Procedure} bytevector-u16-native-ref bv index
4283 @deffnx {Scheme Procedure} bytevector-s16-native-ref bv index
4284 @deffnx {Scheme Procedure} bytevector-u32-native-ref bv index
4285 @deffnx {Scheme Procedure} bytevector-s32-native-ref bv index
4286 @deffnx {Scheme Procedure} bytevector-u64-native-ref bv index
4287 @deffnx {Scheme Procedure} bytevector-s64-native-ref bv index
4288 @deffnx {C Function} scm_bytevector_u16_native_ref (bv, index)
4289 @deffnx {C Function} scm_bytevector_s16_native_ref (bv, index)
4290 @deffnx {C Function} scm_bytevector_u32_native_ref (bv, index)
4291 @deffnx {C Function} scm_bytevector_s32_native_ref (bv, index)
4292 @deffnx {C Function} scm_bytevector_u64_native_ref (bv, index)
4293 @deffnx {C Function} scm_bytevector_s64_native_ref (bv, index)
4294 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
4295 16, 32 or 64) from @var{bv} at @var{index}, decoded according to the
4296 host's native endianness.
4299 @deffn {Scheme Procedure} bytevector-u16-native-set! bv index value
4300 @deffnx {Scheme Procedure} bytevector-s16-native-set! bv index value
4301 @deffnx {Scheme Procedure} bytevector-u32-native-set! bv index value
4302 @deffnx {Scheme Procedure} bytevector-s32-native-set! bv index value
4303 @deffnx {Scheme Procedure} bytevector-u64-native-set! bv index value
4304 @deffnx {Scheme Procedure} bytevector-s64-native-set! bv index value
4305 @deffnx {C Function} scm_bytevector_u16_native_set_x (bv, index, value)
4306 @deffnx {C Function} scm_bytevector_s16_native_set_x (bv, index, value)
4307 @deffnx {C Function} scm_bytevector_u32_native_set_x (bv, index, value)
4308 @deffnx {C Function} scm_bytevector_s32_native_set_x (bv, index, value)
4309 @deffnx {C Function} scm_bytevector_u64_native_set_x (bv, index, value)
4310 @deffnx {C Function} scm_bytevector_s64_native_set_x (bv, index, value)
4311 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
4312 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to the
4313 host's native endianness.
4317 @node Bytevectors and Integer Lists
4318 @subsubsection Converting Bytevectors to/from Integer Lists
4320 Bytevector contents can readily be converted to/from lists of signed or
4324 (bytevector->sint-list (u8-list->bytevector (make-list 4 255))
4325 (endianness little) 2)
4329 @deffn {Scheme Procedure} bytevector->u8-list bv
4330 @deffnx {C Function} scm_bytevector_to_u8_list (bv)
4331 Return a newly allocated list of unsigned 8-bit integers from the
4332 contents of @var{bv}.
4335 @deffn {Scheme Procedure} u8-list->bytevector lst
4336 @deffnx {C Function} scm_u8_list_to_bytevector (lst)
4337 Return a newly allocated bytevector consisting of the unsigned 8-bit
4338 integers listed in @var{lst}.
4341 @deffn {Scheme Procedure} bytevector->uint-list bv endianness size
4342 @deffnx {Scheme Procedure} bytevector->sint-list bv endianness size
4343 @deffnx {C Function} scm_bytevector_to_uint_list (bv, endianness, size)
4344 @deffnx {C Function} scm_bytevector_to_sint_list (bv, endianness, size)
4345 Return a list of unsigned (resp. signed) integers of @var{size} bytes
4346 representing the contents of @var{bv}, decoded according to
4350 @deffn {Scheme Procedure} uint-list->bytevector lst endianness size
4351 @deffnx {Scheme Procedure} sint-list->bytevector lst endianness size
4352 @deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
4353 @deffnx {C Function} scm_sint_list_to_bytevector (lst, endianness, size)
4354 Return a new bytevector containing the unsigned (resp. signed) integers
4355 listed in @var{lst} and encoded on @var{size} bytes according to
4359 @node Bytevectors as Floats
4360 @subsubsection Interpreting Bytevector Contents as Floating Point Numbers
4362 @cindex IEEE-754 floating point numbers
4364 Bytevector contents can also be accessed as IEEE-754 single- or
4365 double-precision floating point numbers (respectively 32 and 64-bit
4366 long) using the procedures described here.
4368 @deffn {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
4369 @deffnx {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
4370 @deffnx {C Function} scm_bytevector_ieee_single_ref (bv, index, endianness)
4371 @deffnx {C Function} scm_bytevector_ieee_double_ref (bv, index, endianness)
4372 Return the IEEE-754 single-precision floating point number from @var{bv}
4373 at @var{index} according to @var{endianness}.
4376 @deffn {Scheme Procedure} bytevector-ieee-single-set! bv index value endianness
4377 @deffnx {Scheme Procedure} bytevector-ieee-double-set! bv index value endianness
4378 @deffnx {C Function} scm_bytevector_ieee_single_set_x (bv, index, value, endianness)
4379 @deffnx {C Function} scm_bytevector_ieee_double_set_x (bv, index, value, endianness)
4380 Store real number @var{value} in @var{bv} at @var{index} according to
4384 Specialized procedures are also available:
4386 @deffn {Scheme Procedure} bytevector-ieee-single-native-ref bv index
4387 @deffnx {Scheme Procedure} bytevector-ieee-double-native-ref bv index
4388 @deffnx {C Function} scm_bytevector_ieee_single_native_ref (bv, index)
4389 @deffnx {C Function} scm_bytevector_ieee_double_native_ref (bv, index)
4390 Return the IEEE-754 single-precision floating point number from @var{bv}
4391 at @var{index} according to the host's native endianness.
4394 @deffn {Scheme Procedure} bytevector-ieee-single-native-set! bv index value
4395 @deffnx {Scheme Procedure} bytevector-ieee-double-native-set! bv index value
4396 @deffnx {C Function} scm_bytevector_ieee_single_native_set_x (bv, index, value)
4397 @deffnx {C Function} scm_bytevector_ieee_double_native_set_x (bv, index, value)
4398 Store real number @var{value} in @var{bv} at @var{index} according to
4399 the host's native endianness.
4403 @node Bytevectors as Strings
4404 @subsubsection Interpreting Bytevector Contents as Unicode Strings
4406 @cindex Unicode string encoding
4408 Bytevector contents can also be interpreted as Unicode strings encoded
4409 in one of the most commonly available encoding formats@footnote{Guile
4410 1.8 does @emph{not} support Unicode strings. Therefore, the procedures
4411 described here assume that Guile strings are internally encoded
4412 according to the current locale. For instance, if @code{$LC_CTYPE} is
4413 @code{fr_FR.ISO-8859-1}, then @code{string->utf-8} @i{et al.} will
4414 assume that Guile strings are Latin-1-encoded.}.
4417 (utf8->string (u8-list->bytevector '(99 97 102 101)))
4420 (string->utf8 "caf@'e") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT
4421 @result{} #vu8(99 97 102 195 169)
4424 @deffn {Scheme Procedure} string->utf8 str
4425 @deffnx {Scheme Procedure} string->utf16 str
4426 @deffnx {Scheme Procedure} string->utf32 str
4427 @deffnx {C Function} scm_string_to_utf8 (str)
4428 @deffnx {C Function} scm_string_to_utf16 (str)
4429 @deffnx {C Function} scm_string_to_utf32 (str)
4430 Return a newly allocated bytevector that contains the UTF-8, UTF-16, or
4431 UTF-32 (aka. UCS-4) encoding of @var{str}.
4434 @deffn {Scheme Procedure} utf8->string utf
4435 @deffnx {Scheme Procedure} utf16->string utf
4436 @deffnx {Scheme Procedure} utf32->string utf
4437 @deffnx {C Function} scm_utf8_to_string (utf)
4438 @deffnx {C Function} scm_utf16_to_string (utf)
4439 @deffnx {C Function} scm_utf32_to_string (utf)
4440 Return a newly allocated string that contains from the UTF-8-, UTF-16-,
4441 or UTF-32-decoded contents of bytevector @var{utf}.
4444 @node Bytevectors as Generalized Vectors
4445 @subsubsection Accessing Bytevectors with the Generalized Vector API
4447 As an extension to the R6RS, Guile allows bytevectors to be manipulated
4448 with the @dfn{generalized vector} procedures (@pxref{Generalized
4449 Vectors}). This also allows bytevectors to be accessed using the
4450 generic @dfn{array} procedures (@pxref{Array Procedures}). When using
4451 these APIs, bytes are accessed one at a time as 8-bit unsigned integers:
4454 (define bv #vu8(0 1 2 3))
4456 (generalized-vector? bv)
4459 (generalized-vector-ref bv 2)
4462 (generalized-vector-set! bv 2 77)
4471 @node Bytevectors as Uniform Vectors
4472 @subsubsection Accessing Bytevectors with the SRFI-4 API
4474 Bytevectors may also be accessed with the SRFI-4 API. @xref{SRFI-4 and
4475 Bytevectors}, for more information.
4478 @node Regular Expressions
4479 @subsection Regular Expressions
4480 @tpindex Regular expressions
4482 @cindex regular expressions
4484 @cindex emacs regexp
4486 A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
4487 describes a whole class of strings. A full description of regular
4488 expressions and their syntax is beyond the scope of this manual;
4489 an introduction can be found in the Emacs manual (@pxref{Regexps,
4490 , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
4491 in many general Unix reference books.
4493 If your system does not include a POSIX regular expression library,
4494 and you have not linked Guile with a third-party regexp library such
4495 as Rx, these functions will not be available. You can tell whether
4496 your Guile installation includes regular expression support by
4497 checking whether @code{(provided? 'regex)} returns true.
4499 The following regexp and string matching features are provided by the
4500 @code{(ice-9 regex)} module. Before using the described functions,
4501 you should load this module by executing @code{(use-modules (ice-9
4505 * Regexp Functions:: Functions that create and match regexps.
4506 * Match Structures:: Finding what was matched by a regexp.
4507 * Backslash Escapes:: Removing the special meaning of regexp
4512 @node Regexp Functions
4513 @subsubsection Regexp Functions
4515 By default, Guile supports POSIX extended regular expressions.
4516 That means that the characters @samp{(}, @samp{)}, @samp{+} and
4517 @samp{?} are special, and must be escaped if you wish to match the
4520 This regular expression interface was modeled after that
4521 implemented by SCSH, the Scheme Shell. It is intended to be
4522 upwardly compatible with SCSH regular expressions.
4524 Zero bytes (@code{#\nul}) cannot be used in regex patterns or input
4525 strings, since the underlying C functions treat that as the end of
4526 string. If there's a zero byte an error is thrown.
4528 Patterns and input strings are treated as being in the locale
4529 character set if @code{setlocale} has been called (@pxref{Locales}),
4530 and in a multibyte locale this includes treating multi-byte sequences
4531 as a single character. (Guile strings are currently merely bytes,
4532 though this may change in the future, @xref{Conversion to/from C}.)
4534 @deffn {Scheme Procedure} string-match pattern str [start]
4535 Compile the string @var{pattern} into a regular expression and compare
4536 it with @var{str}. The optional numeric argument @var{start} specifies
4537 the position of @var{str} at which to begin matching.
4539 @code{string-match} returns a @dfn{match structure} which
4540 describes what, if anything, was matched by the regular
4541 expression. @xref{Match Structures}. If @var{str} does not match
4542 @var{pattern} at all, @code{string-match} returns @code{#f}.
4545 Two examples of a match follow. In the first example, the pattern
4546 matches the four digits in the match string. In the second, the pattern
4550 (string-match "[0-9][0-9][0-9][0-9]" "blah2002")
4551 @result{} #("blah2002" (4 . 8))
4553 (string-match "[A-Za-z]" "123456")
4557 Each time @code{string-match} is called, it must compile its
4558 @var{pattern} argument into a regular expression structure. This
4559 operation is expensive, which makes @code{string-match} inefficient if
4560 the same regular expression is used several times (for example, in a
4561 loop). For better performance, you can compile a regular expression in
4562 advance and then match strings against the compiled regexp.
4564 @deffn {Scheme Procedure} make-regexp pat flag@dots{}
4565 @deffnx {C Function} scm_make_regexp (pat, flaglst)
4566 Compile the regular expression described by @var{pat}, and
4567 return the compiled regexp structure. If @var{pat} does not
4568 describe a legal regular expression, @code{make-regexp} throws
4569 a @code{regular-expression-syntax} error.
4571 The @var{flag} arguments change the behavior of the compiled
4572 regular expression. The following values may be supplied:
4574 @defvar regexp/icase
4575 Consider uppercase and lowercase letters to be the same when
4579 @defvar regexp/newline
4580 If a newline appears in the target string, then permit the
4581 @samp{^} and @samp{$} operators to match immediately after or
4582 immediately before the newline, respectively. Also, the
4583 @samp{.} and @samp{[^...]} operators will never match a newline
4584 character. The intent of this flag is to treat the target
4585 string as a buffer containing many lines of text, and the
4586 regular expression as a pattern that may match a single one of
4590 @defvar regexp/basic
4591 Compile a basic (``obsolete'') regexp instead of the extended
4592 (``modern'') regexps that are the default. Basic regexps do
4593 not consider @samp{|}, @samp{+} or @samp{?} to be special
4594 characters, and require the @samp{@{...@}} and @samp{(...)}
4595 metacharacters to be backslash-escaped (@pxref{Backslash
4596 Escapes}). There are several other differences between basic
4597 and extended regular expressions, but these are the most
4601 @defvar regexp/extended
4602 Compile an extended regular expression rather than a basic
4603 regexp. This is the default behavior; this flag will not
4604 usually be needed. If a call to @code{make-regexp} includes
4605 both @code{regexp/basic} and @code{regexp/extended} flags, the
4606 one which comes last will override the earlier one.
4610 @deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
4611 @deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
4612 Match the compiled regular expression @var{rx} against
4613 @code{str}. If the optional integer @var{start} argument is
4614 provided, begin matching from that position in the string.
4615 Return a match structure describing the results of the match,
4616 or @code{#f} if no match could be found.
4618 The @var{flags} argument changes the matching behavior. The following
4619 flag values may be supplied, use @code{logior} (@pxref{Bitwise
4620 Operations}) to combine them,
4622 @defvar regexp/notbol
4623 Consider that the @var{start} offset into @var{str} is not the
4624 beginning of a line and should not match operator @samp{^}.
4626 If @var{rx} was created with the @code{regexp/newline} option above,
4627 @samp{^} will still match after a newline in @var{str}.
4630 @defvar regexp/noteol
4631 Consider that the end of @var{str} is not the end of a line and should
4632 not match operator @samp{$}.
4634 If @var{rx} was created with the @code{regexp/newline} option above,
4635 @samp{$} will still match before a newline in @var{str}.
4640 ;; Regexp to match uppercase letters
4641 (define r (make-regexp "[A-Z]*"))
4643 ;; Regexp to match letters, ignoring case
4644 (define ri (make-regexp "[A-Z]*" regexp/icase))
4646 ;; Search for bob using regexp r
4647 (match:substring (regexp-exec r "bob"))
4648 @result{} "" ; no match
4650 ;; Search for bob using regexp ri
4651 (match:substring (regexp-exec ri "Bob"))
4652 @result{} "Bob" ; matched case insensitive
4655 @deffn {Scheme Procedure} regexp? obj
4656 @deffnx {C Function} scm_regexp_p (obj)
4657 Return @code{#t} if @var{obj} is a compiled regular expression,
4658 or @code{#f} otherwise.
4662 @deffn {Scheme Procedure} list-matches regexp str [flags]
4663 Return a list of match structures which are the non-overlapping
4664 matches of @var{regexp} in @var{str}. @var{regexp} can be either a
4665 pattern string or a compiled regexp. The @var{flags} argument is as
4666 per @code{regexp-exec} above.
4669 (map match:substring (list-matches "[a-z]+" "abc 42 def 78"))
4670 @result{} ("abc" "def")
4674 @deffn {Scheme Procedure} fold-matches regexp str init proc [flags]
4675 Apply @var{proc} to the non-overlapping matches of @var{regexp} in
4676 @var{str}, to build a result. @var{regexp} can be either a pattern
4677 string or a compiled regexp. The @var{flags} argument is as per
4678 @code{regexp-exec} above.
4680 @var{proc} is called as @code{(@var{proc} match prev)} where
4681 @var{match} is a match structure and @var{prev} is the previous return
4682 from @var{proc}. For the first call @var{prev} is the given
4683 @var{init} parameter. @code{fold-matches} returns the final value
4686 For example to count matches,
4689 (fold-matches "[a-z][0-9]" "abc x1 def y2" 0
4690 (lambda (match count)
4697 Regular expressions are commonly used to find patterns in one string
4698 and replace them with the contents of another string. The following
4699 functions are convenient ways to do this.
4701 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
4702 @deffn {Scheme Procedure} regexp-substitute port match [item@dots{}]
4703 Write to @var{port} selected parts of the match structure @var{match}.
4704 Or if @var{port} is @code{#f} then form a string from those parts and
4707 Each @var{item} specifies a part to be written, and may be one of the
4712 A string. String arguments are written out verbatim.
4715 An integer. The submatch with that number is written
4716 (@code{match:substring}). Zero is the entire match.
4719 The symbol @samp{pre}. The portion of the matched string preceding
4720 the regexp match is written (@code{match:prefix}).
4723 The symbol @samp{post}. The portion of the matched string following
4724 the regexp match is written (@code{match:suffix}).
4727 For example, changing a match and retaining the text before and after,
4730 (regexp-substitute #f (string-match "[0-9]+" "number 25 is good")
4732 @result{} "number 37 is good"
4735 Or matching a @sc{yyyymmdd} format date such as @samp{20020828} and
4736 re-ordering and hyphenating the fields.
4740 "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
4741 (define s "Date 20020429 12am.")
4742 (regexp-substitute #f (string-match date-regex s)
4743 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
4744 @result{} "Date 04-29-2002 12am. (20020429)"
4749 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
4750 @deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
4751 @cindex search and replace
4752 Write to @var{port} selected parts of matches of @var{regexp} in
4753 @var{target}. If @var{port} is @code{#f} then form a string from
4754 those parts and return that. @var{regexp} can be a string or a
4757 This is similar to @code{regexp-substitute}, but allows global
4758 substitutions on @var{target}. Each @var{item} behaves as per
4759 @code{regexp-substitute}, with the following differences,
4763 A function. Called as @code{(@var{item} match)} with the match
4764 structure for the @var{regexp} match, it should return a string to be
4765 written to @var{port}.
4768 The symbol @samp{post}. This doesn't output anything, but instead
4769 causes @code{regexp-substitute/global} to recurse on the unmatched
4770 portion of @var{target}.
4772 This @emph{must} be supplied to perform a global search and replace on
4773 @var{target}; without it @code{regexp-substitute/global} returns after
4774 a single match and output.
4777 For example, to collapse runs of tabs and spaces to a single hyphen
4781 (regexp-substitute/global #f "[ \t]+" "this is the text"
4783 @result{} "this-is-the-text"
4786 Or using a function to reverse the letters in each word,
4789 (regexp-substitute/global #f "[a-z]+" "to do and not-do"
4790 'pre (lambda (m) (string-reverse (match:substring m))) 'post)
4791 @result{} "ot od dna ton-od"
4794 Without the @code{post} symbol, just one regexp match is made. For
4795 example the following is the date example from
4796 @code{regexp-substitute} above, without the need for the separate
4797 @code{string-match} call.
4801 "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
4802 (define s "Date 20020429 12am.")
4803 (regexp-substitute/global #f date-regex s
4804 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
4806 @result{} "Date 04-29-2002 12am. (20020429)"
4811 @node Match Structures
4812 @subsubsection Match Structures
4814 @cindex match structures
4816 A @dfn{match structure} is the object returned by @code{string-match} and
4817 @code{regexp-exec}. It describes which portion of a string, if any,
4818 matched the given regular expression. Match structures include: a
4819 reference to the string that was checked for matches; the starting and
4820 ending positions of the regexp match; and, if the regexp included any
4821 parenthesized subexpressions, the starting and ending positions of each
4824 In each of the regexp match functions described below, the @code{match}
4825 argument must be a match structure returned by a previous call to
4826 @code{string-match} or @code{regexp-exec}. Most of these functions
4827 return some information about the original target string that was
4828 matched against a regular expression; we will call that string
4829 @var{target} for easy reference.
4831 @c begin (scm-doc-string "regex.scm" "regexp-match?")
4832 @deffn {Scheme Procedure} regexp-match? obj
4833 Return @code{#t} if @var{obj} is a match structure returned by a
4834 previous call to @code{regexp-exec}, or @code{#f} otherwise.
4837 @c begin (scm-doc-string "regex.scm" "match:substring")
4838 @deffn {Scheme Procedure} match:substring match [n]
4839 Return the portion of @var{target} matched by subexpression number
4840 @var{n}. Submatch 0 (the default) represents the entire regexp match.
4841 If the regular expression as a whole matched, but the subexpression
4842 number @var{n} did not match, return @code{#f}.
4846 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4850 ;; match starting at offset 6 in the string
4852 (string-match "[0-9][0-9][0-9][0-9]" "blah987654" 6))
4856 @c begin (scm-doc-string "regex.scm" "match:start")
4857 @deffn {Scheme Procedure} match:start match [n]
4858 Return the starting position of submatch number @var{n}.
4861 In the following example, the result is 4, since the match starts at
4865 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4870 @c begin (scm-doc-string "regex.scm" "match:end")
4871 @deffn {Scheme Procedure} match:end match [n]
4872 Return the ending position of submatch number @var{n}.
4875 In the following example, the result is 8, since the match runs between
4876 characters 4 and 8 (i.e. the ``2002'').
4879 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4884 @c begin (scm-doc-string "regex.scm" "match:prefix")
4885 @deffn {Scheme Procedure} match:prefix match
4886 Return the unmatched portion of @var{target} preceding the regexp match.
4889 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4895 @c begin (scm-doc-string "regex.scm" "match:suffix")
4896 @deffn {Scheme Procedure} match:suffix match
4897 Return the unmatched portion of @var{target} following the regexp match.
4901 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4906 @c begin (scm-doc-string "regex.scm" "match:count")
4907 @deffn {Scheme Procedure} match:count match
4908 Return the number of parenthesized subexpressions from @var{match}.
4909 Note that the entire regular expression match itself counts as a
4910 subexpression, and failed submatches are included in the count.
4913 @c begin (scm-doc-string "regex.scm" "match:string")
4914 @deffn {Scheme Procedure} match:string match
4915 Return the original @var{target} string.
4919 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4921 @result{} "blah2002foo"
4925 @node Backslash Escapes
4926 @subsubsection Backslash Escapes
4928 Sometimes you will want a regexp to match characters like @samp{*} or
4929 @samp{$} exactly. For example, to check whether a particular string
4930 represents a menu entry from an Info node, it would be useful to match
4931 it against a regexp like @samp{^* [^:]*::}. However, this won't work;
4932 because the asterisk is a metacharacter, it won't match the @samp{*} at
4933 the beginning of the string. In this case, we want to make the first
4936 You can do this by preceding the metacharacter with a backslash
4937 character @samp{\}. (This is also called @dfn{quoting} the
4938 metacharacter, and is known as a @dfn{backslash escape}.) When Guile
4939 sees a backslash in a regular expression, it considers the following
4940 glyph to be an ordinary character, no matter what special meaning it
4941 would ordinarily have. Therefore, we can make the above example work by
4942 changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells
4943 the regular expression engine to match only a single asterisk in the
4946 Since the backslash is itself a metacharacter, you may force a regexp to
4947 match a backslash in the target string by preceding the backslash with
4948 itself. For example, to find variable references in a @TeX{} program,
4949 you might want to find occurrences of the string @samp{\let\} followed
4950 by any number of alphabetic characters. The regular expression
4951 @samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the
4952 regexp each match a single backslash in the target string.
4954 @c begin (scm-doc-string "regex.scm" "regexp-quote")
4955 @deffn {Scheme Procedure} regexp-quote str
4956 Quote each special character found in @var{str} with a backslash, and
4957 return the resulting string.
4960 @strong{Very important:} Using backslash escapes in Guile source code
4961 (as in Emacs Lisp or C) can be tricky, because the backslash character
4962 has special meaning for the Guile reader. For example, if Guile
4963 encounters the character sequence @samp{\n} in the middle of a string
4964 while processing Scheme code, it replaces those characters with a
4965 newline character. Similarly, the character sequence @samp{\t} is
4966 replaced by a horizontal tab. Several of these @dfn{escape sequences}
4967 are processed by the Guile reader before your code is executed.
4968 Unrecognized escape sequences are ignored: if the characters @samp{\*}
4969 appear in a string, they will be translated to the single character
4972 This translation is obviously undesirable for regular expressions, since
4973 we want to be able to include backslashes in a string in order to
4974 escape regexp metacharacters. Therefore, to make sure that a backslash
4975 is preserved in a string in your Guile program, you must use @emph{two}
4976 consecutive backslashes:
4979 (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
4982 The string in this example is preprocessed by the Guile reader before
4983 any code is executed. The resulting argument to @code{make-regexp} is
4984 the string @samp{^\* [^:]*}, which is what we really want.
4986 This also means that in order to write a regular expression that matches
4987 a single backslash character, the regular expression string in the
4988 source code must include @emph{four} backslashes. Each consecutive pair
4989 of backslashes gets translated by the Guile reader to a single
4990 backslash, and the resulting double-backslash is interpreted by the
4991 regexp engine as matching a single backslash character. Hence:
4994 (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
4997 The reason for the unwieldiness of this syntax is historical. Both
4998 regular expression pattern matchers and Unix string processing systems
4999 have traditionally used backslashes with the special meanings
5000 described above. The POSIX regular expression specification and ANSI C
5001 standard both require these semantics. Attempting to abandon either
5002 convention would cause other kinds of compatibility problems, possibly
5003 more severe ones. Therefore, without extending the Scheme reader to
5004 support strings with different quoting conventions (an ungainly and
5005 confusing extension when implemented in other languages), we must adhere
5006 to this cumbersome escape syntax.
5013 Symbols in Scheme are widely used in three ways: as items of discrete
5014 data, as lookup keys for alists and hash tables, and to denote variable
5017 A @dfn{symbol} is similar to a string in that it is defined by a
5018 sequence of characters. The sequence of characters is known as the
5019 symbol's @dfn{name}. In the usual case --- that is, where the symbol's
5020 name doesn't include any characters that could be confused with other
5021 elements of Scheme syntax --- a symbol is written in a Scheme program by
5022 writing the sequence of characters that make up the name, @emph{without}
5023 any quotation marks or other special syntax. For example, the symbol
5024 whose name is ``multiply-by-2'' is written, simply:
5030 Notice how this differs from a @emph{string} with contents
5031 ``multiply-by-2'', which is written with double quotation marks, like
5038 Looking beyond how they are written, symbols are different from strings
5039 in two important respects.
5041 The first important difference is uniqueness. If the same-looking
5042 string is read twice from two different places in a program, the result
5043 is two @emph{different} string objects whose contents just happen to be
5044 the same. If, on the other hand, the same-looking symbol is read twice
5045 from two different places in a program, the result is the @emph{same}
5046 symbol object both times.
5048 Given two read symbols, you can use @code{eq?} to test whether they are
5049 the same (that is, have the same name). @code{eq?} is the most
5050 efficient comparison operator in Scheme, and comparing two symbols like
5051 this is as fast as comparing, for example, two numbers. Given two
5052 strings, on the other hand, you must use @code{equal?} or
5053 @code{string=?}, which are much slower comparison operators, to
5054 determine whether the strings have the same contents.
5057 (define sym1 (quote hello))
5058 (define sym2 (quote hello))
5059 (eq? sym1 sym2) @result{} #t
5061 (define str1 "hello")
5062 (define str2 "hello")
5063 (eq? str1 str2) @result{} #f
5064 (equal? str1 str2) @result{} #t
5067 The second important difference is that symbols, unlike strings, are not
5068 self-evaluating. This is why we need the @code{(quote @dots{})}s in the
5069 example above: @code{(quote hello)} evaluates to the symbol named
5070 "hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
5071 symbol named "hello" and evaluated as a variable reference @dots{} about
5072 which more below (@pxref{Symbol Variables}).
5075 * Symbol Data:: Symbols as discrete data.
5076 * Symbol Keys:: Symbols as lookup keys.
5077 * Symbol Variables:: Symbols as denoting variables.
5078 * Symbol Primitives:: Operations related to symbols.
5079 * Symbol Props:: Function slots and property lists.
5080 * Symbol Read Syntax:: Extended read syntax for symbols.
5081 * Symbol Uninterned:: Uninterned symbols.
5086 @subsubsection Symbols as Discrete Data
5088 Numbers and symbols are similar to the extent that they both lend
5089 themselves to @code{eq?} comparison. But symbols are more descriptive
5090 than numbers, because a symbol's name can be used directly to describe
5091 the concept for which that symbol stands.
5093 For example, imagine that you need to represent some colours in a
5094 computer program. Using numbers, you would have to choose arbitrarily
5095 some mapping between numbers and colours, and then take care to use that
5096 mapping consistently:
5099 ;; 1=red, 2=green, 3=purple
5101 (if (eq? (colour-of car) 1)
5106 You can make the mapping more explicit and the code more readable by
5114 (if (eq? (colour-of car) red)
5119 But the simplest and clearest approach is not to use numbers at all, but
5120 symbols whose names specify the colours that they refer to:
5123 (if (eq? (colour-of car) 'red)
5127 The descriptive advantages of symbols over numbers increase as the set
5128 of concepts that you want to describe grows. Suppose that a car object
5129 can have other properties as well, such as whether it has or uses:
5133 automatic or manual transmission
5135 leaded or unleaded fuel
5137 power steering (or not).
5141 Then a car's combined property set could be naturally represented and
5142 manipulated as a list of symbols:
5145 (properties-of car1)
5147 (red manual unleaded power-steering)
5149 (if (memq 'power-steering (properties-of car1))
5150 (display "Unfit people can drive this car.\n")
5151 (display "You'll need strong arms to drive this car!\n"))
5153 Unfit people can drive this car.
5156 Remember, the fundamental property of symbols that we are relying on
5157 here is that an occurrence of @code{'red} in one part of a program is an
5158 @emph{indistinguishable} symbol from an occurrence of @code{'red} in
5159 another part of a program; this means that symbols can usefully be
5160 compared using @code{eq?}. At the same time, symbols have naturally
5161 descriptive names. This combination of efficiency and descriptive power
5162 makes them ideal for use as discrete data.
5166 @subsubsection Symbols as Lookup Keys
5168 Given their efficiency and descriptive power, it is natural to use
5169 symbols as the keys in an association list or hash table.
5171 To illustrate this, consider a more structured representation of the car
5172 properties example from the preceding subsection. Rather than
5173 mixing all the properties up together in a flat list, we could use an
5174 association list like this:
5177 (define car1-properties '((colour . red)
5178 (transmission . manual)
5180 (steering . power-assisted)))
5183 Notice how this structure is more explicit and extensible than the flat
5184 list. For example it makes clear that @code{manual} refers to the
5185 transmission rather than, say, the windows or the locking of the car.
5186 It also allows further properties to use the same symbols among their
5187 possible values without becoming ambiguous:
5190 (define car1-properties '((colour . red)
5191 (transmission . manual)
5193 (steering . power-assisted)
5195 (locking . manual)))
5198 With a representation like this, it is easy to use the efficient
5199 @code{assq-XXX} family of procedures (@pxref{Association Lists}) to
5200 extract or change individual pieces of information:
5203 (assq-ref car1-properties 'fuel) @result{} unleaded
5204 (assq-ref car1-properties 'transmission) @result{} manual
5206 (assq-set! car1-properties 'seat-colour 'black)
5209 (transmission . manual)
5211 (steering . power-assisted)
5212 (seat-colour . black)
5213 (locking . manual)))
5216 Hash tables also have keys, and exactly the same arguments apply to the
5217 use of symbols in hash tables as in association lists. The hash value
5218 that Guile uses to decide where to add a symbol-keyed entry to a hash
5219 table can be obtained by calling the @code{symbol-hash} procedure:
5221 @deffn {Scheme Procedure} symbol-hash symbol
5222 @deffnx {C Function} scm_symbol_hash (symbol)
5223 Return a hash value for @var{symbol}.
5226 See @ref{Hash Tables} for information about hash tables in general, and
5227 for why you might choose to use a hash table rather than an association
5231 @node Symbol Variables
5232 @subsubsection Symbols as Denoting Variables
5234 When an unquoted symbol in a Scheme program is evaluated, it is
5235 interpreted as a variable reference, and the result of the evaluation is
5236 the appropriate variable's value.
5238 For example, when the expression @code{(string-length "abcd")} is read
5239 and evaluated, the sequence of characters @code{string-length} is read
5240 as the symbol whose name is "string-length". This symbol is associated
5241 with a variable whose value is the procedure that implements string
5242 length calculation. Therefore evaluation of the @code{string-length}
5243 symbol results in that procedure.
5245 The details of the connection between an unquoted symbol and the
5246 variable to which it refers are explained elsewhere. See @ref{Binding
5247 Constructs}, for how associations between symbols and variables are
5248 created, and @ref{Modules}, for how those associations are affected by
5249 Guile's module system.
5252 @node Symbol Primitives
5253 @subsubsection Operations Related to Symbols
5255 Given any Scheme value, you can determine whether it is a symbol using
5256 the @code{symbol?} primitive:
5259 @deffn {Scheme Procedure} symbol? obj
5260 @deffnx {C Function} scm_symbol_p (obj)
5261 Return @code{#t} if @var{obj} is a symbol, otherwise return
5265 @deftypefn {C Function} int scm_is_symbol (SCM val)
5266 Equivalent to @code{scm_is_true (scm_symbol_p (val))}.
5269 Once you know that you have a symbol, you can obtain its name as a
5270 string by calling @code{symbol->string}. Note that Guile differs by
5271 default from R5RS on the details of @code{symbol->string} as regards
5274 @rnindex symbol->string
5275 @deffn {Scheme Procedure} symbol->string s
5276 @deffnx {C Function} scm_symbol_to_string (s)
5277 Return the name of symbol @var{s} as a string. By default, Guile reads
5278 symbols case-sensitively, so the string returned will have the same case
5279 variation as the sequence of characters that caused @var{s} to be
5282 If Guile is set to read symbols case-insensitively (as specified by
5283 R5RS), and @var{s} comes into being as part of a literal expression
5284 (@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
5285 by a call to the @code{read} or @code{string-ci->symbol} procedures,
5286 Guile converts any alphabetic characters in the symbol's name to
5287 lower case before creating the symbol object, so the string returned
5288 here will be in lower case.
5290 If @var{s} was created by @code{string->symbol}, the case of characters
5291 in the string returned will be the same as that in the string that was
5292 passed to @code{string->symbol}, regardless of Guile's case-sensitivity
5293 setting at the time @var{s} was created.
5295 It is an error to apply mutation procedures like @code{string-set!} to
5296 strings returned by this procedure.
5299 Most symbols are created by writing them literally in code. However it
5300 is also possible to create symbols programmatically using the following
5301 @code{string->symbol} and @code{string-ci->symbol} procedures:
5303 @rnindex string->symbol
5304 @deffn {Scheme Procedure} string->symbol string
5305 @deffnx {C Function} scm_string_to_symbol (string)
5306 Return the symbol whose name is @var{string}. This procedure can create
5307 symbols with names containing special characters or letters in the
5308 non-standard case, but it is usually a bad idea to create such symbols
5309 because in some implementations of Scheme they cannot be read as
5313 @deffn {Scheme Procedure} string-ci->symbol str
5314 @deffnx {C Function} scm_string_ci_to_symbol (str)
5315 Return the symbol whose name is @var{str}. If Guile is currently
5316 reading symbols case-insensitively, @var{str} is converted to lowercase
5317 before the returned symbol is looked up or created.
5320 The following examples illustrate Guile's detailed behaviour as regards
5321 the case-sensitivity of symbols:
5324 (read-enable 'case-insensitive) ; R5RS compliant behaviour
5326 (symbol->string 'flying-fish) @result{} "flying-fish"
5327 (symbol->string 'Martin) @result{} "martin"
5329 (string->symbol "Malvina")) @result{} "Malvina"
5331 (eq? 'mISSISSIppi 'mississippi) @result{} #t
5332 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
5333 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
5335 (string->symbol (symbol->string 'LolliPop))) @result{} #t
5336 (string=? "K. Harper, M.D."
5338 (string->symbol "K. Harper, M.D."))) @result{} #t
5340 (read-disable 'case-insensitive) ; Guile default behaviour
5342 (symbol->string 'flying-fish) @result{} "flying-fish"
5343 (symbol->string 'Martin) @result{} "Martin"
5345 (string->symbol "Malvina")) @result{} "Malvina"
5347 (eq? 'mISSISSIppi 'mississippi) @result{} #f
5348 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
5349 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
5351 (string->symbol (symbol->string 'LolliPop))) @result{} #t
5352 (string=? "K. Harper, M.D."
5354 (string->symbol "K. Harper, M.D."))) @result{} #t
5357 From C, there are lower level functions that construct a Scheme symbol
5358 from a C string in the current locale encoding.
5360 When you want to do more from C, you should convert between symbols
5361 and strings using @code{scm_symbol_to_string} and
5362 @code{scm_string_to_symbol} and work with the strings.
5364 @deffn {C Function} scm_from_locale_symbol (const char *name)
5365 @deffnx {C Function} scm_from_locale_symboln (const char *name, size_t len)
5366 Construct and return a Scheme symbol whose name is specified by
5367 @var{name}. For @code{scm_from_locale_symbol}, @var{name} must be null
5368 terminated; for @code{scm_from_locale_symboln} the length of @var{name} is
5369 specified explicitly by @var{len}.
5372 @deftypefn {C Function} SCM scm_take_locale_symbol (char *str)
5373 @deftypefnx {C Function} SCM scm_take_locale_symboln (char *str, size_t len)
5374 Like @code{scm_from_locale_symbol} and @code{scm_from_locale_symboln},
5375 respectively, but also frees @var{str} with @code{free} eventually.
5376 Thus, you can use this function when you would free @var{str} anyway
5377 immediately after creating the Scheme string. In certain cases, Guile
5378 can then use @var{str} directly as its internal representation.
5381 The size of a symbol can also be obtained from C:
5383 @deftypefn {C Function} size_t scm_c_symbol_length (SCM sym)
5384 Return the number of characters in @var{sym}.
5387 Finally, some applications, especially those that generate new Scheme
5388 code dynamically, need to generate symbols for use in the generated
5389 code. The @code{gensym} primitive meets this need:
5391 @deffn {Scheme Procedure} gensym [prefix]
5392 @deffnx {C Function} scm_gensym (prefix)
5393 Create a new symbol with a name constructed from a prefix and a counter
5394 value. The string @var{prefix} can be specified as an optional
5395 argument. Default prefix is @samp{@w{ g}}. The counter is increased by 1
5396 at each call. There is no provision for resetting the counter.
5399 The symbols generated by @code{gensym} are @emph{likely} to be unique,
5400 since their names begin with a space and it is only otherwise possible
5401 to generate such symbols if a programmer goes out of their way to do
5402 so. Uniqueness can be guaranteed by instead using uninterned symbols
5403 (@pxref{Symbol Uninterned}), though they can't be usefully written out
5408 @subsubsection Function Slots and Property Lists
5410 In traditional Lisp dialects, symbols are often understood as having
5411 three kinds of value at once:
5415 a @dfn{variable} value, which is used when the symbol appears in
5416 code in a variable reference context
5419 a @dfn{function} value, which is used when the symbol appears in
5420 code in a function name position (i.e. as the first element in an
5424 a @dfn{property list} value, which is used when the symbol is given as
5425 the first argument to Lisp's @code{put} or @code{get} functions.
5428 Although Scheme (as one of its simplifications with respect to Lisp)
5429 does away with the distinction between variable and function namespaces,
5430 Guile currently retains some elements of the traditional structure in
5431 case they turn out to be useful when implementing translators for other
5432 languages, in particular Emacs Lisp.
5434 Specifically, Guile symbols have two extra slots. for a symbol's
5435 property list, and for its ``function value.'' The following procedures
5436 are provided to access these slots.
5438 @deffn {Scheme Procedure} symbol-fref symbol
5439 @deffnx {C Function} scm_symbol_fref (symbol)
5440 Return the contents of @var{symbol}'s @dfn{function slot}.
5443 @deffn {Scheme Procedure} symbol-fset! symbol value
5444 @deffnx {C Function} scm_symbol_fset_x (symbol, value)
5445 Set the contents of @var{symbol}'s function slot to @var{value}.
5448 @deffn {Scheme Procedure} symbol-pref symbol
5449 @deffnx {C Function} scm_symbol_pref (symbol)
5450 Return the @dfn{property list} currently associated with @var{symbol}.
5453 @deffn {Scheme Procedure} symbol-pset! symbol value
5454 @deffnx {C Function} scm_symbol_pset_x (symbol, value)
5455 Set @var{symbol}'s property list to @var{value}.
5458 @deffn {Scheme Procedure} symbol-property sym prop
5459 From @var{sym}'s property list, return the value for property
5460 @var{prop}. The assumption is that @var{sym}'s property list is an
5461 association list whose keys are distinguished from each other using
5462 @code{equal?}; @var{prop} should be one of the keys in that list. If
5463 the property list has no entry for @var{prop}, @code{symbol-property}
5467 @deffn {Scheme Procedure} set-symbol-property! sym prop val
5468 In @var{sym}'s property list, set the value for property @var{prop} to
5469 @var{val}, or add a new entry for @var{prop}, with value @var{val}, if
5470 none already exists. For the structure of the property list, see
5471 @code{symbol-property}.
5474 @deffn {Scheme Procedure} symbol-property-remove! sym prop
5475 From @var{sym}'s property list, remove the entry for property
5476 @var{prop}, if there is one. For the structure of the property list,
5477 see @code{symbol-property}.
5480 Support for these extra slots may be removed in a future release, and it
5481 is probably better to avoid using them. For a more modern and Schemely
5482 approach to properties, see @ref{Object Properties}.
5485 @node Symbol Read Syntax
5486 @subsubsection Extended Read Syntax for Symbols
5488 The read syntax for a symbol is a sequence of letters, digits, and
5489 @dfn{extended alphabetic characters}, beginning with a character that
5490 cannot begin a number. In addition, the special cases of @code{+},
5491 @code{-}, and @code{...} are read as symbols even though numbers can
5492 begin with @code{+}, @code{-} or @code{.}.
5494 Extended alphabetic characters may be used within identifiers as if
5495 they were letters. The set of extended alphabetic characters is:
5498 ! $ % & * + - . / : < = > ? @@ ^ _ ~
5501 In addition to the standard read syntax defined above (which is taken
5502 from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
5503 Scheme})), Guile provides an extended symbol read syntax that allows the
5504 inclusion of unusual characters such as space characters, newlines and
5505 parentheses. If (for whatever reason) you need to write a symbol
5506 containing characters not mentioned above, you can do so as follows.
5510 Begin the symbol with the characters @code{#@{},
5513 write the characters of the symbol and
5516 finish the symbol with the characters @code{@}#}.
5519 Here are a few examples of this form of read syntax. The first symbol
5520 needs to use extended syntax because it contains a space character, the
5521 second because it contains a line break, and the last because it looks
5533 Although Guile provides this extended read syntax for symbols,
5534 widespread usage of it is discouraged because it is not portable and not
5538 @node Symbol Uninterned
5539 @subsubsection Uninterned Symbols
5541 What makes symbols useful is that they are automatically kept unique.
5542 There are no two symbols that are distinct objects but have the same
5543 name. But of course, there is no rule without exception. In addition
5544 to the normal symbols that have been discussed up to now, you can also
5545 create special @dfn{uninterned} symbols that behave slightly
5548 To understand what is different about them and why they might be useful,
5549 we look at how normal symbols are actually kept unique.
5551 Whenever Guile wants to find the symbol with a specific name, for
5552 example during @code{read} or when executing @code{string->symbol}, it
5553 first looks into a table of all existing symbols to find out whether a
5554 symbol with the given name already exists. When this is the case, Guile
5555 just returns that symbol. When not, a new symbol with the name is
5556 created and entered into the table so that it can be found later.
5558 Sometimes you might want to create a symbol that is guaranteed `fresh',
5559 i.e. a symbol that did not exist previously. You might also want to
5560 somehow guarantee that no one else will ever unintentionally stumble
5561 across your symbol in the future. These properties of a symbol are
5562 often needed when generating code during macro expansion. When
5563 introducing new temporary variables, you want to guarantee that they
5564 don't conflict with variables in other people's code.
5566 The simplest way to arrange for this is to create a new symbol but
5567 not enter it into the global table of all symbols. That way, no one
5568 will ever get access to your symbol by chance. Symbols that are not in
5569 the table are called @dfn{uninterned}. Of course, symbols that
5570 @emph{are} in the table are called @dfn{interned}.
5572 You create new uninterned symbols with the function @code{make-symbol}.
5573 You can test whether a symbol is interned or not with
5574 @code{symbol-interned?}.
5576 Uninterned symbols break the rule that the name of a symbol uniquely
5577 identifies the symbol object. Because of this, they can not be written
5578 out and read back in like interned symbols. Currently, Guile has no
5579 support for reading uninterned symbols. Note that the function
5580 @code{gensym} does not return uninterned symbols for this reason.
5582 @deffn {Scheme Procedure} make-symbol name
5583 @deffnx {C Function} scm_make_symbol (name)
5584 Return a new uninterned symbol with the name @var{name}. The returned
5585 symbol is guaranteed to be unique and future calls to
5586 @code{string->symbol} will not return it.
5589 @deffn {Scheme Procedure} symbol-interned? symbol
5590 @deffnx {C Function} scm_symbol_interned_p (symbol)
5591 Return @code{#t} if @var{symbol} is interned, otherwise return
5598 (define foo-1 (string->symbol "foo"))
5599 (define foo-2 (string->symbol "foo"))
5600 (define foo-3 (make-symbol "foo"))
5601 (define foo-4 (make-symbol "foo"))
5605 ; Two interned symbols with the same name are the same object,
5609 ; but a call to make-symbol with the same name returns a
5614 ; A call to make-symbol always returns a new object, even for
5618 @result{} #<uninterned-symbol foo 8085290>
5619 ; Uninterned symbols print differently from interned symbols,
5623 ; but they are still symbols,
5625 (symbol-interned? foo-3)
5627 ; just not interned.
5632 @subsection Keywords
5635 Keywords are self-evaluating objects with a convenient read syntax that
5636 makes them easy to type.
5638 Guile's keyword support conforms to R5RS, and adds a (switchable) read
5639 syntax extension to permit keywords to begin with @code{:} as well as
5640 @code{#:}, or to end with @code{:}.
5643 * Why Use Keywords?:: Motivation for keyword usage.
5644 * Coding With Keywords:: How to use keywords.
5645 * Keyword Read Syntax:: Read syntax for keywords.
5646 * Keyword Procedures:: Procedures for dealing with keywords.
5649 @node Why Use Keywords?
5650 @subsubsection Why Use Keywords?
5652 Keywords are useful in contexts where a program or procedure wants to be
5653 able to accept a large number of optional arguments without making its
5654 interface unmanageable.
5656 To illustrate this, consider a hypothetical @code{make-window}
5657 procedure, which creates a new window on the screen for drawing into
5658 using some graphical toolkit. There are many parameters that the caller
5659 might like to specify, but which could also be sensibly defaulted, for
5664 color depth -- Default: the color depth for the screen
5667 background color -- Default: white
5670 width -- Default: 600
5673 height -- Default: 400
5676 If @code{make-window} did not use keywords, the caller would have to
5677 pass in a value for each possible argument, remembering the correct
5678 argument order and using a special value to indicate the default value
5682 (make-window 'default ;; Color depth
5683 'default ;; Background color
5686 @dots{}) ;; More make-window arguments
5689 With keywords, on the other hand, defaulted arguments are omitted, and
5690 non-default arguments are clearly tagged by the appropriate keyword. As
5691 a result, the invocation becomes much clearer:
5694 (make-window #:width 800 #:height 100)
5697 On the other hand, for a simpler procedure with few arguments, the use
5698 of keywords would be a hindrance rather than a help. The primitive
5699 procedure @code{cons}, for example, would not be improved if it had to
5703 (cons #:car x #:cdr y)
5706 So the decision whether to use keywords or not is purely pragmatic: use
5707 them if they will clarify the procedure invocation at point of call.
5709 @node Coding With Keywords
5710 @subsubsection Coding With Keywords
5712 If a procedure wants to support keywords, it should take a rest argument
5713 and then use whatever means is convenient to extract keywords and their
5714 corresponding arguments from the contents of that rest argument.
5716 The following example illustrates the principle: the code for
5717 @code{make-window} uses a helper procedure called
5718 @code{get-keyword-value} to extract individual keyword arguments from
5722 (define (get-keyword-value args keyword default)
5723 (let ((kv (memq keyword args)))
5724 (if (and kv (>= (length kv) 2))
5728 (define (make-window . args)
5729 (let ((depth (get-keyword-value args #:depth screen-depth))
5730 (bg (get-keyword-value args #:bg "white"))
5731 (width (get-keyword-value args #:width 800))
5732 (height (get-keyword-value args #:height 100))
5737 But you don't need to write @code{get-keyword-value}. The @code{(ice-9
5738 optargs)} module provides a set of powerful macros that you can use to
5739 implement keyword-supporting procedures like this:
5742 (use-modules (ice-9 optargs))
5744 (define (make-window . args)
5745 (let-keywords args #f ((depth screen-depth)
5753 Or, even more economically, like this:
5756 (use-modules (ice-9 optargs))
5758 (define* (make-window #:key (depth screen-depth)
5765 For further details on @code{let-keywords}, @code{define*} and other
5766 facilities provided by the @code{(ice-9 optargs)} module, see
5767 @ref{Optional Arguments}.
5770 @node Keyword Read Syntax
5771 @subsubsection Keyword Read Syntax
5773 Guile, by default, only recognizes a keyword syntax that is compatible
5774 with R5RS. A token of the form @code{#:NAME}, where @code{NAME} has the
5775 same syntax as a Scheme symbol (@pxref{Symbol Read Syntax}), is the
5776 external representation of the keyword named @code{NAME}. Keyword
5777 objects print using this syntax as well, so values containing keyword
5778 objects can be read back into Guile. When used in an expression,
5779 keywords are self-quoting objects.
5781 If the @code{keyword} read option is set to @code{'prefix}, Guile also
5782 recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
5783 of the form @code{:NAME} are read as symbols, as required by R5RS.
5785 @cindex SRFI-88 keyword syntax
5787 If the @code{keyword} read option is set to @code{'postfix}, Guile
5788 recognizes the SRFI-88 read syntax @code{NAME:} (@pxref{SRFI-88}).
5789 Otherwise, tokens of this form are read as symbols.
5791 To enable and disable the alternative non-R5RS keyword syntax, you use
5792 the @code{read-set!} procedure documented in @ref{User level options
5793 interfaces} and @ref{Reader options}. Note that the @code{prefix} and
5794 @code{postfix} syntax are mutually exclusive.
5797 (read-set! keywords 'prefix)
5807 (read-set! keywords 'postfix)
5817 (read-set! keywords #f)
5825 ERROR: In expression :type:
5826 ERROR: Unbound variable: :type
5827 ABORT: (unbound-variable)
5830 @node Keyword Procedures
5831 @subsubsection Keyword Procedures
5833 @deffn {Scheme Procedure} keyword? obj
5834 @deffnx {C Function} scm_keyword_p (obj)
5835 Return @code{#t} if the argument @var{obj} is a keyword, else
5839 @deffn {Scheme Procedure} keyword->symbol keyword
5840 @deffnx {C Function} scm_keyword_to_symbol (keyword)
5841 Return the symbol with the same name as @var{keyword}.
5844 @deffn {Scheme Procedure} symbol->keyword symbol
5845 @deffnx {C Function} scm_symbol_to_keyword (symbol)
5846 Return the keyword with the same name as @var{symbol}.
5849 @deftypefn {C Function} int scm_is_keyword (SCM obj)
5850 Equivalent to @code{scm_is_true (scm_keyword_p (@var{obj}))}.
5853 @deftypefn {C Function} SCM scm_from_locale_keyword (const char *str)
5854 @deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *str, size_t len)
5855 Equivalent to @code{scm_symbol_to_keyword (scm_from_locale_symbol
5856 (@var{str}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln
5857 (@var{str}, @var{len}))}, respectively.
5861 @subsection ``Functionality-Centric'' Data Types
5863 Procedures and macros are documented in their own chapter: see
5864 @ref{Procedures and Macros}.
5866 Variable objects are documented as part of the description of Guile's
5867 module system: see @ref{Variables}.
5869 Asyncs, dynamic roots and fluids are described in the chapter on
5870 scheduling: see @ref{Scheduling}.
5872 Hooks are documented in the chapter on general utility functions: see
5875 Ports are described in the chapter on I/O: see @ref{Input and Output}.
5879 @c TeX-master: "guile.texi"