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
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 * Primitive Numerics:: Primitive numeric functions.
188 * Bitwise Operations:: Logical AND, OR, NOT, and so on.
189 * Random:: Random number generation.
193 @node Numerical Tower
194 @subsubsection Scheme's Numerical ``Tower''
197 Scheme's numerical ``tower'' consists of the following categories of
202 Whole numbers, positive or negative; e.g.@: --5, 0, 18.
205 The set of numbers that can be expressed as @math{@var{p}/@var{q}}
206 where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
207 pi (an irrational number) doesn't. These include integers
211 The set of numbers that describes all possible positions along a
212 one-dimensional line. This includes rationals as well as irrational
215 @item complex numbers
216 The set of numbers that describes all possible positions in a two
217 dimensional space. This includes real as well as imaginary numbers
218 (@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
219 @var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
223 It is called a tower because each category ``sits on'' the one that
224 follows it, in the sense that every integer is also a rational, every
225 rational is also real, and every real number is also a complex number
226 (but with zero imaginary part).
228 In addition to the classification into integers, rationals, reals and
229 complex numbers, Scheme also distinguishes between whether a number is
230 represented exactly or not. For example, the result of
231 @m{2\sin(\pi/4),2*sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)}, but Guile
232 can represent neither @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
233 Instead, it stores an inexact approximation, using the C type
236 Guile can represent exact rationals of any magnitude, inexact
237 rationals that fit into a C @code{double}, and inexact complex numbers
238 with @code{double} real and imaginary parts.
240 The @code{number?} predicate may be applied to any Scheme value to
241 discover whether the value is any of the supported numerical types.
243 @deffn {Scheme Procedure} number? obj
244 @deffnx {C Function} scm_number_p (obj)
245 Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
254 (number? "hello there!")
257 (define pi 3.141592654)
262 @deftypefn {C Function} int scm_is_number (SCM obj)
263 This is equivalent to @code{scm_is_true (scm_number_p (obj))}.
266 The next few subsections document each of Guile's numerical data types
270 @subsubsection Integers
272 @tpindex Integer numbers
276 Integers are whole numbers, that is numbers with no fractional part,
277 such as 2, 83, and @minus{}3789.
279 Integers in Guile can be arbitrarily big, as shown by the following
283 (define (factorial n)
284 (let loop ((n n) (product 1))
287 (loop (- n 1) (* product n)))))
293 @result{} 2432902008176640000
296 @result{} -119622220865480194561963161495657715064383733760000000000
299 Readers whose background is in programming languages where integers are
300 limited by the need to fit into just 4 or 8 bytes of memory may find
301 this surprising, or suspect that Guile's representation of integers is
302 inefficient. In fact, Guile achieves a near optimal balance of
303 convenience and efficiency by using the host computer's native
304 representation of integers where possible, and a more general
305 representation where the required number does not fit in the native
306 form. Conversion between these two representations is automatic and
307 completely invisible to the Scheme level programmer.
309 The infinities @samp{+inf.0} and @samp{-inf.0} are considered to be
310 inexact integers. They are explained in detail in the next section,
311 together with reals and rationals.
313 C has a host of different integer types, and Guile offers a host of
314 functions to convert between them and the @code{SCM} representation.
315 For example, a C @code{int} can be handled with @code{scm_to_int} and
316 @code{scm_from_int}. Guile also defines a few C integer types of its
317 own, to help with differences between systems.
319 C integer types that are not covered can be handled with the generic
320 @code{scm_to_signed_integer} and @code{scm_from_signed_integer} for
321 signed types, or with @code{scm_to_unsigned_integer} and
322 @code{scm_from_unsigned_integer} for unsigned types.
324 Scheme integers can be exact and inexact. For example, a number
325 written as @code{3.0} with an explicit decimal-point is inexact, but
326 it is also an integer. The functions @code{integer?} and
327 @code{scm_is_integer} report true for such a number, but the functions
328 @code{scm_is_signed_integer} and @code{scm_is_unsigned_integer} only
329 allow exact integers and thus report false. Likewise, the conversion
330 functions like @code{scm_to_signed_integer} only accept exact
333 The motivation for this behavior is that the inexactness of a number
334 should not be lost silently. If you want to allow inexact integers,
335 you can explicitly insert a call to @code{inexact->exact} or to its C
336 equivalent @code{scm_inexact_to_exact}. (Only inexact integers will
337 be converted by this call into exact integers; inexact non-integers
338 will become exact fractions.)
340 @deffn {Scheme Procedure} integer? x
341 @deffnx {C Function} scm_integer_p (x)
342 Return @code{#t} if @var{x} is an exact or inexact integer number, else
360 @deftypefn {C Function} int scm_is_integer (SCM x)
361 This is equivalent to @code{scm_is_true (scm_integer_p (x))}.
364 @defvr {C Type} scm_t_int8
365 @defvrx {C Type} scm_t_uint8
366 @defvrx {C Type} scm_t_int16
367 @defvrx {C Type} scm_t_uint16
368 @defvrx {C Type} scm_t_int32
369 @defvrx {C Type} scm_t_uint32
370 @defvrx {C Type} scm_t_int64
371 @defvrx {C Type} scm_t_uint64
372 @defvrx {C Type} scm_t_intmax
373 @defvrx {C Type} scm_t_uintmax
374 The C types are equivalent to the corresponding ISO C types but are
375 defined on all platforms, with the exception of @code{scm_t_int64} and
376 @code{scm_t_uint64}, which are only defined when a 64-bit type is
377 available. For example, @code{scm_t_int8} is equivalent to
380 You can regard these definitions as a stop-gap measure until all
381 platforms provide these types. If you know that all the platforms
382 that you are interested in already provide these types, it is better
383 to use them directly instead of the types provided by Guile.
386 @deftypefn {C Function} int scm_is_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
387 @deftypefnx {C Function} int scm_is_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
388 Return @code{1} when @var{x} represents an exact integer that is
389 between @var{min} and @var{max}, inclusive.
391 These functions can be used to check whether a @code{SCM} value will
392 fit into a given range, such as the range of a given C integer type.
393 If you just want to convert a @code{SCM} value to a given C integer
394 type, use one of the conversion functions directly.
397 @deftypefn {C Function} scm_t_intmax scm_to_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
398 @deftypefnx {C Function} scm_t_uintmax scm_to_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
399 When @var{x} represents an exact integer that is between @var{min} and
400 @var{max} inclusive, return that integer. Else signal an error,
401 either a `wrong-type' error when @var{x} is not an exact integer, or
402 an `out-of-range' error when it doesn't fit the given range.
405 @deftypefn {C Function} SCM scm_from_signed_integer (scm_t_intmax x)
406 @deftypefnx {C Function} SCM scm_from_unsigned_integer (scm_t_uintmax x)
407 Return the @code{SCM} value that represents the integer @var{x}. This
408 function will always succeed and will always return an exact number.
411 @deftypefn {C Function} char scm_to_char (SCM x)
412 @deftypefnx {C Function} {signed char} scm_to_schar (SCM x)
413 @deftypefnx {C Function} {unsigned char} scm_to_uchar (SCM x)
414 @deftypefnx {C Function} short scm_to_short (SCM x)
415 @deftypefnx {C Function} {unsigned short} scm_to_ushort (SCM x)
416 @deftypefnx {C Function} int scm_to_int (SCM x)
417 @deftypefnx {C Function} {unsigned int} scm_to_uint (SCM x)
418 @deftypefnx {C Function} long scm_to_long (SCM x)
419 @deftypefnx {C Function} {unsigned long} scm_to_ulong (SCM x)
420 @deftypefnx {C Function} {long long} scm_to_long_long (SCM x)
421 @deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x)
422 @deftypefnx {C Function} size_t scm_to_size_t (SCM x)
423 @deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x)
424 @deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x)
425 @deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x)
426 @deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x)
427 @deftypefnx {C Function} scm_t_uint16 scm_to_uint16 (SCM x)
428 @deftypefnx {C Function} scm_t_int32 scm_to_int32 (SCM x)
429 @deftypefnx {C Function} scm_t_uint32 scm_to_uint32 (SCM x)
430 @deftypefnx {C Function} scm_t_int64 scm_to_int64 (SCM x)
431 @deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x)
432 @deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x)
433 @deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x)
434 When @var{x} represents an exact integer that fits into the indicated
435 C type, return that integer. Else signal an error, either a
436 `wrong-type' error when @var{x} is not an exact integer, or an
437 `out-of-range' error when it doesn't fit the given range.
439 The functions @code{scm_to_long_long}, @code{scm_to_ulong_long},
440 @code{scm_to_int64}, and @code{scm_to_uint64} are only available when
441 the corresponding types are.
444 @deftypefn {C Function} SCM scm_from_char (char x)
445 @deftypefnx {C Function} SCM scm_from_schar (signed char x)
446 @deftypefnx {C Function} SCM scm_from_uchar (unsigned char x)
447 @deftypefnx {C Function} SCM scm_from_short (short x)
448 @deftypefnx {C Function} SCM scm_from_ushort (unsigned short x)
449 @deftypefnx {C Function} SCM scm_from_int (int x)
450 @deftypefnx {C Function} SCM scm_from_uint (unsigned int x)
451 @deftypefnx {C Function} SCM scm_from_long (long x)
452 @deftypefnx {C Function} SCM scm_from_ulong (unsigned long x)
453 @deftypefnx {C Function} SCM scm_from_long_long (long long x)
454 @deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x)
455 @deftypefnx {C Function} SCM scm_from_size_t (size_t x)
456 @deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x)
457 @deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x)
458 @deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x)
459 @deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x)
460 @deftypefnx {C Function} SCM scm_from_uint16 (scm_t_uint16 x)
461 @deftypefnx {C Function} SCM scm_from_int32 (scm_t_int32 x)
462 @deftypefnx {C Function} SCM scm_from_uint32 (scm_t_uint32 x)
463 @deftypefnx {C Function} SCM scm_from_int64 (scm_t_int64 x)
464 @deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x)
465 @deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x)
466 @deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x)
467 Return the @code{SCM} value that represents the integer @var{x}.
468 These functions will always succeed and will always return an exact
472 @deftypefn {C Function} void scm_to_mpz (SCM val, mpz_t rop)
473 Assign @var{val} to the multiple precision integer @var{rop}.
474 @var{val} must be an exact integer, otherwise an error will be
475 signalled. @var{rop} must have been initialized with @code{mpz_init}
476 before this function is called. When @var{rop} is no longer needed
477 the occupied space must be freed with @code{mpz_clear}.
478 @xref{Initializing Integers,,, gmp, GNU MP Manual}, for details.
481 @deftypefn {C Function} SCM scm_from_mpz (mpz_t val)
482 Return the @code{SCM} value that represents @var{val}.
485 @node Reals and Rationals
486 @subsubsection Real and Rational Numbers
487 @tpindex Real numbers
488 @tpindex Rational numbers
493 Mathematically, the real numbers are the set of numbers that describe
494 all possible points along a continuous, infinite, one-dimensional line.
495 The rational numbers are the set of all numbers that can be written as
496 fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
497 All rational numbers are also real, but there are real numbers that
498 are not rational, for example @m{\sqrt2, the square root of 2}, and
501 Guile can represent both exact and inexact rational numbers, but it
502 can not represent irrational numbers. Exact rationals are represented
503 by storing the numerator and denominator as two exact integers.
504 Inexact rationals are stored as floating point numbers using the C
507 Exact rationals are written as a fraction of integers. There must be
508 no whitespace around the slash:
515 Even though the actual encoding of inexact rationals is in binary, it
516 may be helpful to think of it as a decimal number with a limited
517 number of significant figures and a decimal point somewhere, since
518 this corresponds to the standard notation for non-whole numbers. For
524 -5648394822220000000000.0
528 The limited precision of Guile's encoding means that any ``real'' number
529 in Guile can be written in a rational form, by multiplying and then dividing
530 by sufficient powers of 10 (or in fact, 2). For example,
531 @samp{-0.00000142857931198} is the same as @minus{}142857931198 divided by
532 100000000000000000. In Guile's current incarnation, therefore, the
533 @code{rational?} and @code{real?} predicates are equivalent.
536 Dividing by an exact zero leads to a error message, as one might
537 expect. However, dividing by an inexact zero does not produce an
538 error. Instead, the result of the division is either plus or minus
539 infinity, depending on the sign of the divided number.
541 The infinities are written @samp{+inf.0} and @samp{-inf.0},
542 respectively. This syntax is also recognized by @code{read} as an
543 extension to the usual Scheme syntax.
545 Dividing zero by zero yields something that is not a number at all:
546 @samp{+nan.0}. This is the special `not a number' value.
548 On platforms that follow @acronym{IEEE} 754 for their floating point
549 arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
550 are implemented using the corresponding @acronym{IEEE} 754 values.
551 They behave in arithmetic operations like @acronym{IEEE} 754 describes
552 it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
554 The infinities are inexact integers and are considered to be both even
555 and odd. While @samp{+nan.0} is not @code{=} to itself, it is
556 @code{eqv?} to itself.
558 To test for the special values, use the functions @code{inf?} and
561 @deffn {Scheme Procedure} real? obj
562 @deffnx {C Function} scm_real_p (obj)
563 Return @code{#t} if @var{obj} is a real number, else @code{#f}. Note
564 that the sets of integer and rational values form subsets of the set
565 of real numbers, so the predicate will also be fulfilled if @var{obj}
566 is an integer number or a rational number.
569 @deffn {Scheme Procedure} rational? x
570 @deffnx {C Function} scm_rational_p (x)
571 Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise.
572 Note that the set of integer values forms a subset of the set of
573 rational numbers, i. e. the predicate will also be fulfilled if
574 @var{x} is an integer number.
576 Since Guile can not represent irrational numbers, every number
577 satisfying @code{real?} also satisfies @code{rational?} in Guile.
580 @deffn {Scheme Procedure} rationalize x eps
581 @deffnx {C Function} scm_rationalize (x, eps)
582 Returns the @emph{simplest} rational number differing
583 from @var{x} by no more than @var{eps}.
585 As required by @acronym{R5RS}, @code{rationalize} only returns an
586 exact result when both its arguments are exact. Thus, you might need
587 to use @code{inexact->exact} on the arguments.
590 (rationalize (inexact->exact 1.2) 1/100)
596 @deffn {Scheme Procedure} inf? x
597 @deffnx {C Function} scm_inf_p (x)
598 Return @code{#t} if @var{x} is either @samp{+inf.0} or @samp{-inf.0},
602 @deffn {Scheme Procedure} nan? x
603 @deffnx {C Function} scm_nan_p (x)
604 Return @code{#t} if @var{x} is @samp{+nan.0}, @code{#f} otherwise.
607 @deffn {Scheme Procedure} nan
608 @deffnx {C Function} scm_nan ()
612 @deffn {Scheme Procedure} inf
613 @deffnx {C Function} scm_inf ()
617 @deffn {Scheme Procedure} numerator x
618 @deffnx {C Function} scm_numerator (x)
619 Return the numerator of the rational number @var{x}.
622 @deffn {Scheme Procedure} denominator x
623 @deffnx {C Function} scm_denominator (x)
624 Return the denominator of the rational number @var{x}.
627 @deftypefn {C Function} int scm_is_real (SCM val)
628 @deftypefnx {C Function} int scm_is_rational (SCM val)
629 Equivalent to @code{scm_is_true (scm_real_p (val))} and
630 @code{scm_is_true (scm_rational_p (val))}, respectively.
633 @deftypefn {C Function} double scm_to_double (SCM val)
634 Returns the number closest to @var{val} that is representable as a
635 @code{double}. Returns infinity for a @var{val} that is too large in
636 magnitude. The argument @var{val} must be a real number.
639 @deftypefn {C Function} SCM scm_from_double (double val)
640 Return the @code{SCM} value that represents @var{val}. The returned
641 value is inexact according to the predicate @code{inexact?}, but it
642 will be exactly equal to @var{val}.
645 @node Complex Numbers
646 @subsubsection Complex Numbers
647 @tpindex Complex numbers
651 Complex numbers are the set of numbers that describe all possible points
652 in a two-dimensional space. The two coordinates of a particular point
653 in this space are known as the @dfn{real} and @dfn{imaginary} parts of
654 the complex number that describes that point.
656 In Guile, complex numbers are written in rectangular form as the sum of
657 their real and imaginary parts, using the symbol @code{i} to indicate
672 Polar form can also be used, with an @samp{@@} between magnitude and
676 1@@3.141592 @result{} -1.0 (approx)
677 -1@@1.57079 @result{} 0.0-1.0i (approx)
680 Guile represents a complex number with a non-zero imaginary part as a
681 pair of inexact rationals, so the real and imaginary parts of a
682 complex number have the same properties of inexactness and limited
683 precision as single inexact rational numbers. Guile can not represent
684 exact complex numbers with non-zero imaginary parts.
686 @deffn {Scheme Procedure} complex? z
687 @deffnx {C Function} scm_complex_p (z)
688 Return @code{#t} if @var{x} is a complex number, @code{#f}
689 otherwise. Note that the sets of real, rational and integer
690 values form subsets of the set of complex numbers, i. e. the
691 predicate will also be fulfilled if @var{x} is a real,
692 rational or integer number.
695 @deftypefn {C Function} int scm_is_complex (SCM val)
696 Equivalent to @code{scm_is_true (scm_complex_p (val))}.
700 @subsubsection Exact and Inexact Numbers
701 @tpindex Exact numbers
702 @tpindex Inexact numbers
706 @rnindex exact->inexact
707 @rnindex inexact->exact
709 R5RS requires that a calculation involving inexact numbers always
710 produces an inexact result. To meet this requirement, Guile
711 distinguishes between an exact integer value such as @samp{5} and the
712 corresponding inexact real value which, to the limited precision
713 available, has no fractional part, and is printed as @samp{5.0}. Guile
714 will only convert the latter value to the former when forced to do so by
715 an invocation of the @code{inexact->exact} procedure.
717 @deffn {Scheme Procedure} exact? z
718 @deffnx {C Function} scm_exact_p (z)
719 Return @code{#t} if the number @var{z} is exact, @code{#f}
735 @deffn {Scheme Procedure} inexact? z
736 @deffnx {C Function} scm_inexact_p (z)
737 Return @code{#t} if the number @var{z} is inexact, @code{#f}
741 @deffn {Scheme Procedure} inexact->exact z
742 @deffnx {C Function} scm_inexact_to_exact (z)
743 Return an exact number that is numerically closest to @var{z}, when
744 there is one. For inexact rationals, Guile returns the exact rational
745 that is numerically equal to the inexact rational. Inexact complex
746 numbers with a non-zero imaginary part can not be made exact.
753 The following happens because 12/10 is not exactly representable as a
754 @code{double} (on most platforms). However, when reading a decimal
755 number that has been marked exact with the ``#e'' prefix, Guile is
756 able to represent it correctly.
760 @result{} 5404319552844595/4503599627370496
768 @c begin (texi-doc-string "guile" "exact->inexact")
769 @deffn {Scheme Procedure} exact->inexact z
770 @deffnx {C Function} scm_exact_to_inexact (z)
771 Convert the number @var{z} to its inexact representation.
776 @subsubsection Read Syntax for Numerical Data
778 The read syntax for integers is a string of digits, optionally
779 preceded by a minus or plus character, a code indicating the
780 base in which the integer is encoded, and a code indicating whether
781 the number is exact or inexact. The supported base codes are:
786 the integer is written in binary (base 2)
790 the integer is written in octal (base 8)
794 the integer is written in decimal (base 10)
798 the integer is written in hexadecimal (base 16)
801 If the base code is omitted, the integer is assumed to be decimal. The
802 following examples show how these base codes are used.
821 The codes for indicating exactness (which can, incidentally, be applied
822 to all numerical values) are:
831 the number is inexact.
834 If the exactness indicator is omitted, the number is exact unless it
835 contains a radix point. Since Guile can not represent exact complex
836 numbers, an error is signalled when asking for them.
846 ERROR: Wrong type argument
849 Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
850 plus and minus infinity, respectively. The value must be written
851 exactly as shown, that is, they always must have a sign and exactly
852 one zero digit after the decimal point. It also understands
853 @samp{+nan.0} and @samp{-nan.0} for the special `not-a-number' value.
854 The sign is ignored for `not-a-number' and the value is always printed
857 @node Integer Operations
858 @subsubsection Operations on Integer Values
867 @deffn {Scheme Procedure} odd? n
868 @deffnx {C Function} scm_odd_p (n)
869 Return @code{#t} if @var{n} is an odd number, @code{#f}
873 @deffn {Scheme Procedure} even? n
874 @deffnx {C Function} scm_even_p (n)
875 Return @code{#t} if @var{n} is an even number, @code{#f}
879 @c begin (texi-doc-string "guile" "quotient")
880 @c begin (texi-doc-string "guile" "remainder")
881 @deffn {Scheme Procedure} quotient n d
882 @deffnx {Scheme Procedure} remainder n d
883 @deffnx {C Function} scm_quotient (n, d)
884 @deffnx {C Function} scm_remainder (n, d)
885 Return the quotient or remainder from @var{n} divided by @var{d}. The
886 quotient is rounded towards zero, and the remainder will have the same
887 sign as @var{n}. In all cases quotient and remainder satisfy
888 @math{@var{n} = @var{q}*@var{d} + @var{r}}.
891 (remainder 13 4) @result{} 1
892 (remainder -13 4) @result{} -1
896 @c begin (texi-doc-string "guile" "modulo")
897 @deffn {Scheme Procedure} modulo n d
898 @deffnx {C Function} scm_modulo (n, d)
899 Return the remainder from @var{n} divided by @var{d}, with the same
903 (modulo 13 4) @result{} 1
904 (modulo -13 4) @result{} 3
905 (modulo 13 -4) @result{} -3
906 (modulo -13 -4) @result{} -1
910 @c begin (texi-doc-string "guile" "gcd")
911 @deffn {Scheme Procedure} gcd x@dots{}
912 @deffnx {C Function} scm_gcd (x, y)
913 Return the greatest common divisor of all arguments.
914 If called without arguments, 0 is returned.
916 The C function @code{scm_gcd} always takes two arguments, while the
917 Scheme function can take an arbitrary number.
920 @c begin (texi-doc-string "guile" "lcm")
921 @deffn {Scheme Procedure} lcm x@dots{}
922 @deffnx {C Function} scm_lcm (x, y)
923 Return the least common multiple of the arguments.
924 If called without arguments, 1 is returned.
926 The C function @code{scm_lcm} always takes two arguments, while the
927 Scheme function can take an arbitrary number.
930 @deffn {Scheme Procedure} modulo-expt n k m
931 @deffnx {C Function} scm_modulo_expt (n, k, m)
932 Return @var{n} raised to the integer exponent
933 @var{k}, modulo @var{m}.
942 @subsubsection Comparison Predicates
947 The C comparison functions below always takes two arguments, while the
948 Scheme functions can take an arbitrary number. Also keep in mind that
949 the C functions return one of the Scheme boolean values
950 @code{SCM_BOOL_T} or @code{SCM_BOOL_F} which are both true as far as C
951 is concerned. Thus, always write @code{scm_is_true (scm_num_eq_p (x,
952 y))} when testing the two Scheme numbers @code{x} and @code{y} for
953 equality, for example.
955 @c begin (texi-doc-string "guile" "=")
956 @deffn {Scheme Procedure} =
957 @deffnx {C Function} scm_num_eq_p (x, y)
958 Return @code{#t} if all parameters are numerically equal.
961 @c begin (texi-doc-string "guile" "<")
962 @deffn {Scheme Procedure} <
963 @deffnx {C Function} scm_less_p (x, y)
964 Return @code{#t} if the list of parameters is monotonically
968 @c begin (texi-doc-string "guile" ">")
969 @deffn {Scheme Procedure} >
970 @deffnx {C Function} scm_gr_p (x, y)
971 Return @code{#t} if the list of parameters is monotonically
975 @c begin (texi-doc-string "guile" "<=")
976 @deffn {Scheme Procedure} <=
977 @deffnx {C Function} scm_leq_p (x, y)
978 Return @code{#t} if the list of parameters is monotonically
982 @c begin (texi-doc-string "guile" ">=")
983 @deffn {Scheme Procedure} >=
984 @deffnx {C Function} scm_geq_p (x, y)
985 Return @code{#t} if the list of parameters is monotonically
989 @c begin (texi-doc-string "guile" "zero?")
990 @deffn {Scheme Procedure} zero? z
991 @deffnx {C Function} scm_zero_p (z)
992 Return @code{#t} if @var{z} is an exact or inexact number equal to
996 @c begin (texi-doc-string "guile" "positive?")
997 @deffn {Scheme Procedure} positive? x
998 @deffnx {C Function} scm_positive_p (x)
999 Return @code{#t} if @var{x} is an exact or inexact number greater than
1003 @c begin (texi-doc-string "guile" "negative?")
1004 @deffn {Scheme Procedure} negative? x
1005 @deffnx {C Function} scm_negative_p (x)
1006 Return @code{#t} if @var{x} is an exact or inexact number less than
1012 @subsubsection Converting Numbers To and From Strings
1013 @rnindex number->string
1014 @rnindex string->number
1016 The following procedures read and write numbers according to their
1017 external representation as defined by R5RS (@pxref{Lexical structure,
1018 R5RS Lexical Structure,, r5rs, The Revised^5 Report on the Algorithmic
1019 Language Scheme}). @xref{Number Input and Output, the @code{(ice-9
1020 i18n)} module}, for locale-dependent number parsing.
1022 @deffn {Scheme Procedure} number->string n [radix]
1023 @deffnx {C Function} scm_number_to_string (n, radix)
1024 Return a string holding the external representation of the
1025 number @var{n} in the given @var{radix}. If @var{n} is
1026 inexact, a radix of 10 will be used.
1029 @deffn {Scheme Procedure} string->number string [radix]
1030 @deffnx {C Function} scm_string_to_number (string, radix)
1031 Return a number of the maximally precise representation
1032 expressed by the given @var{string}. @var{radix} must be an
1033 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
1034 is a default radix that may be overridden by an explicit radix
1035 prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
1036 supplied, then the default radix is 10. If string is not a
1037 syntactically valid notation for a number, then
1038 @code{string->number} returns @code{#f}.
1041 @deftypefn {C Function} SCM scm_c_locale_stringn_to_number (const char *string, size_t len, unsigned radix)
1042 As per @code{string->number} above, but taking a C string, as pointer
1043 and length. The string characters should be in the current locale
1044 encoding (@code{locale} in the name refers only to that, there's no
1045 locale-dependent parsing).
1050 @subsubsection Complex Number Operations
1051 @rnindex make-rectangular
1058 @deffn {Scheme Procedure} make-rectangular real imaginary
1059 @deffnx {C Function} scm_make_rectangular (real, imaginary)
1060 Return a complex number constructed of the given @var{real} and
1061 @var{imaginary} parts.
1064 @deffn {Scheme Procedure} make-polar x y
1065 @deffnx {C Function} scm_make_polar (x, y)
1067 Return the complex number @var{x} * e^(i * @var{y}).
1070 @c begin (texi-doc-string "guile" "real-part")
1071 @deffn {Scheme Procedure} real-part z
1072 @deffnx {C Function} scm_real_part (z)
1073 Return the real part of the number @var{z}.
1076 @c begin (texi-doc-string "guile" "imag-part")
1077 @deffn {Scheme Procedure} imag-part z
1078 @deffnx {C Function} scm_imag_part (z)
1079 Return the imaginary part of the number @var{z}.
1082 @c begin (texi-doc-string "guile" "magnitude")
1083 @deffn {Scheme Procedure} magnitude z
1084 @deffnx {C Function} scm_magnitude (z)
1085 Return the magnitude of the number @var{z}. This is the same as
1086 @code{abs} for real arguments, but also allows complex numbers.
1089 @c begin (texi-doc-string "guile" "angle")
1090 @deffn {Scheme Procedure} angle z
1091 @deffnx {C Function} scm_angle (z)
1092 Return the angle of the complex number @var{z}.
1095 @deftypefn {C Function} SCM scm_c_make_rectangular (double re, double im)
1096 @deftypefnx {C Function} SCM scm_c_make_polar (double x, double y)
1097 Like @code{scm_make_rectangular} or @code{scm_make_polar},
1098 respectively, but these functions take @code{double}s as their
1102 @deftypefn {C Function} double scm_c_real_part (z)
1103 @deftypefnx {C Function} double scm_c_imag_part (z)
1104 Returns the real or imaginary part of @var{z} as a @code{double}.
1107 @deftypefn {C Function} double scm_c_magnitude (z)
1108 @deftypefnx {C Function} double scm_c_angle (z)
1109 Returns the magnitude or angle of @var{z} as a @code{double}.
1114 @subsubsection Arithmetic Functions
1129 The C arithmetic functions below always takes two arguments, while the
1130 Scheme functions can take an arbitrary number. When you need to
1131 invoke them with just one argument, for example to compute the
1132 equivalent od @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
1133 one: @code{scm_difference (x, SCM_UNDEFINED)}.
1135 @c begin (texi-doc-string "guile" "+")
1136 @deffn {Scheme Procedure} + z1 @dots{}
1137 @deffnx {C Function} scm_sum (z1, z2)
1138 Return the sum of all parameter values. Return 0 if called without any
1142 @c begin (texi-doc-string "guile" "-")
1143 @deffn {Scheme Procedure} - z1 z2 @dots{}
1144 @deffnx {C Function} scm_difference (z1, z2)
1145 If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
1146 the sum of all but the first argument are subtracted from the first
1150 @c begin (texi-doc-string "guile" "*")
1151 @deffn {Scheme Procedure} * z1 @dots{}
1152 @deffnx {C Function} scm_product (z1, z2)
1153 Return the product of all arguments. If called without arguments, 1 is
1157 @c begin (texi-doc-string "guile" "/")
1158 @deffn {Scheme Procedure} / z1 z2 @dots{}
1159 @deffnx {C Function} scm_divide (z1, z2)
1160 Divide the first argument by the product of the remaining arguments. If
1161 called with one argument @var{z1}, 1/@var{z1} is returned.
1164 @deffn {Scheme Procedure} 1+ z
1165 @deffnx {C Function} scm_oneplus (z)
1166 Return @math{@var{z} + 1}.
1169 @deffn {Scheme Procedure} 1- z
1170 @deffnx {C function} scm_oneminus (z)
1171 Return @math{@var{z} - 1}.
1174 @c begin (texi-doc-string "guile" "abs")
1175 @deffn {Scheme Procedure} abs x
1176 @deffnx {C Function} scm_abs (x)
1177 Return the absolute value of @var{x}.
1179 @var{x} must be a number with zero imaginary part. To calculate the
1180 magnitude of a complex number, use @code{magnitude} instead.
1183 @c begin (texi-doc-string "guile" "max")
1184 @deffn {Scheme Procedure} max x1 x2 @dots{}
1185 @deffnx {C Function} scm_max (x1, x2)
1186 Return the maximum of all parameter values.
1189 @c begin (texi-doc-string "guile" "min")
1190 @deffn {Scheme Procedure} min x1 x2 @dots{}
1191 @deffnx {C Function} scm_min (x1, x2)
1192 Return the minimum of all parameter values.
1195 @c begin (texi-doc-string "guile" "truncate")
1196 @deffn {Scheme Procedure} truncate x
1197 @deffnx {C Function} scm_truncate_number (x)
1198 Round the inexact number @var{x} towards zero.
1201 @c begin (texi-doc-string "guile" "round")
1202 @deffn {Scheme Procedure} round x
1203 @deffnx {C Function} scm_round_number (x)
1204 Round the inexact number @var{x} to the nearest integer. When exactly
1205 halfway between two integers, round to the even one.
1208 @c begin (texi-doc-string "guile" "floor")
1209 @deffn {Scheme Procedure} floor x
1210 @deffnx {C Function} scm_floor (x)
1211 Round the number @var{x} towards minus infinity.
1214 @c begin (texi-doc-string "guile" "ceiling")
1215 @deffn {Scheme Procedure} ceiling x
1216 @deffnx {C Function} scm_ceiling (x)
1217 Round the number @var{x} towards infinity.
1220 @deftypefn {C Function} double scm_c_truncate (double x)
1221 @deftypefnx {C Function} double scm_c_round (double x)
1222 Like @code{scm_truncate_number} or @code{scm_round_number},
1223 respectively, but these functions take and return @code{double}
1228 @subsubsection Scientific Functions
1230 The following procedures accept any kind of number as arguments,
1231 including complex numbers.
1234 @c begin (texi-doc-string "guile" "sqrt")
1235 @deffn {Scheme Procedure} sqrt z
1236 Return the square root of @var{z}. Of the two possible roots
1237 (positive and negative), the one with the a positive real part is
1238 returned, or if that's zero then a positive imaginary part. Thus,
1241 (sqrt 9.0) @result{} 3.0
1242 (sqrt -9.0) @result{} 0.0+3.0i
1243 (sqrt 1.0+1.0i) @result{} 1.09868411346781+0.455089860562227i
1244 (sqrt -1.0-1.0i) @result{} 0.455089860562227-1.09868411346781i
1249 @c begin (texi-doc-string "guile" "expt")
1250 @deffn {Scheme Procedure} expt z1 z2
1251 Return @var{z1} raised to the power of @var{z2}.
1255 @c begin (texi-doc-string "guile" "sin")
1256 @deffn {Scheme Procedure} sin z
1257 Return the sine of @var{z}.
1261 @c begin (texi-doc-string "guile" "cos")
1262 @deffn {Scheme Procedure} cos z
1263 Return the cosine of @var{z}.
1267 @c begin (texi-doc-string "guile" "tan")
1268 @deffn {Scheme Procedure} tan z
1269 Return the tangent of @var{z}.
1273 @c begin (texi-doc-string "guile" "asin")
1274 @deffn {Scheme Procedure} asin z
1275 Return the arcsine of @var{z}.
1279 @c begin (texi-doc-string "guile" "acos")
1280 @deffn {Scheme Procedure} acos z
1281 Return the arccosine of @var{z}.
1285 @c begin (texi-doc-string "guile" "atan")
1286 @deffn {Scheme Procedure} atan z
1287 @deffnx {Scheme Procedure} atan y x
1288 Return the arctangent of @var{z}, or of @math{@var{y}/@var{x}}.
1292 @c begin (texi-doc-string "guile" "exp")
1293 @deffn {Scheme Procedure} exp z
1294 Return e to the power of @var{z}, where e is the base of natural
1295 logarithms (2.71828@dots{}).
1299 @c begin (texi-doc-string "guile" "log")
1300 @deffn {Scheme Procedure} log z
1301 Return the natural logarithm of @var{z}.
1304 @c begin (texi-doc-string "guile" "log10")
1305 @deffn {Scheme Procedure} log10 z
1306 Return the base 10 logarithm of @var{z}.
1309 @c begin (texi-doc-string "guile" "sinh")
1310 @deffn {Scheme Procedure} sinh z
1311 Return the hyperbolic sine of @var{z}.
1314 @c begin (texi-doc-string "guile" "cosh")
1315 @deffn {Scheme Procedure} cosh z
1316 Return the hyperbolic cosine of @var{z}.
1319 @c begin (texi-doc-string "guile" "tanh")
1320 @deffn {Scheme Procedure} tanh z
1321 Return the hyperbolic tangent of @var{z}.
1324 @c begin (texi-doc-string "guile" "asinh")
1325 @deffn {Scheme Procedure} asinh z
1326 Return the hyperbolic arcsine of @var{z}.
1329 @c begin (texi-doc-string "guile" "acosh")
1330 @deffn {Scheme Procedure} acosh z
1331 Return the hyperbolic arccosine of @var{z}.
1334 @c begin (texi-doc-string "guile" "atanh")
1335 @deffn {Scheme Procedure} atanh z
1336 Return the hyperbolic arctangent of @var{z}.
1340 @node Primitive Numerics
1341 @subsubsection Primitive Numeric Functions
1343 Many of Guile's numeric procedures which accept any kind of numbers as
1344 arguments, including complex numbers, are implemented as Scheme
1345 procedures that use the following real number-based primitives. These
1346 primitives signal an error if they are called with complex arguments.
1348 @c begin (texi-doc-string "guile" "$abs")
1349 @deffn {Scheme Procedure} $abs x
1350 Return the absolute value of @var{x}.
1353 @c begin (texi-doc-string "guile" "$sqrt")
1354 @deffn {Scheme Procedure} $sqrt x
1355 Return the square root of @var{x}.
1358 @deffn {Scheme Procedure} $expt x y
1359 @deffnx {C Function} scm_sys_expt (x, y)
1360 Return @var{x} raised to the power of @var{y}. This
1361 procedure does not accept complex arguments.
1364 @c begin (texi-doc-string "guile" "$sin")
1365 @deffn {Scheme Procedure} $sin x
1366 Return the sine of @var{x}.
1369 @c begin (texi-doc-string "guile" "$cos")
1370 @deffn {Scheme Procedure} $cos x
1371 Return the cosine of @var{x}.
1374 @c begin (texi-doc-string "guile" "$tan")
1375 @deffn {Scheme Procedure} $tan x
1376 Return the tangent of @var{x}.
1379 @c begin (texi-doc-string "guile" "$asin")
1380 @deffn {Scheme Procedure} $asin x
1381 Return the arcsine of @var{x}.
1384 @c begin (texi-doc-string "guile" "$acos")
1385 @deffn {Scheme Procedure} $acos x
1386 Return the arccosine of @var{x}.
1389 @c begin (texi-doc-string "guile" "$atan")
1390 @deffn {Scheme Procedure} $atan x
1391 Return the arctangent of @var{x} in the range @minus{}@math{PI/2} to
1395 @deffn {Scheme Procedure} $atan2 x y
1396 @deffnx {C Function} scm_sys_atan2 (x, y)
1397 Return the arc tangent of the two arguments @var{x} and
1398 @var{y}. This is similar to calculating the arc tangent of
1399 @var{x} / @var{y}, except that the signs of both arguments
1400 are used to determine the quadrant of the result. This
1401 procedure does not accept complex arguments.
1404 @c begin (texi-doc-string "guile" "$exp")
1405 @deffn {Scheme Procedure} $exp x
1406 Return e to the power of @var{x}, where e is the base of natural
1407 logarithms (2.71828@dots{}).
1410 @c begin (texi-doc-string "guile" "$log")
1411 @deffn {Scheme Procedure} $log x
1412 Return the natural logarithm of @var{x}.
1415 @c begin (texi-doc-string "guile" "$sinh")
1416 @deffn {Scheme Procedure} $sinh x
1417 Return the hyperbolic sine of @var{x}.
1420 @c begin (texi-doc-string "guile" "$cosh")
1421 @deffn {Scheme Procedure} $cosh x
1422 Return the hyperbolic cosine of @var{x}.
1425 @c begin (texi-doc-string "guile" "$tanh")
1426 @deffn {Scheme Procedure} $tanh x
1427 Return the hyperbolic tangent of @var{x}.
1430 @c begin (texi-doc-string "guile" "$asinh")
1431 @deffn {Scheme Procedure} $asinh x
1432 Return the hyperbolic arcsine of @var{x}.
1435 @c begin (texi-doc-string "guile" "$acosh")
1436 @deffn {Scheme Procedure} $acosh x
1437 Return the hyperbolic arccosine of @var{x}.
1440 @c begin (texi-doc-string "guile" "$atanh")
1441 @deffn {Scheme Procedure} $atanh x
1442 Return the hyperbolic arctangent of @var{x}.
1445 C functions for the above are provided by the standard mathematics
1446 library. Naturally these expect and return @code{double} arguments
1447 (@pxref{Mathematics,,, libc, GNU C Library Reference Manual}).
1449 @multitable {xx} {Scheme Procedure} {C Function}
1450 @item @tab Scheme Procedure @tab C Function
1452 @item @tab @code{$abs} @tab @code{fabs}
1453 @item @tab @code{$sqrt} @tab @code{sqrt}
1454 @item @tab @code{$sin} @tab @code{sin}
1455 @item @tab @code{$cos} @tab @code{cos}
1456 @item @tab @code{$tan} @tab @code{tan}
1457 @item @tab @code{$asin} @tab @code{asin}
1458 @item @tab @code{$acos} @tab @code{acos}
1459 @item @tab @code{$atan} @tab @code{atan}
1460 @item @tab @code{$atan2} @tab @code{atan2}
1461 @item @tab @code{$exp} @tab @code{exp}
1462 @item @tab @code{$expt} @tab @code{pow}
1463 @item @tab @code{$log} @tab @code{log}
1464 @item @tab @code{$sinh} @tab @code{sinh}
1465 @item @tab @code{$cosh} @tab @code{cosh}
1466 @item @tab @code{$tanh} @tab @code{tanh}
1467 @item @tab @code{$asinh} @tab @code{asinh}
1468 @item @tab @code{$acosh} @tab @code{acosh}
1469 @item @tab @code{$atanh} @tab @code{atanh}
1472 @code{asinh}, @code{acosh} and @code{atanh} are C99 standard but might
1473 not be available on older systems. Guile provides the following
1474 equivalents (on all systems).
1476 @deftypefn {C Function} double scm_asinh (double x)
1477 @deftypefnx {C Function} double scm_acosh (double x)
1478 @deftypefnx {C Function} double scm_atanh (double x)
1479 Return the hyperbolic arcsine, arccosine or arctangent of @var{x}
1484 @node Bitwise Operations
1485 @subsubsection Bitwise Operations
1487 For the following bitwise functions, negative numbers are treated as
1488 infinite precision twos-complements. For instance @math{-6} is bits
1489 @math{@dots{}111010}, with infinitely many ones on the left. It can
1490 be seen that adding 6 (binary 110) to such a bit pattern gives all
1493 @deffn {Scheme Procedure} logand n1 n2 @dots{}
1494 @deffnx {C Function} scm_logand (n1, n2)
1495 Return the bitwise @sc{and} of the integer arguments.
1498 (logand) @result{} -1
1499 (logand 7) @result{} 7
1500 (logand #b111 #b011 #b001) @result{} 1
1504 @deffn {Scheme Procedure} logior n1 n2 @dots{}
1505 @deffnx {C Function} scm_logior (n1, n2)
1506 Return the bitwise @sc{or} of the integer arguments.
1509 (logior) @result{} 0
1510 (logior 7) @result{} 7
1511 (logior #b000 #b001 #b011) @result{} 3
1515 @deffn {Scheme Procedure} logxor n1 n2 @dots{}
1516 @deffnx {C Function} scm_loxor (n1, n2)
1517 Return the bitwise @sc{xor} of the integer arguments. A bit is
1518 set in the result if it is set in an odd number of arguments.
1521 (logxor) @result{} 0
1522 (logxor 7) @result{} 7
1523 (logxor #b000 #b001 #b011) @result{} 2
1524 (logxor #b000 #b001 #b011 #b011) @result{} 1
1528 @deffn {Scheme Procedure} lognot n
1529 @deffnx {C Function} scm_lognot (n)
1530 Return the integer which is the ones-complement of the integer
1531 argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
1534 (number->string (lognot #b10000000) 2)
1535 @result{} "-10000001"
1536 (number->string (lognot #b0) 2)
1541 @deffn {Scheme Procedure} logtest j k
1542 @deffnx {C Function} scm_logtest (j, k)
1543 Test whether @var{j} and @var{k} have any 1 bits in common. This is
1544 equivalent to @code{(not (zero? (logand j k)))}, but without actually
1545 calculating the @code{logand}, just testing for non-zero.
1548 (logtest #b0100 #b1011) @result{} #f
1549 (logtest #b0100 #b0111) @result{} #t
1553 @deffn {Scheme Procedure} logbit? index j
1554 @deffnx {C Function} scm_logbit_p (index, j)
1555 Test whether bit number @var{index} in @var{j} is set. @var{index}
1556 starts from 0 for the least significant bit.
1559 (logbit? 0 #b1101) @result{} #t
1560 (logbit? 1 #b1101) @result{} #f
1561 (logbit? 2 #b1101) @result{} #t
1562 (logbit? 3 #b1101) @result{} #t
1563 (logbit? 4 #b1101) @result{} #f
1567 @deffn {Scheme Procedure} ash n cnt
1568 @deffnx {C Function} scm_ash (n, cnt)
1569 Return @var{n} shifted left by @var{cnt} bits, or shifted right if
1570 @var{cnt} is negative. This is an ``arithmetic'' shift.
1572 This is effectively a multiplication by @m{2^{cnt}, 2^@var{cnt}}, and
1573 when @var{cnt} is negative it's a division, rounded towards negative
1574 infinity. (Note that this is not the same rounding as @code{quotient}
1577 With @var{n} viewed as an infinite precision twos complement,
1578 @code{ash} means a left shift introducing zero bits, or a right shift
1582 (number->string (ash #b1 3) 2) @result{} "1000"
1583 (number->string (ash #b1010 -1) 2) @result{} "101"
1585 ;; -23 is bits ...11101001, -6 is bits ...111010
1586 (ash -23 -2) @result{} -6
1590 @deffn {Scheme Procedure} logcount n
1591 @deffnx {C Function} scm_logcount (n)
1592 Return the number of bits in integer @var{n}. If @var{n} is
1593 positive, the 1-bits in its binary representation are counted.
1594 If negative, the 0-bits in its two's-complement binary
1595 representation are counted. If zero, 0 is returned.
1598 (logcount #b10101010)
1607 @deffn {Scheme Procedure} integer-length n
1608 @deffnx {C Function} scm_integer_length (n)
1609 Return the number of bits necessary to represent @var{n}.
1611 For positive @var{n} this is how many bits to the most significant one
1612 bit. For negative @var{n} it's how many bits to the most significant
1613 zero bit in twos complement form.
1616 (integer-length #b10101010) @result{} 8
1617 (integer-length #b1111) @result{} 4
1618 (integer-length 0) @result{} 0
1619 (integer-length -1) @result{} 0
1620 (integer-length -256) @result{} 8
1621 (integer-length -257) @result{} 9
1625 @deffn {Scheme Procedure} integer-expt n k
1626 @deffnx {C Function} scm_integer_expt (n, k)
1627 Return @var{n} raised to the power @var{k}. @var{k} must be an exact
1628 integer, @var{n} can be any number.
1630 Negative @var{k} is supported, and results in @m{1/n^|k|, 1/n^abs(k)}
1631 in the usual way. @math{@var{n}^0} is 1, as usual, and that includes
1635 (integer-expt 2 5) @result{} 32
1636 (integer-expt -3 3) @result{} -27
1637 (integer-expt 5 -3) @result{} 1/125
1638 (integer-expt 0 0) @result{} 1
1642 @deffn {Scheme Procedure} bit-extract n start end
1643 @deffnx {C Function} scm_bit_extract (n, start, end)
1644 Return the integer composed of the @var{start} (inclusive)
1645 through @var{end} (exclusive) bits of @var{n}. The
1646 @var{start}th bit becomes the 0-th bit in the result.
1649 (number->string (bit-extract #b1101101010 0 4) 2)
1651 (number->string (bit-extract #b1101101010 4 9) 2)
1658 @subsubsection Random Number Generation
1660 Pseudo-random numbers are generated from a random state object, which
1661 can be created with @code{seed->random-state}. The @var{state}
1662 parameter to the various functions below is optional, it defaults to
1663 the state object in the @code{*random-state*} variable.
1665 @deffn {Scheme Procedure} copy-random-state [state]
1666 @deffnx {C Function} scm_copy_random_state (state)
1667 Return a copy of the random state @var{state}.
1670 @deffn {Scheme Procedure} random n [state]
1671 @deffnx {C Function} scm_random (n, state)
1672 Return a number in [0, @var{n}).
1674 Accepts a positive integer or real n and returns a
1675 number of the same type between zero (inclusive) and
1676 @var{n} (exclusive). The values returned have a uniform
1680 @deffn {Scheme Procedure} random:exp [state]
1681 @deffnx {C Function} scm_random_exp (state)
1682 Return an inexact real in an exponential distribution with mean
1683 1. For an exponential distribution with mean @var{u} use @code{(*
1684 @var{u} (random:exp))}.
1687 @deffn {Scheme Procedure} random:hollow-sphere! vect [state]
1688 @deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
1689 Fills @var{vect} with inexact real random numbers the sum of whose
1690 squares is equal to 1.0. Thinking of @var{vect} as coordinates in
1691 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1692 the coordinates are uniformly distributed over the surface of the unit
1696 @deffn {Scheme Procedure} random:normal [state]
1697 @deffnx {C Function} scm_random_normal (state)
1698 Return an inexact real in a normal distribution. The distribution
1699 used has mean 0 and standard deviation 1. For a normal distribution
1700 with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
1701 (* @var{d} (random:normal)))}.
1704 @deffn {Scheme Procedure} random:normal-vector! vect [state]
1705 @deffnx {C Function} scm_random_normal_vector_x (vect, state)
1706 Fills @var{vect} with inexact real random numbers that are
1707 independent and standard normally distributed
1708 (i.e., with mean 0 and variance 1).
1711 @deffn {Scheme Procedure} random:solid-sphere! vect [state]
1712 @deffnx {C Function} scm_random_solid_sphere_x (vect, state)
1713 Fills @var{vect} with inexact real random numbers the sum of whose
1714 squares is less than 1.0. Thinking of @var{vect} as coordinates in
1715 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1716 the coordinates are uniformly distributed within the unit
1718 @c FIXME: What does this mean, particularly the n-sphere part?
1721 @deffn {Scheme Procedure} random:uniform [state]
1722 @deffnx {C Function} scm_random_uniform (state)
1723 Return a uniformly distributed inexact real random number in
1727 @deffn {Scheme Procedure} seed->random-state seed
1728 @deffnx {C Function} scm_seed_to_random_state (seed)
1729 Return a new random state using @var{seed}.
1732 @defvar *random-state*
1733 The global random state used by the above functions when the
1734 @var{state} parameter is not given.
1737 Note that the initial value of @code{*random-state*} is the same every
1738 time Guile starts up. Therefore, if you don't pass a @var{state}
1739 parameter to the above procedures, and you don't set
1740 @code{*random-state*} to @code{(seed->random-state your-seed)}, where
1741 @code{your-seed} is something that @emph{isn't} the same every time,
1742 you'll get the same sequence of ``random'' numbers on every run.
1744 For example, unless the relevant source code has changed, @code{(map
1745 random (cdr (iota 30)))}, if the first use of random numbers since
1746 Guile started up, will always give:
1749 (map random (cdr (iota 19)))
1751 (0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12)
1754 To use the time of day as the random seed, you can use code like this:
1757 (let ((time (gettimeofday)))
1758 (set! *random-state*
1759 (seed->random-state (+ (car time)
1764 And then (depending on the time of day, of course):
1767 (map random (cdr (iota 19)))
1769 (0 0 1 0 2 4 5 4 5 5 9 3 10 1 8 3 14 17)
1772 For security applications, such as password generation, you should use
1773 more bits of seed. Otherwise an open source password generator could
1774 be attacked by guessing the seed@dots{} but that's a subject for
1779 @subsection Characters
1782 In Scheme, there is a data type to describe a single character.
1784 Defining what exactly a character @emph{is} can be more complicated
1785 than it seems. Guile follows the advice of R6RS and uses The Unicode
1786 Standard to help define what a character is. So, for Guile, a
1787 character is anything in the Unicode Character Database.
1790 @cindex Unicode code point
1792 The Unicode Character Database is basically a table of characters
1793 indexed using integers called 'code points'. Valid code points are in
1794 the ranges 0 to @code{#xD7FF} inclusive or @code{#xE000} to
1795 @code{#x10FFFF} inclusive, which is about 1.1 million code points.
1797 @cindex designated code point
1798 @cindex code point, designated
1800 Any code point that has been assigned to a character or that has
1801 otherwise been given a meaning by Unicode is called a 'designated code
1802 point'. Most of the designated code points, about 200,000 of them,
1803 indicate characters, accents or other combining marks that modify
1804 other characters, symbols, whitespace, and control characters. Some
1805 are not characters but indicators that suggest how to format or
1806 display neighboring characters.
1808 @cindex reserved code point
1809 @cindex code point, reserved
1811 If a code point is not a designated code point -- if it has not been
1812 assigned to a character by The Unicode Standard -- it is a 'reserved
1813 code point', meaning that they are reserved for future use. Most of
1814 the code points, about 800,000, are 'reserved code points'.
1816 By convention, a Unicode code point is written as
1817 ``U+XXXX'' where ``XXXX'' is a hexadecimal number. Please note that
1818 this convenient notation is not valid code. Guile does not interpret
1819 ``U+XXXX'' as a character.
1821 In Scheme, a character literal is written as @code{#\@var{name}} where
1822 @var{name} is the name of the character that you want. Printable
1823 characters have their usual single character name; for example,
1824 @code{#\a} is a lower case @code{a}.
1826 Some of the code points are 'combining characters' that are not meant
1827 to be printed by themselves but are instead meant to modify the
1828 appearance of the previous character. For combining characters, an
1829 alternate form of the character literal is @code{#\} followed by
1830 U+25CC (a small, dotted circle), followed by the combining character.
1831 This allows the combining character to be drawn on the circle, not on
1832 the backslash of @code{#\}.
1834 Many of the non-printing characters, such as whitespace characters and
1835 control characters, also have names.
1837 The most commonly used non-printing characters are space and
1838 newline. Their character names are @code{#\space} and
1839 @code{#\newline}. There are also names for all of the ``C0 control
1840 characters'' (those with code points below 32). The following table
1841 describes the names for each character.
1843 @multitable @columnfractions .25 .25 .25 .25
1844 @item 0 = @code{#\nul}
1845 @tab 1 = @code{#\soh}
1846 @tab 2 = @code{#\stx}
1847 @tab 3 = @code{#\etx}
1848 @item 4 = @code{#\eot}
1849 @tab 5 = @code{#\enq}
1850 @tab 6 = @code{#\ack}
1851 @tab 7 = @code{#\bel}
1852 @item 8 = @code{#\bs}
1853 @tab 9 = @code{#\ht}
1854 @tab 10 = @code{#\lf}
1855 @tab 11 = @code{#\vt}
1856 @item 12 = @code{#\ff}
1857 @tab 13 = @code{#\cr}
1858 @tab 14 = @code{#\so}
1859 @tab 15 = @code{#\si}
1860 @item 16 = @code{#\dle}
1861 @tab 17 = @code{#\dc1}
1862 @tab 18 = @code{#\dc2}
1863 @tab 19 = @code{#\dc3}
1864 @item 20 = @code{#\dc4}
1865 @tab 21 = @code{#\nak}
1866 @tab 22 = @code{#\syn}
1867 @tab 23 = @code{#\etb}
1868 @item 24 = @code{#\can}
1869 @tab 25 = @code{#\em}
1870 @tab 26 = @code{#\sub}
1871 @tab 27 = @code{#\esc}
1872 @item 28 = @code{#\fs}
1873 @tab 29 = @code{#\gs}
1874 @tab 30 = @code{#\rs}
1875 @tab 31 = @code{#\us}
1876 @item 32 = @code{#\sp}
1879 The ``delete'' character (code point U+007F) may be referred to with the
1882 One might note that the space character has two names --
1883 @code{#\space} and @code{#\sp} -- as does the newline character.
1884 Several other non-printing characters have more than one name, for the
1885 sake of compatibility with previous versions.
1887 @multitable {@code{#\backspace}} {Preferred}
1888 @item Alternate @tab Standard
1889 @item @code{#\sp} @tab @code{#\space}
1890 @item @code{#\nl} @tab @code{#\newline}
1891 @item @code{#\lf} @tab @code{#\newline}
1892 @item @code{#\tab} @tab @code{#\ht}
1893 @item @code{#\backspace} @tab @code{#\bs}
1894 @item @code{#\return} @tab @code{#\cr}
1895 @item @code{#\page} @tab @code{#\ff}
1896 @item @code{#\np} @tab @code{#\ff}
1897 @item @code{#\null} @tab @code{#\nul}
1900 Characters may also be written using their code point values. They can
1901 be written with as an octal number, such as @code{#\10} for
1902 @code{#\bs} or @code{#\177} for @code{#\del}.
1905 @deffn {Scheme Procedure} char? x
1906 @deffnx {C Function} scm_char_p (x)
1907 Return @code{#t} iff @var{x} is a character, else @code{#f}.
1910 Fundamentally, the character comparison operations below are
1911 numeric comparisons of the character's code points.
1914 @deffn {Scheme Procedure} char=? x y
1915 Return @code{#t} iff code point of @var{x} is equal to the code point
1916 of @var{y}, else @code{#f}.
1920 @deffn {Scheme Procedure} char<? x y
1921 Return @code{#t} iff the code point of @var{x} is less than the code
1922 point of @var{y}, else @code{#f}.
1926 @deffn {Scheme Procedure} char<=? x y
1927 Return @code{#t} iff the code point of @var{x} is less than or equal
1928 to the code point of @var{y}, else @code{#f}.
1932 @deffn {Scheme Procedure} char>? x y
1933 Return @code{#t} iff the code point of @var{x} is greater than the
1934 code point of @var{y}, else @code{#f}.
1938 @deffn {Scheme Procedure} char>=? x y
1939 Return @code{#t} iff the code point of @var{x} is greater than or
1940 equal to the code point of @var{y}, else @code{#f}.
1943 @cindex case folding
1945 Case-insensitive character comparisons use @emph{Unicode case
1946 folding}. In case folding comparisons, if a character is lowercase
1947 and has an uppercase form that can be expressed as a single character,
1948 it is converted to uppercase before comparison. All other characters
1949 undergo no conversion before the comparison occurs. This includes the
1950 German sharp S (Eszett) which is not uppercased before conversion
1951 because its uppercase form has two characters. Unicode case folding
1952 is language independent: it uses rules that are generally true, but,
1953 it cannot cover all cases for all languages.
1956 @deffn {Scheme Procedure} char-ci=? x y
1957 Return @code{#t} iff the case-folded code point of @var{x} is the same
1958 as the case-folded code point of @var{y}, else @code{#f}.
1962 @deffn {Scheme Procedure} char-ci<? x y
1963 Return @code{#t} iff the case-folded code point of @var{x} is less
1964 than the case-folded code point of @var{y}, else @code{#f}.
1968 @deffn {Scheme Procedure} char-ci<=? x y
1969 Return @code{#t} iff the case-folded code point of @var{x} is less
1970 than or equal to the case-folded code point of @var{y}, else
1975 @deffn {Scheme Procedure} char-ci>? x y
1976 Return @code{#t} iff the case-folded code point of @var{x} is greater
1977 than the case-folded code point of @var{y}, else @code{#f}.
1981 @deffn {Scheme Procedure} char-ci>=? x y
1982 Return @code{#t} iff the case-folded code point of @var{x} is greater
1983 than or equal to the case-folded code point of @var{y}, else
1987 @rnindex char-alphabetic?
1988 @deffn {Scheme Procedure} char-alphabetic? chr
1989 @deffnx {C Function} scm_char_alphabetic_p (chr)
1990 Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
1993 @rnindex char-numeric?
1994 @deffn {Scheme Procedure} char-numeric? chr
1995 @deffnx {C Function} scm_char_numeric_p (chr)
1996 Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
1999 @rnindex char-whitespace?
2000 @deffn {Scheme Procedure} char-whitespace? chr
2001 @deffnx {C Function} scm_char_whitespace_p (chr)
2002 Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
2005 @rnindex char-upper-case?
2006 @deffn {Scheme Procedure} char-upper-case? chr
2007 @deffnx {C Function} scm_char_upper_case_p (chr)
2008 Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
2011 @rnindex char-lower-case?
2012 @deffn {Scheme Procedure} char-lower-case? chr
2013 @deffnx {C Function} scm_char_lower_case_p (chr)
2014 Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
2017 @deffn {Scheme Procedure} char-is-both? chr
2018 @deffnx {C Function} scm_char_is_both_p (chr)
2019 Return @code{#t} iff @var{chr} is either uppercase or lowercase, else
2023 @rnindex char->integer
2024 @deffn {Scheme Procedure} char->integer chr
2025 @deffnx {C Function} scm_char_to_integer (chr)
2026 Return the code point of @var{chr}.
2029 @rnindex integer->char
2030 @deffn {Scheme Procedure} integer->char n
2031 @deffnx {C Function} scm_integer_to_char (n)
2032 Return the character that has code point @var{n}. The integer @var{n}
2033 must be a valid code point. Valid code points are in the ranges 0 to
2034 @code{#xD7FF} inclusive or @code{#xE000} to @code{#x10FFFF} inclusive.
2037 @rnindex char-upcase
2038 @deffn {Scheme Procedure} char-upcase chr
2039 @deffnx {C Function} scm_char_upcase (chr)
2040 Return the uppercase character version of @var{chr}.
2043 @rnindex char-downcase
2044 @deffn {Scheme Procedure} char-downcase chr
2045 @deffnx {C Function} scm_char_downcase (chr)
2046 Return the lowercase character version of @var{chr}.
2049 @node Character Sets
2050 @subsection Character Sets
2052 The features described in this section correspond directly to SRFI-14.
2054 The data type @dfn{charset} implements sets of characters
2055 (@pxref{Characters}). Because the internal representation of
2056 character sets is not visible to the user, a lot of procedures for
2057 handling them are provided.
2059 Character sets can be created, extended, tested for the membership of a
2060 characters and be compared to other character sets.
2063 * Character Set Predicates/Comparison::
2064 * Iterating Over Character Sets:: Enumerate charset elements.
2065 * Creating Character Sets:: Making new charsets.
2066 * Querying Character Sets:: Test charsets for membership etc.
2067 * Character-Set Algebra:: Calculating new charsets.
2068 * Standard Character Sets:: Variables containing predefined charsets.
2071 @node Character Set Predicates/Comparison
2072 @subsubsection Character Set Predicates/Comparison
2074 Use these procedures for testing whether an object is a character set,
2075 or whether several character sets are equal or subsets of each other.
2076 @code{char-set-hash} can be used for calculating a hash value, maybe for
2077 usage in fast lookup procedures.
2079 @deffn {Scheme Procedure} char-set? obj
2080 @deffnx {C Function} scm_char_set_p (obj)
2081 Return @code{#t} if @var{obj} is a character set, @code{#f}
2085 @deffn {Scheme Procedure} char-set= . char_sets
2086 @deffnx {C Function} scm_char_set_eq (char_sets)
2087 Return @code{#t} if all given character sets are equal.
2090 @deffn {Scheme Procedure} char-set<= . char_sets
2091 @deffnx {C Function} scm_char_set_leq (char_sets)
2092 Return @code{#t} if every character set @var{cs}i is a subset
2093 of character set @var{cs}i+1.
2096 @deffn {Scheme Procedure} char-set-hash cs [bound]
2097 @deffnx {C Function} scm_char_set_hash (cs, bound)
2098 Compute a hash value for the character set @var{cs}. If
2099 @var{bound} is given and non-zero, it restricts the
2100 returned value to the range 0 @dots{} @var{bound - 1}.
2103 @c ===================================================================
2105 @node Iterating Over Character Sets
2106 @subsubsection Iterating Over Character Sets
2108 Character set cursors are a means for iterating over the members of a
2109 character sets. After creating a character set cursor with
2110 @code{char-set-cursor}, a cursor can be dereferenced with
2111 @code{char-set-ref}, advanced to the next member with
2112 @code{char-set-cursor-next}. Whether a cursor has passed past the last
2113 element of the set can be checked with @code{end-of-char-set?}.
2115 Additionally, mapping and (un-)folding procedures for character sets are
2118 @deffn {Scheme Procedure} char-set-cursor cs
2119 @deffnx {C Function} scm_char_set_cursor (cs)
2120 Return a cursor into the character set @var{cs}.
2123 @deffn {Scheme Procedure} char-set-ref cs cursor
2124 @deffnx {C Function} scm_char_set_ref (cs, cursor)
2125 Return the character at the current cursor position
2126 @var{cursor} in the character set @var{cs}. It is an error to
2127 pass a cursor for which @code{end-of-char-set?} returns true.
2130 @deffn {Scheme Procedure} char-set-cursor-next cs cursor
2131 @deffnx {C Function} scm_char_set_cursor_next (cs, cursor)
2132 Advance the character set cursor @var{cursor} to the next
2133 character in the character set @var{cs}. It is an error if the
2134 cursor given satisfies @code{end-of-char-set?}.
2137 @deffn {Scheme Procedure} end-of-char-set? cursor
2138 @deffnx {C Function} scm_end_of_char_set_p (cursor)
2139 Return @code{#t} if @var{cursor} has reached the end of a
2140 character set, @code{#f} otherwise.
2143 @deffn {Scheme Procedure} char-set-fold kons knil cs
2144 @deffnx {C Function} scm_char_set_fold (kons, knil, cs)
2145 Fold the procedure @var{kons} over the character set @var{cs},
2146 initializing it with @var{knil}.
2149 @deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
2150 @deffnx {C Function} scm_char_set_unfold (p, f, g, seed, base_cs)
2151 This is a fundamental constructor for character sets.
2153 @item @var{g} is used to generate a series of ``seed'' values
2154 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2155 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2156 @item @var{p} tells us when to stop -- when it returns true
2157 when applied to one of the seed values.
2158 @item @var{f} maps each seed value to a character. These
2159 characters are added to the base character set @var{base_cs} to
2160 form the result; @var{base_cs} defaults to the empty set.
2164 @deffn {Scheme Procedure} char-set-unfold! p f g seed base_cs
2165 @deffnx {C Function} scm_char_set_unfold_x (p, f, g, seed, base_cs)
2166 This is a fundamental constructor for character sets.
2168 @item @var{g} is used to generate a series of ``seed'' values
2169 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2170 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2171 @item @var{p} tells us when to stop -- when it returns true
2172 when applied to one of the seed values.
2173 @item @var{f} maps each seed value to a character. These
2174 characters are added to the base character set @var{base_cs} to
2175 form the result; @var{base_cs} defaults to the empty set.
2179 @deffn {Scheme Procedure} char-set-for-each proc cs
2180 @deffnx {C Function} scm_char_set_for_each (proc, cs)
2181 Apply @var{proc} to every character in the character set
2182 @var{cs}. The return value is not specified.
2185 @deffn {Scheme Procedure} char-set-map proc cs
2186 @deffnx {C Function} scm_char_set_map (proc, cs)
2187 Map the procedure @var{proc} over every character in @var{cs}.
2188 @var{proc} must be a character -> character procedure.
2191 @c ===================================================================
2193 @node Creating Character Sets
2194 @subsubsection Creating Character Sets
2196 New character sets are produced with these procedures.
2198 @deffn {Scheme Procedure} char-set-copy cs
2199 @deffnx {C Function} scm_char_set_copy (cs)
2200 Return a newly allocated character set containing all
2201 characters in @var{cs}.
2204 @deffn {Scheme Procedure} char-set . rest
2205 @deffnx {C Function} scm_char_set (rest)
2206 Return a character set containing all given characters.
2209 @deffn {Scheme Procedure} list->char-set list [base_cs]
2210 @deffnx {C Function} scm_list_to_char_set (list, base_cs)
2211 Convert the character list @var{list} to a character set. If
2212 the character set @var{base_cs} is given, the character in this
2213 set are also included in the result.
2216 @deffn {Scheme Procedure} list->char-set! list base_cs
2217 @deffnx {C Function} scm_list_to_char_set_x (list, base_cs)
2218 Convert the character list @var{list} to a character set. The
2219 characters are added to @var{base_cs} and @var{base_cs} is
2223 @deffn {Scheme Procedure} string->char-set str [base_cs]
2224 @deffnx {C Function} scm_string_to_char_set (str, base_cs)
2225 Convert the string @var{str} to a character set. If the
2226 character set @var{base_cs} is given, the characters in this
2227 set are also included in the result.
2230 @deffn {Scheme Procedure} string->char-set! str base_cs
2231 @deffnx {C Function} scm_string_to_char_set_x (str, base_cs)
2232 Convert the string @var{str} to a character set. The
2233 characters from the string are added to @var{base_cs}, and
2234 @var{base_cs} is returned.
2237 @deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
2238 @deffnx {C Function} scm_char_set_filter (pred, cs, base_cs)
2239 Return a character set containing every character from @var{cs}
2240 so that it satisfies @var{pred}. If provided, the characters
2241 from @var{base_cs} are added to the result.
2244 @deffn {Scheme Procedure} char-set-filter! pred cs base_cs
2245 @deffnx {C Function} scm_char_set_filter_x (pred, cs, base_cs)
2246 Return a character set containing every character from @var{cs}
2247 so that it satisfies @var{pred}. The characters are added to
2248 @var{base_cs} and @var{base_cs} is returned.
2251 @deffn {Scheme Procedure} ucs-range->char-set lower upper [error [base_cs]]
2252 @deffnx {C Function} scm_ucs_range_to_char_set (lower, upper, error, base_cs)
2253 Return a character set containing all characters whose
2254 character codes lie in the half-open range
2255 [@var{lower},@var{upper}).
2257 If @var{error} is a true value, an error is signalled if the
2258 specified range contains characters which are not contained in
2259 the implemented character range. If @var{error} is @code{#f},
2260 these characters are silently left out of the resulting
2263 The characters in @var{base_cs} are added to the result, if
2267 @deffn {Scheme Procedure} ucs-range->char-set! lower upper error base_cs
2268 @deffnx {C Function} scm_ucs_range_to_char_set_x (lower, upper, error, base_cs)
2269 Return a character set containing all characters whose
2270 character codes lie in the half-open range
2271 [@var{lower},@var{upper}).
2273 If @var{error} is a true value, an error is signalled if the
2274 specified range contains characters which are not contained in
2275 the implemented character range. If @var{error} is @code{#f},
2276 these characters are silently left out of the resulting
2279 The characters are added to @var{base_cs} and @var{base_cs} is
2283 @deffn {Scheme Procedure} ->char-set x
2284 @deffnx {C Function} scm_to_char_set (x)
2285 Coerces x into a char-set. @var{x} may be a string, character or
2286 char-set. A string is converted to the set of its constituent
2287 characters; a character is converted to a singleton set; a char-set is
2291 @c ===================================================================
2293 @node Querying Character Sets
2294 @subsubsection Querying Character Sets
2296 Access the elements and other information of a character set with these
2299 @deffn {Scheme Procedure} %char-set-dump cs
2300 Returns an association list containing debugging information
2301 for @var{cs}. The association list has the following entries.
2306 The number of groups of contiguous code points the char-set
2309 A list of lists where each sublist is a range of code points
2310 and their associated characters
2312 The return value of this function cannot be relied upon to be
2313 consistent between versions of Guile and should not be used in code.
2316 @deffn {Scheme Procedure} char-set-size cs
2317 @deffnx {C Function} scm_char_set_size (cs)
2318 Return the number of elements in character set @var{cs}.
2321 @deffn {Scheme Procedure} char-set-count pred cs
2322 @deffnx {C Function} scm_char_set_count (pred, cs)
2323 Return the number of the elements int the character set
2324 @var{cs} which satisfy the predicate @var{pred}.
2327 @deffn {Scheme Procedure} char-set->list cs
2328 @deffnx {C Function} scm_char_set_to_list (cs)
2329 Return a list containing the elements of the character set
2333 @deffn {Scheme Procedure} char-set->string cs
2334 @deffnx {C Function} scm_char_set_to_string (cs)
2335 Return a string containing the elements of the character set
2336 @var{cs}. The order in which the characters are placed in the
2337 string is not defined.
2340 @deffn {Scheme Procedure} char-set-contains? cs ch
2341 @deffnx {C Function} scm_char_set_contains_p (cs, ch)
2342 Return @code{#t} iff the character @var{ch} is contained in the
2343 character set @var{cs}.
2346 @deffn {Scheme Procedure} char-set-every pred cs
2347 @deffnx {C Function} scm_char_set_every (pred, cs)
2348 Return a true value if every character in the character set
2349 @var{cs} satisfies the predicate @var{pred}.
2352 @deffn {Scheme Procedure} char-set-any pred cs
2353 @deffnx {C Function} scm_char_set_any (pred, cs)
2354 Return a true value if any character in the character set
2355 @var{cs} satisfies the predicate @var{pred}.
2358 @c ===================================================================
2360 @node Character-Set Algebra
2361 @subsubsection Character-Set Algebra
2363 Character sets can be manipulated with the common set algebra operation,
2364 such as union, complement, intersection etc. All of these procedures
2365 provide side-effecting variants, which modify their character set
2368 @deffn {Scheme Procedure} char-set-adjoin cs . rest
2369 @deffnx {C Function} scm_char_set_adjoin (cs, rest)
2370 Add all character arguments to the first argument, which must
2374 @deffn {Scheme Procedure} char-set-delete cs . rest
2375 @deffnx {C Function} scm_char_set_delete (cs, rest)
2376 Delete all character arguments from the first argument, which
2377 must be a character set.
2380 @deffn {Scheme Procedure} char-set-adjoin! cs . rest
2381 @deffnx {C Function} scm_char_set_adjoin_x (cs, rest)
2382 Add all character arguments to the first argument, which must
2386 @deffn {Scheme Procedure} char-set-delete! cs . rest
2387 @deffnx {C Function} scm_char_set_delete_x (cs, rest)
2388 Delete all character arguments from the first argument, which
2389 must be a character set.
2392 @deffn {Scheme Procedure} char-set-complement cs
2393 @deffnx {C Function} scm_char_set_complement (cs)
2394 Return the complement of the character set @var{cs}.
2397 Note that the complement of a character set is likely to contain many
2398 reserved code points (code points that are not associated with
2399 characters). It may be helpful to modify the output of
2400 @code{char-set-complement} by computing its intersection with the set
2401 of designated code points, @code{char-set:designated}.
2403 @deffn {Scheme Procedure} char-set-union . rest
2404 @deffnx {C Function} scm_char_set_union (rest)
2405 Return the union of all argument character sets.
2408 @deffn {Scheme Procedure} char-set-intersection . rest
2409 @deffnx {C Function} scm_char_set_intersection (rest)
2410 Return the intersection of all argument character sets.
2413 @deffn {Scheme Procedure} char-set-difference cs1 . rest
2414 @deffnx {C Function} scm_char_set_difference (cs1, rest)
2415 Return the difference of all argument character sets.
2418 @deffn {Scheme Procedure} char-set-xor . rest
2419 @deffnx {C Function} scm_char_set_xor (rest)
2420 Return the exclusive-or of all argument character sets.
2423 @deffn {Scheme Procedure} char-set-diff+intersection cs1 . rest
2424 @deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, rest)
2425 Return the difference and the intersection of all argument
2429 @deffn {Scheme Procedure} char-set-complement! cs
2430 @deffnx {C Function} scm_char_set_complement_x (cs)
2431 Return the complement of the character set @var{cs}.
2434 @deffn {Scheme Procedure} char-set-union! cs1 . rest
2435 @deffnx {C Function} scm_char_set_union_x (cs1, rest)
2436 Return the union of all argument character sets.
2439 @deffn {Scheme Procedure} char-set-intersection! cs1 . rest
2440 @deffnx {C Function} scm_char_set_intersection_x (cs1, rest)
2441 Return the intersection of all argument character sets.
2444 @deffn {Scheme Procedure} char-set-difference! cs1 . rest
2445 @deffnx {C Function} scm_char_set_difference_x (cs1, rest)
2446 Return the difference of all argument character sets.
2449 @deffn {Scheme Procedure} char-set-xor! cs1 . rest
2450 @deffnx {C Function} scm_char_set_xor_x (cs1, rest)
2451 Return the exclusive-or of all argument character sets.
2454 @deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 . rest
2455 @deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, rest)
2456 Return the difference and the intersection of all argument
2460 @c ===================================================================
2462 @node Standard Character Sets
2463 @subsubsection Standard Character Sets
2465 In order to make the use of the character set data type and procedures
2466 useful, several predefined character set variables exist.
2472 These character sets are locale independent and are not recomputed
2473 upon a @code{setlocale} call. They contain characters from the whole
2474 range of Unicode code points. For instance, @code{char-set:letter}
2475 contains about 94,000 characters.
2477 @defvr {Scheme Variable} char-set:lower-case
2478 @defvrx {C Variable} scm_char_set_lower_case
2479 All lower-case characters.
2482 @defvr {Scheme Variable} char-set:upper-case
2483 @defvrx {C Variable} scm_char_set_upper_case
2484 All upper-case characters.
2487 @defvr {Scheme Variable} char-set:title-case
2488 @defvrx {C Variable} scm_char_set_title_case
2489 All single characters that function as if they were an upper-case
2490 letter followed by a lower-case letter.
2493 @defvr {Scheme Variable} char-set:letter
2494 @defvrx {C Variable} scm_char_set_letter
2495 All letters. This includes @code{char-set:lower-case},
2496 @code{char-set:upper-case}, @code{char-set:title-case}, and many
2497 letters that have no case at all. For example, Chinese and Japanese
2498 characters typically have no concept of case.
2501 @defvr {Scheme Variable} char-set:digit
2502 @defvrx {C Variable} scm_char_set_digit
2506 @defvr {Scheme Variable} char-set:letter+digit
2507 @defvrx {C Variable} scm_char_set_letter_and_digit
2508 The union of @code{char-set:letter} and @code{char-set:digit}.
2511 @defvr {Scheme Variable} char-set:graphic
2512 @defvrx {C Variable} scm_char_set_graphic
2513 All characters which would put ink on the paper.
2516 @defvr {Scheme Variable} char-set:printing
2517 @defvrx {C Variable} scm_char_set_printing
2518 The union of @code{char-set:graphic} and @code{char-set:whitespace}.
2521 @defvr {Scheme Variable} char-set:whitespace
2522 @defvrx {C Variable} scm_char_set_whitespace
2523 All whitespace characters.
2526 @defvr {Scheme Variable} char-set:blank
2527 @defvrx {C Variable} scm_char_set_blank
2528 All horizontal whitespace characters, which notably includes
2529 @code{#\space} and @code{#\tab}.
2532 @defvr {Scheme Variable} char-set:iso-control
2533 @defvrx {C Variable} scm_char_set_iso_control
2534 The ISO control characters are the C0 control characters (U+0000 to
2535 U+001F), delete (U+007F), and the C1 control characters (U+0080 to
2539 @defvr {Scheme Variable} char-set:punctuation
2540 @defvrx {C Variable} scm_char_set_punctuation
2541 All punctuation characters, such as the characters
2542 @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
2545 @defvr {Scheme Variable} char-set:symbol
2546 @defvrx {C Variable} scm_char_set_symbol
2547 All symbol characters, such as the characters @code{$+<=>^`|~}.
2550 @defvr {Scheme Variable} char-set:hex-digit
2551 @defvrx {C Variable} scm_char_set_hex_digit
2552 The hexadecimal digits @code{0123456789abcdefABCDEF}.
2555 @defvr {Scheme Variable} char-set:ascii
2556 @defvrx {C Variable} scm_char_set_ascii
2557 All ASCII characters.
2560 @defvr {Scheme Variable} char-set:empty
2561 @defvrx {C Variable} scm_char_set_empty
2562 The empty character set.
2565 @defvr {Scheme Variable} char-set:designated
2566 @defvrx {C Variable} scm_char_set_designated
2567 This character set contains all designated code points. This includes
2568 all the code points to which Unicode has assigned a character or other
2572 @defvr {Scheme Variable} char-set:full
2573 @defvrx {C Variable} scm_char_set_full
2574 This character set contains all possible code points. This includes
2575 both designated and reserved code points.
2582 Strings are fixed-length sequences of characters. They can be created
2583 by calling constructor procedures, but they can also literally get
2584 entered at the @acronym{REPL} or in Scheme source files.
2586 @c Guile provides a rich set of string processing procedures, because text
2587 @c handling is very important when Guile is used as a scripting language.
2589 Strings always carry the information about how many characters they are
2590 composed of with them, so there is no special end-of-string character,
2591 like in C. That means that Scheme strings can contain any character,
2592 even the @samp{#\nul} character @samp{\0}.
2594 To use strings efficiently, you need to know a bit about how Guile
2595 implements them. In Guile, a string consists of two parts, a head and
2596 the actual memory where the characters are stored. When a string (or
2597 a substring of it) is copied, only a new head gets created, the memory
2598 is usually not copied. The two heads start out pointing to the same
2601 When one of these two strings is modified, as with @code{string-set!},
2602 their common memory does get copied so that each string has its own
2603 memory and modifying one does not accidentally modify the other as well.
2604 Thus, Guile's strings are `copy on write'; the actual copying of their
2605 memory is delayed until one string is written to.
2607 This implementation makes functions like @code{substring} very
2608 efficient in the common case that no modifications are done to the
2611 If you do know that your strings are getting modified right away, you
2612 can use @code{substring/copy} instead of @code{substring}. This
2613 function performs the copy immediately at the time of creation. This
2614 is more efficient, especially in a multi-threaded program. Also,
2615 @code{substring/copy} can avoid the problem that a short substring
2616 holds on to the memory of a very large original string that could
2617 otherwise be recycled.
2619 If you want to avoid the copy altogether, so that modifications of one
2620 string show up in the other, you can use @code{substring/shared}. The
2621 strings created by this procedure are called @dfn{mutation sharing
2622 substrings} since the substring and the original string share
2623 modifications to each other.
2625 If you want to prevent modifications, use @code{substring/read-only}.
2627 Guile provides all procedures of SRFI-13 and a few more.
2630 * String Syntax:: Read syntax for strings.
2631 * String Predicates:: Testing strings for certain properties.
2632 * String Constructors:: Creating new string objects.
2633 * List/String Conversion:: Converting from/to lists of characters.
2634 * String Selection:: Select portions from strings.
2635 * String Modification:: Modify parts or whole strings.
2636 * String Comparison:: Lexicographic ordering predicates.
2637 * String Searching:: Searching in strings.
2638 * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
2639 * Reversing and Appending Strings:: Appending strings to form a new string.
2640 * Mapping Folding and Unfolding:: Iterating over strings.
2641 * Miscellaneous String Operations:: Replicating, insertion, parsing, ...
2642 * Conversion to/from C::
2646 @subsubsection String Read Syntax
2648 @c In the following @code is used to get a good font in TeX etc, but
2649 @c is omitted for Info format, so as not to risk any confusion over
2650 @c whether surrounding ` ' quotes are part of the escape or are
2651 @c special in a string (they're not).
2653 The read syntax for strings is an arbitrarily long sequence of
2654 characters enclosed in double quotes (@nicode{"}).
2656 Backslash is an escape character and can be used to insert the
2657 following special characters. @nicode{\"} and @nicode{\\} are R5RS
2658 standard, the rest are Guile extensions, notice they follow C string
2663 Backslash character.
2666 Double quote character (an unescaped @nicode{"} is otherwise the end
2670 NUL character (ASCII 0).
2673 Bell character (ASCII 7).
2676 Formfeed character (ASCII 12).
2679 Newline character (ASCII 10).
2682 Carriage return character (ASCII 13).
2685 Tab character (ASCII 9).
2688 Vertical tab character (ASCII 11).
2691 Character code given by two hexadecimal digits. For example
2692 @nicode{\x7f} for an ASCII DEL (127).
2696 The following are examples of string literals:
2706 @node String Predicates
2707 @subsubsection String Predicates
2709 The following procedures can be used to check whether a given string
2710 fulfills some specified property.
2713 @deffn {Scheme Procedure} string? obj
2714 @deffnx {C Function} scm_string_p (obj)
2715 Return @code{#t} if @var{obj} is a string, else @code{#f}.
2718 @deftypefn {C Function} int scm_is_string (SCM obj)
2719 Returns @code{1} if @var{obj} is a string, @code{0} otherwise.
2722 @deffn {Scheme Procedure} string-null? str
2723 @deffnx {C Function} scm_string_null_p (str)
2724 Return @code{#t} if @var{str}'s length is zero, and
2725 @code{#f} otherwise.
2727 (string-null? "") @result{} #t
2729 (string-null? y) @result{} #f
2733 @deffn {Scheme Procedure} string-any char_pred s [start [end]]
2734 @deffnx {C Function} scm_string_any (char_pred, s, start, end)
2735 Check if @var{char_pred} is true for any character in string @var{s}.
2737 @var{char_pred} can be a character to check for any equal to that, or
2738 a character set (@pxref{Character Sets}) to check for any in that set,
2739 or a predicate procedure to call.
2741 For a procedure, calls @code{(@var{char_pred} c)} are made
2742 successively on the characters from @var{start} to @var{end}. If
2743 @var{char_pred} returns true (ie.@: non-@code{#f}), @code{string-any}
2744 stops and that return value is the return from @code{string-any}. The
2745 call on the last character (ie.@: at @math{@var{end}-1}), if that
2746 point is reached, is a tail call.
2748 If there are no characters in @var{s} (ie.@: @var{start} equals
2749 @var{end}) then the return is @code{#f}.
2752 @deffn {Scheme Procedure} string-every char_pred s [start [end]]
2753 @deffnx {C Function} scm_string_every (char_pred, s, start, end)
2754 Check if @var{char_pred} is true for every character in string
2757 @var{char_pred} can be a character to check for every character equal
2758 to that, or a character set (@pxref{Character Sets}) to check for
2759 every character being in that set, or a predicate procedure to call.
2761 For a procedure, calls @code{(@var{char_pred} c)} are made
2762 successively on the characters from @var{start} to @var{end}. If
2763 @var{char_pred} returns @code{#f}, @code{string-every} stops and
2764 returns @code{#f}. The call on the last character (ie.@: at
2765 @math{@var{end}-1}), if that point is reached, is a tail call and the
2766 return from that call is the return from @code{string-every}.
2768 If there are no characters in @var{s} (ie.@: @var{start} equals
2769 @var{end}) then the return is @code{#t}.
2772 @node String Constructors
2773 @subsubsection String Constructors
2775 The string constructor procedures create new string objects, possibly
2776 initializing them with some specified character data. See also
2777 @xref{String Selection}, for ways to create strings from existing
2780 @c FIXME::martin: list->string belongs into `List/String Conversion'
2782 @deffn {Scheme Procedure} string char@dots{}
2784 Return a newly allocated string made from the given character
2788 (string #\x #\y #\z) @result{} "xyz"
2789 (string) @result{} ""
2793 @deffn {Scheme Procedure} list->string lst
2794 @deffnx {C Function} scm_string (lst)
2795 @rnindex list->string
2796 Return a newly allocated string made from a list of characters.
2799 (list->string '(#\a #\b #\c)) @result{} "abc"
2803 @deffn {Scheme Procedure} reverse-list->string lst
2804 @deffnx {C Function} scm_reverse_list_to_string (lst)
2805 Return a newly allocated string made from a list of characters, in
2809 (reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
2813 @rnindex make-string
2814 @deffn {Scheme Procedure} make-string k [chr]
2815 @deffnx {C Function} scm_make_string (k, chr)
2816 Return a newly allocated string of
2817 length @var{k}. If @var{chr} is given, then all elements of
2818 the string are initialized to @var{chr}, otherwise the contents
2819 of the @var{string} are unspecified.
2822 @deftypefn {C Function} SCM scm_c_make_string (size_t len, SCM chr)
2823 Like @code{scm_make_string}, but expects the length as a
2827 @deffn {Scheme Procedure} string-tabulate proc len
2828 @deffnx {C Function} scm_string_tabulate (proc, len)
2829 @var{proc} is an integer->char procedure. Construct a string
2830 of size @var{len} by applying @var{proc} to each index to
2831 produce the corresponding string element. The order in which
2832 @var{proc} is applied to the indices is not specified.
2835 @deffn {Scheme Procedure} string-join ls [delimiter [grammar]]
2836 @deffnx {C Function} scm_string_join (ls, delimiter, grammar)
2837 Append the string in the string list @var{ls}, using the string
2838 @var{delim} as a delimiter between the elements of @var{ls}.
2839 @var{grammar} is a symbol which specifies how the delimiter is
2840 placed between the strings, and defaults to the symbol
2845 Insert the separator between list elements. An empty string
2846 will produce an empty list.
2848 Like @code{infix}, but will raise an error if given the empty
2851 Insert the separator after every list element.
2853 Insert the separator before each list element.
2857 @node List/String Conversion
2858 @subsubsection List/String conversion
2860 When processing strings, it is often convenient to first convert them
2861 into a list representation by using the procedure @code{string->list},
2862 work with the resulting list, and then convert it back into a string.
2863 These procedures are useful for similar tasks.
2865 @rnindex string->list
2866 @deffn {Scheme Procedure} string->list str [start [end]]
2867 @deffnx {C Function} scm_substring_to_list (str, start, end)
2868 @deffnx {C Function} scm_string_to_list (str)
2869 Convert the string @var{str} into a list of characters.
2872 @deffn {Scheme Procedure} string-split str chr
2873 @deffnx {C Function} scm_string_split (str, chr)
2874 Split the string @var{str} into the a list of the substrings delimited
2875 by appearances of the character @var{chr}. Note that an empty substring
2876 between separator characters will result in an empty string in the
2880 (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
2882 ("root" "x" "0" "0" "root" "/root" "/bin/bash")
2884 (string-split "::" #\:)
2888 (string-split "" #\:)
2895 @node String Selection
2896 @subsubsection String Selection
2898 Portions of strings can be extracted by these procedures.
2899 @code{string-ref} delivers individual characters whereas
2900 @code{substring} can be used to extract substrings from longer strings.
2902 @rnindex string-length
2903 @deffn {Scheme Procedure} string-length string
2904 @deffnx {C Function} scm_string_length (string)
2905 Return the number of characters in @var{string}.
2908 @deftypefn {C Function} size_t scm_c_string_length (SCM str)
2909 Return the number of characters in @var{str} as a @code{size_t}.
2913 @deffn {Scheme Procedure} string-ref str k
2914 @deffnx {C Function} scm_string_ref (str, k)
2915 Return character @var{k} of @var{str} using zero-origin
2916 indexing. @var{k} must be a valid index of @var{str}.
2919 @deftypefn {C Function} SCM scm_c_string_ref (SCM str, size_t k)
2920 Return character @var{k} of @var{str} using zero-origin
2921 indexing. @var{k} must be a valid index of @var{str}.
2924 @rnindex string-copy
2925 @deffn {Scheme Procedure} string-copy str [start [end]]
2926 @deffnx {C Function} scm_substring_copy (str, start, end)
2927 @deffnx {C Function} scm_string_copy (str)
2928 Return a copy of the given string @var{str}.
2930 The returned string shares storage with @var{str} initially, but it is
2931 copied as soon as one of the two strings is modified.
2935 @deffn {Scheme Procedure} substring str start [end]
2936 @deffnx {C Function} scm_substring (str, start, end)
2937 Return a new string formed from the characters
2938 of @var{str} beginning with index @var{start} (inclusive) and
2939 ending with index @var{end} (exclusive).
2940 @var{str} must be a string, @var{start} and @var{end} must be
2941 exact integers satisfying:
2943 0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
2945 The returned string shares storage with @var{str} initially, but it is
2946 copied as soon as one of the two strings is modified.
2949 @deffn {Scheme Procedure} substring/shared str start [end]
2950 @deffnx {C Function} scm_substring_shared (str, start, end)
2951 Like @code{substring}, but the strings continue to share their storage
2952 even if they are modified. Thus, modifications to @var{str} show up
2953 in the new string, and vice versa.
2956 @deffn {Scheme Procedure} substring/copy str start [end]
2957 @deffnx {C Function} scm_substring_copy (str, start, end)
2958 Like @code{substring}, but the storage for the new string is copied
2962 @deffn {Scheme Procedure} substring/read-only str start [end]
2963 @deffnx {C Function} scm_substring_read_only (str, start, end)
2964 Like @code{substring}, but the resulting string can not be modified.
2967 @deftypefn {C Function} SCM scm_c_substring (SCM str, size_t start, size_t end)
2968 @deftypefnx {C Function} SCM scm_c_substring_shared (SCM str, size_t start, size_t end)
2969 @deftypefnx {C Function} SCM scm_c_substring_copy (SCM str, size_t start, size_t end)
2970 @deftypefnx {C Function} SCM scm_c_substring_read_only (SCM str, size_t start, size_t end)
2971 Like @code{scm_substring}, etc. but the bounds are given as a @code{size_t}.
2974 @deffn {Scheme Procedure} string-take s n
2975 @deffnx {C Function} scm_string_take (s, n)
2976 Return the @var{n} first characters of @var{s}.
2979 @deffn {Scheme Procedure} string-drop s n
2980 @deffnx {C Function} scm_string_drop (s, n)
2981 Return all but the first @var{n} characters of @var{s}.
2984 @deffn {Scheme Procedure} string-take-right s n
2985 @deffnx {C Function} scm_string_take_right (s, n)
2986 Return the @var{n} last characters of @var{s}.
2989 @deffn {Scheme Procedure} string-drop-right s n
2990 @deffnx {C Function} scm_string_drop_right (s, n)
2991 Return all but the last @var{n} characters of @var{s}.
2994 @deffn {Scheme Procedure} string-pad s len [chr [start [end]]]
2995 @deffnx {Scheme Procedure} string-pad-right s len [chr [start [end]]]
2996 @deffnx {C Function} scm_string_pad (s, len, chr, start, end)
2997 @deffnx {C Function} scm_string_pad_right (s, len, chr, start, end)
2998 Take characters @var{start} to @var{end} from the string @var{s} and
2999 either pad with @var{char} or truncate them to give @var{len}
3002 @code{string-pad} pads or truncates on the left, so for example
3005 (string-pad "x" 3) @result{} " x"
3006 (string-pad "abcde" 3) @result{} "cde"
3009 @code{string-pad-right} pads or truncates on the right, so for example
3012 (string-pad-right "x" 3) @result{} "x "
3013 (string-pad-right "abcde" 3) @result{} "abc"
3017 @deffn {Scheme Procedure} string-trim s [char_pred [start [end]]]
3018 @deffnx {Scheme Procedure} string-trim-right s [char_pred [start [end]]]
3019 @deffnx {Scheme Procedure} string-trim-both s [char_pred [start [end]]]
3020 @deffnx {C Function} scm_string_trim (s, char_pred, start, end)
3021 @deffnx {C Function} scm_string_trim_right (s, char_pred, start, end)
3022 @deffnx {C Function} scm_string_trim_both (s, char_pred, start, end)
3023 Trim occurrences of @var{char_pred} from the ends of @var{s}.
3025 @code{string-trim} trims @var{char_pred} characters from the left
3026 (start) of the string, @code{string-trim-right} trims them from the
3027 right (end) of the string, @code{string-trim-both} trims from both
3030 @var{char_pred} can be a character, a character set, or a predicate
3031 procedure to call on each character. If @var{char_pred} is not given
3032 the default is whitespace as per @code{char-set:whitespace}
3033 (@pxref{Standard Character Sets}).
3036 (string-trim " x ") @result{} "x "
3037 (string-trim-right "banana" #\a) @result{} "banan"
3038 (string-trim-both ".,xy:;" char-set:punctuation)
3040 (string-trim-both "xyzzy" (lambda (c)
3047 @node String Modification
3048 @subsubsection String Modification
3050 These procedures are for modifying strings in-place. This means that the
3051 result of the operation is not a new string; instead, the original string's
3052 memory representation is modified.
3054 @rnindex string-set!
3055 @deffn {Scheme Procedure} string-set! str k chr
3056 @deffnx {C Function} scm_string_set_x (str, k, chr)
3057 Store @var{chr} in element @var{k} of @var{str} and return
3058 an unspecified value. @var{k} must be a valid index of
3062 @deftypefn {C Function} void scm_c_string_set_x (SCM str, size_t k, SCM chr)
3063 Like @code{scm_string_set_x}, but the index is given as a @code{size_t}.
3066 @rnindex string-fill!
3067 @deffn {Scheme Procedure} string-fill! str chr [start [end]]
3068 @deffnx {C Function} scm_substring_fill_x (str, chr, start, end)
3069 @deffnx {C Function} scm_string_fill_x (str, chr)
3070 Stores @var{chr} in every element of the given @var{str} and
3071 returns an unspecified value.
3074 @deffn {Scheme Procedure} substring-fill! str start end fill
3075 @deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
3076 Change every character in @var{str} between @var{start} and
3077 @var{end} to @var{fill}.
3080 (define y "abcdefg")
3081 (substring-fill! y 1 3 #\r)
3087 @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
3088 @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
3089 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
3090 into @var{str2} beginning at position @var{start2}.
3091 @var{str1} and @var{str2} can be the same string.
3094 @deffn {Scheme Procedure} string-copy! target tstart s [start [end]]
3095 @deffnx {C Function} scm_string_copy_x (target, tstart, s, start, end)
3096 Copy the sequence of characters from index range [@var{start},
3097 @var{end}) in string @var{s} to string @var{target}, beginning
3098 at index @var{tstart}. The characters are copied left-to-right
3099 or right-to-left as needed -- the copy is guaranteed to work,
3100 even if @var{target} and @var{s} are the same string. It is an
3101 error if the copy operation runs off the end of the target
3106 @node String Comparison
3107 @subsubsection String Comparison
3109 The procedures in this section are similar to the character ordering
3110 predicates (@pxref{Characters}), but are defined on character sequences.
3112 The first set is specified in R5RS and has names that end in @code{?}.
3113 The second set is specified in SRFI-13 and the names have no ending
3114 @code{?}. The predicates ending in @code{-ci} ignore the character case
3115 when comparing strings. @xref{Text Collation, the @code{(ice-9
3116 i18n)} module}, for locale-dependent string comparison.
3119 @deffn {Scheme Procedure} string=? s1 s2
3120 Lexicographic equality predicate; return @code{#t} if the two
3121 strings are the same length and contain the same characters in
3122 the same positions, otherwise return @code{#f}.
3124 The procedure @code{string-ci=?} treats upper and lower case
3125 letters as though they were the same character, but
3126 @code{string=?} treats upper and lower case as distinct
3131 @deffn {Scheme Procedure} string<? s1 s2
3132 Lexicographic ordering predicate; return @code{#t} if @var{s1}
3133 is lexicographically less than @var{s2}.
3137 @deffn {Scheme Procedure} string<=? s1 s2
3138 Lexicographic ordering predicate; return @code{#t} if @var{s1}
3139 is lexicographically less than or equal to @var{s2}.
3143 @deffn {Scheme Procedure} string>? s1 s2
3144 Lexicographic ordering predicate; return @code{#t} if @var{s1}
3145 is lexicographically greater than @var{s2}.
3149 @deffn {Scheme Procedure} string>=? s1 s2
3150 Lexicographic ordering predicate; return @code{#t} if @var{s1}
3151 is lexicographically greater than or equal to @var{s2}.
3154 @rnindex string-ci=?
3155 @deffn {Scheme Procedure} string-ci=? s1 s2
3156 Case-insensitive string equality predicate; return @code{#t} if
3157 the two strings are the same length and their component
3158 characters match (ignoring case) at each position; otherwise
3162 @rnindex string-ci<?
3163 @deffn {Scheme Procedure} string-ci<? s1 s2
3164 Case insensitive lexicographic ordering predicate; return
3165 @code{#t} if @var{s1} is lexicographically less than @var{s2}
3170 @deffn {Scheme Procedure} string-ci<=? s1 s2
3171 Case insensitive lexicographic ordering predicate; return
3172 @code{#t} if @var{s1} is lexicographically less than or equal
3173 to @var{s2} regardless of case.
3176 @rnindex string-ci>?
3177 @deffn {Scheme Procedure} string-ci>? s1 s2
3178 Case insensitive lexicographic ordering predicate; return
3179 @code{#t} if @var{s1} is lexicographically greater than
3180 @var{s2} regardless of case.
3183 @rnindex string-ci>=?
3184 @deffn {Scheme Procedure} string-ci>=? s1 s2
3185 Case insensitive lexicographic ordering predicate; return
3186 @code{#t} if @var{s1} is lexicographically greater than or
3187 equal to @var{s2} regardless of case.
3190 @deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3191 @deffnx {C Function} scm_string_compare (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3192 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3193 mismatch index, depending upon whether @var{s1} is less than,
3194 equal to, or greater than @var{s2}. The mismatch index is the
3195 largest index @var{i} such that for every 0 <= @var{j} <
3196 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3197 @var{i} is the first position that does not match.
3200 @deffn {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3201 @deffnx {C Function} scm_string_compare_ci (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3202 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3203 mismatch index, depending upon whether @var{s1} is less than,
3204 equal to, or greater than @var{s2}. The mismatch index is the
3205 largest index @var{i} such that for every 0 <= @var{j} <
3206 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3207 @var{i} is the first position that does not match. The
3208 character comparison is done case-insensitively.
3211 @deffn {Scheme Procedure} string= s1 s2 [start1 [end1 [start2 [end2]]]]
3212 @deffnx {C Function} scm_string_eq (s1, s2, start1, end1, start2, end2)
3213 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3217 @deffn {Scheme Procedure} string<> s1 s2 [start1 [end1 [start2 [end2]]]]
3218 @deffnx {C Function} scm_string_neq (s1, s2, start1, end1, start2, end2)
3219 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3223 @deffn {Scheme Procedure} string< s1 s2 [start1 [end1 [start2 [end2]]]]
3224 @deffnx {C Function} scm_string_lt (s1, s2, start1, end1, start2, end2)
3225 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3226 true value otherwise.
3229 @deffn {Scheme Procedure} string> s1 s2 [start1 [end1 [start2 [end2]]]]
3230 @deffnx {C Function} scm_string_gt (s1, s2, start1, end1, start2, end2)
3231 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3232 true value otherwise.
3235 @deffn {Scheme Procedure} string<= s1 s2 [start1 [end1 [start2 [end2]]]]
3236 @deffnx {C Function} scm_string_le (s1, s2, start1, end1, start2, end2)
3237 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3241 @deffn {Scheme Procedure} string>= s1 s2 [start1 [end1 [start2 [end2]]]]
3242 @deffnx {C Function} scm_string_ge (s1, s2, start1, end1, start2, end2)
3243 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3247 @deffn {Scheme Procedure} string-ci= s1 s2 [start1 [end1 [start2 [end2]]]]
3248 @deffnx {C Function} scm_string_ci_eq (s1, s2, start1, end1, start2, end2)
3249 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3250 value otherwise. The character comparison is done
3254 @deffn {Scheme Procedure} string-ci<> s1 s2 [start1 [end1 [start2 [end2]]]]
3255 @deffnx {C Function} scm_string_ci_neq (s1, s2, start1, end1, start2, end2)
3256 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3257 value otherwise. The character comparison is done
3261 @deffn {Scheme Procedure} string-ci< s1 s2 [start1 [end1 [start2 [end2]]]]
3262 @deffnx {C Function} scm_string_ci_lt (s1, s2, start1, end1, start2, end2)
3263 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3264 true value otherwise. The character comparison is done
3268 @deffn {Scheme Procedure} string-ci> s1 s2 [start1 [end1 [start2 [end2]]]]
3269 @deffnx {C Function} scm_string_ci_gt (s1, s2, start1, end1, start2, end2)
3270 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3271 true value otherwise. The character comparison is done
3275 @deffn {Scheme Procedure} string-ci<= s1 s2 [start1 [end1 [start2 [end2]]]]
3276 @deffnx {C Function} scm_string_ci_le (s1, s2, start1, end1, start2, end2)
3277 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3278 value otherwise. The character comparison is done
3282 @deffn {Scheme Procedure} string-ci>= s1 s2 [start1 [end1 [start2 [end2]]]]
3283 @deffnx {C Function} scm_string_ci_ge (s1, s2, start1, end1, start2, end2)
3284 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3285 otherwise. The character comparison is done
3289 @deffn {Scheme Procedure} string-hash s [bound [start [end]]]
3290 @deffnx {C Function} scm_substring_hash (s, bound, start, end)
3291 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).
3294 @deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
3295 @deffnx {C Function} scm_substring_hash_ci (s, bound, start, end)
3296 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).
3299 @node String Searching
3300 @subsubsection String Searching
3302 @deffn {Scheme Procedure} string-index s char_pred [start [end]]
3303 @deffnx {C Function} scm_string_index (s, char_pred, start, end)
3304 Search through the string @var{s} from left to right, returning
3305 the index of the first occurrence of a character which
3309 equals @var{char_pred}, if it is character,
3312 satisfies the predicate @var{char_pred}, if it is a procedure,
3315 is in the set @var{char_pred}, if it is a character set.
3319 @deffn {Scheme Procedure} string-rindex s char_pred [start [end]]
3320 @deffnx {C Function} scm_string_rindex (s, char_pred, start, end)
3321 Search through the string @var{s} from right to left, returning
3322 the index of the last occurrence of a character which
3326 equals @var{char_pred}, if it is character,
3329 satisfies the predicate @var{char_pred}, if it is a procedure,
3332 is in the set if @var{char_pred} is a character set.
3336 @deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3337 @deffnx {C Function} scm_string_prefix_length (s1, s2, start1, end1, start2, end2)
3338 Return the length of the longest common prefix of the two
3342 @deffn {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3343 @deffnx {C Function} scm_string_prefix_length_ci (s1, s2, start1, end1, start2, end2)
3344 Return the length of the longest common prefix of the two
3345 strings, ignoring character case.
3348 @deffn {Scheme Procedure} string-suffix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3349 @deffnx {C Function} scm_string_suffix_length (s1, s2, start1, end1, start2, end2)
3350 Return the length of the longest common suffix of the two
3354 @deffn {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3355 @deffnx {C Function} scm_string_suffix_length_ci (s1, s2, start1, end1, start2, end2)
3356 Return the length of the longest common suffix of the two
3357 strings, ignoring character case.
3360 @deffn {Scheme Procedure} string-prefix? s1 s2 [start1 [end1 [start2 [end2]]]]
3361 @deffnx {C Function} scm_string_prefix_p (s1, s2, start1, end1, start2, end2)
3362 Is @var{s1} a prefix of @var{s2}?
3365 @deffn {Scheme Procedure} string-prefix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3366 @deffnx {C Function} scm_string_prefix_ci_p (s1, s2, start1, end1, start2, end2)
3367 Is @var{s1} a prefix of @var{s2}, ignoring character case?
3370 @deffn {Scheme Procedure} string-suffix? s1 s2 [start1 [end1 [start2 [end2]]]]
3371 @deffnx {C Function} scm_string_suffix_p (s1, s2, start1, end1, start2, end2)
3372 Is @var{s1} a suffix of @var{s2}?
3375 @deffn {Scheme Procedure} string-suffix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3376 @deffnx {C Function} scm_string_suffix_ci_p (s1, s2, start1, end1, start2, end2)
3377 Is @var{s1} a suffix of @var{s2}, ignoring character case?
3380 @deffn {Scheme Procedure} string-index-right s char_pred [start [end]]
3381 @deffnx {C Function} scm_string_index_right (s, char_pred, start, end)
3382 Search through the string @var{s} from right to left, returning
3383 the index of the last occurrence of a character which
3387 equals @var{char_pred}, if it is character,
3390 satisfies the predicate @var{char_pred}, if it is a procedure,
3393 is in the set if @var{char_pred} is a character set.
3397 @deffn {Scheme Procedure} string-skip s char_pred [start [end]]
3398 @deffnx {C Function} scm_string_skip (s, char_pred, start, end)
3399 Search through the string @var{s} from left to right, returning
3400 the index of the first occurrence of a character which
3404 does not equal @var{char_pred}, if it is character,
3407 does not satisfy the predicate @var{char_pred}, if it is a
3411 is not in the set if @var{char_pred} is a character set.
3415 @deffn {Scheme Procedure} string-skip-right s char_pred [start [end]]
3416 @deffnx {C Function} scm_string_skip_right (s, char_pred, start, end)
3417 Search through the string @var{s} from right to left, returning
3418 the index of the last occurrence of a character which
3422 does not equal @var{char_pred}, if it is character,
3425 does not satisfy the predicate @var{char_pred}, if it is a
3429 is not in the set if @var{char_pred} is a character set.
3433 @deffn {Scheme Procedure} string-count s char_pred [start [end]]
3434 @deffnx {C Function} scm_string_count (s, char_pred, start, end)
3435 Return the count of the number of characters in the string
3440 equals @var{char_pred}, if it is character,
3443 satisfies the predicate @var{char_pred}, if it is a procedure.
3446 is in the set @var{char_pred}, if it is a character set.
3450 @deffn {Scheme Procedure} string-contains s1 s2 [start1 [end1 [start2 [end2]]]]
3451 @deffnx {C Function} scm_string_contains (s1, s2, start1, end1, start2, end2)
3452 Does string @var{s1} contain string @var{s2}? Return the index
3453 in @var{s1} where @var{s2} occurs as a substring, or false.
3454 The optional start/end indices restrict the operation to the
3455 indicated substrings.
3458 @deffn {Scheme Procedure} string-contains-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3459 @deffnx {C Function} scm_string_contains_ci (s1, s2, start1, end1, start2, end2)
3460 Does string @var{s1} contain string @var{s2}? Return the index
3461 in @var{s1} where @var{s2} occurs as a substring, or false.
3462 The optional start/end indices restrict the operation to the
3463 indicated substrings. Character comparison is done
3467 @node Alphabetic Case Mapping
3468 @subsubsection Alphabetic Case Mapping
3470 These are procedures for mapping strings to their upper- or lower-case
3471 equivalents, respectively, or for capitalizing strings.
3473 @deffn {Scheme Procedure} string-upcase str [start [end]]
3474 @deffnx {C Function} scm_substring_upcase (str, start, end)
3475 @deffnx {C Function} scm_string_upcase (str)
3476 Upcase every character in @code{str}.
3479 @deffn {Scheme Procedure} string-upcase! str [start [end]]
3480 @deffnx {C Function} scm_substring_upcase_x (str, start, end)
3481 @deffnx {C Function} scm_string_upcase_x (str)
3482 Destructively upcase every character in @code{str}.
3492 @deffn {Scheme Procedure} string-downcase str [start [end]]
3493 @deffnx {C Function} scm_substring_downcase (str, start, end)
3494 @deffnx {C Function} scm_string_downcase (str)
3495 Downcase every character in @var{str}.
3498 @deffn {Scheme Procedure} string-downcase! str [start [end]]
3499 @deffnx {C Function} scm_substring_downcase_x (str, start, end)
3500 @deffnx {C Function} scm_string_downcase_x (str)
3501 Destructively downcase every character in @var{str}.
3506 (string-downcase! y)
3513 @deffn {Scheme Procedure} string-capitalize str
3514 @deffnx {C Function} scm_string_capitalize (str)
3515 Return a freshly allocated string with the characters in
3516 @var{str}, where the first character of every word is
3520 @deffn {Scheme Procedure} string-capitalize! str
3521 @deffnx {C Function} scm_string_capitalize_x (str)
3522 Upcase the first character of every word in @var{str}
3523 destructively and return @var{str}.
3526 y @result{} "hello world"
3527 (string-capitalize! y) @result{} "Hello World"
3528 y @result{} "Hello World"
3532 @deffn {Scheme Procedure} string-titlecase str [start [end]]
3533 @deffnx {C Function} scm_string_titlecase (str, start, end)
3534 Titlecase every first character in a word in @var{str}.
3537 @deffn {Scheme Procedure} string-titlecase! str [start [end]]
3538 @deffnx {C Function} scm_string_titlecase_x (str, start, end)
3539 Destructively titlecase every first character in a word in
3543 @node Reversing and Appending Strings
3544 @subsubsection Reversing and Appending Strings
3546 @deffn {Scheme Procedure} string-reverse str [start [end]]
3547 @deffnx {C Function} scm_string_reverse (str, start, end)
3548 Reverse the string @var{str}. The optional arguments
3549 @var{start} and @var{end} delimit the region of @var{str} to
3553 @deffn {Scheme Procedure} string-reverse! str [start [end]]
3554 @deffnx {C Function} scm_string_reverse_x (str, start, end)
3555 Reverse the string @var{str} in-place. The optional arguments
3556 @var{start} and @var{end} delimit the region of @var{str} to
3557 operate on. The return value is unspecified.
3560 @rnindex string-append
3561 @deffn {Scheme Procedure} string-append . args
3562 @deffnx {C Function} scm_string_append (args)
3563 Return a newly allocated string whose characters form the
3564 concatenation of the given strings, @var{args}.
3568 (string-append h "world"))
3569 @result{} "hello world"
3573 @deffn {Scheme Procedure} string-append/shared . ls
3574 @deffnx {C Function} scm_string_append_shared (ls)
3575 Like @code{string-append}, but the result may share memory
3576 with the argument strings.
3579 @deffn {Scheme Procedure} string-concatenate ls
3580 @deffnx {C Function} scm_string_concatenate (ls)
3581 Append the elements of @var{ls} (which must be strings)
3582 together into a single string. Guaranteed to return a freshly
3586 @deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]]
3587 @deffnx {C Function} scm_string_concatenate_reverse (ls, final_string, end)
3588 Without optional arguments, this procedure is equivalent to
3591 (string-concatenate (reverse ls))
3594 If the optional argument @var{final_string} is specified, it is
3595 consed onto the beginning to @var{ls} before performing the
3596 list-reverse and string-concatenate operations. If @var{end}
3597 is given, only the characters of @var{final_string} up to index
3600 Guaranteed to return a freshly allocated string.
3603 @deffn {Scheme Procedure} string-concatenate/shared ls
3604 @deffnx {C Function} scm_string_concatenate_shared (ls)
3605 Like @code{string-concatenate}, but the result may share memory
3606 with the strings in the list @var{ls}.
3609 @deffn {Scheme Procedure} string-concatenate-reverse/shared ls [final_string [end]]
3610 @deffnx {C Function} scm_string_concatenate_reverse_shared (ls, final_string, end)
3611 Like @code{string-concatenate-reverse}, but the result may
3612 share memory with the the strings in the @var{ls} arguments.
3615 @node Mapping Folding and Unfolding
3616 @subsubsection Mapping, Folding, and Unfolding
3618 @deffn {Scheme Procedure} string-map proc s [start [end]]
3619 @deffnx {C Function} scm_string_map (proc, s, start, end)
3620 @var{proc} is a char->char procedure, it is mapped over
3621 @var{s}. The order in which the procedure is applied to the
3622 string elements is not specified.
3625 @deffn {Scheme Procedure} string-map! proc s [start [end]]
3626 @deffnx {C Function} scm_string_map_x (proc, s, start, end)
3627 @var{proc} is a char->char procedure, it is mapped over
3628 @var{s}. The order in which the procedure is applied to the
3629 string elements is not specified. The string @var{s} is
3630 modified in-place, the return value is not specified.
3633 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
3634 @deffnx {C Function} scm_string_for_each (proc, s, start, end)
3635 @var{proc} is mapped over @var{s} in left-to-right order. The
3636 return value is not specified.
3639 @deffn {Scheme Procedure} string-for-each-index proc s [start [end]]
3640 @deffnx {C Function} scm_string_for_each_index (proc, s, start, end)
3641 Call @code{(@var{proc} i)} for each index i in @var{s}, from left to
3644 For example, to change characters to alternately upper and lower case,
3647 (define str (string-copy "studly"))
3648 (string-for-each-index
3651 ((if (even? i) char-upcase char-downcase)
3652 (string-ref str i))))
3654 str @result{} "StUdLy"
3658 @deffn {Scheme Procedure} string-fold kons knil s [start [end]]
3659 @deffnx {C Function} scm_string_fold (kons, knil, s, start, end)
3660 Fold @var{kons} over the characters of @var{s}, with @var{knil}
3661 as the terminating element, from left to right. @var{kons}
3662 must expect two arguments: The actual character and the last
3663 result of @var{kons}' application.
3666 @deffn {Scheme Procedure} string-fold-right kons knil s [start [end]]
3667 @deffnx {C Function} scm_string_fold_right (kons, knil, s, start, end)
3668 Fold @var{kons} over the characters of @var{s}, with @var{knil}
3669 as the terminating element, from right to left. @var{kons}
3670 must expect two arguments: The actual character and the last
3671 result of @var{kons}' application.
3674 @deffn {Scheme Procedure} string-unfold p f g seed [base [make_final]]
3675 @deffnx {C Function} scm_string_unfold (p, f, g, seed, base, make_final)
3677 @item @var{g} is used to generate a series of @emph{seed}
3678 values from the initial @var{seed}: @var{seed}, (@var{g}
3679 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
3681 @item @var{p} tells us when to stop -- when it returns true
3682 when applied to one of these seed values.
3683 @item @var{f} maps each seed value to the corresponding
3684 character in the result string. These chars are assembled
3685 into the string in a left-to-right order.
3686 @item @var{base} is the optional initial/leftmost portion
3687 of the constructed string; it default to the empty
3689 @item @var{make_final} is applied to the terminal seed
3690 value (on which @var{p} returns true) to produce
3691 the final/rightmost portion of the constructed string.
3692 The default is nothing extra.
3696 @deffn {Scheme Procedure} string-unfold-right p f g seed [base [make_final]]
3697 @deffnx {C Function} scm_string_unfold_right (p, f, g, seed, base, make_final)
3699 @item @var{g} is used to generate a series of @emph{seed}
3700 values from the initial @var{seed}: @var{seed}, (@var{g}
3701 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
3703 @item @var{p} tells us when to stop -- when it returns true
3704 when applied to one of these seed values.
3705 @item @var{f} maps each seed value to the corresponding
3706 character in the result string. These chars are assembled
3707 into the string in a right-to-left order.
3708 @item @var{base} is the optional initial/rightmost portion
3709 of the constructed string; it default to the empty
3711 @item @var{make_final} is applied to the terminal seed
3712 value (on which @var{p} returns true) to produce
3713 the final/leftmost portion of the constructed string.
3714 It defaults to @code{(lambda (x) )}.
3718 @node Miscellaneous String Operations
3719 @subsubsection Miscellaneous String Operations
3721 @deffn {Scheme Procedure} xsubstring s from [to [start [end]]]
3722 @deffnx {C Function} scm_xsubstring (s, from, to, start, end)
3723 This is the @emph{extended substring} procedure that implements
3724 replicated copying of a substring of some string.
3726 @var{s} is a string, @var{start} and @var{end} are optional
3727 arguments that demarcate a substring of @var{s}, defaulting to
3728 0 and the length of @var{s}. Replicate this substring up and
3729 down index space, in both the positive and negative directions.
3730 @code{xsubstring} returns the substring of this string
3731 beginning at index @var{from}, and ending at @var{to}, which
3732 defaults to @var{from} + (@var{end} - @var{start}).
3735 @deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto [start [end]]]
3736 @deffnx {C Function} scm_string_xcopy_x (target, tstart, s, sfrom, sto, start, end)
3737 Exactly the same as @code{xsubstring}, but the extracted text
3738 is written into the string @var{target} starting at index
3739 @var{tstart}. The operation is not defined if @code{(eq?
3740 @var{target} @var{s})} or these arguments share storage -- you
3741 cannot copy a string on top of itself.
3744 @deffn {Scheme Procedure} string-replace s1 s2 [start1 [end1 [start2 [end2]]]]
3745 @deffnx {C Function} scm_string_replace (s1, s2, start1, end1, start2, end2)
3746 Return the string @var{s1}, but with the characters
3747 @var{start1} @dots{} @var{end1} replaced by the characters
3748 @var{start2} @dots{} @var{end2} from @var{s2}.
3751 @deffn {Scheme Procedure} string-tokenize s [token_set [start [end]]]
3752 @deffnx {C Function} scm_string_tokenize (s, token_set, start, end)
3753 Split the string @var{s} into a list of substrings, where each
3754 substring is a maximal non-empty contiguous sequence of
3755 characters from the character set @var{token_set}, which
3756 defaults to @code{char-set:graphic}.
3757 If @var{start} or @var{end} indices are provided, they restrict
3758 @code{string-tokenize} to operating on the indicated substring
3762 @deffn {Scheme Procedure} string-filter s char_pred [start [end]]
3763 @deffnx {C Function} scm_string_filter (s, char_pred, start, end)
3764 Filter the string @var{s}, retaining only those characters which
3765 satisfy @var{char_pred}.
3767 If @var{char_pred} is a procedure, it is applied to each character as
3768 a predicate, if it is a character, it is tested for equality and if it
3769 is a character set, it is tested for membership.
3772 @deffn {Scheme Procedure} string-delete s char_pred [start [end]]
3773 @deffnx {C Function} scm_string_delete (s, char_pred, start, end)
3774 Delete characters satisfying @var{char_pred} from @var{s}.
3776 If @var{char_pred} is a procedure, it is applied to each character as
3777 a predicate, if it is a character, it is tested for equality and if it
3778 is a character set, it is tested for membership.
3781 @node Conversion to/from C
3782 @subsubsection Conversion to/from C
3784 When creating a Scheme string from a C string or when converting a
3785 Scheme string to a C string, the concept of character encoding becomes
3788 In C, a string is just a sequence of bytes, and the character encoding
3789 describes the relation between these bytes and the actual characters
3790 that make up the string. For Scheme strings, character encoding is
3791 not an issue (most of the time), since in Scheme you never get to see
3792 the bytes, only the characters.
3794 Well, ideally, anyway. Right now, Guile simply equates Scheme
3795 characters and bytes, ignoring the possibility of multi-byte encodings
3796 completely. This will change in the future, where Guile will use
3797 Unicode codepoints as its characters and UTF-8 or some other encoding
3798 as its internal encoding. When you exclusively use the functions
3799 listed in this section, you are `future-proof'.
3801 Converting a Scheme string to a C string will often allocate fresh
3802 memory to hold the result. You must take care that this memory is
3803 properly freed eventually. In many cases, this can be achieved by
3804 using @code{scm_dynwind_free} inside an appropriate dynwind context,
3805 @xref{Dynamic Wind}.
3807 @deftypefn {C Function} SCM scm_from_locale_string (const char *str)
3808 @deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
3809 Creates a new Scheme string that has the same contents as @var{str}
3810 when interpreted in the current locale character encoding.
3812 For @code{scm_from_locale_string}, @var{str} must be null-terminated.
3814 For @code{scm_from_locale_stringn}, @var{len} specifies the length of
3815 @var{str} in bytes, and @var{str} does not need to be null-terminated.
3816 If @var{len} is @code{(size_t)-1}, then @var{str} does need to be
3817 null-terminated and the real length will be found with @code{strlen}.
3820 @deftypefn {C Function} SCM scm_take_locale_string (char *str)
3821 @deftypefnx {C Function} SCM scm_take_locale_stringn (char *str, size_t len)
3822 Like @code{scm_from_locale_string} and @code{scm_from_locale_stringn},
3823 respectively, but also frees @var{str} with @code{free} eventually.
3824 Thus, you can use this function when you would free @var{str} anyway
3825 immediately after creating the Scheme string. In certain cases, Guile
3826 can then use @var{str} directly as its internal representation.
3829 @deftypefn {C Function} {char *} scm_to_locale_string (SCM str)
3830 @deftypefnx {C Function} {char *} scm_to_locale_stringn (SCM str, size_t *lenp)
3831 Returns a C string in the current locale encoding with the same
3832 contents as @var{str}. The C string must be freed with @code{free}
3833 eventually, maybe by using @code{scm_dynwind_free}, @xref{Dynamic
3836 For @code{scm_to_locale_string}, the returned string is
3837 null-terminated and an error is signalled when @var{str} contains
3838 @code{#\nul} characters.
3840 For @code{scm_to_locale_stringn} and @var{lenp} not @code{NULL},
3841 @var{str} might contain @code{#\nul} characters and the length of the
3842 returned string in bytes is stored in @code{*@var{lenp}}. The
3843 returned string will not be null-terminated in this case. If
3844 @var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
3845 @code{scm_to_locale_string}.
3848 @deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
3849 Puts @var{str} as a C string in the current locale encoding into the
3850 memory pointed to by @var{buf}. The buffer at @var{buf} has room for
3851 @var{max_len} bytes and @code{scm_to_local_stringbuf} will never store
3852 more than that. No terminating @code{'\0'} will be stored.
3854 The return value of @code{scm_to_locale_stringbuf} is the number of
3855 bytes that are needed for all of @var{str}, regardless of whether
3856 @var{buf} was large enough to hold them. Thus, when the return value
3857 is larger than @var{max_len}, only @var{max_len} bytes have been
3858 stored and you probably need to try again with a larger buffer.
3862 @subsection Bytevectors
3867 A @dfn{bytevector} is a raw bit string. The @code{(rnrs bytevector)}
3868 module provides the programming interface specified by the
3869 @uref{http://www.r6rs.org/, Revised^6 Report on the Algorithmic Language
3870 Scheme (R6RS)}. It contains procedures to manipulate bytevectors and
3871 interpret their contents in a number of ways: bytevector contents can be
3872 accessed as signed or unsigned integer of various sizes and endianness,
3873 as IEEE-754 floating point numbers, or as strings. It is a useful tool
3874 to encode and decode binary data.
3876 The R6RS (Section 4.3.4) specifies an external representation for
3877 bytevectors, whereby the octets (integers in the range 0--255) contained
3878 in the bytevector are represented as a list prefixed by @code{#vu8}:
3884 denotes a 3-byte bytevector containing the octets 1, 53, and 204. Like
3885 string literals, booleans, etc., bytevectors are ``self-quoting'', i.e.,
3886 they do not need to be quoted:
3890 @result{} #vu8(1 53 204)
3893 Bytevectors can be used with the binary input/output primitives of the
3894 R6RS (@pxref{R6RS I/O Ports}).
3897 * Bytevector Endianness:: Dealing with byte order.
3898 * Bytevector Manipulation:: Creating, copying, manipulating bytevectors.
3899 * Bytevectors as Integers:: Interpreting bytes as integers.
3900 * Bytevectors and Integer Lists:: Converting to/from an integer list.
3901 * Bytevectors as Floats:: Interpreting bytes as real numbers.
3902 * Bytevectors as Strings:: Interpreting bytes as Unicode strings.
3903 * Bytevectors as Generalized Vectors:: Guile extension to the bytevector API.
3906 @node Bytevector Endianness
3907 @subsubsection Endianness
3913 Some of the following procedures take an @var{endianness} parameter.
3914 The @dfn{endianness} is defined as the order of bytes in multi-byte
3915 numbers: numbers encoded in @dfn{big endian} have their most
3916 significant bytes written first, whereas numbers encoded in
3917 @dfn{little endian} have their least significant bytes
3918 first@footnote{Big-endian and little-endian are the most common
3919 ``endiannesses'', but others do exist. For instance, the GNU MP
3920 library allows @dfn{word order} to be specified independently of
3921 @dfn{byte order} (@pxref{Integer Import and Export,,, gmp, The GNU
3922 Multiple Precision Arithmetic Library Manual}).}.
3924 Little-endian is the native endianness of the IA32 architecture and
3925 its derivatives, while big-endian is native to SPARC and PowerPC,
3926 among others. The @code{native-endianness} procedure returns the
3927 native endianness of the machine it runs on.
3929 @deffn {Scheme Procedure} native-endianness
3930 @deffnx {C Function} scm_native_endianness ()
3931 Return a value denoting the native endianness of the host machine.
3934 @deffn {Scheme Macro} endianness symbol
3935 Return an object denoting the endianness specified by @var{symbol}. If
3936 @var{symbol} is neither @code{big} nor @code{little} then an error is
3937 raised at expand-time.
3940 @defvr {C Variable} scm_endianness_big
3941 @defvrx {C Variable} scm_endianness_little
3942 The objects denoting big- and little-endianness, respectively.
3946 @node Bytevector Manipulation
3947 @subsubsection Manipulating Bytevectors
3949 Bytevectors can be created, copied, and analyzed with the following
3950 procedures and C functions.
3952 @deffn {Scheme Procedure} make-bytevector len [fill]
3953 @deffnx {C Function} scm_make_bytevector (len, fill)
3954 @deffnx {C Function} scm_c_make_bytevector (size_t len)
3955 Return a new bytevector of @var{len} bytes. Optionally, if @var{fill}
3956 is given, fill it with @var{fill}; @var{fill} must be in the range
3960 @deffn {Scheme Procedure} bytevector? obj
3961 @deffnx {C Function} scm_bytevector_p (obj)
3962 Return true if @var{obj} is a bytevector.
3965 @deftypefn {C Function} int scm_is_bytevector (SCM obj)
3966 Equivalent to @code{scm_is_true (scm_bytevector_p (obj))}.
3969 @deffn {Scheme Procedure} bytevector-length bv
3970 @deffnx {C Function} scm_bytevector_length (bv)
3971 Return the length in bytes of bytevector @var{bv}.
3974 @deftypefn {C Function} size_t scm_c_bytevector_length (SCM bv)
3975 Likewise, return the length in bytes of bytevector @var{bv}.
3978 @deffn {Scheme Procedure} bytevector=? bv1 bv2
3979 @deffnx {C Function} scm_bytevector_eq_p (bv1, bv2)
3980 Return is @var{bv1} equals to @var{bv2}---i.e., if they have the same
3981 length and contents.
3984 @deffn {Scheme Procedure} bytevector-fill! bv fill
3985 @deffnx {C Function} scm_bytevector_fill_x (bv, fill)
3986 Fill bytevector @var{bv} with @var{fill}, a byte.
3989 @deffn {Scheme Procedure} bytevector-copy! source source-start target target-start len
3990 @deffnx {C Function} scm_bytevector_copy_x (source, source_start, target, target_start, len)
3991 Copy @var{len} bytes from @var{source} into @var{target}, starting
3992 reading from @var{source-start} (a positive index within @var{source})
3993 and start writing at @var{target-start}.
3996 @deffn {Scheme Procedure} bytevector-copy bv
3997 @deffnx {C Function} scm_bytevector_copy (bv)
3998 Return a newly allocated copy of @var{bv}.
4001 @deftypefn {C Function} scm_t_uint8 scm_c_bytevector_ref (SCM bv, size_t index)
4002 Return the byte at @var{index} in bytevector @var{bv}.
4005 @deftypefn {C Function} void scm_c_bytevector_set_x (SCM bv, size_t index, scm_t_uint8 value)
4006 Set the byte at @var{index} in @var{bv} to @var{value}.
4009 Low-level C macros are available. They do not perform any
4010 type-checking; as such they should be used with care.
4012 @deftypefn {C Macro} size_t SCM_BYTEVECTOR_LENGTH (bv)
4013 Return the length in bytes of bytevector @var{bv}.
4016 @deftypefn {C Macro} {signed char *} SCM_BYTEVECTOR_CONTENTS (bv)
4017 Return a pointer to the contents of bytevector @var{bv}.
4021 @node Bytevectors as Integers
4022 @subsubsection Interpreting Bytevector Contents as Integers
4024 The contents of a bytevector can be interpreted as a sequence of
4025 integers of any given size, sign, and endianness.
4028 (let ((bv (make-bytevector 4)))
4029 (bytevector-u8-set! bv 0 #x12)
4030 (bytevector-u8-set! bv 1 #x34)
4031 (bytevector-u8-set! bv 2 #x56)
4032 (bytevector-u8-set! bv 3 #x78)
4034 (map (lambda (number)
4035 (number->string number 16))
4036 (list (bytevector-u8-ref bv 0)
4037 (bytevector-u16-ref bv 0 (endianness big))
4038 (bytevector-u32-ref bv 0 (endianness little)))))
4040 @result{} ("12" "1234" "78563412")
4043 The most generic procedures to interpret bytevector contents as integers
4044 are described below.
4046 @deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
4047 @deffnx {Scheme Procedure} bytevector-sint-ref bv index endianness size
4048 @deffnx {C Function} scm_bytevector_uint_ref (bv, index, endianness, size)
4049 @deffnx {C Function} scm_bytevector_sint_ref (bv, index, endianness, size)
4050 Return the @var{size}-byte long unsigned (resp. signed) integer at
4051 index @var{index} in @var{bv}, decoded according to @var{endianness}.
4054 @deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
4055 @deffnx {Scheme Procedure} bytevector-sint-set! bv index value endianness size
4056 @deffnx {C Function} scm_bytevector_uint_set_x (bv, index, value, endianness, size)
4057 @deffnx {C Function} scm_bytevector_sint_set_x (bv, index, value, endianness, size)
4058 Set the @var{size}-byte long unsigned (resp. signed) integer at
4059 @var{index} to @var{value}, encoded according to @var{endianness}.
4062 The following procedures are similar to the ones above, but specialized
4063 to a given integer size:
4065 @deffn {Scheme Procedure} bytevector-u8-ref bv index
4066 @deffnx {Scheme Procedure} bytevector-s8-ref bv index
4067 @deffnx {Scheme Procedure} bytevector-u16-ref bv index endianness
4068 @deffnx {Scheme Procedure} bytevector-s16-ref bv index endianness
4069 @deffnx {Scheme Procedure} bytevector-u32-ref bv index endianness
4070 @deffnx {Scheme Procedure} bytevector-s32-ref bv index endianness
4071 @deffnx {Scheme Procedure} bytevector-u64-ref bv index endianness
4072 @deffnx {Scheme Procedure} bytevector-s64-ref bv index endianness
4073 @deffnx {C Function} scm_bytevector_u8_ref (bv, index)
4074 @deffnx {C Function} scm_bytevector_s8_ref (bv, index)
4075 @deffnx {C Function} scm_bytevector_u16_ref (bv, index, endianness)
4076 @deffnx {C Function} scm_bytevector_s16_ref (bv, index, endianness)
4077 @deffnx {C Function} scm_bytevector_u32_ref (bv, index, endianness)
4078 @deffnx {C Function} scm_bytevector_s32_ref (bv, index, endianness)
4079 @deffnx {C Function} scm_bytevector_u64_ref (bv, index, endianness)
4080 @deffnx {C Function} scm_bytevector_s64_ref (bv, index, endianness)
4081 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
4082 16, 32 or 64) from @var{bv} at @var{index}, decoded according to
4086 @deffn {Scheme Procedure} bytevector-u8-set! bv index value
4087 @deffnx {Scheme Procedure} bytevector-s8-set! bv index value
4088 @deffnx {Scheme Procedure} bytevector-u16-set! bv index value endianness
4089 @deffnx {Scheme Procedure} bytevector-s16-set! bv index value endianness
4090 @deffnx {Scheme Procedure} bytevector-u32-set! bv index value endianness
4091 @deffnx {Scheme Procedure} bytevector-s32-set! bv index value endianness
4092 @deffnx {Scheme Procedure} bytevector-u64-set! bv index value endianness
4093 @deffnx {Scheme Procedure} bytevector-s64-set! bv index value endianness
4094 @deffnx {C Function} scm_bytevector_u8_set_x (bv, index, value)
4095 @deffnx {C Function} scm_bytevector_s8_set_x (bv, index, value)
4096 @deffnx {C Function} scm_bytevector_u16_set_x (bv, index, value, endianness)
4097 @deffnx {C Function} scm_bytevector_s16_set_x (bv, index, value, endianness)
4098 @deffnx {C Function} scm_bytevector_u32_set_x (bv, index, value, endianness)
4099 @deffnx {C Function} scm_bytevector_s32_set_x (bv, index, value, endianness)
4100 @deffnx {C Function} scm_bytevector_u64_set_x (bv, index, value, endianness)
4101 @deffnx {C Function} scm_bytevector_s64_set_x (bv, index, value, endianness)
4102 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
4103 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to
4107 Finally, a variant specialized for the host's endianness is available
4108 for each of these functions (with the exception of the @code{u8}
4109 accessors, for obvious reasons):
4111 @deffn {Scheme Procedure} bytevector-u16-native-ref bv index
4112 @deffnx {Scheme Procedure} bytevector-s16-native-ref bv index
4113 @deffnx {Scheme Procedure} bytevector-u32-native-ref bv index
4114 @deffnx {Scheme Procedure} bytevector-s32-native-ref bv index
4115 @deffnx {Scheme Procedure} bytevector-u64-native-ref bv index
4116 @deffnx {Scheme Procedure} bytevector-s64-native-ref bv index
4117 @deffnx {C Function} scm_bytevector_u16_native_ref (bv, index)
4118 @deffnx {C Function} scm_bytevector_s16_native_ref (bv, index)
4119 @deffnx {C Function} scm_bytevector_u32_native_ref (bv, index)
4120 @deffnx {C Function} scm_bytevector_s32_native_ref (bv, index)
4121 @deffnx {C Function} scm_bytevector_u64_native_ref (bv, index)
4122 @deffnx {C Function} scm_bytevector_s64_native_ref (bv, index)
4123 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
4124 16, 32 or 64) from @var{bv} at @var{index}, decoded according to the
4125 host's native endianness.
4128 @deffn {Scheme Procedure} bytevector-u16-native-set! bv index value
4129 @deffnx {Scheme Procedure} bytevector-s16-native-set! bv index value
4130 @deffnx {Scheme Procedure} bytevector-u32-native-set! bv index value
4131 @deffnx {Scheme Procedure} bytevector-s32-native-set! bv index value
4132 @deffnx {Scheme Procedure} bytevector-u64-native-set! bv index value
4133 @deffnx {Scheme Procedure} bytevector-s64-native-set! bv index value
4134 @deffnx {C Function} scm_bytevector_u16_native_set_x (bv, index, value)
4135 @deffnx {C Function} scm_bytevector_s16_native_set_x (bv, index, value)
4136 @deffnx {C Function} scm_bytevector_u32_native_set_x (bv, index, value)
4137 @deffnx {C Function} scm_bytevector_s32_native_set_x (bv, index, value)
4138 @deffnx {C Function} scm_bytevector_u64_native_set_x (bv, index, value)
4139 @deffnx {C Function} scm_bytevector_s64_native_set_x (bv, index, value)
4140 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
4141 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to the
4142 host's native endianness.
4146 @node Bytevectors and Integer Lists
4147 @subsubsection Converting Bytevectors to/from Integer Lists
4149 Bytevector contents can readily be converted to/from lists of signed or
4153 (bytevector->sint-list (u8-list->bytevector (make-list 4 255))
4154 (endianness little) 2)
4158 @deffn {Scheme Procedure} bytevector->u8-list bv
4159 @deffnx {C Function} scm_bytevector_to_u8_list (bv)
4160 Return a newly allocated list of unsigned 8-bit integers from the
4161 contents of @var{bv}.
4164 @deffn {Scheme Procedure} u8-list->bytevector lst
4165 @deffnx {C Function} scm_u8_list_to_bytevector (lst)
4166 Return a newly allocated bytevector consisting of the unsigned 8-bit
4167 integers listed in @var{lst}.
4170 @deffn {Scheme Procedure} bytevector->uint-list bv endianness size
4171 @deffnx {Scheme Procedure} bytevector->sint-list bv endianness size
4172 @deffnx {C Function} scm_bytevector_to_uint_list (bv, endianness, size)
4173 @deffnx {C Function} scm_bytevector_to_sint_list (bv, endianness, size)
4174 Return a list of unsigned (resp. signed) integers of @var{size} bytes
4175 representing the contents of @var{bv}, decoded according to
4179 @deffn {Scheme Procedure} uint-list->bytevector lst endianness size
4180 @deffnx {Scheme Procedure} sint-list->bytevector lst endianness size
4181 @deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
4182 @deffnx {C Function} scm_sint_list_to_bytevector (lst, endianness, size)
4183 Return a new bytevector containing the unsigned (resp. signed) integers
4184 listed in @var{lst} and encoded on @var{size} bytes according to
4188 @node Bytevectors as Floats
4189 @subsubsection Interpreting Bytevector Contents as Floating Point Numbers
4191 @cindex IEEE-754 floating point numbers
4193 Bytevector contents can also be accessed as IEEE-754 single- or
4194 double-precision floating point numbers (respectively 32 and 64-bit
4195 long) using the procedures described here.
4197 @deffn {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
4198 @deffnx {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
4199 @deffnx {C Function} scm_bytevector_ieee_single_ref (bv, index, endianness)
4200 @deffnx {C Function} scm_bytevector_ieee_double_ref (bv, index, endianness)
4201 Return the IEEE-754 single-precision floating point number from @var{bv}
4202 at @var{index} according to @var{endianness}.
4205 @deffn {Scheme Procedure} bytevector-ieee-single-set! bv index value endianness
4206 @deffnx {Scheme Procedure} bytevector-ieee-double-set! bv index value endianness
4207 @deffnx {C Function} scm_bytevector_ieee_single_set_x (bv, index, value, endianness)
4208 @deffnx {C Function} scm_bytevector_ieee_double_set_x (bv, index, value, endianness)
4209 Store real number @var{value} in @var{bv} at @var{index} according to
4213 Specialized procedures are also available:
4215 @deffn {Scheme Procedure} bytevector-ieee-single-native-ref bv index
4216 @deffnx {Scheme Procedure} bytevector-ieee-double-native-ref bv index
4217 @deffnx {C Function} scm_bytevector_ieee_single_native_ref (bv, index)
4218 @deffnx {C Function} scm_bytevector_ieee_double_native_ref (bv, index)
4219 Return the IEEE-754 single-precision floating point number from @var{bv}
4220 at @var{index} according to the host's native endianness.
4223 @deffn {Scheme Procedure} bytevector-ieee-single-native-set! bv index value
4224 @deffnx {Scheme Procedure} bytevector-ieee-double-native-set! bv index value
4225 @deffnx {C Function} scm_bytevector_ieee_single_native_set_x (bv, index, value)
4226 @deffnx {C Function} scm_bytevector_ieee_double_native_set_x (bv, index, value)
4227 Store real number @var{value} in @var{bv} at @var{index} according to
4228 the host's native endianness.
4232 @node Bytevectors as Strings
4233 @subsubsection Interpreting Bytevector Contents as Unicode Strings
4235 @cindex Unicode string encoding
4237 Bytevector contents can also be interpreted as Unicode strings encoded
4238 in one of the most commonly available encoding formats@footnote{Guile
4239 1.8 does @emph{not} support Unicode strings. Therefore, the procedures
4240 described here assume that Guile strings are internally encoded
4241 according to the current locale. For instance, if @code{$LC_CTYPE} is
4242 @code{fr_FR.ISO-8859-1}, then @code{string->utf-8} @i{et al.} will
4243 assume that Guile strings are Latin-1-encoded.}.
4246 (utf8->string (u8-list->bytevector '(99 97 102 101)))
4249 (string->utf8 "caf@'e") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT
4250 @result{} #vu8(99 97 102 195 169)
4253 @deffn {Scheme Procedure} string->utf8 str
4254 @deffnx {Scheme Procedure} string->utf16 str
4255 @deffnx {Scheme Procedure} string->utf32 str
4256 @deffnx {C Function} scm_string_to_utf8 (str)
4257 @deffnx {C Function} scm_string_to_utf16 (str)
4258 @deffnx {C Function} scm_string_to_utf32 (str)
4259 Return a newly allocated bytevector that contains the UTF-8, UTF-16, or
4260 UTF-32 (aka. UCS-4) encoding of @var{str}.
4263 @deffn {Scheme Procedure} utf8->string utf
4264 @deffnx {Scheme Procedure} utf16->string utf
4265 @deffnx {Scheme Procedure} utf32->string utf
4266 @deffnx {C Function} scm_utf8_to_string (utf)
4267 @deffnx {C Function} scm_utf16_to_string (utf)
4268 @deffnx {C Function} scm_utf32_to_string (utf)
4269 Return a newly allocated string that contains from the UTF-8-, UTF-16-,
4270 or UTF-32-decoded contents of bytevector @var{utf}.
4273 @node Bytevectors as Generalized Vectors
4274 @subsubsection Accessing Bytevectors with the Generalized Vector API
4276 As an extension to the R6RS, Guile allows bytevectors to be manipulated
4277 with the @dfn{generalized vector} procedures (@pxref{Generalized
4278 Vectors}). This also allows bytevectors to be accessed using the
4279 generic @dfn{array} procedures (@pxref{Array Procedures}). When using
4280 these APIs, bytes are accessed one at a time as 8-bit unsigned integers:
4283 (define bv #vu8(0 1 2 3))
4285 (generalized-vector? bv)
4288 (generalized-vector-ref bv 2)
4291 (generalized-vector-set! bv 2 77)
4300 @node Regular Expressions
4301 @subsection Regular Expressions
4302 @tpindex Regular expressions
4304 @cindex regular expressions
4306 @cindex emacs regexp
4308 A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
4309 describes a whole class of strings. A full description of regular
4310 expressions and their syntax is beyond the scope of this manual;
4311 an introduction can be found in the Emacs manual (@pxref{Regexps,
4312 , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
4313 in many general Unix reference books.
4315 If your system does not include a POSIX regular expression library,
4316 and you have not linked Guile with a third-party regexp library such
4317 as Rx, these functions will not be available. You can tell whether
4318 your Guile installation includes regular expression support by
4319 checking whether @code{(provided? 'regex)} returns true.
4321 The following regexp and string matching features are provided by the
4322 @code{(ice-9 regex)} module. Before using the described functions,
4323 you should load this module by executing @code{(use-modules (ice-9
4327 * Regexp Functions:: Functions that create and match regexps.
4328 * Match Structures:: Finding what was matched by a regexp.
4329 * Backslash Escapes:: Removing the special meaning of regexp
4334 @node Regexp Functions
4335 @subsubsection Regexp Functions
4337 By default, Guile supports POSIX extended regular expressions.
4338 That means that the characters @samp{(}, @samp{)}, @samp{+} and
4339 @samp{?} are special, and must be escaped if you wish to match the
4342 This regular expression interface was modeled after that
4343 implemented by SCSH, the Scheme Shell. It is intended to be
4344 upwardly compatible with SCSH regular expressions.
4346 Zero bytes (@code{#\nul}) cannot be used in regex patterns or input
4347 strings, since the underlying C functions treat that as the end of
4348 string. If there's a zero byte an error is thrown.
4350 Patterns and input strings are treated as being in the locale
4351 character set if @code{setlocale} has been called (@pxref{Locales}),
4352 and in a multibyte locale this includes treating multi-byte sequences
4353 as a single character. (Guile strings are currently merely bytes,
4354 though this may change in the future, @xref{Conversion to/from C}.)
4356 @deffn {Scheme Procedure} string-match pattern str [start]
4357 Compile the string @var{pattern} into a regular expression and compare
4358 it with @var{str}. The optional numeric argument @var{start} specifies
4359 the position of @var{str} at which to begin matching.
4361 @code{string-match} returns a @dfn{match structure} which
4362 describes what, if anything, was matched by the regular
4363 expression. @xref{Match Structures}. If @var{str} does not match
4364 @var{pattern} at all, @code{string-match} returns @code{#f}.
4367 Two examples of a match follow. In the first example, the pattern
4368 matches the four digits in the match string. In the second, the pattern
4372 (string-match "[0-9][0-9][0-9][0-9]" "blah2002")
4373 @result{} #("blah2002" (4 . 8))
4375 (string-match "[A-Za-z]" "123456")
4379 Each time @code{string-match} is called, it must compile its
4380 @var{pattern} argument into a regular expression structure. This
4381 operation is expensive, which makes @code{string-match} inefficient if
4382 the same regular expression is used several times (for example, in a
4383 loop). For better performance, you can compile a regular expression in
4384 advance and then match strings against the compiled regexp.
4386 @deffn {Scheme Procedure} make-regexp pat flag@dots{}
4387 @deffnx {C Function} scm_make_regexp (pat, flaglst)
4388 Compile the regular expression described by @var{pat}, and
4389 return the compiled regexp structure. If @var{pat} does not
4390 describe a legal regular expression, @code{make-regexp} throws
4391 a @code{regular-expression-syntax} error.
4393 The @var{flag} arguments change the behavior of the compiled
4394 regular expression. The following values may be supplied:
4396 @defvar regexp/icase
4397 Consider uppercase and lowercase letters to be the same when
4401 @defvar regexp/newline
4402 If a newline appears in the target string, then permit the
4403 @samp{^} and @samp{$} operators to match immediately after or
4404 immediately before the newline, respectively. Also, the
4405 @samp{.} and @samp{[^...]} operators will never match a newline
4406 character. The intent of this flag is to treat the target
4407 string as a buffer containing many lines of text, and the
4408 regular expression as a pattern that may match a single one of
4412 @defvar regexp/basic
4413 Compile a basic (``obsolete'') regexp instead of the extended
4414 (``modern'') regexps that are the default. Basic regexps do
4415 not consider @samp{|}, @samp{+} or @samp{?} to be special
4416 characters, and require the @samp{@{...@}} and @samp{(...)}
4417 metacharacters to be backslash-escaped (@pxref{Backslash
4418 Escapes}). There are several other differences between basic
4419 and extended regular expressions, but these are the most
4423 @defvar regexp/extended
4424 Compile an extended regular expression rather than a basic
4425 regexp. This is the default behavior; this flag will not
4426 usually be needed. If a call to @code{make-regexp} includes
4427 both @code{regexp/basic} and @code{regexp/extended} flags, the
4428 one which comes last will override the earlier one.
4432 @deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
4433 @deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
4434 Match the compiled regular expression @var{rx} against
4435 @code{str}. If the optional integer @var{start} argument is
4436 provided, begin matching from that position in the string.
4437 Return a match structure describing the results of the match,
4438 or @code{#f} if no match could be found.
4440 The @var{flags} argument changes the matching behavior. The following
4441 flag values may be supplied, use @code{logior} (@pxref{Bitwise
4442 Operations}) to combine them,
4444 @defvar regexp/notbol
4445 Consider that the @var{start} offset into @var{str} is not the
4446 beginning of a line and should not match operator @samp{^}.
4448 If @var{rx} was created with the @code{regexp/newline} option above,
4449 @samp{^} will still match after a newline in @var{str}.
4452 @defvar regexp/noteol
4453 Consider that the end of @var{str} is not the end of a line and should
4454 not match operator @samp{$}.
4456 If @var{rx} was created with the @code{regexp/newline} option above,
4457 @samp{$} will still match before a newline in @var{str}.
4462 ;; Regexp to match uppercase letters
4463 (define r (make-regexp "[A-Z]*"))
4465 ;; Regexp to match letters, ignoring case
4466 (define ri (make-regexp "[A-Z]*" regexp/icase))
4468 ;; Search for bob using regexp r
4469 (match:substring (regexp-exec r "bob"))
4470 @result{} "" ; no match
4472 ;; Search for bob using regexp ri
4473 (match:substring (regexp-exec ri "Bob"))
4474 @result{} "Bob" ; matched case insensitive
4477 @deffn {Scheme Procedure} regexp? obj
4478 @deffnx {C Function} scm_regexp_p (obj)
4479 Return @code{#t} if @var{obj} is a compiled regular expression,
4480 or @code{#f} otherwise.
4484 @deffn {Scheme Procedure} list-matches regexp str [flags]
4485 Return a list of match structures which are the non-overlapping
4486 matches of @var{regexp} in @var{str}. @var{regexp} can be either a
4487 pattern string or a compiled regexp. The @var{flags} argument is as
4488 per @code{regexp-exec} above.
4491 (map match:substring (list-matches "[a-z]+" "abc 42 def 78"))
4492 @result{} ("abc" "def")
4496 @deffn {Scheme Procedure} fold-matches regexp str init proc [flags]
4497 Apply @var{proc} to the non-overlapping matches of @var{regexp} in
4498 @var{str}, to build a result. @var{regexp} can be either a pattern
4499 string or a compiled regexp. The @var{flags} argument is as per
4500 @code{regexp-exec} above.
4502 @var{proc} is called as @code{(@var{proc} match prev)} where
4503 @var{match} is a match structure and @var{prev} is the previous return
4504 from @var{proc}. For the first call @var{prev} is the given
4505 @var{init} parameter. @code{fold-matches} returns the final value
4508 For example to count matches,
4511 (fold-matches "[a-z][0-9]" "abc x1 def y2" 0
4512 (lambda (match count)
4519 Regular expressions are commonly used to find patterns in one string
4520 and replace them with the contents of another string. The following
4521 functions are convenient ways to do this.
4523 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
4524 @deffn {Scheme Procedure} regexp-substitute port match [item@dots{}]
4525 Write to @var{port} selected parts of the match structure @var{match}.
4526 Or if @var{port} is @code{#f} then form a string from those parts and
4529 Each @var{item} specifies a part to be written, and may be one of the
4534 A string. String arguments are written out verbatim.
4537 An integer. The submatch with that number is written
4538 (@code{match:substring}). Zero is the entire match.
4541 The symbol @samp{pre}. The portion of the matched string preceding
4542 the regexp match is written (@code{match:prefix}).
4545 The symbol @samp{post}. The portion of the matched string following
4546 the regexp match is written (@code{match:suffix}).
4549 For example, changing a match and retaining the text before and after,
4552 (regexp-substitute #f (string-match "[0-9]+" "number 25 is good")
4554 @result{} "number 37 is good"
4557 Or matching a @sc{yyyymmdd} format date such as @samp{20020828} and
4558 re-ordering and hyphenating the fields.
4562 "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
4563 (define s "Date 20020429 12am.")
4564 (regexp-substitute #f (string-match date-regex s)
4565 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
4566 @result{} "Date 04-29-2002 12am. (20020429)"
4571 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
4572 @deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
4573 @cindex search and replace
4574 Write to @var{port} selected parts of matches of @var{regexp} in
4575 @var{target}. If @var{port} is @code{#f} then form a string from
4576 those parts and return that. @var{regexp} can be a string or a
4579 This is similar to @code{regexp-substitute}, but allows global
4580 substitutions on @var{target}. Each @var{item} behaves as per
4581 @code{regexp-substitute}, with the following differences,
4585 A function. Called as @code{(@var{item} match)} with the match
4586 structure for the @var{regexp} match, it should return a string to be
4587 written to @var{port}.
4590 The symbol @samp{post}. This doesn't output anything, but instead
4591 causes @code{regexp-substitute/global} to recurse on the unmatched
4592 portion of @var{target}.
4594 This @emph{must} be supplied to perform a global search and replace on
4595 @var{target}; without it @code{regexp-substitute/global} returns after
4596 a single match and output.
4599 For example, to collapse runs of tabs and spaces to a single hyphen
4603 (regexp-substitute/global #f "[ \t]+" "this is the text"
4605 @result{} "this-is-the-text"
4608 Or using a function to reverse the letters in each word,
4611 (regexp-substitute/global #f "[a-z]+" "to do and not-do"
4612 'pre (lambda (m) (string-reverse (match:substring m))) 'post)
4613 @result{} "ot od dna ton-od"
4616 Without the @code{post} symbol, just one regexp match is made. For
4617 example the following is the date example from
4618 @code{regexp-substitute} above, without the need for the separate
4619 @code{string-match} call.
4623 "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
4624 (define s "Date 20020429 12am.")
4625 (regexp-substitute/global #f date-regex s
4626 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
4628 @result{} "Date 04-29-2002 12am. (20020429)"
4633 @node Match Structures
4634 @subsubsection Match Structures
4636 @cindex match structures
4638 A @dfn{match structure} is the object returned by @code{string-match} and
4639 @code{regexp-exec}. It describes which portion of a string, if any,
4640 matched the given regular expression. Match structures include: a
4641 reference to the string that was checked for matches; the starting and
4642 ending positions of the regexp match; and, if the regexp included any
4643 parenthesized subexpressions, the starting and ending positions of each
4646 In each of the regexp match functions described below, the @code{match}
4647 argument must be a match structure returned by a previous call to
4648 @code{string-match} or @code{regexp-exec}. Most of these functions
4649 return some information about the original target string that was
4650 matched against a regular expression; we will call that string
4651 @var{target} for easy reference.
4653 @c begin (scm-doc-string "regex.scm" "regexp-match?")
4654 @deffn {Scheme Procedure} regexp-match? obj
4655 Return @code{#t} if @var{obj} is a match structure returned by a
4656 previous call to @code{regexp-exec}, or @code{#f} otherwise.
4659 @c begin (scm-doc-string "regex.scm" "match:substring")
4660 @deffn {Scheme Procedure} match:substring match [n]
4661 Return the portion of @var{target} matched by subexpression number
4662 @var{n}. Submatch 0 (the default) represents the entire regexp match.
4663 If the regular expression as a whole matched, but the subexpression
4664 number @var{n} did not match, return @code{#f}.
4668 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4672 ;; match starting at offset 6 in the string
4674 (string-match "[0-9][0-9][0-9][0-9]" "blah987654" 6))
4678 @c begin (scm-doc-string "regex.scm" "match:start")
4679 @deffn {Scheme Procedure} match:start match [n]
4680 Return the starting position of submatch number @var{n}.
4683 In the following example, the result is 4, since the match starts at
4687 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4692 @c begin (scm-doc-string "regex.scm" "match:end")
4693 @deffn {Scheme Procedure} match:end match [n]
4694 Return the ending position of submatch number @var{n}.
4697 In the following example, the result is 8, since the match runs between
4698 characters 4 and 8 (i.e. the ``2002'').
4701 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4706 @c begin (scm-doc-string "regex.scm" "match:prefix")
4707 @deffn {Scheme Procedure} match:prefix match
4708 Return the unmatched portion of @var{target} preceding the regexp match.
4711 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4717 @c begin (scm-doc-string "regex.scm" "match:suffix")
4718 @deffn {Scheme Procedure} match:suffix match
4719 Return the unmatched portion of @var{target} following the regexp match.
4723 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4728 @c begin (scm-doc-string "regex.scm" "match:count")
4729 @deffn {Scheme Procedure} match:count match
4730 Return the number of parenthesized subexpressions from @var{match}.
4731 Note that the entire regular expression match itself counts as a
4732 subexpression, and failed submatches are included in the count.
4735 @c begin (scm-doc-string "regex.scm" "match:string")
4736 @deffn {Scheme Procedure} match:string match
4737 Return the original @var{target} string.
4741 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4743 @result{} "blah2002foo"
4747 @node Backslash Escapes
4748 @subsubsection Backslash Escapes
4750 Sometimes you will want a regexp to match characters like @samp{*} or
4751 @samp{$} exactly. For example, to check whether a particular string
4752 represents a menu entry from an Info node, it would be useful to match
4753 it against a regexp like @samp{^* [^:]*::}. However, this won't work;
4754 because the asterisk is a metacharacter, it won't match the @samp{*} at
4755 the beginning of the string. In this case, we want to make the first
4758 You can do this by preceding the metacharacter with a backslash
4759 character @samp{\}. (This is also called @dfn{quoting} the
4760 metacharacter, and is known as a @dfn{backslash escape}.) When Guile
4761 sees a backslash in a regular expression, it considers the following
4762 glyph to be an ordinary character, no matter what special meaning it
4763 would ordinarily have. Therefore, we can make the above example work by
4764 changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells
4765 the regular expression engine to match only a single asterisk in the
4768 Since the backslash is itself a metacharacter, you may force a regexp to
4769 match a backslash in the target string by preceding the backslash with
4770 itself. For example, to find variable references in a @TeX{} program,
4771 you might want to find occurrences of the string @samp{\let\} followed
4772 by any number of alphabetic characters. The regular expression
4773 @samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the
4774 regexp each match a single backslash in the target string.
4776 @c begin (scm-doc-string "regex.scm" "regexp-quote")
4777 @deffn {Scheme Procedure} regexp-quote str
4778 Quote each special character found in @var{str} with a backslash, and
4779 return the resulting string.
4782 @strong{Very important:} Using backslash escapes in Guile source code
4783 (as in Emacs Lisp or C) can be tricky, because the backslash character
4784 has special meaning for the Guile reader. For example, if Guile
4785 encounters the character sequence @samp{\n} in the middle of a string
4786 while processing Scheme code, it replaces those characters with a
4787 newline character. Similarly, the character sequence @samp{\t} is
4788 replaced by a horizontal tab. Several of these @dfn{escape sequences}
4789 are processed by the Guile reader before your code is executed.
4790 Unrecognized escape sequences are ignored: if the characters @samp{\*}
4791 appear in a string, they will be translated to the single character
4794 This translation is obviously undesirable for regular expressions, since
4795 we want to be able to include backslashes in a string in order to
4796 escape regexp metacharacters. Therefore, to make sure that a backslash
4797 is preserved in a string in your Guile program, you must use @emph{two}
4798 consecutive backslashes:
4801 (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
4804 The string in this example is preprocessed by the Guile reader before
4805 any code is executed. The resulting argument to @code{make-regexp} is
4806 the string @samp{^\* [^:]*}, which is what we really want.
4808 This also means that in order to write a regular expression that matches
4809 a single backslash character, the regular expression string in the
4810 source code must include @emph{four} backslashes. Each consecutive pair
4811 of backslashes gets translated by the Guile reader to a single
4812 backslash, and the resulting double-backslash is interpreted by the
4813 regexp engine as matching a single backslash character. Hence:
4816 (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
4819 The reason for the unwieldiness of this syntax is historical. Both
4820 regular expression pattern matchers and Unix string processing systems
4821 have traditionally used backslashes with the special meanings
4822 described above. The POSIX regular expression specification and ANSI C
4823 standard both require these semantics. Attempting to abandon either
4824 convention would cause other kinds of compatibility problems, possibly
4825 more severe ones. Therefore, without extending the Scheme reader to
4826 support strings with different quoting conventions (an ungainly and
4827 confusing extension when implemented in other languages), we must adhere
4828 to this cumbersome escape syntax.
4835 Symbols in Scheme are widely used in three ways: as items of discrete
4836 data, as lookup keys for alists and hash tables, and to denote variable
4839 A @dfn{symbol} is similar to a string in that it is defined by a
4840 sequence of characters. The sequence of characters is known as the
4841 symbol's @dfn{name}. In the usual case --- that is, where the symbol's
4842 name doesn't include any characters that could be confused with other
4843 elements of Scheme syntax --- a symbol is written in a Scheme program by
4844 writing the sequence of characters that make up the name, @emph{without}
4845 any quotation marks or other special syntax. For example, the symbol
4846 whose name is ``multiply-by-2'' is written, simply:
4852 Notice how this differs from a @emph{string} with contents
4853 ``multiply-by-2'', which is written with double quotation marks, like
4860 Looking beyond how they are written, symbols are different from strings
4861 in two important respects.
4863 The first important difference is uniqueness. If the same-looking
4864 string is read twice from two different places in a program, the result
4865 is two @emph{different} string objects whose contents just happen to be
4866 the same. If, on the other hand, the same-looking symbol is read twice
4867 from two different places in a program, the result is the @emph{same}
4868 symbol object both times.
4870 Given two read symbols, you can use @code{eq?} to test whether they are
4871 the same (that is, have the same name). @code{eq?} is the most
4872 efficient comparison operator in Scheme, and comparing two symbols like
4873 this is as fast as comparing, for example, two numbers. Given two
4874 strings, on the other hand, you must use @code{equal?} or
4875 @code{string=?}, which are much slower comparison operators, to
4876 determine whether the strings have the same contents.
4879 (define sym1 (quote hello))
4880 (define sym2 (quote hello))
4881 (eq? sym1 sym2) @result{} #t
4883 (define str1 "hello")
4884 (define str2 "hello")
4885 (eq? str1 str2) @result{} #f
4886 (equal? str1 str2) @result{} #t
4889 The second important difference is that symbols, unlike strings, are not
4890 self-evaluating. This is why we need the @code{(quote @dots{})}s in the
4891 example above: @code{(quote hello)} evaluates to the symbol named
4892 "hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
4893 symbol named "hello" and evaluated as a variable reference @dots{} about
4894 which more below (@pxref{Symbol Variables}).
4897 * Symbol Data:: Symbols as discrete data.
4898 * Symbol Keys:: Symbols as lookup keys.
4899 * Symbol Variables:: Symbols as denoting variables.
4900 * Symbol Primitives:: Operations related to symbols.
4901 * Symbol Props:: Function slots and property lists.
4902 * Symbol Read Syntax:: Extended read syntax for symbols.
4903 * Symbol Uninterned:: Uninterned symbols.
4908 @subsubsection Symbols as Discrete Data
4910 Numbers and symbols are similar to the extent that they both lend
4911 themselves to @code{eq?} comparison. But symbols are more descriptive
4912 than numbers, because a symbol's name can be used directly to describe
4913 the concept for which that symbol stands.
4915 For example, imagine that you need to represent some colours in a
4916 computer program. Using numbers, you would have to choose arbitrarily
4917 some mapping between numbers and colours, and then take care to use that
4918 mapping consistently:
4921 ;; 1=red, 2=green, 3=purple
4923 (if (eq? (colour-of car) 1)
4928 You can make the mapping more explicit and the code more readable by
4936 (if (eq? (colour-of car) red)
4941 But the simplest and clearest approach is not to use numbers at all, but
4942 symbols whose names specify the colours that they refer to:
4945 (if (eq? (colour-of car) 'red)
4949 The descriptive advantages of symbols over numbers increase as the set
4950 of concepts that you want to describe grows. Suppose that a car object
4951 can have other properties as well, such as whether it has or uses:
4955 automatic or manual transmission
4957 leaded or unleaded fuel
4959 power steering (or not).
4963 Then a car's combined property set could be naturally represented and
4964 manipulated as a list of symbols:
4967 (properties-of car1)
4969 (red manual unleaded power-steering)
4971 (if (memq 'power-steering (properties-of car1))
4972 (display "Unfit people can drive this car.\n")
4973 (display "You'll need strong arms to drive this car!\n"))
4975 Unfit people can drive this car.
4978 Remember, the fundamental property of symbols that we are relying on
4979 here is that an occurrence of @code{'red} in one part of a program is an
4980 @emph{indistinguishable} symbol from an occurrence of @code{'red} in
4981 another part of a program; this means that symbols can usefully be
4982 compared using @code{eq?}. At the same time, symbols have naturally
4983 descriptive names. This combination of efficiency and descriptive power
4984 makes them ideal for use as discrete data.
4988 @subsubsection Symbols as Lookup Keys
4990 Given their efficiency and descriptive power, it is natural to use
4991 symbols as the keys in an association list or hash table.
4993 To illustrate this, consider a more structured representation of the car
4994 properties example from the preceding subsection. Rather than
4995 mixing all the properties up together in a flat list, we could use an
4996 association list like this:
4999 (define car1-properties '((colour . red)
5000 (transmission . manual)
5002 (steering . power-assisted)))
5005 Notice how this structure is more explicit and extensible than the flat
5006 list. For example it makes clear that @code{manual} refers to the
5007 transmission rather than, say, the windows or the locking of the car.
5008 It also allows further properties to use the same symbols among their
5009 possible values without becoming ambiguous:
5012 (define car1-properties '((colour . red)
5013 (transmission . manual)
5015 (steering . power-assisted)
5017 (locking . manual)))
5020 With a representation like this, it is easy to use the efficient
5021 @code{assq-XXX} family of procedures (@pxref{Association Lists}) to
5022 extract or change individual pieces of information:
5025 (assq-ref car1-properties 'fuel) @result{} unleaded
5026 (assq-ref car1-properties 'transmission) @result{} manual
5028 (assq-set! car1-properties 'seat-colour 'black)
5031 (transmission . manual)
5033 (steering . power-assisted)
5034 (seat-colour . black)
5035 (locking . manual)))
5038 Hash tables also have keys, and exactly the same arguments apply to the
5039 use of symbols in hash tables as in association lists. The hash value
5040 that Guile uses to decide where to add a symbol-keyed entry to a hash
5041 table can be obtained by calling the @code{symbol-hash} procedure:
5043 @deffn {Scheme Procedure} symbol-hash symbol
5044 @deffnx {C Function} scm_symbol_hash (symbol)
5045 Return a hash value for @var{symbol}.
5048 See @ref{Hash Tables} for information about hash tables in general, and
5049 for why you might choose to use a hash table rather than an association
5053 @node Symbol Variables
5054 @subsubsection Symbols as Denoting Variables
5056 When an unquoted symbol in a Scheme program is evaluated, it is
5057 interpreted as a variable reference, and the result of the evaluation is
5058 the appropriate variable's value.
5060 For example, when the expression @code{(string-length "abcd")} is read
5061 and evaluated, the sequence of characters @code{string-length} is read
5062 as the symbol whose name is "string-length". This symbol is associated
5063 with a variable whose value is the procedure that implements string
5064 length calculation. Therefore evaluation of the @code{string-length}
5065 symbol results in that procedure.
5067 The details of the connection between an unquoted symbol and the
5068 variable to which it refers are explained elsewhere. See @ref{Binding
5069 Constructs}, for how associations between symbols and variables are
5070 created, and @ref{Modules}, for how those associations are affected by
5071 Guile's module system.
5074 @node Symbol Primitives
5075 @subsubsection Operations Related to Symbols
5077 Given any Scheme value, you can determine whether it is a symbol using
5078 the @code{symbol?} primitive:
5081 @deffn {Scheme Procedure} symbol? obj
5082 @deffnx {C Function} scm_symbol_p (obj)
5083 Return @code{#t} if @var{obj} is a symbol, otherwise return
5087 @deftypefn {C Function} int scm_is_symbol (SCM val)
5088 Equivalent to @code{scm_is_true (scm_symbol_p (val))}.
5091 Once you know that you have a symbol, you can obtain its name as a
5092 string by calling @code{symbol->string}. Note that Guile differs by
5093 default from R5RS on the details of @code{symbol->string} as regards
5096 @rnindex symbol->string
5097 @deffn {Scheme Procedure} symbol->string s
5098 @deffnx {C Function} scm_symbol_to_string (s)
5099 Return the name of symbol @var{s} as a string. By default, Guile reads
5100 symbols case-sensitively, so the string returned will have the same case
5101 variation as the sequence of characters that caused @var{s} to be
5104 If Guile is set to read symbols case-insensitively (as specified by
5105 R5RS), and @var{s} comes into being as part of a literal expression
5106 (@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
5107 by a call to the @code{read} or @code{string-ci->symbol} procedures,
5108 Guile converts any alphabetic characters in the symbol's name to
5109 lower case before creating the symbol object, so the string returned
5110 here will be in lower case.
5112 If @var{s} was created by @code{string->symbol}, the case of characters
5113 in the string returned will be the same as that in the string that was
5114 passed to @code{string->symbol}, regardless of Guile's case-sensitivity
5115 setting at the time @var{s} was created.
5117 It is an error to apply mutation procedures like @code{string-set!} to
5118 strings returned by this procedure.
5121 Most symbols are created by writing them literally in code. However it
5122 is also possible to create symbols programmatically using the following
5123 @code{string->symbol} and @code{string-ci->symbol} procedures:
5125 @rnindex string->symbol
5126 @deffn {Scheme Procedure} string->symbol string
5127 @deffnx {C Function} scm_string_to_symbol (string)
5128 Return the symbol whose name is @var{string}. This procedure can create
5129 symbols with names containing special characters or letters in the
5130 non-standard case, but it is usually a bad idea to create such symbols
5131 because in some implementations of Scheme they cannot be read as
5135 @deffn {Scheme Procedure} string-ci->symbol str
5136 @deffnx {C Function} scm_string_ci_to_symbol (str)
5137 Return the symbol whose name is @var{str}. If Guile is currently
5138 reading symbols case-insensitively, @var{str} is converted to lowercase
5139 before the returned symbol is looked up or created.
5142 The following examples illustrate Guile's detailed behaviour as regards
5143 the case-sensitivity of symbols:
5146 (read-enable 'case-insensitive) ; R5RS compliant behaviour
5148 (symbol->string 'flying-fish) @result{} "flying-fish"
5149 (symbol->string 'Martin) @result{} "martin"
5151 (string->symbol "Malvina")) @result{} "Malvina"
5153 (eq? 'mISSISSIppi 'mississippi) @result{} #t
5154 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
5155 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
5157 (string->symbol (symbol->string 'LolliPop))) @result{} #t
5158 (string=? "K. Harper, M.D."
5160 (string->symbol "K. Harper, M.D."))) @result{} #t
5162 (read-disable 'case-insensitive) ; Guile default behaviour
5164 (symbol->string 'flying-fish) @result{} "flying-fish"
5165 (symbol->string 'Martin) @result{} "Martin"
5167 (string->symbol "Malvina")) @result{} "Malvina"
5169 (eq? 'mISSISSIppi 'mississippi) @result{} #f
5170 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
5171 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
5173 (string->symbol (symbol->string 'LolliPop))) @result{} #t
5174 (string=? "K. Harper, M.D."
5176 (string->symbol "K. Harper, M.D."))) @result{} #t
5179 From C, there are lower level functions that construct a Scheme symbol
5180 from a C string in the current locale encoding.
5182 When you want to do more from C, you should convert between symbols
5183 and strings using @code{scm_symbol_to_string} and
5184 @code{scm_string_to_symbol} and work with the strings.
5186 @deffn {C Function} scm_from_locale_symbol (const char *name)
5187 @deffnx {C Function} scm_from_locale_symboln (const char *name, size_t len)
5188 Construct and return a Scheme symbol whose name is specified by
5189 @var{name}. For @code{scm_from_locale_symbol}, @var{name} must be null
5190 terminated; for @code{scm_from_locale_symboln} the length of @var{name} is
5191 specified explicitly by @var{len}.
5194 @deftypefn {C Function} SCM scm_take_locale_symbol (char *str)
5195 @deftypefnx {C Function} SCM scm_take_locale_symboln (char *str, size_t len)
5196 Like @code{scm_from_locale_symbol} and @code{scm_from_locale_symboln},
5197 respectively, but also frees @var{str} with @code{free} eventually.
5198 Thus, you can use this function when you would free @var{str} anyway
5199 immediately after creating the Scheme string. In certain cases, Guile
5200 can then use @var{str} directly as its internal representation.
5203 The size of a symbol can also be obtained from C:
5205 @deftypefn {C Function} size_t scm_c_symbol_length (SCM sym)
5206 Return the number of characters in @var{sym}.
5209 Finally, some applications, especially those that generate new Scheme
5210 code dynamically, need to generate symbols for use in the generated
5211 code. The @code{gensym} primitive meets this need:
5213 @deffn {Scheme Procedure} gensym [prefix]
5214 @deffnx {C Function} scm_gensym (prefix)
5215 Create a new symbol with a name constructed from a prefix and a counter
5216 value. The string @var{prefix} can be specified as an optional
5217 argument. Default prefix is @samp{@w{ g}}. The counter is increased by 1
5218 at each call. There is no provision for resetting the counter.
5221 The symbols generated by @code{gensym} are @emph{likely} to be unique,
5222 since their names begin with a space and it is only otherwise possible
5223 to generate such symbols if a programmer goes out of their way to do
5224 so. Uniqueness can be guaranteed by instead using uninterned symbols
5225 (@pxref{Symbol Uninterned}), though they can't be usefully written out
5230 @subsubsection Function Slots and Property Lists
5232 In traditional Lisp dialects, symbols are often understood as having
5233 three kinds of value at once:
5237 a @dfn{variable} value, which is used when the symbol appears in
5238 code in a variable reference context
5241 a @dfn{function} value, which is used when the symbol appears in
5242 code in a function name position (i.e. as the first element in an
5246 a @dfn{property list} value, which is used when the symbol is given as
5247 the first argument to Lisp's @code{put} or @code{get} functions.
5250 Although Scheme (as one of its simplifications with respect to Lisp)
5251 does away with the distinction between variable and function namespaces,
5252 Guile currently retains some elements of the traditional structure in
5253 case they turn out to be useful when implementing translators for other
5254 languages, in particular Emacs Lisp.
5256 Specifically, Guile symbols have two extra slots. for a symbol's
5257 property list, and for its ``function value.'' The following procedures
5258 are provided to access these slots.
5260 @deffn {Scheme Procedure} symbol-fref symbol
5261 @deffnx {C Function} scm_symbol_fref (symbol)
5262 Return the contents of @var{symbol}'s @dfn{function slot}.
5265 @deffn {Scheme Procedure} symbol-fset! symbol value
5266 @deffnx {C Function} scm_symbol_fset_x (symbol, value)
5267 Set the contents of @var{symbol}'s function slot to @var{value}.
5270 @deffn {Scheme Procedure} symbol-pref symbol
5271 @deffnx {C Function} scm_symbol_pref (symbol)
5272 Return the @dfn{property list} currently associated with @var{symbol}.
5275 @deffn {Scheme Procedure} symbol-pset! symbol value
5276 @deffnx {C Function} scm_symbol_pset_x (symbol, value)
5277 Set @var{symbol}'s property list to @var{value}.
5280 @deffn {Scheme Procedure} symbol-property sym prop
5281 From @var{sym}'s property list, return the value for property
5282 @var{prop}. The assumption is that @var{sym}'s property list is an
5283 association list whose keys are distinguished from each other using
5284 @code{equal?}; @var{prop} should be one of the keys in that list. If
5285 the property list has no entry for @var{prop}, @code{symbol-property}
5289 @deffn {Scheme Procedure} set-symbol-property! sym prop val
5290 In @var{sym}'s property list, set the value for property @var{prop} to
5291 @var{val}, or add a new entry for @var{prop}, with value @var{val}, if
5292 none already exists. For the structure of the property list, see
5293 @code{symbol-property}.
5296 @deffn {Scheme Procedure} symbol-property-remove! sym prop
5297 From @var{sym}'s property list, remove the entry for property
5298 @var{prop}, if there is one. For the structure of the property list,
5299 see @code{symbol-property}.
5302 Support for these extra slots may be removed in a future release, and it
5303 is probably better to avoid using them. For a more modern and Schemely
5304 approach to properties, see @ref{Object Properties}.
5307 @node Symbol Read Syntax
5308 @subsubsection Extended Read Syntax for Symbols
5310 The read syntax for a symbol is a sequence of letters, digits, and
5311 @dfn{extended alphabetic characters}, beginning with a character that
5312 cannot begin a number. In addition, the special cases of @code{+},
5313 @code{-}, and @code{...} are read as symbols even though numbers can
5314 begin with @code{+}, @code{-} or @code{.}.
5316 Extended alphabetic characters may be used within identifiers as if
5317 they were letters. The set of extended alphabetic characters is:
5320 ! $ % & * + - . / : < = > ? @@ ^ _ ~
5323 In addition to the standard read syntax defined above (which is taken
5324 from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
5325 Scheme})), Guile provides an extended symbol read syntax that allows the
5326 inclusion of unusual characters such as space characters, newlines and
5327 parentheses. If (for whatever reason) you need to write a symbol
5328 containing characters not mentioned above, you can do so as follows.
5332 Begin the symbol with the characters @code{#@{},
5335 write the characters of the symbol and
5338 finish the symbol with the characters @code{@}#}.
5341 Here are a few examples of this form of read syntax. The first symbol
5342 needs to use extended syntax because it contains a space character, the
5343 second because it contains a line break, and the last because it looks
5355 Although Guile provides this extended read syntax for symbols,
5356 widespread usage of it is discouraged because it is not portable and not
5360 @node Symbol Uninterned
5361 @subsubsection Uninterned Symbols
5363 What makes symbols useful is that they are automatically kept unique.
5364 There are no two symbols that are distinct objects but have the same
5365 name. But of course, there is no rule without exception. In addition
5366 to the normal symbols that have been discussed up to now, you can also
5367 create special @dfn{uninterned} symbols that behave slightly
5370 To understand what is different about them and why they might be useful,
5371 we look at how normal symbols are actually kept unique.
5373 Whenever Guile wants to find the symbol with a specific name, for
5374 example during @code{read} or when executing @code{string->symbol}, it
5375 first looks into a table of all existing symbols to find out whether a
5376 symbol with the given name already exists. When this is the case, Guile
5377 just returns that symbol. When not, a new symbol with the name is
5378 created and entered into the table so that it can be found later.
5380 Sometimes you might want to create a symbol that is guaranteed `fresh',
5381 i.e. a symbol that did not exist previously. You might also want to
5382 somehow guarantee that no one else will ever unintentionally stumble
5383 across your symbol in the future. These properties of a symbol are
5384 often needed when generating code during macro expansion. When
5385 introducing new temporary variables, you want to guarantee that they
5386 don't conflict with variables in other people's code.
5388 The simplest way to arrange for this is to create a new symbol but
5389 not enter it into the global table of all symbols. That way, no one
5390 will ever get access to your symbol by chance. Symbols that are not in
5391 the table are called @dfn{uninterned}. Of course, symbols that
5392 @emph{are} in the table are called @dfn{interned}.
5394 You create new uninterned symbols with the function @code{make-symbol}.
5395 You can test whether a symbol is interned or not with
5396 @code{symbol-interned?}.
5398 Uninterned symbols break the rule that the name of a symbol uniquely
5399 identifies the symbol object. Because of this, they can not be written
5400 out and read back in like interned symbols. Currently, Guile has no
5401 support for reading uninterned symbols. Note that the function
5402 @code{gensym} does not return uninterned symbols for this reason.
5404 @deffn {Scheme Procedure} make-symbol name
5405 @deffnx {C Function} scm_make_symbol (name)
5406 Return a new uninterned symbol with the name @var{name}. The returned
5407 symbol is guaranteed to be unique and future calls to
5408 @code{string->symbol} will not return it.
5411 @deffn {Scheme Procedure} symbol-interned? symbol
5412 @deffnx {C Function} scm_symbol_interned_p (symbol)
5413 Return @code{#t} if @var{symbol} is interned, otherwise return
5420 (define foo-1 (string->symbol "foo"))
5421 (define foo-2 (string->symbol "foo"))
5422 (define foo-3 (make-symbol "foo"))
5423 (define foo-4 (make-symbol "foo"))
5427 ; Two interned symbols with the same name are the same object,
5431 ; but a call to make-symbol with the same name returns a
5436 ; A call to make-symbol always returns a new object, even for
5440 @result{} #<uninterned-symbol foo 8085290>
5441 ; Uninterned symbols print differently from interned symbols,
5445 ; but they are still symbols,
5447 (symbol-interned? foo-3)
5449 ; just not interned.
5454 @subsection Keywords
5457 Keywords are self-evaluating objects with a convenient read syntax that
5458 makes them easy to type.
5460 Guile's keyword support conforms to R5RS, and adds a (switchable) read
5461 syntax extension to permit keywords to begin with @code{:} as well as
5462 @code{#:}, or to end with @code{:}.
5465 * Why Use Keywords?:: Motivation for keyword usage.
5466 * Coding With Keywords:: How to use keywords.
5467 * Keyword Read Syntax:: Read syntax for keywords.
5468 * Keyword Procedures:: Procedures for dealing with keywords.
5471 @node Why Use Keywords?
5472 @subsubsection Why Use Keywords?
5474 Keywords are useful in contexts where a program or procedure wants to be
5475 able to accept a large number of optional arguments without making its
5476 interface unmanageable.
5478 To illustrate this, consider a hypothetical @code{make-window}
5479 procedure, which creates a new window on the screen for drawing into
5480 using some graphical toolkit. There are many parameters that the caller
5481 might like to specify, but which could also be sensibly defaulted, for
5486 color depth -- Default: the color depth for the screen
5489 background color -- Default: white
5492 width -- Default: 600
5495 height -- Default: 400
5498 If @code{make-window} did not use keywords, the caller would have to
5499 pass in a value for each possible argument, remembering the correct
5500 argument order and using a special value to indicate the default value
5504 (make-window 'default ;; Color depth
5505 'default ;; Background color
5508 @dots{}) ;; More make-window arguments
5511 With keywords, on the other hand, defaulted arguments are omitted, and
5512 non-default arguments are clearly tagged by the appropriate keyword. As
5513 a result, the invocation becomes much clearer:
5516 (make-window #:width 800 #:height 100)
5519 On the other hand, for a simpler procedure with few arguments, the use
5520 of keywords would be a hindrance rather than a help. The primitive
5521 procedure @code{cons}, for example, would not be improved if it had to
5525 (cons #:car x #:cdr y)
5528 So the decision whether to use keywords or not is purely pragmatic: use
5529 them if they will clarify the procedure invocation at point of call.
5531 @node Coding With Keywords
5532 @subsubsection Coding With Keywords
5534 If a procedure wants to support keywords, it should take a rest argument
5535 and then use whatever means is convenient to extract keywords and their
5536 corresponding arguments from the contents of that rest argument.
5538 The following example illustrates the principle: the code for
5539 @code{make-window} uses a helper procedure called
5540 @code{get-keyword-value} to extract individual keyword arguments from
5544 (define (get-keyword-value args keyword default)
5545 (let ((kv (memq keyword args)))
5546 (if (and kv (>= (length kv) 2))
5550 (define (make-window . args)
5551 (let ((depth (get-keyword-value args #:depth screen-depth))
5552 (bg (get-keyword-value args #:bg "white"))
5553 (width (get-keyword-value args #:width 800))
5554 (height (get-keyword-value args #:height 100))
5559 But you don't need to write @code{get-keyword-value}. The @code{(ice-9
5560 optargs)} module provides a set of powerful macros that you can use to
5561 implement keyword-supporting procedures like this:
5564 (use-modules (ice-9 optargs))
5566 (define (make-window . args)
5567 (let-keywords args #f ((depth screen-depth)
5575 Or, even more economically, like this:
5578 (use-modules (ice-9 optargs))
5580 (define* (make-window #:key (depth screen-depth)
5587 For further details on @code{let-keywords}, @code{define*} and other
5588 facilities provided by the @code{(ice-9 optargs)} module, see
5589 @ref{Optional Arguments}.
5592 @node Keyword Read Syntax
5593 @subsubsection Keyword Read Syntax
5595 Guile, by default, only recognizes a keyword syntax that is compatible
5596 with R5RS. A token of the form @code{#:NAME}, where @code{NAME} has the
5597 same syntax as a Scheme symbol (@pxref{Symbol Read Syntax}), is the
5598 external representation of the keyword named @code{NAME}. Keyword
5599 objects print using this syntax as well, so values containing keyword
5600 objects can be read back into Guile. When used in an expression,
5601 keywords are self-quoting objects.
5603 If the @code{keyword} read option is set to @code{'prefix}, Guile also
5604 recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
5605 of the form @code{:NAME} are read as symbols, as required by R5RS.
5607 @cindex SRFI-88 keyword syntax
5609 If the @code{keyword} read option is set to @code{'postfix}, Guile
5610 recognizes the SRFI-88 read syntax @code{NAME:} (@pxref{SRFI-88}).
5611 Otherwise, tokens of this form are read as symbols.
5613 To enable and disable the alternative non-R5RS keyword syntax, you use
5614 the @code{read-set!} procedure documented in @ref{User level options
5615 interfaces} and @ref{Reader options}. Note that the @code{prefix} and
5616 @code{postfix} syntax are mutually exclusive.
5619 (read-set! keywords 'prefix)
5629 (read-set! keywords 'postfix)
5639 (read-set! keywords #f)
5647 ERROR: In expression :type:
5648 ERROR: Unbound variable: :type
5649 ABORT: (unbound-variable)
5652 @node Keyword Procedures
5653 @subsubsection Keyword Procedures
5655 @deffn {Scheme Procedure} keyword? obj
5656 @deffnx {C Function} scm_keyword_p (obj)
5657 Return @code{#t} if the argument @var{obj} is a keyword, else
5661 @deffn {Scheme Procedure} keyword->symbol keyword
5662 @deffnx {C Function} scm_keyword_to_symbol (keyword)
5663 Return the symbol with the same name as @var{keyword}.
5666 @deffn {Scheme Procedure} symbol->keyword symbol
5667 @deffnx {C Function} scm_symbol_to_keyword (symbol)
5668 Return the keyword with the same name as @var{symbol}.
5671 @deftypefn {C Function} int scm_is_keyword (SCM obj)
5672 Equivalent to @code{scm_is_true (scm_keyword_p (@var{obj}))}.
5675 @deftypefn {C Function} SCM scm_from_locale_keyword (const char *str)
5676 @deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *str, size_t len)
5677 Equivalent to @code{scm_symbol_to_keyword (scm_from_locale_symbol
5678 (@var{str}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln
5679 (@var{str}, @var{len}))}, respectively.
5683 @subsection ``Functionality-Centric'' Data Types
5685 Procedures and macros are documented in their own chapter: see
5686 @ref{Procedures and Macros}.
5688 Variable objects are documented as part of the description of Guile's
5689 module system: see @ref{Variables}.
5691 Asyncs, dynamic roots and fluids are described in the chapter on
5692 scheduling: see @ref{Scheduling}.
5694 Hooks are documented in the chapter on general utility functions: see
5697 Ports are described in the chapter on I/O: see @ref{Input and Output}.
5701 @c TeX-master: "guile.texi"