2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
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:: New character names.
46 * Strings:: Special things about strings.
47 * Regular Expressions:: Pattern matching and substitution.
49 * Keywords:: Self-quoting, customizable display keywords.
50 * Other Types:: "Functionality-centric" data types.
58 The two boolean values are @code{#t} for true and @code{#f} for false.
60 Boolean values are returned by predicate procedures, such as the general
61 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
62 (@pxref{Equality}) and numerical and string comparison operators like
63 @code{string=?} (@pxref{String Comparison}) and @code{<=}
73 (equal? "house" "houses")
81 In test condition contexts like @code{if} and @code{cond} (@pxref{if
82 cond case}), where a group of subexpressions will be evaluated only if a
83 @var{condition} expression evaluates to ``true'', ``true'' means any
84 value at all except @code{#f}.
97 A result of this asymmetry is that typical Scheme source code more often
98 uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
99 represent an @code{if} or @code{cond} false value, whereas @code{#t} is
100 not necessary to represent an @code{if} or @code{cond} true value.
102 It is important to note that @code{#f} is @strong{not} equivalent to any
103 other Scheme value. In particular, @code{#f} is not the same as the
104 number 0 (like in C and C++), and not the same as the ``empty list''
105 (like in some Lisp dialects).
107 In C, the two Scheme boolean values are available as the two constants
108 @code{SCM_BOOL_T} for @code{#t} and @code{SCM_BOOL_F} for @code{#f}.
109 Care must be taken with the false value @code{SCM_BOOL_F}: it is not
110 false when used in C conditionals. In order to test for it, use
111 @code{scm_is_false} or @code{scm_is_true}.
114 @deffn {Scheme Procedure} not x
115 @deffnx {C Function} scm_not (x)
116 Return @code{#t} if @var{x} is @code{#f}, else return @code{#f}.
120 @deffn {Scheme Procedure} boolean? obj
121 @deffnx {C Function} scm_boolean_p (obj)
122 Return @code{#t} if @var{obj} is either @code{#t} or @code{#f}, else
126 @deftypevr {C Macro} SCM SCM_BOOL_T
127 The @code{SCM} representation of the Scheme object @code{#t}.
130 @deftypevr {C Macro} SCM SCM_BOOL_F
131 The @code{SCM} representation of the Scheme object @code{#f}.
134 @deftypefn {C Function} int scm_is_true (SCM obj)
135 Return @code{0} if @var{obj} is @code{#f}, else return @code{1}.
138 @deftypefn {C Function} int scm_is_false (SCM obj)
139 Return @code{1} if @var{obj} is @code{#f}, else return @code{0}.
142 @deftypefn {C Function} int scm_is_bool (SCM obj)
143 Return @code{1} if @var{obj} is either @code{#t} or @code{#f}, else
147 @deftypefn {C Function} SCM scm_from_bool (int val)
148 Return @code{#f} if @var{val} is @code{0}, else return @code{#t}.
151 @deftypefn {C Function} int scm_to_bool (SCM val)
152 Return @code{1} if @var{val} is @code{SCM_BOOL_T}, return @code{0}
153 when @var{val} is @code{SCM_BOOL_F}, else signal a `wrong type' error.
155 You should probably use @code{scm_is_true} instead of this function
156 when you just want to test a @code{SCM} value for trueness.
160 @subsection Numerical data types
163 Guile supports a rich ``tower'' of numerical types --- integer,
164 rational, real and complex --- and provides an extensive set of
165 mathematical and scientific functions for operating on numerical
166 data. This section of the manual documents those types and functions.
168 You may also find it illuminating to read R5RS's presentation of numbers
169 in Scheme, which is particularly clear and accessible: see
170 @ref{Numbers,,,r5rs,R5RS}.
173 * Numerical Tower:: Scheme's numerical "tower".
174 * Integers:: Whole numbers.
175 * Reals and Rationals:: Real and rational numbers.
176 * Complex Numbers:: Complex numbers.
177 * Exactness:: Exactness and inexactness.
178 * Number Syntax:: Read syntax for numerical data.
179 * Integer Operations:: Operations on integer values.
180 * Comparison:: Comparison predicates.
181 * Conversion:: Converting numbers to and from strings.
182 * Complex:: Complex number operations.
183 * Arithmetic:: Arithmetic functions.
184 * Scientific:: Scientific functions.
185 * Primitive Numerics:: Primitive numeric functions.
186 * Bitwise Operations:: Logical AND, OR, NOT, and so on.
187 * Random:: Random number generation.
191 @node Numerical Tower
192 @subsubsection Scheme's Numerical ``Tower''
195 Scheme's numerical ``tower'' consists of the following categories of
200 Whole numbers, positive or negative; e.g.@: --5, 0, 18.
203 The set of numbers that can be expressed as @math{@var{p}/@var{q}}
204 where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
205 pi (an irrational number) doesn't. These include integers
209 The set of numbers that describes all possible positions along a
210 one-dimensional line. This includes rationals as well as irrational
213 @item complex numbers
214 The set of numbers that describes all possible positions in a two
215 dimensional space. This includes real as well as imaginary numbers
216 (@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
217 @var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
221 It is called a tower because each category ``sits on'' the one that
222 follows it, in the sense that every integer is also a rational, every
223 rational is also real, and every real number is also a complex number
224 (but with zero imaginary part).
226 In addition to the classification into integers, rationals, reals and
227 complex numbers, Scheme also distinguishes between whether a number is
228 represented exactly or not. For example, the result of
229 @m{2\sin(\pi/4),sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)} but Guile
230 can neither represent @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
231 Instead, it stores an inexact approximation, using the C type
234 Guile can represent exact rationals of any magnitude, inexact
235 rationals that fit into a C @code{double}, and inexact complex numbers
236 with @code{double} real and imaginary parts.
238 The @code{number?} predicate may be applied to any Scheme value to
239 discover whether the value is any of the supported numerical types.
241 @deffn {Scheme Procedure} number? obj
242 @deffnx {C Function} scm_number_p (obj)
243 Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
252 (number? "hello there!")
255 (define pi 3.141592654)
260 @deftypefn {C Function} int scm_is_number (SCM obj)
261 This is equivalent to @code{scm_is_true (scm_number_p (obj))}.
264 The next few subsections document each of Guile's numerical data types
268 @subsubsection Integers
270 @tpindex Integer numbers
274 Integers are whole numbers, that is numbers with no fractional part,
275 such as 2, 83, and @minus{}3789.
277 Integers in Guile can be arbitrarily big, as shown by the following
281 (define (factorial n)
282 (let loop ((n n) (product 1))
285 (loop (- n 1) (* product n)))))
291 @result{} 2432902008176640000
294 @result{} -119622220865480194561963161495657715064383733760000000000
297 Readers whose background is in programming languages where integers are
298 limited by the need to fit into just 4 or 8 bytes of memory may find
299 this surprising, or suspect that Guile's representation of integers is
300 inefficient. In fact, Guile achieves a near optimal balance of
301 convenience and efficiency by using the host computer's native
302 representation of integers where possible, and a more general
303 representation where the required number does not fit in the native
304 form. Conversion between these two representations is automatic and
305 completely invisible to the Scheme level programmer.
307 The infinities @samp{+inf.0} and @samp{-inf.0} are considered to be
308 inexact integers. They are explained in detail in the next section,
309 together with reals and rationals.
311 C has a host of different integer types, and Guile offers a host of
312 functions to convert between them and the @code{SCM} representation.
313 For example, a C @code{int} can be handled with @code{scm_to_int} and
314 @code{scm_from_int}. Guile also defines a few C integer types of its
315 own, to help with differences between systems.
317 C integer types that are not covered can be handled with the generic
318 @code{scm_to_signed_integer} and @code{scm_from_signed_integer} for
319 signed types, or with @code{scm_to_unsigned_integer} and
320 @code{scm_from_unsigned_integer} for unsigned types.
322 Scheme integers can be exact and inexact. For example, a number
323 written as @code{3.0} with an explicit decimal-point is inexact, but
324 it is also an integer. The functions @code{integer?} and
325 @code{scm_is_integer} report true for such a number, but the functions
326 @code{scm_is_signed_integer} and @code{scm_is_unsigned_integer} only
327 allow exact integers and thus report false. Likewise, the conversion
328 functions like @code{scm_to_signed_integer} only accept exact
331 The motivation for this behavior is that the inexactness of a number
332 should not be lost silently. If you want to allow inexact integers,
333 you can explicitely insert a call to @code{inexact->exact} or to its C
334 equivalent @code{scm_inexact_to_exact}. (Only inexact integers will
335 be converted by this call into exact integers; inexact non-integers
336 will become exact fractions.)
338 @deffn {Scheme Procedure} integer? x
339 @deffnx {C Function} scm_integer_p (x)
340 Return @code{#t} if @var{x} is an exactor inexact integer number, else
358 @deftypefn {C Function} int scm_is_integer (SCM x)
359 This is equivalent to @code{scm_is_true (scm_integer_p (x))}.
362 @defvr {C Type} scm_t_int8
363 @defvrx {C Type} scm_t_uint8
364 @defvrx {C Type} scm_t_int16
365 @defvrx {C Type} scm_t_uint16
366 @defvrx {C Type} scm_t_int32
367 @defvrx {C Type} scm_t_uint32
368 @defvrx {C Type} scm_t_int64
369 @defvrx {C Type} scm_t_uint64
370 @defvrx {C Type} scm_t_intmax
371 @defvrx {C Type} scm_t_uintmax
372 The C types are equivalent to the corresponding ISO C types but are
373 defined on all platforms, with the exception of @code{scm_t_int64} and
374 @code{scm_t_uint64}, which are only defined when a 64-bit type is
375 available. For example, @code{scm_t_int8} is equivalent to
378 You can regard these definitions as a stop-gap measure until all
379 platforms provide these types. If you know that all the platforms
380 that you are interested in already provide these types, it is better
381 to use them directly instead of the types provided by Guile.
384 @deftypefn {C Function} int scm_is_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
385 @deftypefnx {C Function} int scm_is_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
386 Return @code{1} when @var{x} represents an exact integer that is
387 between @var{min} and @var{max}, inclusive.
389 These functions can be used to check whether a @code{SCM} value will
390 fit into a given range, such as the range of a given C integer type.
391 If you just want to convert a @code{SCM} value to a given C integer
392 type, use one of the conversion functions directly.
395 @deftypefn {C Function} scm_t_intmax scm_to_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
396 @deftypefnx {C Function} scm_t_uintmax scm_to_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
397 When @var{x} represents an exact integer that is between @var{min} and
398 @var{max} inclusive, return that integer. Else signal an error,
399 either a `wrong-type' error when @var{x} is not an exact integer, or
400 an `out-of-range' error when it doesn't fit the given range.
403 @deftypefn {C Function} SCM scm_from_signed_integer (scm_t_intmax x)
404 @deftypefnx {C Function} SCM scm_from_unsigned_integer (scm_t_uintmax x)
405 Return the @code{SCM} value that represents the integer @var{x}. This
406 function will always succeed and will always return an exact number.
409 @deftypefn {C Function} char scm_to_char (SCM x)
410 @deftypefnx {C Function} {signed char} scm_to_schar (SCM x)
411 @deftypefnx {C Function} {unsigned char} scm_to_uchar (SCM x)
412 @deftypefnx {C Function} short scm_to_short (SCM x)
413 @deftypefnx {C Function} {unsigned short} scm_to_ushort (SCM x)
414 @deftypefnx {C Function} int scm_to_int (SCM x)
415 @deftypefnx {C Function} {unsigned int} scm_to_uint (SCM x)
416 @deftypefnx {C Function} long scm_to_long (SCM x)
417 @deftypefnx {C Function} {unsigned long} scm_to_ulong (SCM x)
418 @deftypefnx {C Function} {long long} scm_to_long_long (SCM x)
419 @deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x)
420 @deftypefnx {C Function} size_t scm_to_size_t (SCM x)
421 @deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x)
422 @deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x)
423 @deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x)
424 @deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x)
425 @deftypefnx {C Function} scm_t_uint16 scm_to_uint16 (SCM x)
426 @deftypefnx {C Function} scm_t_int32 scm_to_int32 (SCM x)
427 @deftypefnx {C Function} scm_t_uint32 scm_to_uint32 (SCM x)
428 @deftypefnx {C Function} scm_t_int64 scm_to_int64 (SCM x)
429 @deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x)
430 @deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x)
431 @deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x)
432 When @var{x} represents an exact integer that fits into the indicated
433 C type, return that integer. Else signal an error, either a
434 `wrong-type' error when @var{x} is not an exact integer, or an
435 `out-of-range' error when it doesn't fit the given range.
437 The functions @code{scm_to_long_long}, @code{scm_to_ulong_long},
438 @code{scm_to_int64}, and @code{scm_to_uint64} are only available when
439 the corresponding types are.
442 @deftypefn {C Function} SCM scm_from_char (char x)
443 @deftypefnx {C Function} SCM scm_from_schar (signed char x)
444 @deftypefnx {C Function} SCM scm_from_uchar (unsigned char x)
445 @deftypefnx {C Function} SCM scm_from_short (short x)
446 @deftypefnx {C Function} SCM scm_from_ushort (unsigned short x)
447 @deftypefnx {C Function} SCM scm_from_int (int x)
448 @deftypefnx {C Function} SCM scm_from_uint (unsigned int x)
449 @deftypefnx {C Function} SCM scm_from_long (long x)
450 @deftypefnx {C Function} SCM scm_from_ulong (unsigned long x)
451 @deftypefnx {C Function} SCM scm_from_long_long (long long x)
452 @deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x)
453 @deftypefnx {C Function} SCM scm_from_size_t (size_t x)
454 @deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x)
455 @deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x)
456 @deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x)
457 @deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x)
458 @deftypefnx {C Function} SCM scm_from_uint16 (scm_t_uint16 x)
459 @deftypefnx {C Function} SCM scm_from_int32 (scm_t_int32 x)
460 @deftypefnx {C Function} SCM scm_from_uint32 (scm_t_uint32 x)
461 @deftypefnx {C Function} SCM scm_from_int64 (scm_t_int64 x)
462 @deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x)
463 @deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x)
464 @deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x)
465 Return the @code{SCM} value that represents the integer @var{x}.
466 These functions will always succeed and will always return an exact
470 @node Reals and Rationals
471 @subsubsection Real and Rational Numbers
472 @tpindex Real numbers
473 @tpindex Rational numbers
478 Mathematically, the real numbers are the set of numbers that describe
479 all possible points along a continuous, infinite, one-dimensional line.
480 The rational numbers are the set of all numbers that can be written as
481 fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
482 All rational numbers are also real, but there are real numbers that
483 are not rational, for example the square root of 2, and pi.
485 Guile can represent both exact and inexact rational numbers, but it
486 can not represent irrational numbers. Exact rationals are represented
487 by storing the numerator and denominator as two exact integers.
488 Inexact rationals are stored as floating point numbers using the C
491 Exact rationals are written as a fraction of integers. There must be
492 no whitespace around the slash:
499 Even though the actual encoding of inexact rationals is in binary, it
500 may be helpful to think of it as a decimal number with a limited
501 number of significant figures and a decimal point somewhere, since
502 this corresponds to the standard notation for non-whole numbers. For
508 -5648394822220000000000.0
512 The limited precision of Guile's encoding means that any ``real'' number
513 in Guile can be written in a rational form, by multiplying and then dividing
514 by sufficient powers of 10 (or in fact, 2). For example,
515 @samp{-0.00000142857931198} is the same as @minus{}142857931198 divided by
516 100000000000000000. In Guile's current incarnation, therefore, the
517 @code{rational?} and @code{real?} predicates are equivalent.
520 Dividing by an exact zero leads to a error message, as one might
521 expect. However, dividing by an inexact zero does not produce an
522 error. Instead, the result of the division is either plus or minus
523 infinity, depending on the sign of the divided number.
525 The infinities are written @samp{+inf.0} and @samp{-inf.0},
526 respectivly. This syntax is also recognized by @code{read} as an
527 extension to the usual Scheme syntax.
529 Dividing zero by zero yields something that is not a number at all:
530 @samp{+nan.0}. This is the special `not a number' value.
532 On platforms that follow @acronym{IEEE} 754 for their floating point
533 arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
534 are implemented using the corresponding @acronym{IEEE} 754 values.
535 They behave in arithmetic operations like @acronym{IEEE} 754 describes
536 it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
538 The infinities are inexact integers and are considered to be both even
539 and odd. While @samp{+nan.0} is not @code{=} to itself, it is
540 @code{eqv?} to itself.
542 To test for the special values, use the functions @code{inf?} and
545 @deffn {Scheme Procedure} real? obj
546 @deffnx {C Function} scm_real_p (obj)
547 Return @code{#t} if @var{obj} is a real number, else @code{#f}. Note
548 that the sets of integer and rational values form subsets of the set
549 of real numbers, so the predicate will also be fulfilled if @var{obj}
550 is an integer number or a rational number.
553 @deffn {Scheme Procedure} rational? x
554 @deffnx {C Function} scm_rational_p (x)
555 Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise.
556 Note that the set of integer values forms a subset of the set of
557 rational numbers, i. e. the predicate will also be fulfilled if
558 @var{x} is an integer number.
560 Since Guile can not represent irrational numbers, every number
561 satisfying @code{real?} also satisfies @code{rational?} in Guile.
564 @deffn {Scheme Procedure} rationalize x eps
565 @deffnx {C Function} scm_rationalize (x, eps)
566 Returns the @emph{simplest} rational number differing
567 from @var{x} by no more than @var{eps}.
569 As required by @acronym{R5RS}, @code{rationalize} only returns an
570 exact result when both its arguments are exact. Thus, you might need
571 to use @code{inexact->exact} on the arguments.
574 (rationalize (inexact->exact 1.2) 1/100)
580 @deffn {Scheme Procedure} inf? x
581 @deffnx {C Function} scm_inf_p (x)
582 Return @code{#t} if @var{x} is either @samp{+inf.0} or @samp{-inf.0},
586 @deffn {Scheme Procedure} nan? x
587 @deffnx {C Function} scm_nan_p (x)
588 Return @code{#t} if @var{x} is @samp{+nan.0}, @code{#f} otherwise.
591 @deffn {Scheme Procedure} numerator x
592 @deffnx {C Function} scm_numerator (x)
593 Return the numerator of the rational number @var{x}.
596 @deffn {Scheme Procedure} denominator x
597 @deffnx {C Function} scm_denominator (x)
598 Return the denominator of the rational number @var{x}.
601 @deftypefn {C Function} int scm_is_real (SCM val)
602 @deftypefnx {C Function} int scm_is_rational (SCM val)
603 Equivalent to @code{scm_is_true (scm_real_p (val))} and
604 @code{scm_is_true (scm_rational_p (val))}, respectively.
607 @deftypefn {C Function} double scm_to_double (SCM val)
608 Returns the number closest to @var{val} that is representable as a
609 @code{double}. Returns infinity for a @var{val} that is too large in
610 magnitude. The argument @var{val} must be a real number.
613 @deftypefn {C Function} SCM scm_from_double (double val)
614 Return the @code{SCM} value that representats @var{val}. The returned
615 value is inexact according to the predicate @code{inexact?}, but it
616 will be exactly equal to @var{val}.
619 @node Complex Numbers
620 @subsubsection Complex Numbers
621 @tpindex Complex numbers
625 Complex numbers are the set of numbers that describe all possible points
626 in a two-dimensional space. The two coordinates of a particular point
627 in this space are known as the @dfn{real} and @dfn{imaginary} parts of
628 the complex number that describes that point.
630 In Guile, complex numbers are written in rectangular form as the sum of
631 their real and imaginary parts, using the symbol @code{i} to indicate
644 Guile represents a complex number with a non-zero imaginary part as a
645 pair of inexact rationals, so the real and imaginary parts of a
646 complex number have the same properties of inexactness and limited
647 precision as single inexact rational numbers. Guile can not represent
648 exact complex numbers with non-zero imaginary parts.
650 @deffn {Scheme Procedure} complex? z
651 @deffnx {C Function} scm_complex_p (z)
652 Return @code{#t} if @var{x} is a complex number, @code{#f}
653 otherwise. Note that the sets of real, rational and integer
654 values form subsets of the set of complex numbers, i. e. the
655 predicate will also be fulfilled if @var{x} is a real,
656 rational or integer number.
660 @subsubsection Exact and Inexact Numbers
661 @tpindex Exact numbers
662 @tpindex Inexact numbers
666 @rnindex exact->inexact
667 @rnindex inexact->exact
669 R5RS requires that a calculation involving inexact numbers always
670 produces an inexact result. To meet this requirement, Guile
671 distinguishes between an exact integer value such as @samp{5} and the
672 corresponding inexact real value which, to the limited precision
673 available, has no fractional part, and is printed as @samp{5.0}. Guile
674 will only convert the latter value to the former when forced to do so by
675 an invocation of the @code{inexact->exact} procedure.
677 @deffn {Scheme Procedure} exact? z
678 @deffnx {C Function} scm_exact_p (z)
679 Return @code{#t} if the number @var{z} is exact, @code{#f}
695 @deffn {Scheme Procedure} inexact? z
696 @deffnx {C Function} scm_inexact_p (z)
697 Return @code{#t} if the number @var{z} is inexact, @code{#f}
701 @deffn {Scheme Procedure} inexact->exact z
702 @deffnx {C Function} scm_inexact_to_exact (z)
703 Return an exact number that is numerically closest to @var{z}, when
704 there is one. For inexact rationals, Guile returns the exact rational
705 that is numerically equal to the inexact rational. Inexact complex
706 numbers with a non-zero imaginary part can not be made exact.
713 The following happens because 12/10 is not exactly representable as a
714 @code{double} (on most platforms). However, when reading a decimal
715 number that has been marked exact with the ``#e'' prefix, Guile is
716 able to represent it correctly.
720 @result{} 5404319552844595/4503599627370496
728 @c begin (texi-doc-string "guile" "exact->inexact")
729 @deffn {Scheme Procedure} exact->inexact z
730 @deffnx {C Function} scm_exact_to_inexact (z)
731 Convert the number @var{z} to its inexact representation.
736 @subsubsection Read Syntax for Numerical Data
738 The read syntax for integers is a string of digits, optionally
739 preceded by a minus or plus character, a code indicating the
740 base in which the integer is encoded, and a code indicating whether
741 the number is exact or inexact. The supported base codes are:
746 the integer is written in binary (base 2)
750 the integer is written in octal (base 8)
754 the integer is written in decimal (base 10)
758 the integer is written in hexadecimal (base 16)
761 If the base code is omitted, the integer is assumed to be decimal. The
762 following examples show how these base codes are used.
781 The codes for indicating exactness (which can, incidentally, be applied
782 to all numerical values) are:
791 the number is inexact.
794 If the exactness indicator is omitted, the number is exact unless it
795 contains a radix point. Since Guile can not represent exact complex
796 numbers, an error is signalled when asking for them.
806 ERROR: Wrong type argument
809 Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
810 plus and minus infinity, respectively. The value must be written
811 exactly as shown, that is, they always must have a sign and exactly
812 one zero digit after the decimal point. It also understands
813 @samp{+nan.0} and @samp{-nan.0} for the special `not-a-number' value.
814 The sign is ignored for `not-a-number' and the value is always printed
817 @node Integer Operations
818 @subsubsection Operations on Integer Values
827 @deffn {Scheme Procedure} odd? n
828 @deffnx {C Function} scm_odd_p (n)
829 Return @code{#t} if @var{n} is an odd number, @code{#f}
833 @deffn {Scheme Procedure} even? n
834 @deffnx {C Function} scm_even_p (n)
835 Return @code{#t} if @var{n} is an even number, @code{#f}
839 @c begin (texi-doc-string "guile" "quotient")
840 @c begin (texi-doc-string "guile" "remainder")
841 @deffn {Scheme Procedure} quotient n d
842 @deffnx {Scheme Procedure} remainder n d
843 @deffnx {C Function} scm_quotient (n, d)
844 @deffnx {C Function} scm_remainder (n, d)
845 Return the quotient or remainder from @var{n} divided by @var{d}. The
846 quotient is rounded towards zero, and the remainder will have the same
847 sign as @var{n}. In all cases quotient and remainder satisfy
848 @math{@var{n} = @var{q}*@var{d} + @var{r}}.
851 (remainder 13 4) @result{} 1
852 (remainder -13 4) @result{} -1
856 @c begin (texi-doc-string "guile" "modulo")
857 @deffn {Scheme Procedure} modulo n d
858 @deffnx {C Function} scm_modulo (n, d)
859 Return the remainder from @var{n} divided by @var{d}, with the same
863 (modulo 13 4) @result{} 1
864 (modulo -13 4) @result{} 3
865 (modulo 13 -4) @result{} -3
866 (modulo -13 -4) @result{} -1
870 @c begin (texi-doc-string "guile" "gcd")
871 @deffn {Scheme Procedure} gcd
872 @deffnx {C Function} scm_gcd (x, y)
873 Return the greatest common divisor of all arguments.
874 If called without arguments, 0 is returned.
876 The C function @code{scm_gcd} always takes two arguments, while the
877 Scheme function can take an arbitrary number.
880 @c begin (texi-doc-string "guile" "lcm")
881 @deffn {Scheme Procedure} lcm
882 @deffnx {C Function} scm_lcm (x, y)
883 Return the least common multiple of the arguments.
884 If called without arguments, 1 is returned.
886 The C function @code{scm_lcm} always takes two arguments, while the
887 Scheme function can take an arbitrary number.
892 @subsubsection Comparison Predicates
897 The C comparison functions below always takes two arguments, while the
898 Scheme functions can take an arbitrary number. Also keep in mind that
899 the C functions return one of the Scheme boolean values
900 @code{SCM_BOOL_T} or @code{SCM_BOOL_F} which are both true as far as C
901 is concerned. Thus, always write @code{scm_is_true (scm_num_eq_p (x,
902 y))} when testing the two Scheme numbers @code{x} and @code{y} for
903 equality, for example.
905 @c begin (texi-doc-string "guile" "=")
906 @deffn {Scheme Procedure} =
907 @deffnx {C Function} scm_num_eq_p (x, y)
908 Return @code{#t} if all parameters are numerically equal.
911 @c begin (texi-doc-string "guile" "<")
912 @deffn {Scheme Procedure} <
913 @deffnx {C Function} scm_less_p (x, y)
914 Return @code{#t} if the list of parameters is monotonically
918 @c begin (texi-doc-string "guile" ">")
919 @deffn {Scheme Procedure} >
920 @deffnx {C Function} scm_gr_p (x, y)
921 Return @code{#t} if the list of parameters is monotonically
925 @c begin (texi-doc-string "guile" "<=")
926 @deffn {Scheme Procedure} <=
927 @deffnx {C Function} scm_leq_p (x, y)
928 Return @code{#t} if the list of parameters is monotonically
932 @c begin (texi-doc-string "guile" ">=")
933 @deffn {Scheme Procedure} >=
934 @deffnx {C Function} scm_geq_p (x, y)
935 Return @code{#t} if the list of parameters is monotonically
939 @c begin (texi-doc-string "guile" "zero?")
940 @deffn {Scheme Procedure} zero? z
941 @deffnx {C Function} scm_zero_p (z)
942 Return @code{#t} if @var{z} is an exact or inexact number equal to
946 @c begin (texi-doc-string "guile" "positive?")
947 @deffn {Scheme Procedure} positive? x
948 @deffnx {C Function} scm_positive_p (x)
949 Return @code{#t} if @var{x} is an exact or inexact number greater than
953 @c begin (texi-doc-string "guile" "negative?")
954 @deffn {Scheme Procedure} negative? x
955 @deffnx {C Function} scm_negative_p (x)
956 Return @code{#t} if @var{x} is an exact or inexact number less than
962 @subsubsection Converting Numbers To and From Strings
963 @rnindex number->string
964 @rnindex string->number
966 @deffn {Scheme Procedure} number->string n [radix]
967 @deffnx {C Function} scm_number_to_string (n, radix)
968 Return a string holding the external representation of the
969 number @var{n} in the given @var{radix}. If @var{n} is
970 inexact, a radix of 10 will be used.
973 @deffn {Scheme Procedure} string->number string [radix]
974 @deffnx {C Function} scm_string_to_number (string, radix)
975 Return a number of the maximally precise representation
976 expressed by the given @var{string}. @var{radix} must be an
977 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
978 is a default radix that may be overridden by an explicit radix
979 prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
980 supplied, then the default radix is 10. If string is not a
981 syntactically valid notation for a number, then
982 @code{string->number} returns @code{#f}.
987 @subsubsection Complex Number Operations
988 @rnindex make-rectangular
995 @deffn {Scheme Procedure} make-rectangular real imaginary
996 @deffnx {C Function} scm_make_rectangular (real, imaginary)
997 Return a complex number constructed of the given @var{real} and
998 @var{imaginary} parts.
1001 @deffn {Scheme Procedure} make-polar x y
1002 @deffnx {C Function} scm_make_polar (x, y)
1003 Return the complex number @var{x} * e^(i * @var{y}).
1006 @c begin (texi-doc-string "guile" "real-part")
1007 @deffn {Scheme Procedure} real-part z
1008 @deffnx {C Function} scm_real_part (z)
1009 Return the real part of the number @var{z}.
1012 @c begin (texi-doc-string "guile" "imag-part")
1013 @deffn {Scheme Procedure} imag-part z
1014 @deffnx {C Function} scm_imag_part (z)
1015 Return the imaginary part of the number @var{z}.
1018 @c begin (texi-doc-string "guile" "magnitude")
1019 @deffn {Scheme Procedure} magnitude z
1020 @deffnx {C Function} scm_magnitude (z)
1021 Return the magnitude of the number @var{z}. This is the same as
1022 @code{abs} for real arguments, but also allows complex numbers.
1025 @c begin (texi-doc-string "guile" "angle")
1026 @deffn {Scheme Procedure} angle z
1027 @deffnx {C Function} scm_angle (z)
1028 Return the angle of the complex number @var{z}.
1031 @deftypefn {C Function} SCM scm_c_make_rectangular (double re, double im)
1032 @deftypefnx {C Function} SCM scm_c_make_polar (double x, double y)
1033 Like @code{scm_make_rectangular} or @code{scm_make_polar},
1034 respectively, but these functions take @code{double}s as their
1038 @deftypefn {C Function} double scm_c_real_part (z)
1039 @deftypefnx {C Function} double scm_c_imag_part (z)
1040 Returns the real or imaginary part of @var{z} as a @code{double}.
1043 @deftypefn {C Function} double scm_c_magnitude (z)
1044 @deftypefnx {C Function} double scm_c_angle (z)
1045 Returns the magnitude or angle of @var{z} as a @code{double}.
1050 @subsubsection Arithmetic Functions
1063 The C arithmetic functions below always takes two arguments, while the
1064 Scheme functions can take an arbitrary number. When you need to
1065 invoke them with just one argument, for example to compute the
1066 equivalent od @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
1067 one: @code{scm_difference (x, SCM_UNDEFINED)}.
1069 @c begin (texi-doc-string "guile" "+")
1070 @deffn {Scheme Procedure} + z1 @dots{}
1071 @deffnx {C Function} scm_sum (z1, z2)
1072 Return the sum of all parameter values. Return 0 if called without any
1076 @c begin (texi-doc-string "guile" "-")
1077 @deffn {Scheme Procedure} - z1 z2 @dots{}
1078 @deffnx {C Function} scm_difference (z1, z2)
1079 If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
1080 the sum of all but the first argument are subtracted from the first
1084 @c begin (texi-doc-string "guile" "*")
1085 @deffn {Scheme Procedure} * z1 @dots{}
1086 @deffnx {C Function} scm_product (z1, z2)
1087 Return the product of all arguments. If called without arguments, 1 is
1091 @c begin (texi-doc-string "guile" "/")
1092 @deffn {Scheme Procedure} / z1 z2 @dots{}
1093 @deffnx {C Function} scm_divide (z1, z2)
1094 Divide the first argument by the product of the remaining arguments. If
1095 called with one argument @var{z1}, 1/@var{z1} is returned.
1098 @c begin (texi-doc-string "guile" "abs")
1099 @deffn {Scheme Procedure} abs x
1100 @deffnx {C Function} scm_abs (x)
1101 Return the absolute value of @var{x}.
1103 @var{x} must be a number with zero imaginary part. To calculate the
1104 magnitude of a complex number, use @code{magnitude} instead.
1107 @c begin (texi-doc-string "guile" "max")
1108 @deffn {Scheme Procedure} max x1 x2 @dots{}
1109 @deffnx {C Function} scm_max (x1, x2)
1110 Return the maximum of all parameter values.
1113 @c begin (texi-doc-string "guile" "min")
1114 @deffn {Scheme Procedure} min x1 x2 @dots{}
1115 @deffnx {C Function} scm_min (x1, x2)
1116 Return the minimum of all parameter values.
1119 @c begin (texi-doc-string "guile" "truncate")
1120 @deffn {Scheme Procedure} truncate
1121 @deffnx {C Function} scm_truncate_number (x)
1122 Round the inexact number @var{x} towards zero.
1125 @c begin (texi-doc-string "guile" "round")
1126 @deffn {Scheme Procedure} round x
1127 @deffnx {C Function} scm_round_number (x)
1128 Round the inexact number @var{x} to the nearest integer. When exactly
1129 halfway between two integers, round to the even one.
1132 @c begin (texi-doc-string "guile" "floor")
1133 @deffn {Scheme Procedure} floor x
1134 @deffnx {C Function} scm_floor (x)
1135 Round the number @var{x} towards minus infinity.
1138 @c begin (texi-doc-string "guile" "ceiling")
1139 @deffn {Scheme Procedure} ceiling x
1140 @deffnx {C Function} scm_ceiling (x)
1141 Round the number @var{x} towards infinity.
1144 @deftypefn {C Function} double scm_c_truncate (double x)
1145 @deftypefnx {C Function} double scm_c_round (double x)
1146 Like @code{scm_truncate_number} or @code{scm_round_number},
1147 respectively, but these functions take and return @code{double}
1152 @subsubsection Scientific Functions
1154 The following procedures accept any kind of number as arguments,
1155 including complex numbers.
1158 @c begin (texi-doc-string "guile" "sqrt")
1159 @deffn {Scheme Procedure} sqrt z
1160 Return the square root of @var{z}.
1164 @c begin (texi-doc-string "guile" "expt")
1165 @deffn {Scheme Procedure} expt z1 z2
1166 Return @var{z1} raised to the power of @var{z2}.
1170 @c begin (texi-doc-string "guile" "sin")
1171 @deffn {Scheme Procedure} sin z
1172 Return the sine of @var{z}.
1176 @c begin (texi-doc-string "guile" "cos")
1177 @deffn {Scheme Procedure} cos z
1178 Return the cosine of @var{z}.
1182 @c begin (texi-doc-string "guile" "tan")
1183 @deffn {Scheme Procedure} tan z
1184 Return the tangent of @var{z}.
1188 @c begin (texi-doc-string "guile" "asin")
1189 @deffn {Scheme Procedure} asin z
1190 Return the arcsine of @var{z}.
1194 @c begin (texi-doc-string "guile" "acos")
1195 @deffn {Scheme Procedure} acos z
1196 Return the arccosine of @var{z}.
1200 @c begin (texi-doc-string "guile" "atan")
1201 @deffn {Scheme Procedure} atan z
1202 @deffnx {Scheme Procedure} atan y x
1203 Return the arctangent of @var{z}, or of @math{@var{y}/@var{x}}.
1207 @c begin (texi-doc-string "guile" "exp")
1208 @deffn {Scheme Procedure} exp z
1209 Return e to the power of @var{z}, where e is the base of natural
1210 logarithms (2.71828@dots{}).
1214 @c begin (texi-doc-string "guile" "log")
1215 @deffn {Scheme Procedure} log z
1216 Return the natural logarithm of @var{z}.
1219 @c begin (texi-doc-string "guile" "log10")
1220 @deffn {Scheme Procedure} log10 z
1221 Return the base 10 logarithm of @var{z}.
1224 @c begin (texi-doc-string "guile" "sinh")
1225 @deffn {Scheme Procedure} sinh z
1226 Return the hyperbolic sine of @var{z}.
1229 @c begin (texi-doc-string "guile" "cosh")
1230 @deffn {Scheme Procedure} cosh z
1231 Return the hyperbolic cosine of @var{z}.
1234 @c begin (texi-doc-string "guile" "tanh")
1235 @deffn {Scheme Procedure} tanh z
1236 Return the hyperbolic tangent of @var{z}.
1239 @c begin (texi-doc-string "guile" "asinh")
1240 @deffn {Scheme Procedure} asinh z
1241 Return the hyperbolic arcsine of @var{z}.
1244 @c begin (texi-doc-string "guile" "acosh")
1245 @deffn {Scheme Procedure} acosh z
1246 Return the hyperbolic arccosine of @var{z}.
1249 @c begin (texi-doc-string "guile" "atanh")
1250 @deffn {Scheme Procedure} atanh z
1251 Return the hyperbolic arctangent of @var{z}.
1255 @node Primitive Numerics
1256 @subsubsection Primitive Numeric Functions
1258 Many of Guile's numeric procedures which accept any kind of numbers as
1259 arguments, including complex numbers, are implemented as Scheme
1260 procedures that use the following real number-based primitives. These
1261 primitives signal an error if they are called with complex arguments.
1263 @c begin (texi-doc-string "guile" "$abs")
1264 @deffn {Scheme Procedure} $abs x
1265 Return the absolute value of @var{x}.
1268 @c begin (texi-doc-string "guile" "$sqrt")
1269 @deffn {Scheme Procedure} $sqrt x
1270 Return the square root of @var{x}.
1273 @deffn {Scheme Procedure} $expt x y
1274 @deffnx {C Function} scm_sys_expt (x, y)
1275 Return @var{x} raised to the power of @var{y}. This
1276 procedure does not accept complex arguments.
1279 @c begin (texi-doc-string "guile" "$sin")
1280 @deffn {Scheme Procedure} $sin x
1281 Return the sine of @var{x}.
1284 @c begin (texi-doc-string "guile" "$cos")
1285 @deffn {Scheme Procedure} $cos x
1286 Return the cosine of @var{x}.
1289 @c begin (texi-doc-string "guile" "$tan")
1290 @deffn {Scheme Procedure} $tan x
1291 Return the tangent of @var{x}.
1294 @c begin (texi-doc-string "guile" "$asin")
1295 @deffn {Scheme Procedure} $asin x
1296 Return the arcsine of @var{x}.
1299 @c begin (texi-doc-string "guile" "$acos")
1300 @deffn {Scheme Procedure} $acos x
1301 Return the arccosine of @var{x}.
1304 @c begin (texi-doc-string "guile" "$atan")
1305 @deffn {Scheme Procedure} $atan x
1306 Return the arctangent of @var{x} in the range @minus{}@math{PI/2} to
1310 @deffn {Scheme Procedure} $atan2 x y
1311 @deffnx {C Function} scm_sys_atan2 (x, y)
1312 Return the arc tangent of the two arguments @var{x} and
1313 @var{y}. This is similar to calculating the arc tangent of
1314 @var{x} / @var{y}, except that the signs of both arguments
1315 are used to determine the quadrant of the result. This
1316 procedure does not accept complex arguments.
1319 @c begin (texi-doc-string "guile" "$exp")
1320 @deffn {Scheme Procedure} $exp x
1321 Return e to the power of @var{x}, where e is the base of natural
1322 logarithms (2.71828@dots{}).
1325 @c begin (texi-doc-string "guile" "$log")
1326 @deffn {Scheme Procedure} $log x
1327 Return the natural logarithm of @var{x}.
1330 @c begin (texi-doc-string "guile" "$sinh")
1331 @deffn {Scheme Procedure} $sinh x
1332 Return the hyperbolic sine of @var{x}.
1335 @c begin (texi-doc-string "guile" "$cosh")
1336 @deffn {Scheme Procedure} $cosh x
1337 Return the hyperbolic cosine of @var{x}.
1340 @c begin (texi-doc-string "guile" "$tanh")
1341 @deffn {Scheme Procedure} $tanh x
1342 Return the hyperbolic tangent of @var{x}.
1345 @c begin (texi-doc-string "guile" "$asinh")
1346 @deffn {Scheme Procedure} $asinh x
1347 Return the hyperbolic arcsine of @var{x}.
1350 @c begin (texi-doc-string "guile" "$acosh")
1351 @deffn {Scheme Procedure} $acosh x
1352 Return the hyperbolic arccosine of @var{x}.
1355 @c begin (texi-doc-string "guile" "$atanh")
1356 @deffn {Scheme Procedure} $atanh x
1357 Return the hyperbolic arctangent of @var{x}.
1360 C functions for the above are provided by the standard mathematics
1361 library. Naturally these expect and return @code{double} arguments
1362 (@pxref{Mathematics,,, libc, GNU C Library Reference Manual}).
1364 @multitable {xx} {Scheme Procedure} {C Function}
1365 @item @tab Scheme Procedure @tab C Function
1367 @item @tab @code{$abs} @tab @code{fabs}
1368 @item @tab @code{$sqrt} @tab @code{sqrt}
1369 @item @tab @code{$sin} @tab @code{sin}
1370 @item @tab @code{$cos} @tab @code{cos}
1371 @item @tab @code{$tan} @tab @code{tan}
1372 @item @tab @code{$asin} @tab @code{asin}
1373 @item @tab @code{$acos} @tab @code{acos}
1374 @item @tab @code{$atan} @tab @code{atan}
1375 @item @tab @code{$atan2} @tab @code{atan2}
1376 @item @tab @code{$exp} @tab @code{exp}
1377 @item @tab @code{$expt} @tab @code{pow}
1378 @item @tab @code{$log} @tab @code{log}
1379 @item @tab @code{$sinh} @tab @code{sinh}
1380 @item @tab @code{$cosh} @tab @code{cosh}
1381 @item @tab @code{$tanh} @tab @code{tanh}
1382 @item @tab @code{$asinh} @tab @code{asinh}
1383 @item @tab @code{$acosh} @tab @code{acosh}
1384 @item @tab @code{$atanh} @tab @code{atanh}
1387 @code{asinh}, @code{acosh} and @code{atanh} are C99 standard but might
1388 not be available on older systems. Guile provides the following
1389 equivalents (on all systems).
1391 @deftypefn {C Function} double scm_asinh (double x)
1392 @deftypefnx {C Function} double scm_acosh (double x)
1393 @deftypefnx {C Function} double scm_atanh (double x)
1394 Return the hyperbolic arcsine, arccosine or arctangent of @var{x}
1399 @node Bitwise Operations
1400 @subsubsection Bitwise Operations
1402 For the following bitwise functions, negative numbers are treated as
1403 infinite precision twos-complements. For instance @math{-6} is bits
1404 @math{@dots{}111010}, with infinitely many ones on the left. It can
1405 be seen that adding 6 (binary 110) to such a bit pattern gives all
1408 @deffn {Scheme Procedure} logand n1 n2 @dots{}
1409 @deffnx {C Function} scm_logand (n1, n2)
1410 Return the bitwise @sc{and} of the integer arguments.
1413 (logand) @result{} -1
1414 (logand 7) @result{} 7
1415 (logand #b111 #b011 #b001) @result{} 1
1419 @deffn {Scheme Procedure} logior n1 n2 @dots{}
1420 @deffnx {C Function} scm_logior (n1, n2)
1421 Return the bitwise @sc{or} of the integer arguments.
1424 (logior) @result{} 0
1425 (logior 7) @result{} 7
1426 (logior #b000 #b001 #b011) @result{} 3
1430 @deffn {Scheme Procedure} logxor n1 n2 @dots{}
1431 @deffnx {C Function} scm_loxor (n1, n2)
1432 Return the bitwise @sc{xor} of the integer arguments. A bit is
1433 set in the result if it is set in an odd number of arguments.
1436 (logxor) @result{} 0
1437 (logxor 7) @result{} 7
1438 (logxor #b000 #b001 #b011) @result{} 2
1439 (logxor #b000 #b001 #b011 #b011) @result{} 1
1443 @deffn {Scheme Procedure} lognot n
1444 @deffnx {C Function} scm_lognot (n)
1445 Return the integer which is the ones-complement of the integer
1446 argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
1449 (number->string (lognot #b10000000) 2)
1450 @result{} "-10000001"
1451 (number->string (lognot #b0) 2)
1456 @deffn {Scheme Procedure} logtest j k
1457 @deffnx {C Function} scm_logtest (j, k)
1459 (logtest j k) @equiv{} (not (zero? (logand j k)))
1461 (logtest #b0100 #b1011) @result{} #f
1462 (logtest #b0100 #b0111) @result{} #t
1466 @deffn {Scheme Procedure} logbit? index j
1467 @deffnx {C Function} scm_logbit_p (index, j)
1469 (logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
1471 (logbit? 0 #b1101) @result{} #t
1472 (logbit? 1 #b1101) @result{} #f
1473 (logbit? 2 #b1101) @result{} #t
1474 (logbit? 3 #b1101) @result{} #t
1475 (logbit? 4 #b1101) @result{} #f
1479 @deffn {Scheme Procedure} ash n cnt
1480 @deffnx {C Function} scm_ash (n, cnt)
1481 Return @var{n} shifted left by @var{cnt} bits, or shifted right if
1482 @var{cnt} is negative. This is an ``arithmetic'' shift.
1484 This is effectively a multiplication by @m{2^{cnt}, 2^@var{cnt}}, and
1485 when @var{cnt} is negative it's a division, rounded towards negative
1486 infinity. (Note that this is not the same rounding as @code{quotient}
1489 With @var{n} viewed as an infinite precision twos complement,
1490 @code{ash} means a left shift introducing zero bits, or a right shift
1494 (number->string (ash #b1 3) 2) @result{} "1000"
1495 (number->string (ash #b1010 -1) 2) @result{} "101"
1497 ;; -23 is bits ...11101001, -6 is bits ...111010
1498 (ash -23 -2) @result{} -6
1502 @deffn {Scheme Procedure} logcount n
1503 @deffnx {C Function} scm_logcount (n)
1504 Return the number of bits in integer @var{n}. If integer is
1505 positive, the 1-bits in its binary representation are counted.
1506 If negative, the 0-bits in its two's-complement binary
1507 representation are counted. If 0, 0 is returned.
1510 (logcount #b10101010)
1519 @deffn {Scheme Procedure} integer-length n
1520 @deffnx {C Function} scm_integer_length (n)
1521 Return the number of bits necessary to represent @var{n}.
1523 For positive @var{n} this is how many bits to the most significant one
1524 bit. For negative @var{n} it's how many bits to the most significant
1525 zero bit in twos complement form.
1528 (integer-length #b10101010) @result{} 8
1529 (integer-length #b1111) @result{} 4
1530 (integer-length 0) @result{} 0
1531 (integer-length -1) @result{} 0
1532 (integer-length -256) @result{} 8
1533 (integer-length -257) @result{} 9
1537 @deffn {Scheme Procedure} integer-expt n k
1538 @deffnx {C Function} scm_integer_expt (n, k)
1539 Return @var{n} raised to the non-negative integer exponent
1550 @deffn {Scheme Procedure} bit-extract n start end
1551 @deffnx {C Function} scm_bit_extract (n, start, end)
1552 Return the integer composed of the @var{start} (inclusive)
1553 through @var{end} (exclusive) bits of @var{n}. The
1554 @var{start}th bit becomes the 0-th bit in the result.
1557 (number->string (bit-extract #b1101101010 0 4) 2)
1559 (number->string (bit-extract #b1101101010 4 9) 2)
1566 @subsubsection Random Number Generation
1568 Pseudo-random numbers are generated from a random state object, which
1569 can be created with @code{seed->random-state}. The @var{state}
1570 parameter to the various functions below is optional, it defaults to
1571 the state object in the @code{*random-state*} variable.
1573 @deffn {Scheme Procedure} copy-random-state [state]
1574 @deffnx {C Function} scm_copy_random_state (state)
1575 Return a copy of the random state @var{state}.
1578 @deffn {Scheme Procedure} random n [state]
1579 @deffnx {C Function} scm_random (n, state)
1580 Return a number in [0, @var{n}).
1582 Accepts a positive integer or real n and returns a
1583 number of the same type between zero (inclusive) and
1584 @var{n} (exclusive). The values returned have a uniform
1588 @deffn {Scheme Procedure} random:exp [state]
1589 @deffnx {C Function} scm_random_exp (state)
1590 Return an inexact real in an exponential distribution with mean
1591 1. For an exponential distribution with mean @var{u} use @code{(*
1592 @var{u} (random:exp))}.
1595 @deffn {Scheme Procedure} random:hollow-sphere! vect [state]
1596 @deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
1597 Fills @var{vect} with inexact real random numbers the sum of whose
1598 squares is equal to 1.0. Thinking of @var{vect} as coordinates in
1599 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1600 the coordinates are uniformly distributed over the surface of the unit
1604 @deffn {Scheme Procedure} random:normal [state]
1605 @deffnx {C Function} scm_random_normal (state)
1606 Return an inexact real in a normal distribution. The distribution
1607 used has mean 0 and standard deviation 1. For a normal distribution
1608 with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
1609 (* @var{d} (random:normal)))}.
1612 @deffn {Scheme Procedure} random:normal-vector! vect [state]
1613 @deffnx {C Function} scm_random_normal_vector_x (vect, state)
1614 Fills @var{vect} with inexact real random numbers that are
1615 independent and standard normally distributed
1616 (i.e., with mean 0 and variance 1).
1619 @deffn {Scheme Procedure} random:solid-sphere! vect [state]
1620 @deffnx {C Function} scm_random_solid_sphere_x (vect, state)
1621 Fills @var{vect} with inexact real random numbers the sum of whose
1622 squares is less than 1.0. Thinking of @var{vect} as coordinates in
1623 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1624 the coordinates are uniformly distributed within the unit
1625 @var{n}-sphere. The sum of the squares of the numbers is returned.
1626 @c FIXME: What does this mean, particularly the n-sphere part?
1629 @deffn {Scheme Procedure} random:uniform [state]
1630 @deffnx {C Function} scm_random_uniform (state)
1631 Return a uniformly distributed inexact real random number in
1635 @deffn {Scheme Procedure} seed->random-state seed
1636 @deffnx {C Function} scm_seed_to_random_state (seed)
1637 Return a new random state using @var{seed}.
1640 @defvar *random-state*
1641 The global random state used by the above functions when the
1642 @var{state} parameter is not given.
1647 @subsection Characters
1651 [@strong{FIXME}: how do you specify regular (non-control) characters?]
1653 Most of the ``control characters'' (those below codepoint 32) in the
1654 @acronym{ASCII} character set, as well as the space, may be referred
1655 to by name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and
1656 so on. The following table describes the @acronym{ASCII} names for
1659 @multitable @columnfractions .25 .25 .25 .25
1660 @item 0 = @code{#\nul}
1661 @tab 1 = @code{#\soh}
1662 @tab 2 = @code{#\stx}
1663 @tab 3 = @code{#\etx}
1664 @item 4 = @code{#\eot}
1665 @tab 5 = @code{#\enq}
1666 @tab 6 = @code{#\ack}
1667 @tab 7 = @code{#\bel}
1668 @item 8 = @code{#\bs}
1669 @tab 9 = @code{#\ht}
1670 @tab 10 = @code{#\nl}
1671 @tab 11 = @code{#\vt}
1672 @item 12 = @code{#\np}
1673 @tab 13 = @code{#\cr}
1674 @tab 14 = @code{#\so}
1675 @tab 15 = @code{#\si}
1676 @item 16 = @code{#\dle}
1677 @tab 17 = @code{#\dc1}
1678 @tab 18 = @code{#\dc2}
1679 @tab 19 = @code{#\dc3}
1680 @item 20 = @code{#\dc4}
1681 @tab 21 = @code{#\nak}
1682 @tab 22 = @code{#\syn}
1683 @tab 23 = @code{#\etb}
1684 @item 24 = @code{#\can}
1685 @tab 25 = @code{#\em}
1686 @tab 26 = @code{#\sub}
1687 @tab 27 = @code{#\esc}
1688 @item 28 = @code{#\fs}
1689 @tab 29 = @code{#\gs}
1690 @tab 30 = @code{#\rs}
1691 @tab 31 = @code{#\us}
1692 @item 32 = @code{#\sp}
1695 The ``delete'' character (octal 177) may be referred to with the name
1698 Several characters have more than one name:
1700 @multitable {@code{#\backspace}} {Original}
1701 @item Alias @tab Original
1702 @item @code{#\space} @tab @code{#\sp}
1703 @item @code{#\newline} @tab @code{#\nl}
1704 @item @code{#\tab} @tab @code{#\ht}
1705 @item @code{#\backspace} @tab @code{#\bs}
1706 @item @code{#\return} @tab @code{#\cr}
1707 @item @code{#\page} @tab @code{#\np}
1708 @item @code{#\null} @tab @code{#\nul}
1712 @deffn {Scheme Procedure} char? x
1713 @deffnx {C Function} scm_char_p (x)
1714 Return @code{#t} iff @var{x} is a character, else @code{#f}.
1718 @deffn {Scheme Procedure} char=? x y
1719 Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
1723 @deffn {Scheme Procedure} char<? x y
1724 Return @code{#t} iff @var{x} is less than @var{y} in the @acronym{ASCII} sequence,
1729 @deffn {Scheme Procedure} char<=? x y
1730 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
1731 @acronym{ASCII} sequence, else @code{#f}.
1735 @deffn {Scheme Procedure} char>? x y
1736 Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII}
1737 sequence, else @code{#f}.
1741 @deffn {Scheme Procedure} char>=? x y
1742 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
1743 @acronym{ASCII} sequence, else @code{#f}.
1747 @deffn {Scheme Procedure} char-ci=? x y
1748 Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
1749 case, else @code{#f}.
1753 @deffn {Scheme Procedure} char-ci<? x y
1754 Return @code{#t} iff @var{x} is less than @var{y} in the @acronym{ASCII} sequence
1755 ignoring case, else @code{#f}.
1759 @deffn {Scheme Procedure} char-ci<=? x y
1760 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
1761 @acronym{ASCII} sequence ignoring case, else @code{#f}.
1765 @deffn {Scheme Procedure} char-ci>? x y
1766 Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII}
1767 sequence ignoring case, else @code{#f}.
1771 @deffn {Scheme Procedure} char-ci>=? x y
1772 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
1773 @acronym{ASCII} sequence ignoring case, else @code{#f}.
1776 @rnindex char-alphabetic?
1777 @deffn {Scheme Procedure} char-alphabetic? chr
1778 @deffnx {C Function} scm_char_alphabetic_p (chr)
1779 Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
1780 Alphabetic means the same thing as the @code{isalpha} C library function.
1783 @rnindex char-numeric?
1784 @deffn {Scheme Procedure} char-numeric? chr
1785 @deffnx {C Function} scm_char_numeric_p (chr)
1786 Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
1787 Numeric means the same thing as the @code{isdigit} C library function.
1790 @rnindex char-whitespace?
1791 @deffn {Scheme Procedure} char-whitespace? chr
1792 @deffnx {C Function} scm_char_whitespace_p (chr)
1793 Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
1794 Whitespace means the same thing as the @code{isspace} C library function.
1797 @rnindex char-upper-case?
1798 @deffn {Scheme Procedure} char-upper-case? chr
1799 @deffnx {C Function} scm_char_upper_case_p (chr)
1800 Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
1801 Uppercase means the same thing as the @code{isupper} C library function.
1804 @rnindex char-lower-case?
1805 @deffn {Scheme Procedure} char-lower-case? chr
1806 @deffnx {C Function} scm_char_lower_case_p (chr)
1807 Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
1808 Lowercase means the same thing as the @code{islower} C library function.
1811 @deffn {Scheme Procedure} char-is-both? chr
1812 @deffnx {C Function} scm_char_is_both_p (chr)
1813 Return @code{#t} iff @var{chr} is either uppercase or lowercase, else
1814 @code{#f}. Uppercase and lowercase are as defined by the
1815 @code{isupper} and @code{islower} C library functions.
1818 @rnindex char->integer
1819 @deffn {Scheme Procedure} char->integer chr
1820 @deffnx {C Function} scm_char_to_integer (chr)
1821 Return the number corresponding to ordinal position of @var{chr} in the
1822 @acronym{ASCII} sequence.
1825 @rnindex integer->char
1826 @deffn {Scheme Procedure} integer->char n
1827 @deffnx {C Function} scm_integer_to_char (n)
1828 Return the character at position @var{n} in the @acronym{ASCII} sequence.
1831 @rnindex char-upcase
1832 @deffn {Scheme Procedure} char-upcase chr
1833 @deffnx {C Function} scm_char_upcase (chr)
1834 Return the uppercase character version of @var{chr}.
1837 @rnindex char-downcase
1838 @deffn {Scheme Procedure} char-downcase chr
1839 @deffnx {C Function} scm_char_downcase (chr)
1840 Return the lowercase character version of @var{chr}.
1843 @xref{Classification of Characters,,,libc,GNU C Library Reference
1844 Manual}, for information about the @code{is*} Standard C functions
1852 Strings are fixed-length sequences of characters. They can be created
1853 by calling constructor procedures, but they can also literally get
1854 entered at the @acronym{REPL} or in Scheme source files.
1856 @c Guile provides a rich set of string processing procedures, because text
1857 @c handling is very important when Guile is used as a scripting language.
1859 Strings always carry the information about how many characters they are
1860 composed of with them, so there is no special end-of-string character,
1861 like in C. That means that Scheme strings can contain any character,
1862 even the @samp{NUL} character @samp{\0}. But note: Since most operating
1863 system calls dealing with strings (such as for file operations) expect
1864 strings to be zero-terminated, they might do unexpected things when
1865 called with string containing unusual characters.
1868 * String Syntax:: Read syntax for strings.
1869 * String Predicates:: Testing strings for certain properties.
1870 * String Constructors:: Creating new string objects.
1871 * List/String Conversion:: Converting from/to lists of characters.
1872 * String Selection:: Select portions from strings.
1873 * String Modification:: Modify parts or whole strings.
1874 * String Comparison:: Lexicographic ordering predicates.
1875 * String Searching:: Searching in strings.
1876 * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
1877 * Appending Strings:: Appending strings to form a new string.
1878 * Conversion to/from C::
1882 @subsubsection String Read Syntax
1884 @c In the following @code is used to get a good font in TeX etc, but
1885 @c is omitted for Info format, so as not to risk any confusion over
1886 @c whether surrounding ` ' quotes are part of the escape or are
1887 @c special in a string (they're not).
1889 The read syntax for strings is an arbitrarily long sequence of
1890 characters enclosed in double quotes (@nicode{"}). @footnote{Actually,
1891 the current implementation restricts strings to a length of
1892 @math{2^24}, or 16,777,216, characters. Sorry.}
1894 Backslash is an escape character and can be used to insert the
1895 following special characters. @nicode{\"} and @nicode{\\} are R5RS
1896 standard, the rest are Guile extensions, notice they follow C string
1901 Backslash character.
1904 Double quote character (an unescaped @nicode{"} is otherwise the end
1908 NUL character (ASCII 0).
1911 Bell character (ASCII 7).
1914 Formfeed character (ASCII 12).
1917 Newline character (ASCII 10).
1920 Carriage return character (ASCII 13).
1923 Tab character (ASCII 9).
1926 Vertical tab character (ASCII 11).
1929 Character code given by two hexadecimal digits. For example
1930 @nicode{\x7f} for an ASCII DEL (127).
1934 The following are examples of string literals:
1944 @node String Predicates
1945 @subsubsection String Predicates
1947 The following procedures can be used to check whether a given string
1948 fulfills some specified property.
1951 @deffn {Scheme Procedure} string? obj
1952 @deffnx {C Function} scm_string_p (obj)
1953 Return @code{#t} if @var{obj} is a string, else @code{#f}.
1956 @deftypefn {C Function} int scm_is_string (SCM obj)
1957 Returns @code{1} if @var{obj} is a string, @code{0} otherwise.
1960 @deffn {Scheme Procedure} string-null? str
1961 @deffnx {C Function} scm_string_null_p (str)
1962 Return @code{#t} if @var{str}'s length is zero, and
1963 @code{#f} otherwise.
1965 (string-null? "") @result{} #t
1967 (string-null? y) @result{} #f
1971 @node String Constructors
1972 @subsubsection String Constructors
1974 The string constructor procedures create new string objects, possibly
1975 initializing them with some specified character data.
1977 @c FIXME::martin: list->string belongs into `List/String Conversion'
1980 @rnindex list->string
1981 @deffn {Scheme Procedure} string . chrs
1982 @deffnx {Scheme Procedure} list->string chrs
1983 @deffnx {C Function} scm_string (chrs)
1984 Return a newly allocated string composed of the arguments,
1988 @rnindex make-string
1989 @deffn {Scheme Procedure} make-string k [chr]
1990 @deffnx {C Function} scm_make_string (k, chr)
1991 Return a newly allocated string of
1992 length @var{k}. If @var{chr} is given, then all elements of
1993 the string are initialized to @var{chr}, otherwise the contents
1994 of the @var{string} are unspecified.
1997 @node List/String Conversion
1998 @subsubsection List/String conversion
2000 When processing strings, it is often convenient to first convert them
2001 into a list representation by using the procedure @code{string->list},
2002 work with the resulting list, and then convert it back into a string.
2003 These procedures are useful for similar tasks.
2005 @rnindex string->list
2006 @deffn {Scheme Procedure} string->list str
2007 @deffnx {C Function} scm_string_to_list (str)
2008 Return a newly allocated list of the characters that make up
2009 the given string @var{str}. @code{string->list} and
2010 @code{list->string} are inverses as far as @samp{equal?} is
2014 @deffn {Scheme Procedure} string-split str chr
2015 @deffnx {C Function} scm_string_split (str, chr)
2016 Split the string @var{str} into the a list of the substrings delimited
2017 by appearances of the character @var{chr}. Note that an empty substring
2018 between separator characters will result in an empty string in the
2022 (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
2024 ("root" "x" "0" "0" "root" "/root" "/bin/bash")
2026 (string-split "::" #\:)
2030 (string-split "" #\:)
2037 @node String Selection
2038 @subsubsection String Selection
2040 Portions of strings can be extracted by these procedures.
2041 @code{string-ref} delivers individual characters whereas
2042 @code{substring} can be used to extract substrings from longer strings.
2044 @rnindex string-length
2045 @deffn {Scheme Procedure} string-length string
2046 @deffnx {C Function} scm_string_length (string)
2047 Return the number of characters in @var{string}.
2051 @deffn {Scheme Procedure} string-ref str k
2052 @deffnx {C Function} scm_string_ref (str, k)
2053 Return character @var{k} of @var{str} using zero-origin
2054 indexing. @var{k} must be a valid index of @var{str}.
2057 @rnindex string-copy
2058 @deffn {Scheme Procedure} string-copy str
2059 @deffnx {C Function} scm_string_copy (str)
2060 Return a newly allocated copy of the given @var{string}.
2064 @deffn {Scheme Procedure} substring str start [end]
2065 @deffnx {C Function} scm_substring (str, start, end)
2066 Return a newly allocated string formed from the characters
2067 of @var{str} beginning with index @var{start} (inclusive) and
2068 ending with index @var{end} (exclusive).
2069 @var{str} must be a string, @var{start} and @var{end} must be
2070 exact integers satisfying:
2072 0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
2075 @node String Modification
2076 @subsubsection String Modification
2078 These procedures are for modifying strings in-place. This means that the
2079 result of the operation is not a new string; instead, the original string's
2080 memory representation is modified.
2082 @rnindex string-set!
2083 @deffn {Scheme Procedure} string-set! str k chr
2084 @deffnx {C Function} scm_string_set_x (str, k, chr)
2085 Store @var{chr} in element @var{k} of @var{str} and return
2086 an unspecified value. @var{k} must be a valid index of
2090 @rnindex string-fill!
2091 @deffn {Scheme Procedure} string-fill! str chr
2092 @deffnx {C Function} scm_string_fill_x (str, chr)
2093 Store @var{char} in every element of the given @var{string} and
2094 return an unspecified value.
2097 @deffn {Scheme Procedure} substring-fill! str start end fill
2098 @deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
2099 Change every character in @var{str} between @var{start} and
2100 @var{end} to @var{fill}.
2103 (define y "abcdefg")
2104 (substring-fill! y 1 3 #\r)
2110 @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
2111 @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
2112 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
2113 into @var{str2} beginning at position @var{start2}.
2114 @var{str1} and @var{str2} can be the same string.
2118 @node String Comparison
2119 @subsubsection String Comparison
2121 The procedures in this section are similar to the character ordering
2122 predicates (@pxref{Characters}), but are defined on character sequences.
2123 They all return @code{#t} on success and @code{#f} on failure. The
2124 predicates ending in @code{-ci} ignore the character case when comparing
2129 @deffn {Scheme Procedure} string=? s1 s2
2130 Lexicographic equality predicate; return @code{#t} if the two
2131 strings are the same length and contain the same characters in
2132 the same positions, otherwise return @code{#f}.
2134 The procedure @code{string-ci=?} treats upper and lower case
2135 letters as though they were the same character, but
2136 @code{string=?} treats upper and lower case as distinct
2141 @deffn {Scheme Procedure} string<? s1 s2
2142 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2143 is lexicographically less than @var{s2}.
2147 @deffn {Scheme Procedure} string<=? s1 s2
2148 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2149 is lexicographically less than or equal to @var{s2}.
2153 @deffn {Scheme Procedure} string>? s1 s2
2154 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2155 is lexicographically greater than @var{s2}.
2159 @deffn {Scheme Procedure} string>=? s1 s2
2160 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2161 is lexicographically greater than or equal to @var{s2}.
2164 @rnindex string-ci=?
2165 @deffn {Scheme Procedure} string-ci=? s1 s2
2166 Case-insensitive string equality predicate; return @code{#t} if
2167 the two strings are the same length and their component
2168 characters match (ignoring case) at each position; otherwise
2173 @deffn {Scheme Procedure} string-ci<? s1 s2
2174 Case insensitive lexicographic ordering predicate; return
2175 @code{#t} if @var{s1} is lexicographically less than @var{s2}
2180 @deffn {Scheme Procedure} string-ci<=? s1 s2
2181 Case insensitive lexicographic ordering predicate; return
2182 @code{#t} if @var{s1} is lexicographically less than or equal
2183 to @var{s2} regardless of case.
2186 @rnindex string-ci>?
2187 @deffn {Scheme Procedure} string-ci>? s1 s2
2188 Case insensitive lexicographic ordering predicate; return
2189 @code{#t} if @var{s1} is lexicographically greater than
2190 @var{s2} regardless of case.
2193 @rnindex string-ci>=?
2194 @deffn {Scheme Procedure} string-ci>=? s1 s2
2195 Case insensitive lexicographic ordering predicate; return
2196 @code{#t} if @var{s1} is lexicographically greater than or
2197 equal to @var{s2} regardless of case.
2201 @node String Searching
2202 @subsubsection String Searching
2204 When searching for the index of a character in a string, these
2205 procedures can be used.
2207 @deffn {Scheme Procedure} string-index str chr [frm [to]]
2208 @deffnx {C Function} scm_string_index (str, chr, frm, to)
2209 Return the index of the first occurrence of @var{chr} in
2210 @var{str}. The optional integer arguments @var{frm} and
2211 @var{to} limit the search to a portion of the string. This
2212 procedure essentially implements the @code{index} or
2213 @code{strchr} functions from the C library.
2216 (string-index "weiner" #\e)
2219 (string-index "weiner" #\e 2)
2222 (string-index "weiner" #\e 2 4)
2227 @deffn {Scheme Procedure} string-rindex str chr [frm [to]]
2228 @deffnx {C Function} scm_string_rindex (str, chr, frm, to)
2229 Like @code{string-index}, but search from the right of the
2230 string rather than from the left. This procedure essentially
2231 implements the @code{rindex} or @code{strrchr} functions from
2235 (string-rindex "weiner" #\e)
2238 (string-rindex "weiner" #\e 2 4)
2241 (string-rindex "weiner" #\e 2 5)
2246 @node Alphabetic Case Mapping
2247 @subsubsection Alphabetic Case Mapping
2249 These are procedures for mapping strings to their upper- or lower-case
2250 equivalents, respectively, or for capitalizing strings.
2252 @deffn {Scheme Procedure} string-upcase str
2253 @deffnx {C Function} scm_string_upcase (str)
2254 Return a freshly allocated string containing the characters of
2255 @var{str} in upper case.
2258 @deffn {Scheme Procedure} string-upcase! str
2259 @deffnx {C Function} scm_string_upcase_x (str)
2260 Destructively upcase every character in @var{str} and return
2263 y @result{} "arrdefg"
2264 (string-upcase! y) @result{} "ARRDEFG"
2265 y @result{} "ARRDEFG"
2269 @deffn {Scheme Procedure} string-downcase str
2270 @deffnx {C Function} scm_string_downcase (str)
2271 Return a freshly allocation string containing the characters in
2272 @var{str} in lower case.
2275 @deffn {Scheme Procedure} string-downcase! str
2276 @deffnx {C Function} scm_string_downcase_x (str)
2277 Destructively downcase every character in @var{str} and return
2280 y @result{} "ARRDEFG"
2281 (string-downcase! y) @result{} "arrdefg"
2282 y @result{} "arrdefg"
2286 @deffn {Scheme Procedure} string-capitalize str
2287 @deffnx {C Function} scm_string_capitalize (str)
2288 Return a freshly allocated string with the characters in
2289 @var{str}, where the first character of every word is
2293 @deffn {Scheme Procedure} string-capitalize! str
2294 @deffnx {C Function} scm_string_capitalize_x (str)
2295 Upcase the first character of every word in @var{str}
2296 destructively and return @var{str}.
2299 y @result{} "hello world"
2300 (string-capitalize! y) @result{} "Hello World"
2301 y @result{} "Hello World"
2306 @node Appending Strings
2307 @subsubsection Appending Strings
2309 The procedure @code{string-append} appends several strings together to
2310 form a longer result string.
2312 @rnindex string-append
2313 @deffn {Scheme Procedure} string-append . args
2314 @deffnx {C Function} scm_string_append (args)
2315 Return a newly allocated string whose characters form the
2316 concatenation of the given strings, @var{args}.
2320 (string-append h "world"))
2321 @result{} "hello world"
2325 @node Conversion to/from C
2326 @subsubsection Conversion to/from C
2328 When creating a Scheme string from a C string or when converting a
2329 Scheme string to a C string, the concept of character encoding becomes
2332 In C, a string is just a sequence of bytes, and the character encoding
2333 describes the relation between these bytes and the actual characters
2334 that make up the string. For Scheme strings, character encoding is
2335 not an issue (most of the time), since in Scheme you never get to see
2336 the bytes, only the characters.
2338 Well, ideally, anyway. Right now, Guile simply equates Scheme
2339 characters and bytes, ignoring the possibility of multi-byte encodings
2340 completely. This will change in the future, where Guile will use
2341 Unicode codepoints as its characters and UTF-8 (or maybe UCS-4) as its
2342 internal encoding. When you exclusively use the functions listed in
2343 this section, you are `future-proof'.
2345 Converting a Scheme string to a C string will often allocate fresh
2346 memory to hold the result. You must take care that this memory is
2347 properly freed eventually. In many cases, this can be achieved by
2348 using @code{scm_frame_free} inside an appropriate frame,
2351 @deftypefn {C Function} SCM scm_from_locale_string (const char *str)
2352 @deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
2353 Creates a new Scheme string that has the same contents as @var{str}
2354 when interpreted in the current locale character encoding.
2356 For @code{scm_from_locale_string}, @var{str} must be null-terminated.
2358 For @code{scm_from_locale_stringn}, @var{len} specifies the length of
2359 @var{str} in bytes, and @var{str} does not need to be null-terminated.
2360 If @var{len} is @code{(size_t)-1}, then @var{str} does need to be
2361 null-terminated and the real length will be found with @code{strlen}.
2364 @deftypefn {C Function} SCM scm_take_locale_string (char *str)
2365 @deftypefnx {C Function} SCM scm_take_locale_stringn (char *str, size_t len)
2366 Like @code{scm_from_locale_string} and @code{scm_from_locale_stringn},
2367 respectively, but also frees @var{str} with @code{free} eventually.
2368 Thus, you can use this function when you would free @var{str} anyway
2369 immediately after creating the Scheme string. In certain cases, Guile
2370 can then use @var{str} directly as its internal representation.
2373 @deftypefn {C Function} char *scm_to_locale_string (SCM str)
2374 @deftypefnx {C Function} char *scm_to_locale_stringn (SCM str, size_t *lenp)
2375 Returns a C string in the current locale encoding with the same
2376 contents as @var{str}. The C string must be freed with @code{free}
2377 eventually, maybe by using @code{scm_frame_free}, @xref{Frames}.
2379 For @code{scm_to_locale_string}, the returned string is
2380 null-terminated and an error is signalled when @var{str} contains
2381 @code{#\nul} characters.
2383 For @code{scm_to_locale_stringn} and @var{lenp} not @code{NULL},
2384 @var{str} might contain @code{#\nul} characters and the length of the
2385 returned string in bytes is stored in @code{*@var{lenp}}. The
2386 returned string will not be null-terminated in this case. If
2387 @var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
2388 @code{scm_to_locale_string}.
2391 @deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
2392 Puts @var{str} as a C string in the current locale encoding into the
2393 memory pointed to by @var{buf}. The buffer at @var{buf} has room for
2394 @var{max_len} bytes and @code{scm_to_local_stringbuf} will never store
2395 more than that. No terminating @code{'\0'} will be stored.
2397 The return value of @code{scm_to_locale_stringbuf} is the number of
2398 bytes that are needed for all of @var{str}, regardless of whether
2399 @var{buf} was large enough to hold them. Thus, when the return value
2400 is larger than @var{max_len}, only @var{max_len} bytes have been
2401 stored and you probably need to try again with a larger buffer.
2404 @node Regular Expressions
2405 @subsection Regular Expressions
2406 @tpindex Regular expressions
2408 @cindex regular expressions
2410 @cindex emacs regexp
2412 A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
2413 describes a whole class of strings. A full description of regular
2414 expressions and their syntax is beyond the scope of this manual;
2415 an introduction can be found in the Emacs manual (@pxref{Regexps,
2416 , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
2417 in many general Unix reference books.
2419 If your system does not include a POSIX regular expression library,
2420 and you have not linked Guile with a third-party regexp library such
2421 as Rx, these functions will not be available. You can tell whether
2422 your Guile installation includes regular expression support by
2423 checking whether @code{(provided? 'regex)} returns true.
2425 The following regexp and string matching features are provided by the
2426 @code{(ice-9 regex)} module. Before using the described functions,
2427 you should load this module by executing @code{(use-modules (ice-9
2431 * Regexp Functions:: Functions that create and match regexps.
2432 * Match Structures:: Finding what was matched by a regexp.
2433 * Backslash Escapes:: Removing the special meaning of regexp
2438 @node Regexp Functions
2439 @subsubsection Regexp Functions
2441 By default, Guile supports POSIX extended regular expressions.
2442 That means that the characters @samp{(}, @samp{)}, @samp{+} and
2443 @samp{?} are special, and must be escaped if you wish to match the
2446 This regular expression interface was modeled after that
2447 implemented by SCSH, the Scheme Shell. It is intended to be
2448 upwardly compatible with SCSH regular expressions.
2450 @deffn {Scheme Procedure} string-match pattern str [start]
2451 Compile the string @var{pattern} into a regular expression and compare
2452 it with @var{str}. The optional numeric argument @var{start} specifies
2453 the position of @var{str} at which to begin matching.
2455 @code{string-match} returns a @dfn{match structure} which
2456 describes what, if anything, was matched by the regular
2457 expression. @xref{Match Structures}. If @var{str} does not match
2458 @var{pattern} at all, @code{string-match} returns @code{#f}.
2461 Two examples of a match follow. In the first example, the pattern
2462 matches the four digits in the match string. In the second, the pattern
2466 (string-match "[0-9][0-9][0-9][0-9]" "blah2002")
2467 @result{} #("blah2002" (4 . 8))
2469 (string-match "[A-Za-z]" "123456")
2473 Each time @code{string-match} is called, it must compile its
2474 @var{pattern} argument into a regular expression structure. This
2475 operation is expensive, which makes @code{string-match} inefficient if
2476 the same regular expression is used several times (for example, in a
2477 loop). For better performance, you can compile a regular expression in
2478 advance and then match strings against the compiled regexp.
2480 @deffn {Scheme Procedure} make-regexp pat flag@dots{}
2481 @deffnx {C Function} scm_make_regexp (pat, flaglst)
2482 Compile the regular expression described by @var{pat}, and
2483 return the compiled regexp structure. If @var{pat} does not
2484 describe a legal regular expression, @code{make-regexp} throws
2485 a @code{regular-expression-syntax} error.
2487 The @var{flag} arguments change the behavior of the compiled
2488 regular expression. The following values may be supplied:
2490 @defvar regexp/icase
2491 Consider uppercase and lowercase letters to be the same when
2495 @defvar regexp/newline
2496 If a newline appears in the target string, then permit the
2497 @samp{^} and @samp{$} operators to match immediately after or
2498 immediately before the newline, respectively. Also, the
2499 @samp{.} and @samp{[^...]} operators will never match a newline
2500 character. The intent of this flag is to treat the target
2501 string as a buffer containing many lines of text, and the
2502 regular expression as a pattern that may match a single one of
2506 @defvar regexp/basic
2507 Compile a basic (``obsolete'') regexp instead of the extended
2508 (``modern'') regexps that are the default. Basic regexps do
2509 not consider @samp{|}, @samp{+} or @samp{?} to be special
2510 characters, and require the @samp{@{...@}} and @samp{(...)}
2511 metacharacters to be backslash-escaped (@pxref{Backslash
2512 Escapes}). There are several other differences between basic
2513 and extended regular expressions, but these are the most
2517 @defvar regexp/extended
2518 Compile an extended regular expression rather than a basic
2519 regexp. This is the default behavior; this flag will not
2520 usually be needed. If a call to @code{make-regexp} includes
2521 both @code{regexp/basic} and @code{regexp/extended} flags, the
2522 one which comes last will override the earlier one.
2526 @deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
2527 @deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
2528 Match the compiled regular expression @var{rx} against
2529 @code{str}. If the optional integer @var{start} argument is
2530 provided, begin matching from that position in the string.
2531 Return a match structure describing the results of the match,
2532 or @code{#f} if no match could be found.
2534 The @var{flags} arguments change the matching behavior.
2535 The following flags may be supplied:
2537 @defvar regexp/notbol
2538 Operator @samp{^} always fails (unless @code{regexp/newline}
2539 is used). Use this when the beginning of the string should
2540 not be considered the beginning of a line.
2543 @defvar regexp/noteol
2544 Operator @samp{$} always fails (unless @code{regexp/newline}
2545 is used). Use this when the end of the string should not be
2546 considered the end of a line.
2551 ;; Regexp to match uppercase letters
2552 (define r (make-regexp "[A-Z]*"))
2554 ;; Regexp to match letters, ignoring case
2555 (define ri (make-regexp "[A-Z]*" regexp/icase))
2557 ;; Search for bob using regexp r
2558 (match:substring (regexp-exec r "bob"))
2559 @result{} "" ; no match
2561 ;; Search for bob using regexp ri
2562 (match:substring (regexp-exec ri "Bob"))
2563 @result{} "Bob" ; matched case insensitive
2566 @deffn {Scheme Procedure} regexp? obj
2567 @deffnx {C Function} scm_regexp_p (obj)
2568 Return @code{#t} if @var{obj} is a compiled regular expression,
2569 or @code{#f} otherwise.
2572 Regular expressions are commonly used to find patterns in one string and
2573 replace them with the contents of another string.
2575 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
2576 @deffn {Scheme Procedure} regexp-substitute port match [item@dots{}]
2577 Write to the output port @var{port} selected contents of the match
2578 structure @var{match}. Each @var{item} specifies what should be
2579 written, and may be one of the following arguments:
2583 A string. String arguments are written out verbatim.
2586 An integer. The submatch with that number is written.
2589 The symbol @samp{pre}. The portion of the matched string preceding
2590 the regexp match is written.
2593 The symbol @samp{post}. The portion of the matched string following
2594 the regexp match is written.
2597 The @var{port} argument may be @code{#f}, in which case nothing is
2598 written; instead, @code{regexp-substitute} constructs a string from the
2599 specified @var{item}s and returns that.
2602 The following example takes a regular expression that matches a standard
2603 @sc{yyyymmdd}-format date such as @code{"20020828"}. The
2604 @code{regexp-substitute} call returns a string computed from the
2605 information in the match structure, consisting of the fields and text
2606 from the original string reordered and reformatted.
2609 (define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
2610 (define s "Date 20020429 12am.")
2611 (define sm (string-match date-regex s))
2612 (regexp-substitute #f sm 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
2613 @result{} "Date 04-29-2002 12am. (20020429)"
2616 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
2617 @deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
2618 Similar to @code{regexp-substitute}, but can be used to perform global
2619 substitutions on @var{str}. Instead of taking a match structure as an
2620 argument, @code{regexp-substitute/global} takes two string arguments: a
2621 @var{regexp} string describing a regular expression, and a @var{target}
2622 string which should be matched against this regular expression.
2624 Each @var{item} behaves as in @code{regexp-substitute}, with the
2625 following exceptions:
2629 A function may be supplied. When this function is called, it will be
2630 passed one argument: a match structure for a given regular expression
2631 match. It should return a string to be written out to @var{port}.
2634 The @samp{post} symbol causes @code{regexp-substitute/global} to recurse
2635 on the unmatched portion of @var{str}. This @emph{must} be supplied in
2636 order to perform global search-and-replace on @var{str}; if it is not
2637 present among the @var{item}s, then @code{regexp-substitute/global} will
2638 return after processing a single match.
2642 The example above for @code{regexp-substitute} could be rewritten as
2643 follows to remove the @code{string-match} stage:
2646 (define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
2647 (define s "Date 20020429 12am.")
2648 (regexp-substitute/global #f date-regex s
2649 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
2650 @result{} "Date 04-29-2002 12am. (20020429)"
2654 @node Match Structures
2655 @subsubsection Match Structures
2657 @cindex match structures
2659 A @dfn{match structure} is the object returned by @code{string-match} and
2660 @code{regexp-exec}. It describes which portion of a string, if any,
2661 matched the given regular expression. Match structures include: a
2662 reference to the string that was checked for matches; the starting and
2663 ending positions of the regexp match; and, if the regexp included any
2664 parenthesized subexpressions, the starting and ending positions of each
2667 In each of the regexp match functions described below, the @code{match}
2668 argument must be a match structure returned by a previous call to
2669 @code{string-match} or @code{regexp-exec}. Most of these functions
2670 return some information about the original target string that was
2671 matched against a regular expression; we will call that string
2672 @var{target} for easy reference.
2674 @c begin (scm-doc-string "regex.scm" "regexp-match?")
2675 @deffn {Scheme Procedure} regexp-match? obj
2676 Return @code{#t} if @var{obj} is a match structure returned by a
2677 previous call to @code{regexp-exec}, or @code{#f} otherwise.
2680 @c begin (scm-doc-string "regex.scm" "match:substring")
2681 @deffn {Scheme Procedure} match:substring match [n]
2682 Return the portion of @var{target} matched by subexpression number
2683 @var{n}. Submatch 0 (the default) represents the entire regexp match.
2684 If the regular expression as a whole matched, but the subexpression
2685 number @var{n} did not match, return @code{#f}.
2689 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2693 ;; match starting at offset 6 in the string
2695 (string-match "[0-9][0-9][0-9][0-9]" "blah987654" 6))
2699 @c begin (scm-doc-string "regex.scm" "match:start")
2700 @deffn {Scheme Procedure} match:start match [n]
2701 Return the starting position of submatch number @var{n}.
2704 In the following example, the result is 4, since the match starts at
2708 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2713 @c begin (scm-doc-string "regex.scm" "match:end")
2714 @deffn {Scheme Procedure} match:end match [n]
2715 Return the ending position of submatch number @var{n}.
2718 In the following example, the result is 8, since the match runs between
2719 characters 4 and 8 (i.e. the ``2002'').
2722 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2727 @c begin (scm-doc-string "regex.scm" "match:prefix")
2728 @deffn {Scheme Procedure} match:prefix match
2729 Return the unmatched portion of @var{target} preceding the regexp match.
2732 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2738 @c begin (scm-doc-string "regex.scm" "match:suffix")
2739 @deffn {Scheme Procedure} match:suffix match
2740 Return the unmatched portion of @var{target} following the regexp match.
2744 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2749 @c begin (scm-doc-string "regex.scm" "match:count")
2750 @deffn {Scheme Procedure} match:count match
2751 Return the number of parenthesized subexpressions from @var{match}.
2752 Note that the entire regular expression match itself counts as a
2753 subexpression, and failed submatches are included in the count.
2756 @c begin (scm-doc-string "regex.scm" "match:string")
2757 @deffn {Scheme Procedure} match:string match
2758 Return the original @var{target} string.
2762 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2764 @result{} "blah2002foo"
2768 @node Backslash Escapes
2769 @subsubsection Backslash Escapes
2771 Sometimes you will want a regexp to match characters like @samp{*} or
2772 @samp{$} exactly. For example, to check whether a particular string
2773 represents a menu entry from an Info node, it would be useful to match
2774 it against a regexp like @samp{^* [^:]*::}. However, this won't work;
2775 because the asterisk is a metacharacter, it won't match the @samp{*} at
2776 the beginning of the string. In this case, we want to make the first
2779 You can do this by preceding the metacharacter with a backslash
2780 character @samp{\}. (This is also called @dfn{quoting} the
2781 metacharacter, and is known as a @dfn{backslash escape}.) When Guile
2782 sees a backslash in a regular expression, it considers the following
2783 glyph to be an ordinary character, no matter what special meaning it
2784 would ordinarily have. Therefore, we can make the above example work by
2785 changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells
2786 the regular expression engine to match only a single asterisk in the
2789 Since the backslash is itself a metacharacter, you may force a regexp to
2790 match a backslash in the target string by preceding the backslash with
2791 itself. For example, to find variable references in a @TeX{} program,
2792 you might want to find occurrences of the string @samp{\let\} followed
2793 by any number of alphabetic characters. The regular expression
2794 @samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the
2795 regexp each match a single backslash in the target string.
2797 @c begin (scm-doc-string "regex.scm" "regexp-quote")
2798 @deffn {Scheme Procedure} regexp-quote str
2799 Quote each special character found in @var{str} with a backslash, and
2800 return the resulting string.
2803 @strong{Very important:} Using backslash escapes in Guile source code
2804 (as in Emacs Lisp or C) can be tricky, because the backslash character
2805 has special meaning for the Guile reader. For example, if Guile
2806 encounters the character sequence @samp{\n} in the middle of a string
2807 while processing Scheme code, it replaces those characters with a
2808 newline character. Similarly, the character sequence @samp{\t} is
2809 replaced by a horizontal tab. Several of these @dfn{escape sequences}
2810 are processed by the Guile reader before your code is executed.
2811 Unrecognized escape sequences are ignored: if the characters @samp{\*}
2812 appear in a string, they will be translated to the single character
2815 This translation is obviously undesirable for regular expressions, since
2816 we want to be able to include backslashes in a string in order to
2817 escape regexp metacharacters. Therefore, to make sure that a backslash
2818 is preserved in a string in your Guile program, you must use @emph{two}
2819 consecutive backslashes:
2822 (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
2825 The string in this example is preprocessed by the Guile reader before
2826 any code is executed. The resulting argument to @code{make-regexp} is
2827 the string @samp{^\* [^:]*}, which is what we really want.
2829 This also means that in order to write a regular expression that matches
2830 a single backslash character, the regular expression string in the
2831 source code must include @emph{four} backslashes. Each consecutive pair
2832 of backslashes gets translated by the Guile reader to a single
2833 backslash, and the resulting double-backslash is interpreted by the
2834 regexp engine as matching a single backslash character. Hence:
2837 (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
2840 The reason for the unwieldiness of this syntax is historical. Both
2841 regular expression pattern matchers and Unix string processing systems
2842 have traditionally used backslashes with the special meanings
2843 described above. The POSIX regular expression specification and ANSI C
2844 standard both require these semantics. Attempting to abandon either
2845 convention would cause other kinds of compatibility problems, possibly
2846 more severe ones. Therefore, without extending the Scheme reader to
2847 support strings with different quoting conventions (an ungainly and
2848 confusing extension when implemented in other languages), we must adhere
2849 to this cumbersome escape syntax.
2856 Symbols in Scheme are widely used in three ways: as items of discrete
2857 data, as lookup keys for alists and hash tables, and to denote variable
2860 A @dfn{symbol} is similar to a string in that it is defined by a
2861 sequence of characters. The sequence of characters is known as the
2862 symbol's @dfn{name}. In the usual case --- that is, where the symbol's
2863 name doesn't include any characters that could be confused with other
2864 elements of Scheme syntax --- a symbol is written in a Scheme program by
2865 writing the sequence of characters that make up the name, @emph{without}
2866 any quotation marks or other special syntax. For example, the symbol
2867 whose name is ``multiply-by-2'' is written, simply:
2873 Notice how this differs from a @emph{string} with contents
2874 ``multiply-by-2'', which is written with double quotation marks, like
2881 Looking beyond how they are written, symbols are different from strings
2882 in two important respects.
2884 The first important difference is uniqueness. If the same-looking
2885 string is read twice from two different places in a program, the result
2886 is two @emph{different} string objects whose contents just happen to be
2887 the same. If, on the other hand, the same-looking symbol is read twice
2888 from two different places in a program, the result is the @emph{same}
2889 symbol object both times.
2891 Given two read symbols, you can use @code{eq?} to test whether they are
2892 the same (that is, have the same name). @code{eq?} is the most
2893 efficient comparison operator in Scheme, and comparing two symbols like
2894 this is as fast as comparing, for example, two numbers. Given two
2895 strings, on the other hand, you must use @code{equal?} or
2896 @code{string=?}, which are much slower comparison operators, to
2897 determine whether the strings have the same contents.
2900 (define sym1 (quote hello))
2901 (define sym2 (quote hello))
2902 (eq? sym1 sym2) @result{} #t
2904 (define str1 "hello")
2905 (define str2 "hello")
2906 (eq? str1 str2) @result{} #f
2907 (equal? str1 str2) @result{} #t
2910 The second important difference is that symbols, unlike strings, are not
2911 self-evaluating. This is why we need the @code{(quote @dots{})}s in the
2912 example above: @code{(quote hello)} evaluates to the symbol named
2913 "hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
2914 symbol named "hello" and evaluated as a variable reference @dots{} about
2915 which more below (@pxref{Symbol Variables}).
2918 * Symbol Data:: Symbols as discrete data.
2919 * Symbol Keys:: Symbols as lookup keys.
2920 * Symbol Variables:: Symbols as denoting variables.
2921 * Symbol Primitives:: Operations related to symbols.
2922 * Symbol Props:: Function slots and property lists.
2923 * Symbol Read Syntax:: Extended read syntax for symbols.
2924 * Symbol Uninterned:: Uninterned symbols.
2929 @subsubsection Symbols as Discrete Data
2931 Numbers and symbols are similar to the extent that they both lend
2932 themselves to @code{eq?} comparison. But symbols are more descriptive
2933 than numbers, because a symbol's name can be used directly to describe
2934 the concept for which that symbol stands.
2936 For example, imagine that you need to represent some colours in a
2937 computer program. Using numbers, you would have to choose arbitrarily
2938 some mapping between numbers and colours, and then take care to use that
2939 mapping consistently:
2942 ;; 1=red, 2=green, 3=purple
2944 (if (eq? (colour-of car) 1)
2949 You can make the mapping more explicit and the code more readable by
2957 (if (eq? (colour-of car) red)
2962 But the simplest and clearest approach is not to use numbers at all, but
2963 symbols whose names specify the colours that they refer to:
2966 (if (eq? (colour-of car) 'red)
2970 The descriptive advantages of symbols over numbers increase as the set
2971 of concepts that you want to describe grows. Suppose that a car object
2972 can have other properties as well, such as whether it has or uses:
2976 automatic or manual transmission
2978 leaded or unleaded fuel
2980 power steering (or not).
2984 Then a car's combined property set could be naturally represented and
2985 manipulated as a list of symbols:
2988 (properties-of car1)
2990 (red manual unleaded power-steering)
2992 (if (memq 'power-steering (properties-of car1))
2993 (display "Unfit people can drive this car.\n")
2994 (display "You'll need strong arms to drive this car!\n"))
2996 Unfit people can drive this car.
2999 Remember, the fundamental property of symbols that we are relying on
3000 here is that an occurrence of @code{'red} in one part of a program is an
3001 @emph{indistinguishable} symbol from an occurrence of @code{'red} in
3002 another part of a program; this means that symbols can usefully be
3003 compared using @code{eq?}. At the same time, symbols have naturally
3004 descriptive names. This combination of efficiency and descriptive power
3005 makes them ideal for use as discrete data.
3009 @subsubsection Symbols as Lookup Keys
3011 Given their efficiency and descriptive power, it is natural to use
3012 symbols as the keys in an association list or hash table.
3014 To illustrate this, consider a more structured representation of the car
3015 properties example from the preceding subsection. Rather than
3016 mixing all the properties up together in a flat list, we could use an
3017 association list like this:
3020 (define car1-properties '((colour . red)
3021 (transmission . manual)
3023 (steering . power-assisted)))
3026 Notice how this structure is more explicit and extensible than the flat
3027 list. For example it makes clear that @code{manual} refers to the
3028 transmission rather than, say, the windows or the locking of the car.
3029 It also allows further properties to use the same symbols among their
3030 possible values without becoming ambiguous:
3033 (define car1-properties '((colour . red)
3034 (transmission . manual)
3036 (steering . power-assisted)
3038 (locking . manual)))
3041 With a representation like this, it is easy to use the efficient
3042 @code{assq-XXX} family of procedures (@pxref{Association Lists}) to
3043 extract or change individual pieces of information:
3046 (assq-ref car1-properties 'fuel) @result{} unleaded
3047 (assq-ref car1-properties 'transmission) @result{} manual
3049 (assq-set! car1-properties 'seat-colour 'black)
3052 (transmission . manual)
3054 (steering . power-assisted)
3055 (seat-colour . black)
3056 (locking . manual)))
3059 Hash tables also have keys, and exactly the same arguments apply to the
3060 use of symbols in hash tables as in association lists. The hash value
3061 that Guile uses to decide where to add a symbol-keyed entry to a hash
3062 table can be obtained by calling the @code{symbol-hash} procedure:
3064 @deffn {Scheme Procedure} symbol-hash symbol
3065 @deffnx {C Function} scm_symbol_hash (symbol)
3066 Return a hash value for @var{symbol}.
3069 See @ref{Hash Tables} for information about hash tables in general, and
3070 for why you might choose to use a hash table rather than an association
3074 @node Symbol Variables
3075 @subsubsection Symbols as Denoting Variables
3077 When an unquoted symbol in a Scheme program is evaluated, it is
3078 interpreted as a variable reference, and the result of the evaluation is
3079 the appropriate variable's value.
3081 For example, when the expression @code{(string-length "abcd")} is read
3082 and evaluated, the sequence of characters @code{string-length} is read
3083 as the symbol whose name is "string-length". This symbol is associated
3084 with a variable whose value is the procedure that implements string
3085 length calculation. Therefore evaluation of the @code{string-length}
3086 symbol results in that procedure.
3088 The details of the connection between an unquoted symbol and the
3089 variable to which it refers are explained elsewhere. See @ref{Binding
3090 Constructs}, for how associations between symbols and variables are
3091 created, and @ref{Modules}, for how those associations are affected by
3092 Guile's module system.
3095 @node Symbol Primitives
3096 @subsubsection Operations Related to Symbols
3098 Given any Scheme value, you can determine whether it is a symbol using
3099 the @code{symbol?} primitive:
3102 @deffn {Scheme Procedure} symbol? obj
3103 @deffnx {C Function} scm_symbol_p (obj)
3104 Return @code{#t} if @var{obj} is a symbol, otherwise return
3108 Once you know that you have a symbol, you can obtain its name as a
3109 string by calling @code{symbol->string}. Note that Guile differs by
3110 default from R5RS on the details of @code{symbol->string} as regards
3113 @rnindex symbol->string
3114 @deffn {Scheme Procedure} symbol->string s
3115 @deffnx {C Function} scm_symbol_to_string (s)
3116 Return the name of symbol @var{s} as a string. By default, Guile reads
3117 symbols case-sensitively, so the string returned will have the same case
3118 variation as the sequence of characters that caused @var{s} to be
3121 If Guile is set to read symbols case-insensitively (as specified by
3122 R5RS), and @var{s} comes into being as part of a literal expression
3123 (@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
3124 by a call to the @code{read} or @code{string-ci->symbol} procedures,
3125 Guile converts any alphabetic characters in the symbol's name to
3126 lower case before creating the symbol object, so the string returned
3127 here will be in lower case.
3129 If @var{s} was created by @code{string->symbol}, the case of characters
3130 in the string returned will be the same as that in the string that was
3131 passed to @code{string->symbol}, regardless of Guile's case-sensitivity
3132 setting at the time @var{s} was created.
3134 It is an error to apply mutation procedures like @code{string-set!} to
3135 strings returned by this procedure.
3138 Most symbols are created by writing them literally in code. However it
3139 is also possible to create symbols programmatically using the following
3140 @code{string->symbol} and @code{string-ci->symbol} procedures:
3142 @rnindex string->symbol
3143 @deffn {Scheme Procedure} string->symbol string
3144 @deffnx {C Function} scm_string_to_symbol (string)
3145 Return the symbol whose name is @var{string}. This procedure can create
3146 symbols with names containing special characters or letters in the
3147 non-standard case, but it is usually a bad idea to create such symbols
3148 because in some implementations of Scheme they cannot be read as
3152 @deffn {Scheme Procedure} string-ci->symbol str
3153 @deffnx {C Function} scm_string_ci_to_symbol (str)
3154 Return the symbol whose name is @var{str}. If Guile is currently
3155 reading symbols case-insensitively, @var{str} is converted to lowercase
3156 before the returned symbol is looked up or created.
3159 The following examples illustrate Guile's detailed behaviour as regards
3160 the case-sensitivity of symbols:
3163 (read-enable 'case-insensitive) ; R5RS compliant behaviour
3165 (symbol->string 'flying-fish) @result{} "flying-fish"
3166 (symbol->string 'Martin) @result{} "martin"
3168 (string->symbol "Malvina")) @result{} "Malvina"
3170 (eq? 'mISSISSIppi 'mississippi) @result{} #t
3171 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
3172 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
3174 (string->symbol (symbol->string 'LolliPop))) @result{} #t
3175 (string=? "K. Harper, M.D."
3177 (string->symbol "K. Harper, M.D."))) @result{} #t
3179 (read-disable 'case-insensitive) ; Guile default behaviour
3181 (symbol->string 'flying-fish) @result{} "flying-fish"
3182 (symbol->string 'Martin) @result{} "Martin"
3184 (string->symbol "Malvina")) @result{} "Malvina"
3186 (eq? 'mISSISSIppi 'mississippi) @result{} #f
3187 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
3188 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
3190 (string->symbol (symbol->string 'LolliPop))) @result{} #t
3191 (string=? "K. Harper, M.D."
3193 (string->symbol "K. Harper, M.D."))) @result{} #t
3196 From C, there are lower level functions that construct a Scheme symbol
3197 from a null terminated C string or from a sequence of bytes whose length
3198 is specified explicitly.
3200 @deffn {C Function} scm_str2symbol (const char * name)
3201 @deffnx {C Function} scm_mem2symbol (const char * name, size_t len)
3202 Construct and return a Scheme symbol whose name is specified by
3203 @var{name}. For @code{scm_str2symbol} @var{name} must be null
3204 terminated; For @code{scm_mem2symbol} the length of @var{name} is
3205 specified explicitly by @var{len}.
3208 Finally, some applications, especially those that generate new Scheme
3209 code dynamically, need to generate symbols for use in the generated
3210 code. The @code{gensym} primitive meets this need:
3212 @deffn {Scheme Procedure} gensym [prefix]
3213 @deffnx {C Function} scm_gensym (prefix)
3214 Create a new symbol with a name constructed from a prefix and a counter
3215 value. The string @var{prefix} can be specified as an optional
3216 argument. Default prefix is @samp{@w{ g}}. The counter is increased by 1
3217 at each call. There is no provision for resetting the counter.
3220 The symbols generated by @code{gensym} are @emph{likely} to be unique,
3221 since their names begin with a space and it is only otherwise possible
3222 to generate such symbols if a programmer goes out of their way to do
3223 so. Uniqueness can be guaranteed by instead using uninterned symbols
3224 (@pxref{Symbol Uninterned}), though they can't be usefully written out
3229 @subsubsection Function Slots and Property Lists
3231 In traditional Lisp dialects, symbols are often understood as having
3232 three kinds of value at once:
3236 a @dfn{variable} value, which is used when the symbol appears in
3237 code in a variable reference context
3240 a @dfn{function} value, which is used when the symbol appears in
3241 code in a function name position (i.e. as the first element in an
3245 a @dfn{property list} value, which is used when the symbol is given as
3246 the first argument to Lisp's @code{put} or @code{get} functions.
3249 Although Scheme (as one of its simplifications with respect to Lisp)
3250 does away with the distinction between variable and function namespaces,
3251 Guile currently retains some elements of the traditional structure in
3252 case they turn out to be useful when implementing translators for other
3253 languages, in particular Emacs Lisp.
3255 Specifically, Guile symbols have two extra slots. for a symbol's
3256 property list, and for its ``function value.'' The following procedures
3257 are provided to access these slots.
3259 @deffn {Scheme Procedure} symbol-fref symbol
3260 @deffnx {C Function} scm_symbol_fref (symbol)
3261 Return the contents of @var{symbol}'s @dfn{function slot}.
3264 @deffn {Scheme Procedure} symbol-fset! symbol value
3265 @deffnx {C Function} scm_symbol_fset_x (symbol, value)
3266 Set the contents of @var{symbol}'s function slot to @var{value}.
3269 @deffn {Scheme Procedure} symbol-pref symbol
3270 @deffnx {C Function} scm_symbol_pref (symbol)
3271 Return the @dfn{property list} currently associated with @var{symbol}.
3274 @deffn {Scheme Procedure} symbol-pset! symbol value
3275 @deffnx {C Function} scm_symbol_pset_x (symbol, value)
3276 Set @var{symbol}'s property list to @var{value}.
3279 @deffn {Scheme Procedure} symbol-property sym prop
3280 From @var{sym}'s property list, return the value for property
3281 @var{prop}. The assumption is that @var{sym}'s property list is an
3282 association list whose keys are distinguished from each other using
3283 @code{equal?}; @var{prop} should be one of the keys in that list. If
3284 the property list has no entry for @var{prop}, @code{symbol-property}
3288 @deffn {Scheme Procedure} set-symbol-property! sym prop val
3289 In @var{sym}'s property list, set the value for property @var{prop} to
3290 @var{val}, or add a new entry for @var{prop}, with value @var{val}, if
3291 none already exists. For the structure of the property list, see
3292 @code{symbol-property}.
3295 @deffn {Scheme Procedure} symbol-property-remove! sym prop
3296 From @var{sym}'s property list, remove the entry for property
3297 @var{prop}, if there is one. For the structure of the property list,
3298 see @code{symbol-property}.
3301 Support for these extra slots may be removed in a future release, and it
3302 is probably better to avoid using them. (In release 1.6, Guile itself
3303 uses the property list slot sparingly, and the function slot not at
3304 all.) For a more modern and Schemely approach to properties, see
3305 @ref{Object Properties}.
3308 @node Symbol Read Syntax
3309 @subsubsection Extended Read Syntax for Symbols
3311 The read syntax for a symbol is a sequence of letters, digits, and
3312 @dfn{extended alphabetic characters}, beginning with a character that
3313 cannot begin a number. In addition, the special cases of @code{+},
3314 @code{-}, and @code{...} are read as symbols even though numbers can
3315 begin with @code{+}, @code{-} or @code{.}.
3317 Extended alphabetic characters may be used within identifiers as if
3318 they were letters. The set of extended alphabetic characters is:
3321 ! $ % & * + - . / : < = > ? @@ ^ _ ~
3324 In addition to the standard read syntax defined above (which is taken
3325 from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
3326 Scheme})), Guile provides an extended symbol read syntax that allows the
3327 inclusion of unusual characters such as space characters, newlines and
3328 parentheses. If (for whatever reason) you need to write a symbol
3329 containing characters not mentioned above, you can do so as follows.
3333 Begin the symbol with the characters @code{#@{},
3336 write the characters of the symbol and
3339 finish the symbol with the characters @code{@}#}.
3342 Here are a few examples of this form of read syntax. The first symbol
3343 needs to use extended syntax because it contains a space character, the
3344 second because it contains a line break, and the last because it looks
3356 Although Guile provides this extended read syntax for symbols,
3357 widespread usage of it is discouraged because it is not portable and not
3361 @node Symbol Uninterned
3362 @subsubsection Uninterned Symbols
3364 What makes symbols useful is that they are automatically kept unique.
3365 There are no two symbols that are distinct objects but have the same
3366 name. But of course, there is no rule without exception. In addition
3367 to the normal symbols that have been discussed up to now, you can also
3368 create special @dfn{uninterned} symbols that behave slightly
3371 To understand what is different about them and why they might be useful,
3372 we look at how normal symbols are actually kept unique.
3374 Whenever Guile wants to find the symbol with a specific name, for
3375 example during @code{read} or when executing @code{string->symbol}, it
3376 first looks into a table of all existing symbols to find out whether a
3377 symbol with the given name already exists. When this is the case, Guile
3378 just returns that symbol. When not, a new symbol with the name is
3379 created and entered into the table so that it can be found later.
3381 Sometimes you might want to create a symbol that is guaranteed `fresh',
3382 i.e. a symbol that did not exist previously. You might also want to
3383 somehow guarantee that no one else will ever unintentionally stumble
3384 across your symbol in the future. These properties of a symbol are
3385 often needed when generating code during macro expansion. When
3386 introducing new temporary variables, you want to guarantee that they
3387 don't conflict with variables in other people's code.
3389 The simplest way to arrange for this is to create a new symbol but
3390 not enter it into the global table of all symbols. That way, no one
3391 will ever get access to your symbol by chance. Symbols that are not in
3392 the table are called @dfn{uninterned}. Of course, symbols that
3393 @emph{are} in the table are called @dfn{interned}.
3395 You create new uninterned symbols with the function @code{make-symbol}.
3396 You can test whether a symbol is interned or not with
3397 @code{symbol-interned?}.
3399 Uninterned symbols break the rule that the name of a symbol uniquely
3400 identifies the symbol object. Because of this, they can not be written
3401 out and read back in like interned symbols. Currently, Guile has no
3402 support for reading uninterned symbols. Note that the function
3403 @code{gensym} does not return uninterned symbols for this reason.
3405 @deffn {Scheme Procedure} make-symbol name
3406 @deffnx {C Function} scm_make_symbol (name)
3407 Return a new uninterned symbol with the name @var{name}. The returned
3408 symbol is guaranteed to be unique and future calls to
3409 @code{string->symbol} will not return it.
3412 @deffn {Scheme Procedure} symbol-interned? symbol
3413 @deffnx {C Function} scm_symbol_interned_p (symbol)
3414 Return @code{#t} if @var{symbol} is interned, otherwise return
3421 (define foo-1 (string->symbol "foo"))
3422 (define foo-2 (string->symbol "foo"))
3423 (define foo-3 (make-symbol "foo"))
3424 (define foo-4 (make-symbol "foo"))
3428 ; Two interned symbols with the same name are the same object,
3432 ; but a call to make-symbol with the same name returns a
3437 ; A call to make-symbol always returns a new object, even for
3441 @result{} #<uninterned-symbol foo 8085290>
3442 ; Uninterned symbols print differently from interned symbols,
3446 ; but they are still symbols,
3448 (symbol-interned? foo-3)
3450 ; just not interned.
3455 @subsection Keywords
3458 Keywords are self-evaluating objects with a convenient read syntax that
3459 makes them easy to type.
3461 Guile's keyword support conforms to R5RS, and adds a (switchable) read
3462 syntax extension to permit keywords to begin with @code{:} as well as
3466 * Why Use Keywords?:: Motivation for keyword usage.
3467 * Coding With Keywords:: How to use keywords.
3468 * Keyword Read Syntax:: Read syntax for keywords.
3469 * Keyword Procedures:: Procedures for dealing with keywords.
3470 * Keyword Primitives:: The underlying primitive procedures.
3473 @node Why Use Keywords?
3474 @subsubsection Why Use Keywords?
3476 Keywords are useful in contexts where a program or procedure wants to be
3477 able to accept a large number of optional arguments without making its
3478 interface unmanageable.
3480 To illustrate this, consider a hypothetical @code{make-window}
3481 procedure, which creates a new window on the screen for drawing into
3482 using some graphical toolkit. There are many parameters that the caller
3483 might like to specify, but which could also be sensibly defaulted, for
3488 color depth -- Default: the color depth for the screen
3491 background color -- Default: white
3494 width -- Default: 600
3497 height -- Default: 400
3500 If @code{make-window} did not use keywords, the caller would have to
3501 pass in a value for each possible argument, remembering the correct
3502 argument order and using a special value to indicate the default value
3506 (make-window 'default ;; Color depth
3507 'default ;; Background color
3510 @dots{}) ;; More make-window arguments
3513 With keywords, on the other hand, defaulted arguments are omitted, and
3514 non-default arguments are clearly tagged by the appropriate keyword. As
3515 a result, the invocation becomes much clearer:
3518 (make-window #:width 800 #:height 100)
3521 On the other hand, for a simpler procedure with few arguments, the use
3522 of keywords would be a hindrance rather than a help. The primitive
3523 procedure @code{cons}, for example, would not be improved if it had to
3527 (cons #:car x #:cdr y)
3530 So the decision whether to use keywords or not is purely pragmatic: use
3531 them if they will clarify the procedure invocation at point of call.
3533 @node Coding With Keywords
3534 @subsubsection Coding With Keywords
3536 If a procedure wants to support keywords, it should take a rest argument
3537 and then use whatever means is convenient to extract keywords and their
3538 corresponding arguments from the contents of that rest argument.
3540 The following example illustrates the principle: the code for
3541 @code{make-window} uses a helper procedure called
3542 @code{get-keyword-value} to extract individual keyword arguments from
3546 (define (get-keyword-value args keyword default)
3547 (let ((kv (memq keyword args)))
3548 (if (and kv (>= (length kv) 2))
3552 (define (make-window . args)
3553 (let ((depth (get-keyword-value args #:depth screen-depth))
3554 (bg (get-keyword-value args #:bg "white"))
3555 (width (get-keyword-value args #:width 800))
3556 (height (get-keyword-value args #:height 100))
3561 But you don't need to write @code{get-keyword-value}. The @code{(ice-9
3562 optargs)} module provides a set of powerful macros that you can use to
3563 implement keyword-supporting procedures like this:
3566 (use-modules (ice-9 optargs))
3568 (define (make-window . args)
3569 (let-keywords args #f ((depth screen-depth)
3577 Or, even more economically, like this:
3580 (use-modules (ice-9 optargs))
3582 (define* (make-window #:key (depth screen-depth)
3589 For further details on @code{let-keywords}, @code{define*} and other
3590 facilities provided by the @code{(ice-9 optargs)} module, see
3591 @ref{Optional Arguments}.
3594 @node Keyword Read Syntax
3595 @subsubsection Keyword Read Syntax
3597 Guile, by default, only recognizes the keyword syntax specified by R5RS.
3598 A token of the form @code{#:NAME}, where @code{NAME} has the same syntax
3599 as a Scheme symbol (@pxref{Symbol Read Syntax}), is the external
3600 representation of the keyword named @code{NAME}. Keyword objects print
3601 using this syntax as well, so values containing keyword objects can be
3602 read back into Guile. When used in an expression, keywords are
3603 self-quoting objects.
3605 If the @code{keyword} read option is set to @code{'prefix}, Guile also
3606 recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
3607 of the form @code{:NAME} are read as symbols, as required by R5RS.
3609 To enable and disable the alternative non-R5RS keyword syntax, you use
3610 the @code{read-set!} procedure documented in @ref{User level options
3611 interfaces} and @ref{Reader options}.
3614 (read-set! keywords 'prefix)
3624 (read-set! keywords #f)
3632 ERROR: In expression :type:
3633 ERROR: Unbound variable: :type
3634 ABORT: (unbound-variable)
3637 @node Keyword Procedures
3638 @subsubsection Keyword Procedures
3640 The following procedures can be used for converting symbols to keywords
3643 @deffn {Scheme Procedure} symbol->keyword sym
3644 Return a keyword with the same characters as in @var{sym}.
3647 @deffn {Scheme Procedure} keyword->symbol kw
3648 Return a symbol with the same characters as in @var{kw}.
3652 @node Keyword Primitives
3653 @subsubsection Keyword Primitives
3655 Internally, a keyword is implemented as something like a tagged symbol,
3656 where the tag identifies the keyword as being self-evaluating, and the
3657 symbol, known as the keyword's @dfn{dash symbol} has the same name as
3658 the keyword name but prefixed by a single dash. For example, the
3659 keyword @code{#:name} has the corresponding dash symbol @code{-name}.
3661 Most keyword objects are constructed automatically by the reader when it
3662 reads a token beginning with @code{#:}. However, if you need to
3663 construct a keyword object programmatically, you can do so by calling
3664 @code{make-keyword-from-dash-symbol} with the corresponding dash symbol
3665 (as the reader does). The dash symbol for a keyword object can be
3666 retrieved using the @code{keyword-dash-symbol} procedure.
3668 @deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
3669 @deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
3670 Make a keyword object from a @var{symbol} that starts with a dash.
3674 (make-keyword-from-dash-symbol '-foo)
3679 @deffn {Scheme Procedure} keyword? obj
3680 @deffnx {C Function} scm_keyword_p (obj)
3681 Return @code{#t} if the argument @var{obj} is a keyword, else
3685 @deffn {Scheme Procedure} keyword-dash-symbol keyword
3686 @deffnx {C Function} scm_keyword_dash_symbol (keyword)
3687 Return the dash symbol for @var{keyword}.
3688 This is the inverse of @code{make-keyword-from-dash-symbol}.
3692 (keyword-dash-symbol #:foo)
3697 @deftypefn {C Function} SCM scm_c_make_keyword (char *@var{str})
3698 Make a keyword object from a string. For example,
3701 scm_c_make_keyword ("foo")
3705 @c FIXME: What can be said about the string argument? Currently it's
3706 @c not used after creation, but should that be documented?
3711 @subsection ``Functionality-Centric'' Data Types
3713 Procedures and macros are documented in their own chapter: see
3714 @ref{Procedures and Macros}.
3716 Variable objects are documented as part of the description of Guile's
3717 module system: see @ref{Variables}.
3719 Asyncs, dynamic roots and fluids are described in the chapter on
3720 scheduling: see @ref{Scheduling}.
3722 Hooks are documented in the chapter on general utility functions: see
3725 Ports are described in the chapter on I/O: see @ref{Input and Output}.
3729 @c TeX-master: "guile.texi"