3 @chapter Data Types for Generic Use
5 This chapter describes all the data types that Guile provides for
8 One of the great strengths of Scheme is that there is no straightforward
9 distinction between ``data'' and ``functionality''. For example,
10 Guile's support for dynamic linking could be described
14 either in a ``data-centric'' way, as the behaviour and properties of the
15 ``dynamically linked object'' data type, and the operations that may be
16 applied to instances of this type
19 or in a ``functionality-centric'' way, as the set of procedures that
20 constitute Guile's support for dynamic linking, in the context of the
24 The contents of this chapter are, therefore, a matter of judgement. By
25 ``generic use'', we mean to select those data types whose typical use as
26 @emph{data} in a wide variety of programming contexts is more important
27 than their use in the implementation of a particular piece of
34 The table of contents for this chapter
37 The following table of contents
39 shows the data types that are documented in this chapter. The final
40 section of this chapter lists all the core Guile data types that are not
41 documented here, and provides links to the ``functionality-centric''
42 sections of this manual that cover them.
45 * Booleans:: True/false values.
46 * Numbers:: Numerical data types.
47 * Characters:: New character names.
48 * Strings:: Special things about strings.
49 * Regular Expressions:: Pattern matching and substitution.
50 * Symbols and Variables:: Manipulating the Scheme symbol table.
51 * Keywords:: Self-quoting, customizable display keywords.
52 * Pairs:: Scheme's basic building block.
53 * Lists:: Special list functions supported by Guile.
54 * Vectors:: One-dimensional arrays of Scheme objects.
57 * Arrays:: Arrays of values.
58 * Association Lists and Hash Tables:: Dictionary data types.
59 * Hooks:: User-customizable event lists.
60 * Other Data Types:: Data types that are documented elsewhere.
68 The two boolean values are @code{#t} for true and @code{#f} for false.
70 Boolean values are returned by predicate procedures, such as the general
71 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
72 (@pxref{Equality}) and numerical and string comparison operators like
73 @code{string=?} (@pxref{String Comparison}) and @code{<=}
85 (equal? "house" "houses")
94 In test condition contexts like @code{if} and @code{cond} (@pxref{if
95 cond case}), where a group of subexpressions will be evaluated only if a
96 @var{condition} expression evaluates to ``true'', ``true'' means any
97 value at all except @code{#f}.
113 A result of this asymmetry is that typical Scheme source code more often
114 uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
115 represent an @code{if} or @code{cond} false value, whereas @code{#t} is
116 not necessary to represent an @code{if} or @code{cond} true value.
118 It is important to note that @code{#f} is @strong{not} equivalent to any
119 other Scheme value. In particular, @code{#f} is not the same as the
120 number 0 (like in C and C++), and not the same as the ``empty list''
121 (like in some Lisp dialects).
123 The @code{not} procedure returns the boolean inverse of its argument:
126 @deffn {Scheme Procedure} not x
127 @deffnx {C Function} scm_not (x)
128 Return @code{#t} iff @var{x} is @code{#f}, else return @code{#f}.
131 The @code{boolean?} procedure is a predicate that returns @code{#t} if
132 its argument is one of the boolean values, otherwise @code{#f}.
135 @deffn {Scheme Procedure} boolean? obj
136 @deffnx {C Function} scm_boolean_p (obj)
137 Return @code{#t} iff @var{obj} is either @code{#t} or @code{#f}.
142 @section Numerical data types
145 Guile supports a rich ``tower'' of numerical types --- integer,
146 rational, real and complex --- and provides an extensive set of
147 mathematical and scientific functions for operating on numerical
148 data. This section of the manual documents those types and functions.
150 You may also find it illuminating to read R5RS's presentation of numbers
151 in Scheme, which is particularly clear and accessible: see
152 @xref{Numbers,,,r5rs}.
155 * Numerical Tower:: Scheme's numerical "tower".
156 * Integers:: Whole numbers.
157 * Reals and Rationals:: Real and rational numbers.
158 * Complex Numbers:: Complex numbers.
159 * Exactness:: Exactness and inexactness.
160 * Number Syntax:: Read syntax for numerical data.
161 * Integer Operations:: Operations on integer values.
162 * Comparison:: Comparison predicates.
163 * Conversion:: Converting numbers to and from strings.
164 * Complex:: Complex number operations.
165 * Arithmetic:: Arithmetic functions.
166 * Scientific:: Scientific functions.
167 * Primitive Numerics:: Primitive numeric functions.
168 * Bitwise Operations:: Logical AND, OR, NOT, and so on.
169 * Random:: Random number generation.
173 @node Numerical Tower
174 @subsection Scheme's Numerical ``Tower''
177 Scheme's numerical ``tower'' consists of the following categories of
182 integers (whole numbers)
185 rationals (the set of numbers that can be expressed as P/Q where P and Q
189 real numbers (the set of numbers that describes all possible positions
190 along a one dimensional line)
193 complex numbers (the set of numbers that describes all possible
194 positions in a two dimensional space)
197 It is called a tower because each category ``sits on'' the one that
198 follows it, in the sense that every integer is also a rational, every
199 rational is also real, and every real number is also a complex number
200 (but with zero imaginary part).
202 Of these, Guile implements integers, reals and complex numbers as
203 distinct types. Rationals are implemented as regards the read syntax
204 for rational numbers that is specified by R5RS, but are immediately
205 converted by Guile to the corresponding real number.
207 The @code{number?} predicate may be applied to any Scheme value to
208 discover whether the value is any of the supported numerical types.
210 @deffn {Scheme Procedure} number? obj
211 @deffnx {C Function} scm_number_p (obj)
212 Return @code{#t} if @var{obj} is any kind of number, @code{#f} else.
223 (number? "hello there!")
227 (define pi 3.141592654)
233 The next few subsections document each of Guile's numerical data types
239 @tpindex Integer numbers
243 Integers are whole numbers, that is numbers with no fractional part,
244 such as 2, 83 and -3789.
246 Integers in Guile can be arbitrarily big, as shown by the following
250 (define (factorial n)
251 (let loop ((n n) (product 1))
254 (loop (- n 1) (* product n)))))
266 -119622220865480194561963161495657715064383733760000000000
269 Readers whose background is in programming languages where integers are
270 limited by the need to fit into just 4 or 8 bytes of memory may find
271 this surprising, or suspect that Guile's representation of integers is
272 inefficient. In fact, Guile achieves a near optimal balance of
273 convenience and efficiency by using the host computer's native
274 representation of integers where possible, and a more general
275 representation where the required number does not fit in the native
276 form. Conversion between these two representations is automatic and
277 completely invisible to the Scheme level programmer.
279 @c REFFIXME Maybe point here to discussion of handling immediates/bignums
280 @c on the C level, where the conversion is not so automatic - NJ
282 @deffn {Scheme Procedure} integer? x
283 @deffnx {C Function} scm_integer_p (x)
284 Return @code{#t} if @var{x} is an integer number, @code{#f} else.
298 @node Reals and Rationals
299 @subsection Real and Rational Numbers
300 @tpindex Real numbers
301 @tpindex Rational numbers
306 Mathematically, the real numbers are the set of numbers that describe
307 all possible points along a continuous, infinite, one-dimensional line.
308 The rational numbers are the set of all numbers that can be written as
309 fractions P/Q, where P and Q are integers. All rational numbers are
310 also real, but there are real numbers that are not rational, for example
311 the square root of 2, and pi.
313 Guile represents both real and rational numbers approximately using a
314 floating point encoding with limited precision. Even though the actual
315 encoding is in binary, it may be helpful to think of it as a decimal
316 number with a limited number of significant figures and a decimal point
317 somewhere, since this corresponds to the standard notation for non-whole
318 numbers. For example:
323 -5648394822220000000000.0
327 The limited precision of Guile's encoding means that any ``real'' number
328 in Guile can be written in a rational form, by multiplying and then dividing
329 by sufficient powers of 10 (or in fact, 2). For example,
330 @code{-0.00000142857931198} is the same as @code{142857931198} divided by
331 @code{100000000000000000}. In Guile's current incarnation, therefore,
332 the @code{rational?} and @code{real?} predicates are equivalent.
334 Another aspect of this equivalence is that Guile currently does not
335 preserve the exactness that is possible with rational arithmetic.
336 If such exactness is needed, it is of course possible to implement
337 exact rational arithmetic at the Scheme level using Guile's arbitrary
340 A planned future revision of Guile's numerical tower will make it
341 possible to implement exact representations and arithmetic for both
342 rational numbers and real irrational numbers such as square roots,
343 and in such a way that the new kinds of number integrate seamlessly
344 with those that are already implemented.
346 @deffn {Scheme Procedure} real? obj
347 @deffnx {C Function} scm_real_p (obj)
348 Return @code{#t} if @var{obj} is a real number, @code{#f} else.
349 Note that the sets of integer and rational values form subsets
350 of the set of real numbers, so the predicate will also be fulfilled
351 if @var{obj} is an integer number or a rational number.
355 @deffn {Scheme Procedure} rational? x
356 @deffnx {C Function} scm_real_p (x)
357 Return @code{#t} if @var{x} is a rational number, @code{#f}
358 else. Note that the set of integer values forms a subset of
359 the set of rational numbers, i. e. the predicate will also be
360 fulfilled if @var{x} is an integer number. Real numbers
361 will also satisfy this predicate, because of their limited
366 @node Complex Numbers
367 @subsection Complex Numbers
368 @tpindex Complex numbers
372 Complex numbers are the set of numbers that describe all possible points
373 in a two-dimensional space. The two coordinates of a particular point
374 in this space are known as the @dfn{real} and @dfn{imaginary} parts of
375 the complex number that describes that point.
377 In Guile, complex numbers are written in rectangular form as the sum of
378 their real and imaginary parts, using the symbol @code{i} to indicate
391 Guile represents a complex number as a pair of numbers both of which are
392 real, so the real and imaginary parts of a complex number have the same
393 properties of inexactness and limited precision as single real numbers.
395 @deffn {Scheme Procedure} complex? x
396 @deffnx {C Function} scm_number_p (x)
397 Return @code{#t} if @var{x} is a complex number, @code{#f}
398 else. Note that the sets of real, rational and integer
399 values form subsets of the set of complex numbers, i. e. the
400 predicate will also be fulfilled if @var{x} is a real,
401 rational or integer number.
406 @subsection Exact and Inexact Numbers
407 @tpindex Exact numbers
408 @tpindex Inexact numbers
412 @rnindex exact->inexact
413 @rnindex inexact->exact
415 R5RS requires that a calculation involving inexact numbers always
416 produces an inexact result. To meet this requirement, Guile
417 distinguishes between an exact integer value such as @code{5} and the
418 corresponding inexact real value which, to the limited precision
419 available, has no fractional part, and is printed as @code{5.0}. Guile
420 will only convert the latter value to the former when forced to do so by
421 an invocation of the @code{inexact->exact} procedure.
423 @deffn {Scheme Procedure} exact? x
424 @deffnx {C Function} scm_exact_p (x)
425 Return @code{#t} if @var{x} is an exact number, @code{#f}
429 @deffn {Scheme Procedure} inexact? x
430 @deffnx {C Function} scm_inexact_p (x)
431 Return @code{#t} if @var{x} is an inexact number, @code{#f}
435 @deffn {Scheme Procedure} inexact->exact z
436 @deffnx {C Function} scm_inexact_to_exact (z)
437 Return an exact number that is numerically closest to @var{z}.
440 @c begin (texi-doc-string "guile" "exact->inexact")
441 @deffn {Scheme Procedure} exact->inexact z
442 Convert the number @var{z} to its inexact representation.
447 @subsection Read Syntax for Numerical Data
449 The read syntax for integers is a string of digits, optionally
450 preceded by a minus or plus character, a code indicating the
451 base in which the integer is encoded, and a code indicating whether
452 the number is exact or inexact. The supported base codes are:
456 @code{#b}, @code{#B} --- the integer is written in binary (base 2)
459 @code{#o}, @code{#O} --- the integer is written in octal (base 8)
462 @code{#d}, @code{#D} --- the integer is written in decimal (base 10)
465 @code{#x}, @code{#X} --- the integer is written in hexadecimal (base 16).
468 If the base code is omitted, the integer is assumed to be decimal. The
469 following examples show how these base codes are used.
493 The codes for indicating exactness (which can, incidentally, be applied
494 to all numerical values) are:
498 @code{#e}, @code{#E} --- the number is exact
501 @code{#i}, @code{#I} --- the number is inexact.
504 If the exactness indicator is omitted, the integer is assumed to be exact,
505 since Guile's internal representation for integers is always exact.
506 Real numbers have limited precision similar to the precision of the
507 @code{double} type in C. A consequence of the limited precision is that
508 all real numbers in Guile are also rational, since any number R with a
509 limited number of decimal places, say N, can be made into an integer by
513 @node Integer Operations
514 @subsection Operations on Integer Values
523 @deffn {Scheme Procedure} odd? n
524 @deffnx {C Function} scm_odd_p (n)
525 Return @code{#t} if @var{n} is an odd number, @code{#f}
529 @deffn {Scheme Procedure} even? n
530 @deffnx {C Function} scm_even_p (n)
531 Return @code{#t} if @var{n} is an even number, @code{#f}
535 @c begin (texi-doc-string "guile" "quotient")
536 @deffn {Scheme Procedure} quotient
537 Return the quotient of the numbers @var{x} and @var{y}.
540 @c begin (texi-doc-string "guile" "remainder")
541 @deffn {Scheme Procedure} remainder
542 Return the remainder of the numbers @var{x} and @var{y}.
544 (remainder 13 4) @result{} 1
545 (remainder -13 4) @result{} -1
549 @c begin (texi-doc-string "guile" "modulo")
550 @deffn {Scheme Procedure} modulo
551 Return the modulo of the numbers @var{x} and @var{y}.
553 (modulo 13 4) @result{} 1
554 (modulo -13 4) @result{} 3
558 @c begin (texi-doc-string "guile" "gcd")
559 @deffn {Scheme Procedure} gcd
560 Return the greatest common divisor of all arguments.
561 If called without arguments, 0 is returned.
564 @c begin (texi-doc-string "guile" "lcm")
565 @deffn {Scheme Procedure} lcm
566 Return the least common multiple of the arguments.
567 If called without arguments, 1 is returned.
572 @subsection Comparison Predicates
577 @c begin (texi-doc-string "guile" "=")
578 @deffn {Scheme Procedure} =
579 Return @code{#t} if all parameters are numerically equal.
582 @c begin (texi-doc-string "guile" "<")
583 @deffn {Scheme Procedure} <
584 Return @code{#t} if the list of parameters is monotonically
588 @c begin (texi-doc-string "guile" ">")
589 @deffn {Scheme Procedure} >
590 Return @code{#t} if the list of parameters is monotonically
594 @c begin (texi-doc-string "guile" "<=")
595 @deffn {Scheme Procedure} <=
596 Return @code{#t} if the list of parameters is monotonically
600 @c begin (texi-doc-string "guile" ">=")
601 @deffn {Scheme Procedure} >=
602 Return @code{#t} if the list of parameters is monotonically
606 @c begin (texi-doc-string "guile" "zero?")
607 @deffn {Scheme Procedure} zero?
608 Return @code{#t} if @var{z} is an exact or inexact number equal to
612 @c begin (texi-doc-string "guile" "positive?")
613 @deffn {Scheme Procedure} positive?
614 Return @code{#t} if @var{x} is an exact or inexact number greater than
618 @c begin (texi-doc-string "guile" "negative?")
619 @deffn {Scheme Procedure} negative?
620 Return @code{#t} if @var{x} is an exact or inexact number less than
626 @subsection Converting Numbers To and From Strings
627 @rnindex number->string
628 @rnindex string->number
630 @deffn {Scheme Procedure} number->string n [radix]
631 @deffnx {C Function} scm_number_to_string (n, radix)
632 Return a string holding the external representation of the
633 number @var{n} in the given @var{radix}. If @var{n} is
634 inexact, a radix of 10 will be used.
637 @deffn {Scheme Procedure} string->number string [radix]
638 @deffnx {C Function} scm_string_to_number (string, radix)
639 Return a number of the maximally precise representation
640 expressed by the given @var{string}. @var{radix} must be an
641 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
642 is a default radix that may be overridden by an explicit radix
643 prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
644 supplied, then the default radix is 10. If string is not a
645 syntactically valid notation for a number, then
646 @code{string->number} returns @code{#f}.
651 @subsection Complex Number Operations
652 @rnindex make-rectangular
659 @deffn {Scheme Procedure} make-rectangular real imaginary
660 @deffnx {C Function} scm_make_rectangular (real, imaginary)
661 Return a complex number constructed of the given @var{real} and
662 @var{imaginary} parts.
665 @deffn {Scheme Procedure} make-polar x y
666 @deffnx {C Function} scm_make_polar (x, y)
667 Return the complex number @var{x} * e^(i * @var{y}).
670 @c begin (texi-doc-string "guile" "real-part")
671 @deffn {Scheme Procedure} real-part
672 Return the real part of the number @var{z}.
675 @c begin (texi-doc-string "guile" "imag-part")
676 @deffn {Scheme Procedure} imag-part
677 Return the imaginary part of the number @var{z}.
680 @c begin (texi-doc-string "guile" "magnitude")
681 @deffn {Scheme Procedure} magnitude
682 Return the magnitude of the number @var{z}. This is the same as
683 @code{abs} for real arguments, but also allows complex numbers.
686 @c begin (texi-doc-string "guile" "angle")
687 @deffn {Scheme Procedure} angle
688 Return the angle of the complex number @var{z}.
693 @subsection Arithmetic Functions
706 @c begin (texi-doc-string "guile" "+")
707 @deffn {Scheme Procedure} + z1 @dots{}
708 Return the sum of all parameter values. Return 0 if called without any
712 @c begin (texi-doc-string "guile" "-")
713 @deffn {Scheme Procedure} - z1 z2 @dots{}
714 If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
715 the sum of all but the first argument are subtracted from the first
719 @c begin (texi-doc-string "guile" "*")
720 @deffn {Scheme Procedure} * z1 @dots{}
721 Return the product of all arguments. If called without arguments, 1 is
725 @c begin (texi-doc-string "guile" "/")
726 @deffn {Scheme Procedure} / z1 z2 @dots{}
727 Divide the first argument by the product of the remaining arguments. If
728 called with one argument @var{z1}, 1/@var{z1} is returned.
731 @c begin (texi-doc-string "guile" "abs")
732 @deffn {Scheme Procedure} abs x
733 Return the absolute value of @var{x}.
736 @c begin (texi-doc-string "guile" "max")
737 @deffn {Scheme Procedure} max x1 x2 @dots{}
738 Return the maximum of all parameter values.
741 @c begin (texi-doc-string "guile" "min")
742 @deffn {Scheme Procedure} min x1 x2 @dots{}
743 Return the minium of all parameter values.
746 @c begin (texi-doc-string "guile" "truncate")
747 @deffn {Scheme Procedure} truncate
748 Round the inexact number @var{x} towards zero.
751 @c begin (texi-doc-string "guile" "round")
752 @deffn {Scheme Procedure} round x
753 Round the inexact number @var{x} towards zero.
756 @c begin (texi-doc-string "guile" "floor")
757 @deffn {Scheme Procedure} floor x
758 Round the number @var{x} towards minus infinity.
761 @c begin (texi-doc-string "guile" "ceiling")
762 @deffn {Scheme Procedure} ceiling x
763 Round the number @var{x} towards infinity.
768 @subsection Scientific Functions
770 The following procedures accept any kind of number as arguments,
771 including complex numbers.
774 @c begin (texi-doc-string "guile" "sqrt")
775 @deffn {Scheme Procedure} sqrt z
776 Return the square root of @var{z}.
780 @c begin (texi-doc-string "guile" "expt")
781 @deffn {Scheme Procedure} expt z1 z2
782 Return @var{z1} raised to the power of @var{z2}.
786 @c begin (texi-doc-string "guile" "sin")
787 @deffn {Scheme Procedure} sin z
788 Return the sine of @var{z}.
792 @c begin (texi-doc-string "guile" "cos")
793 @deffn {Scheme Procedure} cos z
794 Return the cosine of @var{z}.
798 @c begin (texi-doc-string "guile" "tan")
799 @deffn {Scheme Procedure} tan z
800 Return the tangent of @var{z}.
804 @c begin (texi-doc-string "guile" "asin")
805 @deffn {Scheme Procedure} asin z
806 Return the arcsine of @var{z}.
810 @c begin (texi-doc-string "guile" "acos")
811 @deffn {Scheme Procedure} acos z
812 Return the arccosine of @var{z}.
816 @c begin (texi-doc-string "guile" "atan")
817 @deffn {Scheme Procedure} atan z
818 Return the arctangent of @var{z}.
822 @c begin (texi-doc-string "guile" "exp")
823 @deffn {Scheme Procedure} exp z
824 Return e to the power of @var{z}, where e is the base of natural
825 logarithms (2.71828@dots{}).
829 @c begin (texi-doc-string "guile" "log")
830 @deffn {Scheme Procedure} log z
831 Return the natural logarithm of @var{z}.
834 @c begin (texi-doc-string "guile" "log10")
835 @deffn {Scheme Procedure} log10 z
836 Return the base 10 logarithm of @var{z}.
839 @c begin (texi-doc-string "guile" "sinh")
840 @deffn {Scheme Procedure} sinh z
841 Return the hyperbolic sine of @var{z}.
844 @c begin (texi-doc-string "guile" "cosh")
845 @deffn {Scheme Procedure} cosh z
846 Return the hyperbolic cosine of @var{z}.
849 @c begin (texi-doc-string "guile" "tanh")
850 @deffn {Scheme Procedure} tanh z
851 Return the hyperbolic tangent of @var{z}.
854 @c begin (texi-doc-string "guile" "asinh")
855 @deffn {Scheme Procedure} asinh z
856 Return the hyperbolic arcsine of @var{z}.
859 @c begin (texi-doc-string "guile" "acosh")
860 @deffn {Scheme Procedure} acosh z
861 Return the hyperbolic arccosine of @var{z}.
864 @c begin (texi-doc-string "guile" "atanh")
865 @deffn {Scheme Procedure} atanh z
866 Return the hyperbolic arctangent of @var{z}.
870 @node Primitive Numerics
871 @subsection Primitive Numeric Functions
873 Many of Guile's numeric procedures which accept any kind of numbers as
874 arguments, including complex numbers, are implemented as Scheme
875 procedures that use the following real number-based primitives. These
876 primitives signal an error if they are called with complex arguments.
878 @c begin (texi-doc-string "guile" "$abs")
879 @deffn {Scheme Procedure} $abs x
880 Return the absolute value of @var{x}.
883 @c begin (texi-doc-string "guile" "$sqrt")
884 @deffn {Scheme Procedure} $sqrt x
885 Return the square root of @var{x}.
888 @deffn {Scheme Procedure} $expt x y
889 @deffnx {C Function} scm_sys_expt (x, y)
890 Return @var{x} raised to the power of @var{y}. This
891 procedure does not accept complex arguments.
894 @c begin (texi-doc-string "guile" "$sin")
895 @deffn {Scheme Procedure} $sin x
896 Return the sine of @var{x}.
899 @c begin (texi-doc-string "guile" "$cos")
900 @deffn {Scheme Procedure} $cos x
901 Return the cosine of @var{x}.
904 @c begin (texi-doc-string "guile" "$tan")
905 @deffn {Scheme Procedure} $tan x
906 Return the tangent of @var{x}.
909 @c begin (texi-doc-string "guile" "$asin")
910 @deffn {Scheme Procedure} $asin x
911 Return the arcsine of @var{x}.
914 @c begin (texi-doc-string "guile" "$acos")
915 @deffn {Scheme Procedure} $acos x
916 Return the arccosine of @var{x}.
919 @c begin (texi-doc-string "guile" "$atan")
920 @deffn {Scheme Procedure} $atan x
921 Return the arctangent of @var{x} in the range -PI/2 to PI/2.
924 @deffn {Scheme Procedure} $atan2 x y
925 @deffnx {C Function} scm_sys_atan2 (x, y)
926 Return the arc tangent of the two arguments @var{x} and
927 @var{y}. This is similar to calculating the arc tangent of
928 @var{x} / @var{y}, except that the signs of both arguments
929 are used to determine the quadrant of the result. This
930 procedure does not accept complex arguments.
933 @c begin (texi-doc-string "guile" "$exp")
934 @deffn {Scheme Procedure} $exp x
935 Return e to the power of @var{x}, where e is the base of natural
936 logarithms (2.71828@dots{}).
939 @c begin (texi-doc-string "guile" "$log")
940 @deffn {Scheme Procedure} $log x
941 Return the natural logarithm of @var{x}.
944 @c begin (texi-doc-string "guile" "$sinh")
945 @deffn {Scheme Procedure} $sinh x
946 Return the hyperbolic sine of @var{x}.
949 @c begin (texi-doc-string "guile" "$cosh")
950 @deffn {Scheme Procedure} $cosh x
951 Return the hyperbolic cosine of @var{x}.
954 @c begin (texi-doc-string "guile" "$tanh")
955 @deffn {Scheme Procedure} $tanh x
956 Return the hyperbolic tangent of @var{x}.
959 @c begin (texi-doc-string "guile" "$asinh")
960 @deffn {Scheme Procedure} $asinh x
961 Return the hyperbolic arcsine of @var{x}.
964 @c begin (texi-doc-string "guile" "$acosh")
965 @deffn {Scheme Procedure} $acosh x
966 Return the hyperbolic arccosine of @var{x}.
969 @c begin (texi-doc-string "guile" "$atanh")
970 @deffn {Scheme Procedure} $atanh x
971 Return the hyperbolic arctangent of @var{x}.
975 @node Bitwise Operations
976 @subsection Bitwise Operations
978 @deffn {Scheme Procedure} logand n1 n2
979 Return the bitwise AND of the integer arguments.
982 (logand) @result{} -1
983 (logand 7) @result{} 7
984 (logand #b111 #b011 #b001) @result{} 1
988 @deffn {Scheme Procedure} logior n1 n2
989 Return the bitwise OR of the integer arguments.
993 (logior 7) @result{} 7
994 (logior #b000 #b001 #b011) @result{} 3
998 @deffn {Scheme Procedure} logxor n1 n2
999 Return the bitwise XOR of the integer arguments. A bit is
1000 set in the result if it is set in an odd number of arguments.
1002 (logxor) @result{} 0
1003 (logxor 7) @result{} 7
1004 (logxor #b000 #b001 #b011) @result{} 2
1005 (logxor #b000 #b001 #b011 #b011) @result{} 1
1009 @deffn {Scheme Procedure} lognot n
1010 @deffnx {C Function} scm_lognot (n)
1011 Return the integer which is the 2s-complement of the integer
1015 (number->string (lognot #b10000000) 2)
1016 @result{} "-10000001"
1017 (number->string (lognot #b0) 2)
1022 @deffn {Scheme Procedure} logtest j k
1023 @deffnx {C Function} scm_logtest (j, k)
1025 (logtest j k) @equiv{} (not (zero? (logand j k)))
1027 (logtest #b0100 #b1011) @result{} #f
1028 (logtest #b0100 #b0111) @result{} #t
1032 @deffn {Scheme Procedure} logbit? index j
1033 @deffnx {C Function} scm_logbit_p (index, j)
1035 (logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
1037 (logbit? 0 #b1101) @result{} #t
1038 (logbit? 1 #b1101) @result{} #f
1039 (logbit? 2 #b1101) @result{} #t
1040 (logbit? 3 #b1101) @result{} #t
1041 (logbit? 4 #b1101) @result{} #f
1045 @deffn {Scheme Procedure} ash n cnt
1046 @deffnx {C Function} scm_ash (n, cnt)
1047 The function ash performs an arithmetic shift left by @var{cnt}
1048 bits (or shift right, if @var{cnt} is negative). 'Arithmetic'
1049 means, that the function does not guarantee to keep the bit
1050 structure of @var{n}, but rather guarantees that the result
1051 will always be rounded towards minus infinity. Therefore, the
1052 results of ash and a corresponding bitwise shift will differ if
1053 @var{n} is negative.
1055 Formally, the function returns an integer equivalent to
1056 @code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
1059 (number->string (ash #b1 3) 2) @result{} "1000"
1060 (number->string (ash #b1010 -1) 2) @result{} "101"
1064 @deffn {Scheme Procedure} logcount n
1065 @deffnx {C Function} scm_logcount (n)
1066 Return the number of bits in integer @var{n}. If integer is
1067 positive, the 1-bits in its binary representation are counted.
1068 If negative, the 0-bits in its two's-complement binary
1069 representation are counted. If 0, 0 is returned.
1072 (logcount #b10101010)
1081 @deffn {Scheme Procedure} integer-length n
1082 @deffnx {C Function} scm_integer_length (n)
1083 Return the number of bits neccessary to represent @var{n}.
1086 (integer-length #b10101010)
1090 (integer-length #b1111)
1095 @deffn {Scheme Procedure} integer-expt n k
1096 @deffnx {C Function} scm_integer_expt (n, k)
1097 Return @var{n} raised to the non-negative integer exponent
1108 @deffn {Scheme Procedure} bit-extract n start end
1109 @deffnx {C Function} scm_bit_extract (n, start, end)
1110 Return the integer composed of the @var{start} (inclusive)
1111 through @var{end} (exclusive) bits of @var{n}. The
1112 @var{start}th bit becomes the 0-th bit in the result.
1115 (number->string (bit-extract #b1101101010 0 4) 2)
1117 (number->string (bit-extract #b1101101010 4 9) 2)
1124 @subsection Random Number Generation
1126 @deffn {Scheme Procedure} copy-random-state [state]
1127 @deffnx {C Function} scm_copy_random_state (state)
1128 Return a copy of the random state @var{state}.
1131 @deffn {Scheme Procedure} random n [state]
1132 @deffnx {C Function} scm_random (n, state)
1133 Return a number in [0,N).
1135 Accepts a positive integer or real n and returns a
1136 number of the same type between zero (inclusive) and
1137 N (exclusive). The values returned have a uniform
1140 The optional argument @var{state} must be of the type produced
1141 by @code{seed->random-state}. It defaults to the value of the
1142 variable @var{*random-state*}. This object is used to maintain
1143 the state of the pseudo-random-number generator and is altered
1144 as a side effect of the random operation.
1147 @deffn {Scheme Procedure} random:exp [state]
1148 @deffnx {C Function} scm_random_exp (state)
1149 Return an inexact real in an exponential distribution with mean
1150 1. For an exponential distribution with mean u use (* u
1154 @deffn {Scheme Procedure} random:hollow-sphere! v [state]
1155 @deffnx {C Function} scm_random_hollow_sphere_x (v, state)
1156 Fills vect with inexact real random numbers
1157 the sum of whose squares is equal to 1.0.
1158 Thinking of vect as coordinates in space of
1159 dimension n = (vector-length vect), the coordinates
1160 are uniformly distributed over the surface of the
1164 @deffn {Scheme Procedure} random:normal [state]
1165 @deffnx {C Function} scm_random_normal (state)
1166 Return an inexact real in a normal distribution. The
1167 distribution used has mean 0 and standard deviation 1. For a
1168 normal distribution with mean m and standard deviation d use
1169 @code{(+ m (* d (random:normal)))}.
1172 @deffn {Scheme Procedure} random:normal-vector! v [state]
1173 @deffnx {C Function} scm_random_normal_vector_x (v, state)
1174 Fills vect with inexact real random numbers that are
1175 independent and standard normally distributed
1176 (i.e., with mean 0 and variance 1).
1179 @deffn {Scheme Procedure} random:solid-sphere! v [state]
1180 @deffnx {C Function} scm_random_solid_sphere_x (v, state)
1181 Fills vect with inexact real random numbers
1182 the sum of whose squares is less than 1.0.
1183 Thinking of vect as coordinates in space of
1184 dimension n = (vector-length vect), the coordinates
1185 are uniformly distributed within the unit n-sphere.
1186 The sum of the squares of the numbers is returned.
1189 @deffn {Scheme Procedure} random:uniform [state]
1190 @deffnx {C Function} scm_random_uniform (state)
1191 Return a uniformly distributed inexact real random number in
1195 @deffn {Scheme Procedure} seed->random-state seed
1196 @deffnx {C Function} scm_seed_to_random_state (seed)
1197 Return a new random state using @var{seed}.
1205 Most of the characters in the ASCII character set may be referred to by
1206 name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and so on.
1207 The following table describes the ASCII names for each character.
1209 @multitable @columnfractions .25 .25 .25 .25
1210 @item 0 = @code{#\nul}
1211 @tab 1 = @code{#\soh}
1212 @tab 2 = @code{#\stx}
1213 @tab 3 = @code{#\etx}
1214 @item 4 = @code{#\eot}
1215 @tab 5 = @code{#\enq}
1216 @tab 6 = @code{#\ack}
1217 @tab 7 = @code{#\bel}
1218 @item 8 = @code{#\bs}
1219 @tab 9 = @code{#\ht}
1220 @tab 10 = @code{#\nl}
1221 @tab 11 = @code{#\vt}
1222 @item 12 = @code{#\np}
1223 @tab 13 = @code{#\cr}
1224 @tab 14 = @code{#\so}
1225 @tab 15 = @code{#\si}
1226 @item 16 = @code{#\dle}
1227 @tab 17 = @code{#\dc1}
1228 @tab 18 = @code{#\dc2}
1229 @tab 19 = @code{#\dc3}
1230 @item 20 = @code{#\dc4}
1231 @tab 21 = @code{#\nak}
1232 @tab 22 = @code{#\syn}
1233 @tab 23 = @code{#\etb}
1234 @item 24 = @code{#\can}
1235 @tab 25 = @code{#\em}
1236 @tab 26 = @code{#\sub}
1237 @tab 27 = @code{#\esc}
1238 @item 28 = @code{#\fs}
1239 @tab 29 = @code{#\gs}
1240 @tab 30 = @code{#\rs}
1241 @tab 31 = @code{#\us}
1242 @item 32 = @code{#\sp}
1245 The @code{delete} character (octal 177) may be referred to with the name
1248 Several characters have more than one name:
1252 @code{#\space}, @code{#\sp}
1254 @code{#\newline}, @code{#\nl}
1256 @code{#\tab}, @code{#\ht}
1258 @code{#\backspace}, @code{#\bs}
1260 @code{#\return}, @code{#\cr}
1262 @code{#\page}, @code{#\np}
1264 @code{#\null}, @code{#\nul}
1268 @deffn {Scheme Procedure} char? x
1269 @deffnx {C Function} scm_char_p (x)
1270 Return @code{#t} iff @var{x} is a character, else @code{#f}.
1274 @deffn {Scheme Procedure} char=? x y
1275 Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
1279 @deffn {Scheme Procedure} char<? x y
1280 Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence,
1285 @deffn {Scheme Procedure} char<=? x y
1286 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
1287 ASCII sequence, else @code{#f}.
1291 @deffn {Scheme Procedure} char>? x y
1292 Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
1293 sequence, else @code{#f}.
1297 @deffn {Scheme Procedure} char>=? x y
1298 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
1299 ASCII sequence, else @code{#f}.
1303 @deffn {Scheme Procedure} char-ci=? x y
1304 Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
1305 case, else @code{#f}.
1309 @deffn {Scheme Procedure} char-ci<? x y
1310 Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence
1311 ignoring case, else @code{#f}.
1315 @deffn {Scheme Procedure} char-ci<=? x y
1316 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
1317 ASCII sequence ignoring case, else @code{#f}.
1321 @deffn {Scheme Procedure} char-ci>? x y
1322 Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
1323 sequence ignoring case, else @code{#f}.
1327 @deffn {Scheme Procedure} char-ci>=? x y
1328 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
1329 ASCII sequence ignoring case, else @code{#f}.
1332 @rnindex char-alphabetic?
1333 @deffn {Scheme Procedure} char-alphabetic? chr
1334 @deffnx {C Function} scm_char_alphabetic_p (chr)
1335 Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
1336 Alphabetic means the same thing as the isalpha C library function.
1339 @rnindex char-numeric?
1340 @deffn {Scheme Procedure} char-numeric? chr
1341 @deffnx {C Function} scm_char_numeric_p (chr)
1342 Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
1343 Numeric means the same thing as the isdigit C library function.
1346 @rnindex char-whitespace?
1347 @deffn {Scheme Procedure} char-whitespace? chr
1348 @deffnx {C Function} scm_char_whitespace_p (chr)
1349 Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
1350 Whitespace means the same thing as the isspace C library function.
1353 @rnindex char-upper-case?
1354 @deffn {Scheme Procedure} char-upper-case? chr
1355 @deffnx {C Function} scm_char_upper_case_p (chr)
1356 Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
1357 Uppercase means the same thing as the isupper C library function.
1360 @rnindex char-lower-case?
1361 @deffn {Scheme Procedure} char-lower-case? chr
1362 @deffnx {C Function} scm_char_lower_case_p (chr)
1363 Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
1364 Lowercase means the same thing as the islower C library function.
1367 @deffn {Scheme Procedure} char-is-both? chr
1368 @deffnx {C Function} scm_char_is_both_p (chr)
1369 Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}.
1370 Uppercase and lowercase are as defined by the isupper and islower
1371 C library functions.
1374 @rnindex char->integer
1375 @deffn {Scheme Procedure} char->integer chr
1376 @deffnx {C Function} scm_char_to_integer (chr)
1377 Return the number corresponding to ordinal position of @var{chr} in the
1381 @rnindex integer->char
1382 @deffn {Scheme Procedure} integer->char n
1383 @deffnx {C Function} scm_integer_to_char (n)
1384 Return the character at position @var{n} in the ASCII sequence.
1387 @rnindex char-upcase
1388 @deffn {Scheme Procedure} char-upcase chr
1389 @deffnx {C Function} scm_char_upcase (chr)
1390 Return the uppercase character version of @var{chr}.
1393 @rnindex char-downcase
1394 @deffn {Scheme Procedure} char-downcase chr
1395 @deffnx {C Function} scm_char_downcase (chr)
1396 Return the lowercase character version of @var{chr}.
1404 Strings are fixed-length sequences of characters. They can be created
1405 by calling constructor procedures, but they can also literally get
1406 entered at the REPL or in Scheme source files.
1408 Guile provides a rich set of string processing procedures, because text
1409 handling is very important when Guile is used as a scripting language.
1411 Strings always carry the information about how many characters they are
1412 composed of with them, so there is no special end-of-string character,
1413 like in C. That means that Scheme strings can contain any character,
1414 even the NUL character @code{'\0'}. But note: Since most operating
1415 system calls dealing with strings (such as for file operations) expect
1416 strings to be zero-terminated, they might do unexpected things when
1417 called with string containing unusal characters.
1420 * String Syntax:: Read syntax for strings.
1421 * String Predicates:: Testing strings for certain properties.
1422 * String Constructors:: Creating new string objects.
1423 * List/String Conversion:: Converting from/to lists of characters.
1424 * String Selection:: Select portions from strings.
1425 * String Modification:: Modify parts or whole strings.
1426 * String Comparison:: Lexicographic ordering predicates.
1427 * String Searching:: Searching in strings.
1428 * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
1429 * Appending Strings:: Appending strings to form a new string.
1430 * String Miscellanea:: Miscellaneous string procedures.
1434 @subsection String Read Syntax
1436 The read syntax for strings is an arbitrarily long sequence of
1437 characters enclosed in double quotes (@code{"}). @footnote{Actually, the
1438 current implementation restricts strings to a length of 2^24
1439 characters.} If you want to insert a double quote character into a
1440 string literal, it must be prefixed with a backslash @code{\} character
1441 (called an @dfn{escape character}).
1443 The following are examples of string literals:
1452 @c FIXME::martin: What about escape sequences like \r, \n etc.?
1454 @node String Predicates
1455 @subsection String Predicates
1457 The following procedures can be used to check whether a given string
1458 fulfills some specified property.
1461 @deffn {Scheme Procedure} string? obj
1462 @deffnx {C Function} scm_string_p (obj)
1463 Return @code{#t} iff @var{obj} is a string, else @code{#f}.
1466 @deffn {Scheme Procedure} string-null? str
1467 @deffnx {C Function} scm_string_null_p (str)
1468 Return @code{#t} if @var{str}'s length is zero, and
1469 @code{#f} otherwise.
1471 (string-null? "") @result{} #t
1473 (string-null? y) @result{} #f
1477 @node String Constructors
1478 @subsection String Constructors
1480 The string constructor procedures create new string objects, possibly
1481 initializing them with some specified character data.
1483 @c FIXME::martin: list->string belongs into `List/String Conversion'
1486 @rnindex list->string
1487 @deffn {Scheme Procedure} string . chrs
1488 @deffnx {Scheme Procedure} list->string chrs
1489 @deffnx {C Function} scm_string (chrs)
1490 Return a newly allocated string composed of the arguments,
1494 @rnindex make-string
1495 @deffn {Scheme Procedure} make-string k [chr]
1496 @deffnx {C Function} scm_make_string (k, chr)
1497 Return a newly allocated string of
1498 length @var{k}. If @var{chr} is given, then all elements of
1499 the string are initialized to @var{chr}, otherwise the contents
1500 of the @var{string} are unspecified.
1503 @node List/String Conversion
1504 @subsection List/String conversion
1506 When processing strings, it is often convenient to first convert them
1507 into a list representation by using the procedure @code{string->list},
1508 work with the resulting list, and then convert it back into a string.
1509 These procedures are useful for similar tasks.
1511 @rnindex string->list
1512 @deffn {Scheme Procedure} string->list str
1513 @deffnx {C Function} scm_string_to_list (str)
1514 Return a newly allocated list of the characters that make up
1515 the given string @var{str}. @code{string->list} and
1516 @code{list->string} are inverses as far as @samp{equal?} is
1520 @deffn {Scheme Procedure} string-split str chr
1521 @deffnx {C Function} scm_string_split (str, chr)
1522 Split the string @var{str} into the a list of the substrings delimited
1523 by appearances of the character @var{chr}. Note that an empty substring
1524 between separator characters will result in an empty string in the
1528 (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
1530 ("root" "x" "0" "0" "root" "/root" "/bin/bash")
1532 (string-split "::" #\:)
1536 (string-split "" #\:)
1543 @node String Selection
1544 @subsection String Selection
1546 Portions of strings can be extracted by these procedures.
1547 @code{string-ref} delivers individual characters whereas
1548 @code{substring} can be used to extract substrings from longer strings.
1550 @rnindex string-length
1551 @deffn {Scheme Procedure} string-length string
1552 @deffnx {C Function} scm_string_length (string)
1553 Return the number of characters in @var{string}.
1557 @deffn {Scheme Procedure} string-ref str k
1558 @deffnx {C Function} scm_string_ref (str, k)
1559 Return character @var{k} of @var{str} using zero-origin
1560 indexing. @var{k} must be a valid index of @var{str}.
1563 @rnindex string-copy
1564 @deffn {Scheme Procedure} string-copy str
1565 @deffnx {C Function} scm_string_copy (str)
1566 Return a newly allocated copy of the given @var{string}.
1570 @deffn {Scheme Procedure} substring str start [end]
1571 @deffnx {C Function} scm_substring (str, start, end)
1572 Return a newly allocated string formed from the characters
1573 of @var{str} beginning with index @var{start} (inclusive) and
1574 ending with index @var{end} (exclusive).
1575 @var{str} must be a string, @var{start} and @var{end} must be
1576 exact integers satisfying:
1578 0 <= @var{start} <= @var{end} <= (string-length @var{str}).
1581 @node String Modification
1582 @subsection String Modification
1584 These procedures are for modifying strings in-place. This means that the
1585 result of the operation is not a new string; instead, the original string's
1586 memory representation is modified.
1588 @rnindex string-set!
1589 @deffn {Scheme Procedure} string-set! str k chr
1590 @deffnx {C Function} scm_string_set_x (str, k, chr)
1591 Store @var{chr} in element @var{k} of @var{str} and return
1592 an unspecified value. @var{k} must be a valid index of
1596 @rnindex string-fill!
1597 @deffn {Scheme Procedure} string-fill! str chr
1598 @deffnx {C Function} scm_string_fill_x (str, chr)
1599 Store @var{char} in every element of the given @var{string} and
1600 return an unspecified value.
1603 @deffn {Scheme Procedure} substring-fill! str start end fill
1604 @deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
1605 Change every character in @var{str} between @var{start} and
1606 @var{end} to @var{fill}.
1609 (define y "abcdefg")
1610 (substring-fill! y 1 3 #\r)
1616 @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
1617 @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
1618 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
1619 into @var{str2} beginning at position @var{start2}.
1620 @var{str1} and @var{str2} can be the same string.
1624 @node String Comparison
1625 @subsection String Comparison
1627 The procedures in this section are similar to the character ordering
1628 predicates (@pxref{Characters}), but are defined on character sequences.
1629 They all return @code{#t} on success and @code{#f} on failure. The
1630 predicates ending in @code{-ci} ignore the character case when comparing
1635 @deffn {Scheme Procedure} string=? s1 s2
1636 Lexicographic equality predicate; return @code{#t} if the two
1637 strings are the same length and contain the same characters in
1638 the same positions, otherwise return @code{#f}.
1640 The procedure @code{string-ci=?} treats upper and lower case
1641 letters as though they were the same character, but
1642 @code{string=?} treats upper and lower case as distinct
1647 @deffn {Scheme Procedure} string<? s1 s2
1648 Lexicographic ordering predicate; return @code{#t} if @var{s1}
1649 is lexicographically less than @var{s2}.
1653 @deffn {Scheme Procedure} string<=? s1 s2
1654 Lexicographic ordering predicate; return @code{#t} if @var{s1}
1655 is lexicographically less than or equal to @var{s2}.
1659 @deffn {Scheme Procedure} string>? s1 s2
1660 Lexicographic ordering predicate; return @code{#t} if @var{s1}
1661 is lexicographically greater than @var{s2}.
1665 @deffn {Scheme Procedure} string>=? s1 s2
1666 Lexicographic ordering predicate; return @code{#t} if @var{s1}
1667 is lexicographically greater than or equal to @var{s2}.
1670 @rnindex string-ci=?
1671 @deffn {Scheme Procedure} string-ci=? s1 s2
1672 Case-insensitive string equality predicate; return @code{#t} if
1673 the two strings are the same length and their component
1674 characters match (ignoring case) at each position; otherwise
1679 @deffn {Scheme Procedure} string-ci<? s1 s2
1680 Case insensitive lexicographic ordering predicate; return
1681 @code{#t} if @var{s1} is lexicographically less than @var{s2}
1686 @deffn {Scheme Procedure} string-ci<=? s1 s2
1687 Case insensitive lexicographic ordering predicate; return
1688 @code{#t} if @var{s1} is lexicographically less than or equal
1689 to @var{s2} regardless of case.
1692 @rnindex string-ci>?
1693 @deffn {Scheme Procedure} string-ci>? s1 s2
1694 Case insensitive lexicographic ordering predicate; return
1695 @code{#t} if @var{s1} is lexicographically greater than
1696 @var{s2} regardless of case.
1699 @rnindex string-ci>=?
1700 @deffn {Scheme Procedure} string-ci>=? s1 s2
1701 Case insensitive lexicographic ordering predicate; return
1702 @code{#t} if @var{s1} is lexicographically greater than or
1703 equal to @var{s2} regardless of case.
1707 @node String Searching
1708 @subsection String Searching
1710 When searching for the index of a character in a string, these
1711 procedures can be used.
1713 @deffn {Scheme Procedure} string-index str chr [frm [to]]
1714 @deffnx {C Function} scm_string_index (str, chr, frm, to)
1715 Return the index of the first occurrence of @var{chr} in
1716 @var{str}. The optional integer arguments @var{frm} and
1717 @var{to} limit the search to a portion of the string. This
1718 procedure essentially implements the @code{index} or
1719 @code{strchr} functions from the C library.
1722 (string-index "weiner" #\e)
1725 (string-index "weiner" #\e 2)
1728 (string-index "weiner" #\e 2 4)
1733 @deffn {Scheme Procedure} string-rindex str chr [frm [to]]
1734 @deffnx {C Function} scm_string_rindex (str, chr, frm, to)
1735 Like @code{string-index}, but search from the right of the
1736 string rather than from the left. This procedure essentially
1737 implements the @code{rindex} or @code{strrchr} functions from
1741 (string-rindex "weiner" #\e)
1744 (string-rindex "weiner" #\e 2 4)
1747 (string-rindex "weiner" #\e 2 5)
1752 @node Alphabetic Case Mapping
1753 @subsection Alphabetic Case Mapping
1755 These are procedures for mapping strings to their upper- or lower-case
1756 equivalents, respectively, or for capitalizing strings.
1758 @deffn {Scheme Procedure} string-upcase str
1759 @deffnx {C Function} scm_string_upcase (str)
1760 Return a freshly allocated string containing the characters of
1761 @var{str} in upper case.
1764 @deffn {Scheme Procedure} string-upcase! str
1765 @deffnx {C Function} scm_string_upcase_x (str)
1766 Destructively upcase every character in @var{str} and return
1769 y @result{} "arrdefg"
1770 (string-upcase! y) @result{} "ARRDEFG"
1771 y @result{} "ARRDEFG"
1775 @deffn {Scheme Procedure} string-downcase str
1776 @deffnx {C Function} scm_string_downcase (str)
1777 Return a freshly allocation string containing the characters in
1778 @var{str} in lower case.
1781 @deffn {Scheme Procedure} string-downcase! str
1782 @deffnx {C Function} scm_string_downcase_x (str)
1783 Destructively downcase every character in @var{str} and return
1786 y @result{} "ARRDEFG"
1787 (string-downcase! y) @result{} "arrdefg"
1788 y @result{} "arrdefg"
1792 @deffn {Scheme Procedure} string-capitalize str
1793 @deffnx {C Function} scm_string_capitalize (str)
1794 Return a freshly allocated string with the characters in
1795 @var{str}, where the first character of every word is
1799 @deffn {Scheme Procedure} string-capitalize! str
1800 @deffnx {C Function} scm_string_capitalize_x (str)
1801 Upcase the first character of every word in @var{str}
1802 destructively and return @var{str}.
1805 y @result{} "hello world"
1806 (string-capitalize! y) @result{} "Hello World"
1807 y @result{} "Hello World"
1812 @node Appending Strings
1813 @subsection Appending Strings
1815 The procedure @code{string-append} appends several strings together to
1816 form a longer result string.
1818 @rnindex string-append
1819 @deffn {Scheme Procedure} string-append . args
1820 @deffnx {C Function} scm_string_append (args)
1821 Return a newly allocated string whose characters form the
1822 concatenation of the given strings, @var{args}.
1826 @node String Miscellanea
1827 @subsection String Miscellanea
1829 This section contains all remaining string procedures.
1831 @deffn {Scheme Procedure} string-ci->symbol str
1832 @deffnx {C Function} scm_string_ci_to_symbol (str)
1833 Return the symbol whose name is @var{str}. @var{str} is
1834 converted to lowercase before the conversion is done, if Guile
1835 is currently reading symbols case-insensitively.
1839 @node Regular Expressions
1840 @section Regular Expressions
1841 @tpindex Regular expressions
1843 @cindex regular expressions
1845 @cindex emacs regexp
1847 A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
1848 describes a whole class of strings. A full description of regular
1849 expressions and their syntax is beyond the scope of this manual;
1850 an introduction can be found in the Emacs manual (@pxref{Regexps,
1851 , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
1852 in many general Unix reference books.
1854 If your system does not include a POSIX regular expression library, and
1855 you have not linked Guile with a third-party regexp library such as Rx,
1856 these functions will not be available. You can tell whether your Guile
1857 installation includes regular expression support by checking whether the
1858 @code{*features*} list includes the @code{regex} symbol.
1861 * Regexp Functions:: Functions that create and match regexps.
1862 * Match Structures:: Finding what was matched by a regexp.
1863 * Backslash Escapes:: Removing the special meaning of regexp metacharacters.
1864 * Rx Interface:: Tom Lord's Rx library does things differently.
1867 [FIXME: it may be useful to include an Examples section. Parts of this
1868 interface are bewildering on first glance.]
1870 @node Regexp Functions
1871 @subsection Regexp Functions
1873 By default, Guile supports POSIX extended regular expressions.
1874 That means that the characters @samp{(}, @samp{)}, @samp{+} and
1875 @samp{?} are special, and must be escaped if you wish to match the
1878 This regular expression interface was modeled after that
1879 implemented by SCSH, the Scheme Shell. It is intended to be
1880 upwardly compatible with SCSH regular expressions.
1882 @c begin (scm-doc-string "regex.scm" "string-match")
1883 @deffn {Scheme Procedure} string-match pattern str [start]
1884 Compile the string @var{pattern} into a regular expression and compare
1885 it with @var{str}. The optional numeric argument @var{start} specifies
1886 the position of @var{str} at which to begin matching.
1888 @code{string-match} returns a @dfn{match structure} which
1889 describes what, if anything, was matched by the regular
1890 expression. @xref{Match Structures}. If @var{str} does not match
1891 @var{pattern} at all, @code{string-match} returns @code{#f}.
1894 Each time @code{string-match} is called, it must compile its
1895 @var{pattern} argument into a regular expression structure. This
1896 operation is expensive, which makes @code{string-match} inefficient if
1897 the same regular expression is used several times (for example, in a
1898 loop). For better performance, you can compile a regular expression in
1899 advance and then match strings against the compiled regexp.
1901 @deffn {Scheme Procedure} make-regexp pat . flags
1902 @deffnx {C Function} scm_make_regexp (pat, flags)
1903 Compile the regular expression described by @var{pat}, and
1904 return the compiled regexp structure. If @var{pat} does not
1905 describe a legal regular expression, @code{make-regexp} throws
1906 a @code{regular-expression-syntax} error.
1908 The @var{flags} arguments change the behavior of the compiled
1909 regular expression. The following flags may be supplied:
1913 Consider uppercase and lowercase letters to be the same when
1915 @item regexp/newline
1916 If a newline appears in the target string, then permit the
1917 @samp{^} and @samp{$} operators to match immediately after or
1918 immediately before the newline, respectively. Also, the
1919 @samp{.} and @samp{[^...]} operators will never match a newline
1920 character. The intent of this flag is to treat the target
1921 string as a buffer containing many lines of text, and the
1922 regular expression as a pattern that may match a single one of
1925 Compile a basic (``obsolete'') regexp instead of the extended
1926 (``modern'') regexps that are the default. Basic regexps do
1927 not consider @samp{|}, @samp{+} or @samp{?} to be special
1928 characters, and require the @samp{@{...@}} and @samp{(...)}
1929 metacharacters to be backslash-escaped (@pxref{Backslash
1930 Escapes}). There are several other differences between basic
1931 and extended regular expressions, but these are the most
1933 @item regexp/extended
1934 Compile an extended regular expression rather than a basic
1935 regexp. This is the default behavior; this flag will not
1936 usually be needed. If a call to @code{make-regexp} includes
1937 both @code{regexp/basic} and @code{regexp/extended} flags, the
1938 one which comes last will override the earlier one.
1942 @deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
1943 @deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
1944 Match the compiled regular expression @var{rx} against
1945 @code{str}. If the optional integer @var{start} argument is
1946 provided, begin matching from that position in the string.
1947 Return a match structure describing the results of the match,
1948 or @code{#f} if no match could be found.
1950 The @var{flags} arguments change the matching behavior.
1951 The following flags may be supplied:
1955 Operator @samp{^} always fails (unless @code{regexp/newline}
1956 is used). Use this when the beginning of the string should
1957 not be considered the beginning of a line.
1959 Operator @samp{$} always fails (unless @code{regexp/newline}
1960 is used). Use this when the end of the string should not be
1961 considered the end of a line.
1965 @deffn {Scheme Procedure} regexp? obj
1966 @deffnx {C Function} scm_regexp_p (obj)
1967 Return @code{#t} if @var{obj} is a compiled regular expression,
1968 or @code{#f} otherwise.
1971 Regular expressions are commonly used to find patterns in one string and
1972 replace them with the contents of another string.
1974 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
1975 @deffn {Scheme Procedure} regexp-substitute port match [item@dots{}]
1976 Write to the output port @var{port} selected contents of the match
1977 structure @var{match}. Each @var{item} specifies what should be
1978 written, and may be one of the following arguments:
1982 A string. String arguments are written out verbatim.
1985 An integer. The submatch with that number is written.
1988 The symbol @samp{pre}. The portion of the matched string preceding
1989 the regexp match is written.
1992 The symbol @samp{post}. The portion of the matched string following
1993 the regexp match is written.
1996 @var{port} may be @code{#f}, in which case nothing is written; instead,
1997 @code{regexp-substitute} constructs a string from the specified
1998 @var{item}s and returns that.
2001 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
2002 @deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
2003 Similar to @code{regexp-substitute}, but can be used to perform global
2004 substitutions on @var{str}. Instead of taking a match structure as an
2005 argument, @code{regexp-substitute/global} takes two string arguments: a
2006 @var{regexp} string describing a regular expression, and a @var{target}
2007 string which should be matched against this regular expression.
2009 Each @var{item} behaves as in @var{regexp-substitute}, with the
2010 following exceptions:
2014 A function may be supplied. When this function is called, it will be
2015 passed one argument: a match structure for a given regular expression
2016 match. It should return a string to be written out to @var{port}.
2019 The @samp{post} symbol causes @code{regexp-substitute/global} to recurse
2020 on the unmatched portion of @var{str}. This @emph{must} be supplied in
2021 order to perform global search-and-replace on @var{str}; if it is not
2022 present among the @var{item}s, then @code{regexp-substitute/global} will
2023 return after processing a single match.
2027 @node Match Structures
2028 @subsection Match Structures
2030 @cindex match structures
2032 A @dfn{match structure} is the object returned by @code{string-match} and
2033 @code{regexp-exec}. It describes which portion of a string, if any,
2034 matched the given regular expression. Match structures include: a
2035 reference to the string that was checked for matches; the starting and
2036 ending positions of the regexp match; and, if the regexp included any
2037 parenthesized subexpressions, the starting and ending positions of each
2040 In each of the regexp match functions described below, the @code{match}
2041 argument must be a match structure returned by a previous call to
2042 @code{string-match} or @code{regexp-exec}. Most of these functions
2043 return some information about the original target string that was
2044 matched against a regular expression; we will call that string
2045 @var{target} for easy reference.
2047 @c begin (scm-doc-string "regex.scm" "regexp-match?")
2048 @deffn {Scheme Procedure} regexp-match? obj
2049 Return @code{#t} if @var{obj} is a match structure returned by a
2050 previous call to @code{regexp-exec}, or @code{#f} otherwise.
2053 @c begin (scm-doc-string "regex.scm" "match:substring")
2054 @deffn {Scheme Procedure} match:substring match [n]
2055 Return the portion of @var{target} matched by subexpression number
2056 @var{n}. Submatch 0 (the default) represents the entire regexp match.
2057 If the regular expression as a whole matched, but the subexpression
2058 number @var{n} did not match, return @code{#f}.
2061 @c begin (scm-doc-string "regex.scm" "match:start")
2062 @deffn {Scheme Procedure} match:start match [n]
2063 Return the starting position of submatch number @var{n}.
2066 @c begin (scm-doc-string "regex.scm" "match:end")
2067 @deffn {Scheme Procedure} match:end match [n]
2068 Return the ending position of submatch number @var{n}.
2071 @c begin (scm-doc-string "regex.scm" "match:prefix")
2072 @deffn {Scheme Procedure} match:prefix match
2073 Return the unmatched portion of @var{target} preceding the regexp match.
2076 @c begin (scm-doc-string "regex.scm" "match:suffix")
2077 @deffn {Scheme Procedure} match:suffix match
2078 Return the unmatched portion of @var{target} following the regexp match.
2081 @c begin (scm-doc-string "regex.scm" "match:count")
2082 @deffn {Scheme Procedure} match:count match
2083 Return the number of parenthesized subexpressions from @var{match}.
2084 Note that the entire regular expression match itself counts as a
2085 subexpression, and failed submatches are included in the count.
2088 @c begin (scm-doc-string "regex.scm" "match:string")
2089 @deffn {Scheme Procedure} match:string match
2090 Return the original @var{target} string.
2093 @node Backslash Escapes
2094 @subsection Backslash Escapes
2096 Sometimes you will want a regexp to match characters like @samp{*} or
2097 @samp{$} exactly. For example, to check whether a particular string
2098 represents a menu entry from an Info node, it would be useful to match
2099 it against a regexp like @samp{^* [^:]*::}. However, this won't work;
2100 because the asterisk is a metacharacter, it won't match the @samp{*} at
2101 the beginning of the string. In this case, we want to make the first
2104 You can do this by preceding the metacharacter with a backslash
2105 character @samp{\}. (This is also called @dfn{quoting} the
2106 metacharacter, and is known as a @dfn{backslash escape}.) When Guile
2107 sees a backslash in a regular expression, it considers the following
2108 glyph to be an ordinary character, no matter what special meaning it
2109 would ordinarily have. Therefore, we can make the above example work by
2110 changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells
2111 the regular expression engine to match only a single asterisk in the
2114 Since the backslash is itself a metacharacter, you may force a regexp to
2115 match a backslash in the target string by preceding the backslash with
2116 itself. For example, to find variable references in a @TeX{} program,
2117 you might want to find occurrences of the string @samp{\let\} followed
2118 by any number of alphabetic characters. The regular expression
2119 @samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the
2120 regexp each match a single backslash in the target string.
2122 @c begin (scm-doc-string "regex.scm" "regexp-quote")
2123 @deffn {Scheme Procedure} regexp-quote str
2124 Quote each special character found in @var{str} with a backslash, and
2125 return the resulting string.
2128 @strong{Very important:} Using backslash escapes in Guile source code
2129 (as in Emacs Lisp or C) can be tricky, because the backslash character
2130 has special meaning for the Guile reader. For example, if Guile
2131 encounters the character sequence @samp{\n} in the middle of a string
2132 while processing Scheme code, it replaces those characters with a
2133 newline character. Similarly, the character sequence @samp{\t} is
2134 replaced by a horizontal tab. Several of these @dfn{escape sequences}
2135 are processed by the Guile reader before your code is executed.
2136 Unrecognized escape sequences are ignored: if the characters @samp{\*}
2137 appear in a string, they will be translated to the single character
2140 This translation is obviously undesirable for regular expressions, since
2141 we want to be able to include backslashes in a string in order to
2142 escape regexp metacharacters. Therefore, to make sure that a backslash
2143 is preserved in a string in your Guile program, you must use @emph{two}
2144 consecutive backslashes:
2147 (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
2150 The string in this example is preprocessed by the Guile reader before
2151 any code is executed. The resulting argument to @code{make-regexp} is
2152 the string @samp{^\* [^:]*}, which is what we really want.
2154 This also means that in order to write a regular expression that matches
2155 a single backslash character, the regular expression string in the
2156 source code must include @emph{four} backslashes. Each consecutive pair
2157 of backslashes gets translated by the Guile reader to a single
2158 backslash, and the resulting double-backslash is interpreted by the
2159 regexp engine as matching a single backslash character. Hence:
2162 (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
2165 The reason for the unwieldiness of this syntax is historical. Both
2166 regular expression pattern matchers and Unix string processing systems
2167 have traditionally used backslashes with the special meanings
2168 described above. The POSIX regular expression specification and ANSI C
2169 standard both require these semantics. Attempting to abandon either
2170 convention would cause other kinds of compatibility problems, possibly
2171 more severe ones. Therefore, without extending the Scheme reader to
2172 support strings with different quoting conventions (an ungainly and
2173 confusing extension when implemented in other languages), we must adhere
2174 to this cumbersome escape syntax.
2177 @subsection Rx Interface
2179 @c FIXME::martin: Shouldn't this be removed or moved to the
2180 @c ``Guile Modules'' chapter? The functions are not available in
2183 [FIXME: this is taken from Gary and Mark's quick summaries and should be
2184 reviewed and expanded. Rx is pretty stable, so could already be done!]
2187 @cindex finite automaton
2189 Guile includes an interface to Tom Lord's Rx library (currently only to
2190 POSIX regular expressions). Use of the library requires a two step
2191 process: compile a regular expression into an efficient structure, then
2192 use the structure in any number of string comparisons.
2194 For example, given the
2195 regular expression @samp{abc.} (which matches any string containing
2196 @samp{abc} followed by any single character):
2199 guile> @kbd{(define r (regcomp "abc."))}
2202 guile> @kbd{(regexec r "abc")}
2204 guile> @kbd{(regexec r "abcd")}
2209 The definitions of @code{regcomp} and @code{regexec} are as follows:
2211 @c NJFIXME not in libguile!
2212 @deffn {Scheme Procedure} regcomp pattern [flags]
2213 Compile the regular expression pattern using POSIX rules. Flags is
2214 optional and should be specified using symbolic names:
2215 @defvar REG_EXTENDED
2216 use extended POSIX syntax
2219 use case-insensitive matching
2222 allow anchors to match after newline characters in the
2223 string and prevents @code{.} or @code{[^...]} from matching newlines.
2226 The @code{logior} procedure can be used to combine multiple flags.
2227 The default is to use
2228 POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+}
2230 operators. Backslashes in @var{pattern} must be escaped if specified in a
2231 literal string e.g., @code{"\\(a\\)\\?"}.
2234 @c NJFIXME not in libguile!
2235 @deffn {Scheme Procedure} regexec regex string [match-pick] [flags]
2237 Match @var{string} against the compiled POSIX regular expression
2239 @var{match-pick} and @var{flags} are optional. Possible flags (which can be
2240 combined using the logior procedure) are:
2243 The beginning of line operator won't match the beginning of
2244 @var{string} (presumably because it's not the beginning of a line)
2248 Similar to REG_NOTBOL, but prevents the end of line operator
2249 from matching the end of @var{string}.
2252 If no match is possible, regexec returns #f. Otherwise @var{match-pick}
2253 determines the return value:
2255 @code{#t} or unspecified: a newly-allocated vector is returned,
2256 containing pairs with the indices of the matched part of @var{string} and any
2259 @code{""}: a list is returned: the first element contains a nested list
2260 with the matched part of @var{string} surrounded by the the unmatched parts.
2261 Remaining elements are matched substrings (if any). All returned
2262 substrings share memory with @var{string}.
2264 @code{#f}: regexec returns #t if a match is made, otherwise #f.
2266 vector: the supplied vector is returned, with the first element replaced
2267 by a pair containing the indices of the matched portion of @var{string} and
2268 further elements replaced by pairs containing the indices of matched
2269 substrings (if any).
2271 list: a list will be returned, with each member of the list
2272 specified by a code in the corresponding position of the supplied list:
2274 a number: the numbered matching substring (0 for the entire match).
2276 @code{#\<}: the beginning of @var{string} to the beginning of the part matched
2279 @code{#\>}: the end of the matched part of @var{string} to the end of
2282 @code{#\c}: the "final tag", which seems to be associated with the "cut
2283 operator", which doesn't seem to be available through the posix
2286 e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
2290 Here are some other procedures that might be used when using regular
2293 @c NJFIXME not in libguile!
2294 @deffn {Scheme Procedure} compiled-regexp? obj
2295 Test whether obj is a compiled regular expression.
2298 @c NJFIXME not in libguile!
2299 @deffn {Scheme Procedure} regexp->dfa regex [flags]
2302 @c NJFIXME not in libguile!
2303 @deffn {Scheme Procedure} dfa-fork dfa
2306 @c NJFIXME not in libguile!
2307 @deffn {Scheme Procedure} reset-dfa! dfa
2310 @c NJFIXME not in libguile!
2311 @deffn {Scheme Procedure} dfa-final-tag dfa
2314 @c NJFIXME not in libguile!
2315 @deffn {Scheme Procedure} dfa-continuable? dfa
2318 @c NJFIXME not in libguile!
2319 @deffn {Scheme Procedure} advance-dfa! dfa string
2323 @node Symbols and Variables
2324 @section Symbols and Variables
2326 @c FIXME::martin: Review me!
2328 Symbols are a data type with a special property. On the one hand,
2329 symbols are used for denoting variables in a Scheme program, on the
2330 other they can be used as literal data as well.
2332 The association between symbols and values is maintained in special data
2333 structures, the symbol tables.
2335 In addition, Guile offers variables as first-class objects. They can
2336 be used for interacting with the module system.
2339 * Symbols:: All about symbols as a data type.
2340 * Symbol Tables:: Tables for mapping symbols to values.
2341 * Variables:: First-class variables.
2348 @c FIXME::martin: Review me!
2350 Symbols are especially useful because two symbols which are spelled the
2351 same way are equivalent in the sense of @code{eq?}. That means that
2352 they are actually the same Scheme object. The advantage is that symbols
2353 can be compared extremely efficiently, although they carry more
2354 information for the human reader than, say, numbers.
2356 It is very common in Scheme programs to use symbols as keys in
2357 association lists (@pxref{Association Lists}) or hash tables
2358 (@pxref{Hash Tables}), because this usage improves the readability a
2359 lot, and does not cause any performance loss.
2361 The read syntax for symbols is a sequence of letters, digits, and
2362 @dfn{extended alphabetic characters} that begins with a character that
2363 cannot begin a number is an identifier. In addition, @code{+},
2364 @code{-}, and @code{...} are identifiers.
2366 Extended alphabetic characters may be used within identifiers as if
2367 they were letters. The following are extended alphabetic characters:
2370 ! $ % & * + - . / : < = > ? @@ ^ _ ~
2373 In addition to the read syntax defined above (which is taken from R5RS
2374 (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on Scheme})), Guile
2375 provides a method for writing symbols with unusual characters, such as
2376 space characters. If you (for whatever reason) need to write a symbol
2377 containing characters not mentioned above, you write symbols as follows:
2381 Begin the symbol with the two character @code{#@{},
2384 write the characters of the symbol and
2387 finish the symbol with the characters @code{@}#}.
2390 Here are a few examples of this form of read syntax; the first
2391 containing a space character, the second containing a line break and the
2392 last one looks like a number.
2401 Usage of this form of read syntax is discouraged, because it is not
2402 portable at all, and is not very readable.
2405 @deffn {Scheme Procedure} symbol? obj
2406 @deffnx {C Function} scm_symbol_p (obj)
2407 Return @code{#t} if @var{obj} is a symbol, otherwise return
2411 @rnindex string->symbol
2412 @deffn {Scheme Procedure} string->symbol string
2413 @deffnx {C Function} scm_string_to_symbol (string)
2414 Return the symbol whose name is @var{string}. This procedure
2415 can create symbols with names containing special characters or
2416 letters in the non-standard case, but it is usually a bad idea
2417 to create such symbols because in some implementations of
2418 Scheme they cannot be read as themselves. See
2419 @code{symbol->string}.
2421 The following examples assume that the implementation's
2422 standard case is lower case:
2425 (eq? 'mISSISSIppi 'mississippi) @result{} #t
2426 (string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
2427 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
2429 (string->symbol (symbol->string 'JollyWog))) @result{} #t
2430 (string=? "K. Harper, M.D."
2432 (string->symbol "K. Harper, M.D."))) @result{}#t
2436 @rnindex symbol->string
2437 @deffn {Scheme Procedure} symbol->string s
2438 @deffnx {C Function} scm_symbol_to_string (s)
2439 Return the name of @var{symbol} as a string. If the symbol was
2440 part of an object returned as the value of a literal expression
2441 (section @pxref{Literal expressions,,,r5rs, The Revised^5
2442 Report on Scheme}) or by a call to the @code{read} procedure,
2443 and its name contains alphabetic characters, then the string
2444 returned will contain characters in the implementation's
2445 preferred standard case---some implementations will prefer
2446 upper case, others lower case. If the symbol was returned by
2447 @code{string->symbol}, the case of characters in the string
2448 returned will be the same as the case in the string that was
2449 passed to @code{string->symbol}. It is an error to apply
2450 mutation procedures like @code{string-set!} to strings returned
2453 The following examples assume that the implementation's
2454 standard case is lower case:
2457 (symbol->string 'flying-fish) @result{} "flying-fish"
2458 (symbol->string 'Martin) @result{} "martin"
2460 (string->symbol "Malvina")) @result{} "Malvina"
2465 @subsection Symbol Tables
2467 @c FIXME::martin: Review me!
2469 @c FIXME::martin: Are all these procedures still relevant?
2471 Guile symbol tables are hash tables. Each hash table, also called an
2472 @dfn{obarray} (for `object array'), is a vector of association lists.
2473 Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}). To
2474 @dfn{intern} a symbol in a symbol table means to return its
2475 (@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol
2476 table (with an undefined value) if none is yet present.
2478 @c FIXME::martin: According to NEWS, removed. Remove here too, or
2479 @c leave for compatibility?
2480 @c @c docstring begin (texi-doc-string "guile" "builtin-bindings")
2481 @c @deffn {Scheme Procedure} builtin-bindings
2482 @c Create and return a copy of the global symbol table, removing all
2486 @deffn {Scheme Procedure} gensym [prefix]
2487 @deffnx {C Function} scm_gensym (prefix)
2488 Create a new symbol with a name constructed from a prefix and
2489 a counter value. The string @var{prefix} can be specified as
2490 an optional argument. Default prefix is @code{g}. The counter
2491 is increased by 1 at each call. There is no provision for
2492 resetting the counter.
2495 @deffn {Scheme Procedure} gentemp [prefix [obarray]]
2496 Create a new symbol with a name unique in an obarray.
2497 The name is constructed from an optional string @var{prefix}
2498 and a counter value. The default prefix is @code{t}. The
2499 @var{obarray} is specified as a second optional argument.
2500 Default is the system obarray where all normal symbols are
2501 interned. The counter is increased by 1 at each
2502 call. There is no provision for resetting the counter.
2505 @deffn {Scheme Procedure} intern-symbol obarray string
2506 Add a new symbol to @var{obarray} with name @var{string}, bound to an
2507 unspecified initial value. The symbol table is not modified if a symbol
2508 with this name is already present.
2511 @deffn {Scheme Procedure} string->obarray-symbol obarray string [soft?]
2512 Intern a new symbol in @var{obarray}, a symbol table, with name
2516 @deffn {Scheme Procedure} symbol-binding obarray string
2517 Look up in @var{obarray} the symbol whose name is @var{string}, and
2518 return the value to which it is bound. If @var{obarray} is @code{#f},
2519 use the global symbol table. If @var{string} is not interned in
2520 @var{obarray}, an error is signalled.
2523 @deffn {Scheme Procedure} symbol-bound? obarray string
2524 Return @code{#t} if @var{obarray} contains a symbol with name
2525 @var{string} bound to a defined value. This differs from
2526 @var{symbol-interned?} in that the mere mention of a symbol
2527 usually causes it to be interned; @code{symbol-bound?}
2528 determines whether a symbol has been given any meaningful
2532 @deffn {Scheme Procedure} symbol-fref symbol
2533 @deffnx {C Function} scm_symbol_fref (symbol)
2534 Return the contents of @var{symbol}'s @dfn{function slot}.
2537 @deffn {Scheme Procedure} symbol-fset! symbol value
2538 @deffnx {C Function} scm_symbol_fset_x (symbol, value)
2539 Change the binding of @var{symbol}'s function slot.
2542 @deffn {Scheme Procedure} symbol-hash symbol
2543 @deffnx {C Function} scm_symbol_hash (symbol)
2544 Return a hash value for @var{symbol}.
2547 @deffn {Scheme Procedure} symbol-interned? obarray string
2548 Return @code{#t} if @var{obarray} contains a symbol with name
2549 @var{string}, and @code{#f} otherwise.
2552 @deffn {Scheme Procedure} symbol-pref symbol
2553 @deffnx {C Function} scm_symbol_pref (symbol)
2554 Return the @dfn{property list} currently associated with @var{symbol}.
2557 @deffn {Scheme Procedure} symbol-pset! symbol value
2558 @deffnx {C Function} scm_symbol_pset_x (symbol, value)
2559 Change the binding of @var{symbol}'s property slot.
2562 @deffn {Scheme Procedure} symbol-set! obarray string value
2563 Find the symbol in @var{obarray} whose name is @var{string}, and rebind
2564 it to @var{value}. An error is signalled if @var{string} is not present
2568 @deffn {Scheme Procedure} unintern-symbol obarray string
2569 Remove the symbol with name @var{string} from @var{obarray}. This
2570 function returns @code{#t} if the symbol was present and @code{#f}
2575 @subsection Variables
2578 @c FIXME::martin: Review me!
2580 Variables are objects with two fields. They contain a value and they
2581 can contain a symbol, which is the name of the variable. A variable is
2582 said to be bound if it does not contain the object denoting unbound
2583 variables in the value slot.
2585 Variables do not have a read syntax, they have to be created by calling
2586 one of the constructor procedures @code{make-variable} or
2587 @code{make-undefined-variable} or retrieved by @code{builtin-variable}.
2589 First-class variables are especially useful for interacting with the
2590 current module system (@pxref{The Guile module system}).
2592 @deffn {Scheme Procedure} builtin-variable name
2593 Return the built-in variable with the name @var{name}.
2594 @var{name} must be a symbol (not a string).
2595 Then use @code{variable-ref} to access its value.
2598 @deffn {Scheme Procedure} make-undefined-variable
2599 @deffnx {C Function} scm_make_undefined_variable ()
2600 Return a variable that is initially unbound.
2603 @deffn {Scheme Procedure} make-variable init
2604 @deffnx {C Function} scm_make_variable (init)
2605 Return a variable initialized to value @var{init}.
2608 @deffn {Scheme Procedure} variable-bound? var
2609 @deffnx {C Function} scm_variable_bound_p (var)
2610 Return @code{#t} iff @var{var} is bound to a value.
2611 Throws an error if @var{var} is not a variable object.
2614 @deffn {Scheme Procedure} variable-ref var
2615 @deffnx {C Function} scm_variable_ref (var)
2616 Dereference @var{var} and return its value.
2617 @var{var} must be a variable object; see @code{make-variable}
2618 and @code{make-undefined-variable}.
2621 @deffn {Scheme Procedure} variable-set! var val
2622 @deffnx {C Function} scm_variable_set_x (var, val)
2623 Set the value of the variable @var{var} to @var{val}.
2624 @var{var} must be a variable object, @var{val} can be any
2625 value. Return an unspecified value.
2628 @deffn {Scheme Procedure} variable? obj
2629 @deffnx {C Function} scm_variable_p (obj)
2630 Return @code{#t} iff @var{obj} is a variable object, else
2639 Keywords are self-evaluating objects with a convenient read syntax that
2640 makes them easy to type.
2642 Guile's keyword support conforms to R5RS, and adds a (switchable) read
2643 syntax extension to permit keywords to begin with @code{:} as well as
2647 * Why Use Keywords?:: Motivation for keyword usage.
2648 * Coding With Keywords:: How to use keywords.
2649 * Keyword Read Syntax:: Read syntax for keywords.
2650 * Keyword Procedures:: Procedures for dealing with keywords.
2651 * Keyword Primitives:: The underlying primitive procedures.
2654 @node Why Use Keywords?
2655 @subsection Why Use Keywords?
2657 Keywords are useful in contexts where a program or procedure wants to be
2658 able to accept a large number of optional arguments without making its
2659 interface unmanageable.
2661 To illustrate this, consider a hypothetical @code{make-window}
2662 procedure, which creates a new window on the screen for drawing into
2663 using some graphical toolkit. There are many parameters that the caller
2664 might like to specify, but which could also be sensibly defaulted, for
2669 colour depth -- Default: the colour depth for the screen
2672 background colour -- Default: white
2675 width -- Default: 600
2678 height -- Default: 400
2681 If @code{make-window} did not use keywords, the caller would have to
2682 pass in a value for each possible argument, remembering the correct
2683 argument order and using a special value to indicate the default value
2687 (make-window 'default ;; Colour depth
2688 'default ;; Background colour
2691 @dots{}) ;; More make-window arguments
2694 With keywords, on the other hand, defaulted arguments are omitted, and
2695 non-default arguments are clearly tagged by the appropriate keyword. As
2696 a result, the invocation becomes much clearer:
2699 (make-window #:width 800 #:height 100)
2702 On the other hand, for a simpler procedure with few arguments, the use
2703 of keywords would be a hindrance rather than a help. The primitive
2704 procedure @code{cons}, for example, would not be improved if it had to
2708 (cons #:car x #:cdr y)
2711 So the decision whether to use keywords or not is purely pragmatic: use
2712 them if they will clarify the procedure invocation at point of call.
2714 @node Coding With Keywords
2715 @subsection Coding With Keywords
2717 If a procedure wants to support keywords, it should take a rest argument
2718 and then use whatever means is convenient to extract keywords and their
2719 corresponding arguments from the contents of that rest argument.
2721 The following example illustrates the principle: the code for
2722 @code{make-window} uses a helper procedure called
2723 @code{get-keyword-value} to extract individual keyword arguments from
2727 (define (get-keyword-value args keyword default)
2728 (let ((kv (memq keyword args)))
2729 (if (and kv (>= (length kv) 2))
2733 (define (make-window . args)
2734 (let ((depth (get-keyword-value args #:depth screen-depth))
2735 (bg (get-keyword-value args #:bg "white"))
2736 (width (get-keyword-value args #:width 800))
2737 (height (get-keyword-value args #:height 100))
2742 But you don't need to write @code{get-keyword-value}. The @code{(ice-9
2743 optargs)} module provides a set of powerful macros that you can use to
2744 implement keyword-supporting procedures like this:
2747 (use-modules (ice-9 optargs))
2749 (define (make-window . args)
2750 (let-keywords args #f ((depth screen-depth)
2758 Or, even more economically, like this:
2761 (use-modules (ice-9 optargs))
2763 (define* (make-window #:key (depth screen-depth)
2770 For further details on @code{let-keywords}, @code{define*} and other
2771 facilities provided by the @code{(ice-9 optargs)} module, @ref{Optional
2775 @node Keyword Read Syntax
2776 @subsection Keyword Read Syntax
2778 Guile, by default, only recognizes the keyword syntax specified by R5RS.
2779 A token of the form @code{#:NAME}, where @code{NAME} has the same syntax
2780 as a Scheme symbol, is the external representation of the keyword named
2781 @code{NAME}. Keyword objects print using this syntax as well, so values
2782 containing keyword objects can be read back into Guile. When used in an
2783 expression, keywords are self-quoting objects.
2785 If the @code{keyword} read option is set to @code{'prefix}, Guile also
2786 recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
2787 of the form @code{:NAME} are read as symbols, as required by R5RS.
2789 To enable and disable the alternative non-R5RS keyword syntax, you use
2790 the @code{read-options} procedure documented in @ref{General option
2791 interface} and @ref{Reader options}.
2794 (read-set! keywords 'prefix)
2804 (read-set! keywords #f)
2812 ERROR: In expression :type:
2813 ERROR: Unbound variable: :type
2814 ABORT: (unbound-variable)
2817 @node Keyword Procedures
2818 @subsection Keyword Procedures
2820 @c FIXME::martin: Review me!
2822 The following procedures can be used for converting symbols to keywords
2825 @deffn {Scheme Procedure} symbol->keyword sym
2826 Return a keyword with the same characters as in @var{sym}.
2829 @deffn {Scheme Procedure} keyword->symbol kw
2830 Return a symbol with the same characters as in @var{kw}.
2834 @node Keyword Primitives
2835 @subsection Keyword Primitives
2837 Internally, a keyword is implemented as something like a tagged symbol,
2838 where the tag identifies the keyword as being self-evaluating, and the
2839 symbol, known as the keyword's @dfn{dash symbol} has the same name as
2840 the keyword name but prefixed by a single dash. For example, the
2841 keyword @code{#:name} has the corresponding dash symbol @code{-name}.
2843 Most keyword objects are constructed automatically by the reader when it
2844 reads a token beginning with @code{#:}. However, if you need to
2845 construct a keyword object programmatically, you can do so by calling
2846 @code{make-keyword-from-dash-symbol} with the corresponding dash symbol
2847 (as the reader does). The dash symbol for a keyword object can be
2848 retrieved using the @code{keyword-dash-symbol} procedure.
2850 @deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
2851 @deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
2852 Make a keyword object from a @var{symbol} that starts with a dash.
2855 @deffn {Scheme Procedure} keyword? obj
2856 @deffnx {C Function} scm_keyword_p (obj)
2857 Return @code{#t} if the argument @var{obj} is a keyword, else
2861 @deffn {Scheme Procedure} keyword-dash-symbol keyword
2862 @deffnx {C Function} scm_keyword_dash_symbol (keyword)
2863 Return the dash symbol for @var{keyword}.
2864 This is the inverse of @code{make-keyword-from-dash-symbol}.
2871 @c FIXME::martin: Review me!
2873 Pairs are used to combine two Scheme objects into one compound object.
2874 Hence the name: A pair stores a pair of objects.
2876 The data type @dfn{pair} is extremely important in Scheme, just like in
2877 any other Lisp dialect. The reason is that pairs are not only used to
2878 make two values available as one object, but that pairs are used for
2879 constructing lists of values. Because lists are so important in Scheme,
2880 they are described in a section of their own (@pxref{Lists}).
2882 Pairs can literally get entered in source code or at the REPL, in the
2883 so-called @dfn{dotted list} syntax. This syntax consists of an opening
2884 parentheses, the first element of the pair, a dot, the second element
2885 and a closing parentheses. The following example shows how a pair
2886 consisting of the two numbers 1 and 2, and a pair containing the symbols
2887 @code{foo} and @code{bar} can be entered. It is very important to write
2888 the whitespace before and after the dot, because otherwise the Scheme
2889 parser whould not be able to figure out where to split the tokens.
2896 But beware, if you want to try out these examples, you have to
2897 @dfn{quote} the expressions. More information about quotation is
2898 available in the section (REFFIXME). The correct way to try these
2899 examples is as follows.
2910 A new pair is made by calling the procedure @code{cons} with two
2911 arguments. Then the argument values are stored into a newly allocated
2912 pair, and the pair is returned. The name @code{cons} stands for
2913 "construct". Use the procedure @code{pair?} to test whether a
2914 given Scheme object is a pair or not.
2917 @deffn {Scheme Procedure} cons x y
2918 @deffnx {C Function} scm_cons (x, y)
2919 Return a newly allocated pair whose car is @var{x} and whose
2920 cdr is @var{y}. The pair is guaranteed to be different (in the
2921 sense of @code{eq?}) from every previously existing object.
2925 @deffn {Scheme Procedure} pair? x
2926 @deffnx {C Function} scm_pair_p (x)
2927 Return @code{#t} if @var{x} is a pair; otherwise return
2931 The two parts of a pair are traditionally called @dfn{car} and
2932 @dfn{cdr}. They can be retrieved with procedures of the same name
2933 (@code{car} and @code{cdr}), and can be modified with the procedures
2934 @code{set-car!} and @code{set-cdr!}. Since a very common operation in
2935 Scheme programs is to access the car of a pair, or the car of the cdr of
2936 a pair, etc., the procedures called @code{caar}, @code{cadr} and so on
2937 are also predefined.
2941 @deffn {Scheme Procedure} car pair
2942 @deffnx {Scheme Procedure} cdr pair
2943 Return the car or the cdr of @var{pair}, respectively.
2946 @deffn {Scheme Procedure} caar pair
2947 @deffnx {Scheme Procedure} cadr pair @dots{}
2948 @deffnx {Scheme Procedure} cdddar pair
2949 @deffnx {Scheme Procedure} cddddr pair
2950 These procedures are compositions of @code{car} and @code{cdr}, where
2951 for example @code{caddr} could be defined by
2954 (define caddr (lambda (x) (car (cdr (cdr x)))))
2959 @deffn {Scheme Procedure} set-car! pair value
2960 @deffnx {C Function} scm_set_car_x (pair, value)
2961 Stores @var{value} in the car field of @var{pair}. The value returned
2962 by @code{set-car!} is unspecified.
2966 @deffn {Scheme Procedure} set-cdr! pair value
2967 @deffnx {C Function} scm_set_cdr_x (pair, value)
2968 Stores @var{value} in the cdr field of @var{pair}. The value returned
2969 by @code{set-cdr!} is unspecified.
2977 @c FIXME::martin: Review me!
2979 A very important data type in Scheme---as well as in all other Lisp
2980 dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
2981 Scheme does not have a real datatype @dfn{list}. Lists are made up of
2982 @dfn{chained pairs}, and only exist by definition---a list is a chain
2983 of pairs which looks like a list.}
2985 This is the short definition of what a list is:
2989 Either the empty list @code{()},
2992 or a pair which has a list in its cdr.
2995 @c FIXME::martin: Describe the pair chaining in more detail.
2997 @c FIXME::martin: What is a proper, what an improper list?
2998 @c What is a circular list?
3000 @c FIXME::martin: Maybe steal some graphics from the Elisp reference
3004 * List Syntax:: Writing literal lists.
3005 * List Predicates:: Testing lists.
3006 * List Constructors:: Creating new lists.
3007 * List Selection:: Selecting from lists, getting their length.
3008 * Append/Reverse:: Appending and reversing lists.
3009 * List Modification:: Modifying existing lists.
3010 * List Searching:: Searching for list elements
3011 * List Mapping:: Applying procedures to lists.
3015 @subsection List Read Syntax
3017 @c FIXME::martin: Review me!
3019 The syntax for lists is an opening parentheses, then all the elements of
3020 the list (separated by whitespace) and finally a closing
3021 parentheses.@footnote{Note that there is no separation character between
3022 the list elements, like a comma or a semicolon.}.
3025 (1 2 3) ; @r{a list of the numbers 1, 2 and 3}
3026 ("foo" bar 3.1415) ; @r{a string, a symbol and a real number}
3027 () ; @r{the empty list}
3030 The last example needs a bit more explanation. A list with no elements,
3031 called the @dfn{empty list}, is special in some ways. It is used for
3032 terminating lists by storing it into the cdr of the last pair that makes
3033 up a list. An example will clear that up:
3044 This example also shows that lists have to be quoted (REFFIXME) when
3045 written, because they would otherwise be mistakingly taken as procedure
3046 applications (@pxref{Simple Invocation}).
3049 @node List Predicates
3050 @subsection List Predicates
3052 @c FIXME::martin: Review me!
3054 Often it is useful to test whether a given Scheme object is a list or
3055 not. List-processing procedures could use this information to test
3056 whether their input is valid, or they could do different things
3057 depending on the datatype of their arguments.
3060 @deffn {Scheme Procedure} list? x
3061 @deffnx {C Function} scm_list_p (x)
3062 Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
3065 The predicate @code{null?} is often used in list-processing code to
3066 tell whether a given list has run out of elements. That is, a loop
3067 somehow deals with the elements of a list until the list satisfies
3068 @code{null?}. Then, the algorithm terminates.
3071 @deffn {Scheme Procedure} null? x
3072 @deffnx {C Function} scm_null_p (x)
3073 Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
3076 @node List Constructors
3077 @subsection List Constructors
3079 This section describes the procedures for constructing new lists.
3080 @code{list} simply returns a list where the elements are the arguments,
3081 @code{cons*} is similar, but the last argument is stored in the cdr of
3082 the last pair of the list.
3085 @deffn {Scheme Procedure} list . objs
3086 @deffnx {C Function} scm_list (objs)
3087 Return a list containing @var{objs}, the arguments to
3091 @deffn {Scheme Procedure} cons* arg1 arg2 @dots{}
3092 @deffnx {C Function} scm_cons_star (arg1, rest)
3093 Like @code{list}, but the last arg provides the tail of the
3094 constructed list, returning @code{(cons @var{arg1} (cons
3095 @var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
3096 argument. If given one argument, that argument is returned as
3097 result. This function is called @code{list*} in some other
3098 Schemes and in Common LISP.
3101 @deffn {Scheme Procedure} list-copy lst
3102 @deffnx {C Function} scm_list_copy (lst)
3103 Return a (newly-created) copy of @var{lst}.
3106 @deffn {Scheme Procedure} make-list n [init]
3107 Create a list containing of @var{n} elements, where each element is
3108 initialized to @var{init}. @var{init} defaults to the empty list
3109 @code{()} if not given.
3112 Note that @code{list-copy} only makes a copy of the pairs which make up
3113 the spine of the lists. The list elements are not copied, which means
3114 that modifying the elements of the new list also modyfies the elements
3115 of the old list. On the other hand, applying procedures like
3116 @code{set-cdr!} or @code{delv!} to the new list will not alter the old
3117 list. If you also need to copy the list elements (making a deep copy),
3118 use the procedure @code{copy-tree} (@pxref{Copying}).
3120 @node List Selection
3121 @subsection List Selection
3123 @c FIXME::martin: Review me!
3125 These procedures are used to get some information about a list, or to
3126 retrieve one or more elements of a list.
3129 @deffn {Scheme Procedure} length lst
3130 @deffnx {C Function} scm_length (lst)
3131 Return the number of elements in list @var{lst}.
3134 @deffn {Scheme Procedure} last-pair lst
3135 @deffnx {C Function} scm_last_pair (lst)
3136 Return a pointer to the last pair in @var{lst}, signalling an error if
3137 @var{lst} is circular.
3141 @deffn {Scheme Procedure} list-ref list k
3142 @deffnx {C Function} scm_list_ref (list, k)
3143 Return the @var{k}th element from @var{list}.
3147 @deffn {Scheme Procedure} list-tail lst k
3148 @deffnx {Scheme Procedure} list-cdr-ref lst k
3149 @deffnx {C Function} scm_list_tail (lst, k)
3150 Return the "tail" of @var{lst} beginning with its @var{k}th element.
3151 The first element of the list is considered to be element 0.
3153 @code{list-tail} and @code{list-cdr-ref} are identical. It may help to
3154 think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
3155 or returning the results of cdring @var{k} times down @var{lst}.
3158 @deffn {Scheme Procedure} list-head lst k
3159 @deffnx {C Function} scm_list_head (lst, k)
3160 Copy the first @var{k} elements from @var{lst} into a new list, and
3164 @node Append/Reverse
3165 @subsection Append and Reverse
3167 @c FIXME::martin: Review me!
3169 @code{append} and @code{append!} are used to concatenate two or more
3170 lists in order to form a new list. @code{reverse} and @code{reverse!}
3171 return lists with the same elements as their arguments, but in reverse
3172 order. The procedure variants with an @code{!} directly modify the
3173 pairs which form the list, whereas the other procedures create new
3174 pairs. This is why you should be careful when using the side-effecting
3178 @deffn {Scheme Procedure} append . args
3179 @deffnx {C Function} scm_append (args)
3180 Return a list consisting of the elements the lists passed as
3183 (append '(x) '(y)) @result{} (x y)
3184 (append '(a) '(b c d)) @result{} (a b c d)
3185 (append '(a (b)) '((c))) @result{} (a (b) (c))
3187 The resulting list is always newly allocated, except that it
3188 shares structure with the last list argument. The last
3189 argument may actually be any object; an improper list results
3190 if the last argument is not a proper list.
3192 (append '(a b) '(c . d)) @result{} (a b c . d)
3193 (append '() 'a) @result{} a
3197 @deffn {Scheme Procedure} append! . lists
3198 @deffnx {C Function} scm_append_x (lists)
3199 A destructive version of @code{append} (@pxref{Pairs and
3200 Lists,,,r5rs, The Revised^5 Report on Scheme}). The cdr field
3201 of each list's final pair is changed to point to the head of
3202 the next list, so no consing is performed. Return a pointer to
3207 @deffn {Scheme Procedure} reverse lst
3208 @deffnx {C Function} scm_reverse (lst)
3209 Return a new list that contains the elements of @var{lst} but
3213 @c NJFIXME explain new_tail
3214 @deffn {Scheme Procedure} reverse! lst [new_tail]
3215 @deffnx {C Function} scm_reverse_x (lst, new_tail)
3216 A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r5rs,
3217 The Revised^5 Report on Scheme}). The cdr of each cell in @var{lst} is
3218 modified to point to the previous list element. Return a pointer to the
3219 head of the reversed list.
3221 Caveat: because the list is modified in place, the tail of the original
3222 list now becomes its head, and the head of the original list now becomes
3223 the tail. Therefore, the @var{lst} symbol to which the head of the
3224 original list was bound now points to the tail. To ensure that the head
3225 of the modified list is not lost, it is wise to save the return value of
3229 @node List Modification
3230 @subsection List Modification
3232 The following procedures modify an existing list, either by changing
3233 elements of the list, or by changing the list structure itself.
3235 @deffn {Scheme Procedure} list-set! list k val
3236 @deffnx {C Function} scm_list_set_x (list, k, val)
3237 Set the @var{k}th element of @var{list} to @var{val}.
3240 @deffn {Scheme Procedure} list-cdr-set! list k val
3241 @deffnx {C Function} scm_list_cdr_set_x (list, k, val)
3242 Set the @var{k}th cdr of @var{list} to @var{val}.
3245 @deffn {Scheme Procedure} delq item lst
3246 @deffnx {C Function} scm_delq (item, lst)
3247 Return a newly-created copy of @var{lst} with elements
3248 @code{eq?} to @var{item} removed. This procedure mirrors
3249 @code{memq}: @code{delq} compares elements of @var{lst} against
3250 @var{item} with @code{eq?}.
3253 @deffn {Scheme Procedure} delv item lst
3254 @deffnx {C Function} scm_delv (item, lst)
3255 Return a newly-created copy of @var{lst} with elements
3256 @code{eqv?} to @var{item} removed. This procedure mirrors
3257 @code{memv}: @code{delv} compares elements of @var{lst} against
3258 @var{item} with @code{eqv?}.
3261 @deffn {Scheme Procedure} delete item lst
3262 @deffnx {C Function} scm_delete (item, lst)
3263 Return a newly-created copy of @var{lst} with elements
3264 @code{equal?} to @var{item} removed. This procedure mirrors
3265 @code{member}: @code{delete} compares elements of @var{lst}
3266 against @var{item} with @code{equal?}.
3269 @deffn {Scheme Procedure} delq! item lst
3270 @deffnx {Scheme Procedure} delv! item lst
3271 @deffnx {Scheme Procedure} delete! item lst
3272 @deffnx {C Function} scm_delq_x (item, lst)
3273 @deffnx {C Function} scm_delv_x (item, lst)
3274 @deffnx {C Function} scm_delete_x (item, lst)
3275 These procedures are destructive versions of @code{delq}, @code{delv}
3276 and @code{delete}: they modify the pointers in the existing @var{lst}
3277 rather than creating a new list. Caveat evaluator: Like other
3278 destructive list functions, these functions cannot modify the binding of
3279 @var{lst}, and so cannot be used to delete the first element of
3280 @var{lst} destructively.
3283 @deffn {Scheme Procedure} delq1! item lst
3284 @deffnx {C Function} scm_delq1_x (item, lst)
3285 Like @code{delq!}, but only deletes the first occurrence of
3286 @var{item} from @var{lst}. Tests for equality using
3287 @code{eq?}. See also @code{delv1!} and @code{delete1!}.
3290 @deffn {Scheme Procedure} delv1! item lst
3291 @deffnx {C Function} scm_delv1_x (item, lst)
3292 Like @code{delv!}, but only deletes the first occurrence of
3293 @var{item} from @var{lst}. Tests for equality using
3294 @code{eqv?}. See also @code{delq1!} and @code{delete1!}.
3297 @deffn {Scheme Procedure} delete1! item lst
3298 @deffnx {C Function} scm_delete1_x (item, lst)
3299 Like @code{delete!}, but only deletes the first occurrence of
3300 @var{item} from @var{lst}. Tests for equality using
3301 @code{equal?}. See also @code{delq1!} and @code{delv1!}.
3304 @node List Searching
3305 @subsection List Searching
3307 @c FIXME::martin: Review me!
3309 The following procedures search lists for particular elements. They use
3310 different comparison predicates for comparing list elements with the
3311 object to be searched. When they fail, they return @code{#f}, otherwise
3312 they return the sublist whose car is equal to the search object, where
3313 equality depends on the equality predicate used.
3316 @deffn {Scheme Procedure} memq x lst
3317 @deffnx {C Function} scm_memq (x, lst)
3318 Return the first sublist of @var{lst} whose car is @code{eq?}
3319 to @var{x} where the sublists of @var{lst} are the non-empty
3320 lists returned by @code{(list-tail @var{lst} @var{k})} for
3321 @var{k} less than the length of @var{lst}. If @var{x} does not
3322 occur in @var{lst}, then @code{#f} (not the empty list) is
3327 @deffn {Scheme Procedure} memv x lst
3328 @deffnx {C Function} scm_memv (x, lst)
3329 Return the first sublist of @var{lst} whose car is @code{eqv?}
3330 to @var{x} where the sublists of @var{lst} are the non-empty
3331 lists returned by @code{(list-tail @var{lst} @var{k})} for
3332 @var{k} less than the length of @var{lst}. If @var{x} does not
3333 occur in @var{lst}, then @code{#f} (not the empty list) is
3338 @deffn {Scheme Procedure} member x lst
3339 @deffnx {C Function} scm_member (x, lst)
3340 Return the first sublist of @var{lst} whose car is
3341 @code{equal?} to @var{x} where the sublists of @var{lst} are
3342 the non-empty lists returned by @code{(list-tail @var{lst}
3343 @var{k})} for @var{k} less than the length of @var{lst}. If
3344 @var{x} does not occur in @var{lst}, then @code{#f} (not the
3345 empty list) is returned.
3348 [FIXME: Is there any reason to have the `sloppy' functions available at
3349 high level at all? Maybe these docs should be relegated to a "Guile
3350 Internals" node or something. -twp]
3352 @deffn {Scheme Procedure} sloppy-memq x lst
3353 This procedure behaves like @code{memq}, but does no type or error checking.
3354 Its use is recommended only in writing Guile internals,
3355 not for high-level Scheme programs.
3358 @deffn {Scheme Procedure} sloppy-memv x lst
3359 This procedure behaves like @code{memv}, but does no type or error checking.
3360 Its use is recommended only in writing Guile internals,
3361 not for high-level Scheme programs.
3364 @deffn {Scheme Procedure} sloppy-member x lst
3365 This procedure behaves like @code{member}, but does no type or error checking.
3366 Its use is recommended only in writing Guile internals,
3367 not for high-level Scheme programs.
3371 @subsection List Mapping
3373 @c FIXME::martin: Review me!
3375 List processing is very convenient in Scheme because the process of
3376 iterating over the elements of a list can be highly abstracted. The
3377 procedures in this section are the most basic iterating procedures for
3378 lists. They take a procedure and one or more lists as arguments, and
3379 apply the procedure to each element of the list. They differ in their
3383 @c begin (texi-doc-string "guile" "map")
3384 @deffn {Scheme Procedure} map proc arg1 arg2 @dots{}
3385 @deffnx {Scheme Procedure} map-in-order proc arg1 arg2 @dots{}
3386 @deffnx {C Function} scm_map (proc, arg1, args)
3387 Apply @var{proc} to each element of the list @var{arg1} (if only two
3388 arguments are given), or to the corresponding elements of the argument
3389 lists (if more than two arguments are given). The result(s) of the
3390 procedure applications are saved and returned in a list. For
3391 @code{map}, the order of procedure applications is not specified,
3392 @code{map-in-order} applies the procedure from left to right to the list
3397 @c begin (texi-doc-string "guile" "for-each")
3398 @deffn {Scheme Procedure} for-each proc arg1 arg2 @dots{}
3399 Like @code{map}, but the procedure is always applied from left to right,
3400 and the result(s) of the procedure applications are thrown away. The
3401 return value is not specified.
3409 @c FIXME::martin: Review me!
3411 @c FIXME::martin: Should the subsections of this section be nodes
3412 @c of their own, or are the resulting nodes too short, then?
3414 Vectors are sequences of Scheme objects. Unlike lists, the length of a
3415 vector, once the vector is created, cannot be changed. The advantage of
3416 vectors over lists is that the time required to access one element of a vector
3417 given its @dfn{position} (synonymous with @dfn{index}), a zero-origin number,
3418 is constant, whereas lists have an access time linear to the position of the
3419 accessed element in the list.
3421 Vectors can contain any kind of Scheme object; it is even possible to have
3422 different types of objects in the same vector. For vectors containing
3423 vectors, you may wish to use arrays, instead. Note, too, that some array
3424 procedures operate happily on vectors (@pxref{Arrays}).
3426 @subsection Vector Read Syntax
3428 Vectors can literally be entered in source code, just like strings,
3429 characters or some of the other data types. The read syntax for vectors
3430 is as follows: A sharp sign (@code{#}), followed by an opening
3431 parentheses, all elements of the vector in their respective read syntax,
3432 and finally a closing parentheses. The following are examples of the
3433 read syntax for vectors; where the first vector only contains numbers
3434 and the second three different object types: a string, a symbol and a
3435 number in hexadecimal notation.
3439 #("Hello" foo #xdeadbeef)
3442 @subsection Vector Predicates
3445 @deffn {Scheme Procedure} vector? obj
3446 @deffnx {C Function} scm_vector_p (obj)
3447 Return @code{#t} if @var{obj} is a vector, otherwise return
3451 @subsection Vector Constructors
3453 @rnindex make-vector
3454 @deffn {Scheme Procedure} make-vector k [fill]
3455 @deffnx {C Function} scm_make_vector (k, fill)
3456 Return a newly allocated vector of @var{k} elements. If a
3457 second argument is given, then each position is initialized to
3458 @var{fill}. Otherwise the initial contents of each position is
3463 @rnindex list->vector
3464 @deffn {Scheme Procedure} vector . l
3465 @deffnx {Scheme Procedure} list->vector l
3466 @deffnx {C Function} scm_vector (l)
3467 Return a newly allocated vector composed of the
3468 given arguments. Analogous to @code{list}.
3471 (vector 'a 'b 'c) @result{} #(a b c)
3475 @rnindex vector->list
3476 @deffn {Scheme Procedure} vector->list v
3477 @deffnx {C Function} scm_vector_to_list (v)
3478 Return a newly allocated list composed of the elements of @var{v}.
3481 (vector->list '#(dah dah didah)) @result{} (dah dah didah)
3482 (list->vector '(dididit dah)) @result{} #(dididit dah)
3486 @subsection Vector Modification
3488 A vector created by any of the vector constructor procedures
3489 (@pxref{Vectors}) documented above can be modified using the
3490 following procedures.
3492 @emph{NOTE:} According to R5RS, using any of these procedures on
3493 literally entered vectors is an error, because these vectors are
3494 considered to be constant, although Guile currently does not detect this
3497 @rnindex vector-set!
3498 @deffn {Scheme Procedure} vector-set! vector k obj
3499 Store @var{obj} in position @var{k} of @var{vector}.
3500 @var{k} must be a valid index of @var{vector}.
3501 The value returned by @samp{vector-set!} is unspecified.
3503 (let ((vec (vector 0 '(2 2 2 2) "Anna")))
3504 (vector-set! vec 1 '("Sue" "Sue"))
3505 vec) @result{} #(0 ("Sue" "Sue") "Anna")
3509 @rnindex vector-fill!
3510 @deffn {Scheme Procedure} vector-fill! v fill
3511 @deffnx {C Function} scm_vector_fill_x (v, fill)
3512 Store @var{fill} in every position of @var{vector}. The value
3513 returned by @code{vector-fill!} is unspecified.
3516 @deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2
3517 @deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
3518 Vector version of @code{substring-move-left!}.
3521 @deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2
3522 @deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2)
3523 Vector version of @code{substring-move-right!}.
3526 @subsection Vector Selection
3528 These procedures return information about a given vector, such as the
3529 size or what elements are contained in the vector.
3531 @rnindex vector-length
3532 @deffn {Scheme Procedure} vector-length vector
3533 Return the number of elements in @var{vector} as an exact integer.
3537 @deffn {Scheme Procedure} vector-ref vector k
3538 Return the contents of position @var{k} of @var{vector}.
3539 @var{k} must be a valid index of @var{vector}.
3541 (vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
3542 (vector-ref '#(1 1 2 3 5 8 13 21)
3543 (let ((i (round (* 2 (acos -1)))))
3554 A @dfn{record type} is a first class object representing a user-defined
3555 data type. A @dfn{record} is an instance of a record type.
3557 @deffn {Scheme Procedure} record? obj
3558 Return @code{#t} if @var{obj} is a record of any type and @code{#f}
3561 Note that @code{record?} may be true of any Scheme value; there is no
3562 promise that records are disjoint with other Scheme types.
3565 @deffn {Scheme Procedure} make-record-type type-name field-names
3566 Return a @dfn{record-type descriptor}, a value representing a new data
3567 type disjoint from all others. The @var{type-name} argument must be a
3568 string, but is only used for debugging purposes (such as the printed
3569 representation of a record of the new type). The @var{field-names}
3570 argument is a list of symbols naming the @dfn{fields} of a record of the
3571 new type. It is an error if the list contains any duplicates. It is
3572 unspecified how record-type descriptors are represented.
3575 @deffn {Scheme Procedure} record-constructor rtd [field-names]
3576 Return a procedure for constructing new members of the type represented
3577 by @var{rtd}. The returned procedure accepts exactly as many arguments
3578 as there are symbols in the given list, @var{field-names}; these are
3579 used, in order, as the initial values of those fields in a new record,
3580 which is returned by the constructor procedure. The values of any
3581 fields not named in that list are unspecified. The @var{field-names}
3582 argument defaults to the list of field names in the call to
3583 @code{make-record-type} that created the type represented by @var{rtd};
3584 if the @var{field-names} argument is provided, it is an error if it
3585 contains any duplicates or any symbols not in the default list.
3588 @deffn {Scheme Procedure} record-predicate rtd
3589 Return a procedure for testing membership in the type represented by
3590 @var{rtd}. The returned procedure accepts exactly one argument and
3591 returns a true value if the argument is a member of the indicated record
3592 type; it returns a false value otherwise.
3595 @deffn {Scheme Procedure} record-accessor rtd field-name
3596 Return a procedure for reading the value of a particular field of a
3597 member of the type represented by @var{rtd}. The returned procedure
3598 accepts exactly one argument which must be a record of the appropriate
3599 type; it returns the current value of the field named by the symbol
3600 @var{field-name} in that record. The symbol @var{field-name} must be a
3601 member of the list of field-names in the call to @code{make-record-type}
3602 that created the type represented by @var{rtd}.
3605 @deffn {Scheme Procedure} record-modifier rtd field-name
3606 Return a procedure for writing the value of a particular field of a
3607 member of the type represented by @var{rtd}. The returned procedure
3608 accepts exactly two arguments: first, a record of the appropriate type,
3609 and second, an arbitrary Scheme value; it modifies the field named by
3610 the symbol @var{field-name} in that record to contain the given value.
3611 The returned value of the modifier procedure is unspecified. The symbol
3612 @var{field-name} must be a member of the list of field-names in the call
3613 to @code{make-record-type} that created the type represented by
3617 @deffn {Scheme Procedure} record-type-descriptor record
3618 Return a record-type descriptor representing the type of the given
3619 record. That is, for example, if the returned descriptor were passed to
3620 @code{record-predicate}, the resulting predicate would return a true
3621 value when passed the given record. Note that it is not necessarily the
3622 case that the returned descriptor is the one that was passed to
3623 @code{record-constructor} in the call that created the constructor
3624 procedure that created the given record.
3627 @deffn {Scheme Procedure} record-type-name rtd
3628 Return the type-name associated with the type represented by rtd. The
3629 returned value is @code{eqv?} to the @var{type-name} argument given in
3630 the call to @code{make-record-type} that created the type represented by
3634 @deffn {Scheme Procedure} record-type-fields rtd
3635 Return a list of the symbols naming the fields in members of the type
3636 represented by @var{rtd}. The returned value is @code{equal?} to the
3637 field-names argument given in the call to @code{make-record-type} that
3638 created the type represented by @var{rtd}.
3646 [FIXME: this is pasted in from Tom Lord's original guile.texi and should
3649 A @dfn{structure type} is a first class user-defined data type. A
3650 @dfn{structure} is an instance of a structure type. A structure type is
3653 Structures are less abstract and more general than traditional records.
3654 In fact, in Guile Scheme, records are implemented using structures.
3657 * Structure Concepts:: The structure of Structures
3658 * Structure Layout:: Defining the layout of structure types
3659 * Structure Basics:: make-, -ref and -set! procedures for structs
3660 * Vtables:: Accessing type-specific data
3663 @node Structure Concepts
3664 @subsection Structure Concepts
3666 A structure object consists of a handle, structure data, and a vtable.
3667 The handle is a Scheme value which points to both the vtable and the
3668 structure's data. Structure data is a dynamically allocated region of
3669 memory, private to the structure, divided up into typed fields. A
3670 vtable is another structure used to hold type-specific data. Multiple
3671 structures can share a common vtable.
3673 Three concepts are key to understanding structures.
3676 @item @dfn{layout specifications}
3678 Layout specifications determine how memory allocated to structures is
3679 divided up into fields. Programmers must write a layout specification
3680 whenever a new type of structure is defined.
3682 @item @dfn{structural accessors}
3684 Structure access is by field number. There is only one set of
3685 accessors common to all structure objects.
3689 Vtables, themselves structures, are first class representations of
3690 disjoint sub-types of structures in general. In most cases, when a
3691 new structure is created, programmers must specifiy a vtable for the
3692 new structure. Each vtable has a field describing the layout of its
3693 instances. Vtables can have additional, user-defined fields as well.
3698 @node Structure Layout
3699 @subsection Structure Layout
3701 When a structure is created, a region of memory is allocated to hold its
3702 state. The @dfn{layout} of the structure's type determines how that
3703 memory is divided into fields.
3705 Each field has a specified type. There are only three types allowed, each
3706 corresponding to a one letter code. The allowed types are:
3709 @item 'u' -- unprotected
3711 The field holds binary data that is not GC protected.
3713 @item 'p' -- protected
3715 The field holds a Scheme value and is GC protected.
3719 The field holds a Scheme value and is GC protected. When a structure is
3720 created with this type of field, the field is initialized to refer to
3721 the structure's own handle. This kind of field is mainly useful when
3722 mixing Scheme and C code in which the C code may need to compute a
3723 structure's handle given only the address of its malloced data.
3727 Each field also has an associated access protection. There are only
3728 three kinds of protection, each corresponding to a one letter code.
3729 The allowed protections are:
3732 @item 'w' -- writable
3734 The field can be read and written.
3736 @item 'r' -- readable
3738 The field can be read, but not written.
3742 The field can be neither read nor written. This kind
3743 of protection is for fields useful only to built-in routines.
3746 A layout specification is described by stringing together pairs
3747 of letters: one to specify a field type and one to specify a field
3748 protection. For example, a traditional cons pair type object could
3752 ; cons pairs have two writable fields of Scheme data
3756 A pair object in which the first field is held constant could be:
3762 Binary fields, (fields of type "u"), hold one @dfn{word} each. The
3763 size of a word is a machine dependent value defined to be equal to the
3764 value of the C expression: @code{sizeof (long)}.
3766 The last field of a structure layout may specify a tail array.
3767 A tail array is indicated by capitalizing the field's protection
3768 code ('W', 'R' or 'O'). A tail-array field is replaced by
3769 a read-only binary data field containing an array size. The array
3770 size is determined at the time the structure is created. It is followed
3771 by a corresponding number of fields of the type specified for the
3772 tail array. For example, a conventional Scheme vector can be
3776 ; A vector is an arbitrary number of writable fields holding Scheme
3781 In the above example, field 0 contains the size of the vector and
3782 fields beginning at 1 contain the vector elements.
3784 A kind of tagged vector (a constant tag followed by conventioal
3785 vector elements) might be:
3792 Structure layouts are represented by specially interned symbols whose
3793 name is a string of type and protection codes. To create a new
3794 structure layout, use this procedure:
3796 @deffn {Scheme Procedure} make-struct-layout fields
3797 @deffnx {C Function} scm_make_struct_layout (fields)
3798 Return a new structure layout object.
3800 @var{fields} must be a string made up of pairs of characters
3801 strung together. The first character of each pair describes a field
3802 type, the second a field protection. Allowed types are 'p' for
3803 GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
3804 a field that points to the structure itself. Allowed protections
3805 are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
3806 fields. The last field protection specification may be capitalized to
3807 indicate that the field is a tail-array.
3812 @node Structure Basics
3813 @subsection Structure Basics
3815 This section describes the basic procedures for creating and accessing
3818 @deffn {Scheme Procedure} make-struct vtable tail_array_size . init
3819 @deffnx {C Function} scm_make_struct (vtable, tail_array_size, init)
3820 Create a new structure.
3822 @var{type} must be a vtable structure (@pxref{Vtables}).
3824 @var{tail-elts} must be a non-negative integer. If the layout
3825 specification indicated by @var{type} includes a tail-array,
3826 this is the number of elements allocated to that array.
3828 The @var{init1}, @dots{} are optional arguments describing how
3829 successive fields of the structure should be initialized. Only fields
3830 with protection 'r' or 'w' can be initialized, except for fields of
3831 type 's', which are automatically initialized to point to the new
3832 structure itself; fields with protection 'o' can not be initialized by
3835 If fewer optional arguments than initializable fields are supplied,
3836 fields of type 'p' get default value #f while fields of type 'u' are
3839 Structs are currently the basic representation for record-like data
3840 structures in Guile. The plan is to eventually replace them with a
3841 new representation which will at the same time be easier to use and
3844 For more information, see the documentation for @code{make-vtable-vtable}.
3847 @deffn {Scheme Procedure} struct? x
3848 @deffnx {C Function} scm_struct_p (x)
3849 Return @code{#t} iff @var{x} is a structure object, else
3854 @deffn {Scheme Procedure} struct-ref handle pos
3855 @deffnx {Scheme Procedure} struct-set! struct n value
3856 @deffnx {C Function} scm_struct_ref (handle, pos)
3857 @deffnx {C Function} scm_struct_set_x (struct, n, value)
3858 Access (or modify) the @var{n}th field of @var{struct}.
3860 If the field is of type 'p', then it can be set to an arbitrary value.
3862 If the field is of type 'u', then it can only be set to a non-negative
3863 integer value small enough to fit in one machine word.
3871 Vtables are structures that are used to represent structure types. Each
3872 vtable contains a layout specification in field
3873 @code{vtable-index-layout} -- instances of the type are laid out
3874 according to that specification. Vtables contain additional fields
3875 which are used only internally to libguile. The variable
3876 @code{vtable-offset-user} is bound to a field number. Vtable fields
3877 at that position or greater are user definable.
3879 @deffn {Scheme Procedure} struct-vtable handle
3880 @deffnx {C Function} scm_struct_vtable (handle)
3881 Return the vtable structure that describes the type of @var{struct}.
3884 @deffn {Scheme Procedure} struct-vtable? x
3885 @deffnx {C Function} scm_struct_vtable_p (x)
3886 Return @code{#t} iff @var{x} is a vtable structure.
3889 If you have a vtable structure, @code{V}, you can create an instance of
3890 the type it describes by using @code{(make-struct V ...)}. But where
3891 does @code{V} itself come from? One possibility is that @code{V} is an
3892 instance of a user-defined vtable type, @code{V'}, so that @code{V} is
3893 created by using @code{(make-struct V' ...)}. Another possibility is
3894 that @code{V} is an instance of the type it itself describes. Vtable
3895 structures of the second sort are created by this procedure:
3897 @deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init
3898 @deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init)
3899 Return a new, self-describing vtable structure.
3901 @var{user-fields} is a string describing user defined fields of the
3902 vtable beginning at index @code{vtable-offset-user}
3903 (see @code{make-struct-layout}).
3905 @var{tail-size} specifies the size of the tail-array (if any) of
3908 @var{init1}, @dots{} are the optional initializers for the fields of
3911 Vtables have one initializable system field---the struct printer.
3912 This field comes before the user fields in the initializers passed
3913 to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
3914 a third optional argument to @code{make-vtable-vtable} and a fourth to
3915 @code{make-struct} when creating vtables:
3917 If the value is a procedure, it will be called instead of the standard
3918 printer whenever a struct described by this vtable is printed.
3919 The procedure will be called with arguments STRUCT and PORT.
3921 The structure of a struct is described by a vtable, so the vtable is
3922 in essence the type of the struct. The vtable is itself a struct with
3923 a vtable. This could go on forever if it weren't for the
3924 vtable-vtables which are self-describing vtables, and thus terminate
3927 There are several potential ways of using structs, but the standard
3928 one is to use three kinds of structs, together building up a type
3929 sub-system: one vtable-vtable working as the root and one or several
3930 "types", each with a set of "instances". (The vtable-vtable should be
3931 compared to the class <class> which is the class of itself.)
3934 (define ball-root (make-vtable-vtable "pr" 0))
3936 (define (make-ball-type ball-color)
3937 (make-struct ball-root 0
3938 (make-struct-layout "pw")
3940 (format port "#<a ~A ball owned by ~A>"
3944 (define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
3945 (define (owner ball) (struct-ref ball 0))
3947 (define red (make-ball-type 'red))
3948 (define green (make-ball-type 'green))
3950 (define (make-ball type owner) (make-struct type 0 owner))
3952 (define ball (make-ball green 'Nisse))
3953 ball @result{} #<a green ball owned by Nisse>
3957 @deffn {Scheme Procedure} struct-vtable-name vtable
3958 @deffnx {C Function} scm_struct_vtable_name (vtable)
3959 Return the name of the vtable @var{vtable}.
3962 @deffn {Scheme Procedure} set-struct-vtable-name! vtable name
3963 @deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
3964 Set the name of the vtable @var{vtable} to @var{name}.
3967 @deffn {Scheme Procedure} struct-vtable-tag handle
3968 @deffnx {C Function} scm_struct_vtable_tag (handle)
3969 Return the vtable tag of the structure @var{handle}.
3978 * Conventional Arrays:: Arrays with arbitrary data.
3979 * Array Mapping:: Applying a procedure to the contents of an array.
3980 * Uniform Arrays:: Arrays with data of a single type.
3981 * Bit Vectors:: Vectors of bits.
3984 @node Conventional Arrays
3985 @subsection Conventional Arrays
3987 @dfn{Conventional arrays} are a collection of cells organized into an
3988 arbitrary number of dimensions. Each cell can hold any kind of Scheme
3989 value and can be accessed in constant time by supplying an index for
3990 each dimension. This contrasts with uniform arrays, which use memory
3991 more efficiently but can hold data of only a single type, and lists
3992 where inserting and deleting cells is more efficient, but more time
3993 is usually required to access a particular cell.
3995 A conventional array is displayed as @code{#} followed by the @dfn{rank}
3996 (number of dimensions) followed by the cells, organized into dimensions
3997 using parentheses. The nesting depth of the parentheses is equal to
4000 When an array is created, the number of dimensions and range of each
4001 dimension must be specified, e.g., to create a 2x3 array with a
4005 (make-array 'ho 2 3) @result{}
4006 #2((ho ho ho) (ho ho ho))
4009 The range of each dimension can also be given explicitly, e.g., another
4010 way to create the same array:
4013 (make-array 'ho '(0 1) '(0 2)) @result{}
4014 #2((ho ho ho) (ho ho ho))
4017 A conventional array with one dimension based at zero is identical to
4021 (make-array 'ho 3) @result{}
4025 The following procedures can be used with conventional arrays (or vectors).
4027 @deffn {Scheme Procedure} array? v [prot]
4028 @deffnx {C Function} scm_array_p (v, prot)
4029 Return @code{#t} if the @var{obj} is an array, and @code{#f} if
4030 not. The @var{prototype} argument is used with uniform arrays
4031 and is described elsewhere.
4034 @deffn {Scheme Procedure} make-array initial-value bound1 bound2 @dots{}
4035 Create and return an array that has as many dimensions as there are
4036 @var{bound}s and fill it with @var{initial-value}. Each @var{bound}
4037 may be a positive non-zero integer @var{N}, in which case the index for
4038 that dimension can range from 0 through @var{N-1}; or an explicit index
4039 range specifier in the form @code{(LOWER UPPER)}, where both @var{lower}
4040 and @var{upper} are integers, possibly less than zero, and possibly the
4041 same number (however, @var{lower} cannot be greater than @var{upper}).
4044 @c array-ref's type is `compiled-closure'. There's some weird stuff
4045 @c going on in array.c, too. Let's call it a primitive. -twp
4047 @deffn {Scheme Procedure} uniform-vector-ref v args
4048 @deffnx {Scheme Procedure} array-ref v . args
4049 @deffnx {C Function} scm_uniform_vector_ref (v, args)
4050 Return the element at the @code{(index1, index2)} element in
4054 @deffn {Scheme Procedure} array-in-bounds? v . args
4055 @deffnx {C Function} scm_array_in_bounds_p (v, args)
4056 Return @code{#t} if its arguments would be acceptable to
4060 @c fixme: why do these sigs differ? -ttn 2001/07/19 01:14:12
4061 @deffn {Scheme Procedure} array-set! v obj . args
4062 @deffnx {Scheme Procedure} uniform-array-set1! v obj args
4063 @deffnx {C Function} scm_array_set_x (v, obj, args)
4064 Set the element at the @code{(index1, index2)} element in @var{array} to
4065 @var{new-value}. The value returned by array-set! is unspecified.
4068 @deffn {Scheme Procedure} make-shared-array oldra mapfunc . dims
4069 @deffnx {C Function} scm_make_shared_array (oldra, mapfunc, dims)
4070 @code{make-shared-array} can be used to create shared subarrays of other
4071 arrays. The @var{mapper} is a function that translates coordinates in
4072 the new array into coordinates in the old array. A @var{mapper} must be
4073 linear, and its range must stay within the bounds of the old array, but
4074 it can be otherwise arbitrary. A simple example:
4076 (define fred (make-array #f 8 8))
4077 (define freds-diagonal
4078 (make-shared-array fred (lambda (i) (list i i)) 8))
4079 (array-set! freds-diagonal 'foo 3)
4080 (array-ref fred 3 3) @result{} foo
4081 (define freds-center
4082 (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
4083 (array-ref freds-center 0 0) @result{} foo
4087 @deffn {Scheme Procedure} shared-array-increments ra
4088 @deffnx {C Function} scm_shared_array_increments (ra)
4089 For each dimension, return the distance between elements in the root vector.
4092 @deffn {Scheme Procedure} shared-array-offset ra
4093 @deffnx {C Function} scm_shared_array_offset (ra)
4094 Return the root vector index of the first element in the array.
4097 @deffn {Scheme Procedure} shared-array-root ra
4098 @deffnx {C Function} scm_shared_array_root (ra)
4099 Return the root vector of a shared array.
4102 @deffn {Scheme Procedure} transpose-array ra . args
4103 @deffnx {C Function} scm_transpose_array (ra, args)
4104 Return an array sharing contents with @var{array}, but with
4105 dimensions arranged in a different order. There must be one
4106 @var{dim} argument for each dimension of @var{array}.
4107 @var{dim0}, @var{dim1}, @dots{} should be integers between 0
4108 and the rank of the array to be returned. Each integer in that
4109 range must appear at least once in the argument list.
4111 The values of @var{dim0}, @var{dim1}, @dots{} correspond to
4112 dimensions in the array to be returned, their positions in the
4113 argument list to dimensions of @var{array}. Several @var{dim}s
4114 may have the same value, in which case the returned array will
4115 have smaller rank than @var{array}.
4118 (transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
4119 (transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
4120 (transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
4121 #2((a 4) (b 5) (c 6))
4125 @deffn {Scheme Procedure} enclose-array ra . axes
4126 @deffnx {C Function} scm_enclose_array (ra, axes)
4127 @var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
4128 the rank of @var{array}. @var{enclose-array} returns an array
4129 resembling an array of shared arrays. The dimensions of each shared
4130 array are the same as the @var{dim}th dimensions of the original array,
4131 the dimensions of the outer array are the same as those of the original
4132 array that did not match a @var{dim}.
4134 An enclosed array is not a general Scheme array. Its elements may not
4135 be set using @code{array-set!}. Two references to the same element of
4136 an enclosed array will be @code{equal?} but will not in general be
4137 @code{eq?}. The value returned by @var{array-prototype} when given an
4138 enclosed array is unspecified.
4142 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
4143 #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
4145 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
4146 #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
4150 @deffn {Scheme Procedure} array-shape array
4151 Return a list of inclusive bounds of integers.
4153 (array-shape (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) (0 4))
4157 @deffn {Scheme Procedure} array-dimensions ra
4158 @deffnx {C Function} scm_array_dimensions (ra)
4159 @code{Array-dimensions} is similar to @code{array-shape} but replaces
4160 elements with a @code{0} minimum with one greater than the maximum. So:
4162 (array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
4166 @deffn {Scheme Procedure} array-rank ra
4167 @deffnx {C Function} scm_array_rank (ra)
4168 Return the number of dimensions of @var{obj}. If @var{obj} is
4169 not an array, @code{0} is returned.
4172 @deffn {Scheme Procedure} array->list v
4173 @deffnx {C Function} scm_t_arrayo_list (v)
4174 Return a list consisting of all the elements, in order, of
4178 @deffn {Scheme Procedure} array-copy! src dst
4179 @deffnx {Scheme Procedure} array-copy-in-order! src dst
4180 @deffnx {C Function} scm_array_copy_x (src, dst)
4181 Copy every element from vector or array @var{source} to the
4182 corresponding element of @var{destination}. @var{destination} must have
4183 the same rank as @var{source}, and be at least as large in each
4184 dimension. The order is unspecified.
4187 @deffn {Scheme Procedure} array-fill! ra fill
4188 @deffnx {C Function} scm_array_fill_x (ra, fill)
4189 Store @var{fill} in every element of @var{array}. The value returned
4193 @c begin (texi-doc-string "guile" "array-equal?")
4194 @deffn {Scheme Procedure} array-equal? ra0 ra1
4195 Return @code{#t} iff all arguments are arrays with the same shape, the
4196 same type, and have corresponding elements which are either
4197 @code{equal?} or @code{array-equal?}. This function differs from
4198 @code{equal?} in that a one dimensional shared array may be
4199 @var{array-equal?} but not @var{equal?} to a vector or uniform vector.
4202 @deffn {Scheme Procedure} array-contents array [strict]
4203 @deffnx {C Function} scm_array_contents (array, strict)
4204 If @var{array} may be @dfn{unrolled} into a one dimensional shared array
4205 without changing their order (last subscript changing fastest), then
4206 @code{array-contents} returns that shared array, otherwise it returns
4207 @code{#f}. All arrays made by @var{make-array} and
4208 @var{make-uniform-array} may be unrolled, some arrays made by
4209 @var{make-shared-array} may not be.
4211 If the optional argument @var{strict} is provided, a shared array will
4212 be returned only if its elements are stored internally contiguous in
4217 @subsection Array Mapping
4219 @deffn {Scheme Procedure} array-map! ra0 proc . lra
4220 @deffnx {Scheme Procedure} array-map-in-order! ra0 proc . lra
4221 @deffnx {C Function} scm_array_map_x (ra0, proc, lra)
4222 @var{array1}, @dots{} must have the same number of dimensions as
4223 @var{array0} and have a range for each index which includes the range
4224 for the corresponding index in @var{array0}. @var{proc} is applied to
4225 each tuple of elements of @var{array1} @dots{} and the result is stored
4226 as the corresponding element in @var{array0}. The value returned is
4227 unspecified. The order of application is unspecified.
4230 @deffn {Scheme Procedure} array-for-each proc ra0 . lra
4231 @deffnx {C Function} scm_array_for_each (proc, ra0, lra)
4232 Apply @var{proc} to each tuple of elements of @var{array0} @dots{}
4233 in row-major order. The value returned is unspecified.
4236 @deffn {Scheme Procedure} array-index-map! ra proc
4237 @deffnx {C Function} scm_array_index_map_x (ra, proc)
4238 Apply @var{proc} to the indices of each element of @var{array} in
4239 turn, storing the result in the corresponding element. The value
4240 returned and the order of application are unspecified.
4242 One can implement @var{array-indexes} as
4244 (define (array-indexes array)
4245 (let ((ra (apply make-array #f (array-shape array))))
4246 (array-index-map! ra (lambda x x))
4251 (define (apl:index-generator n)
4252 (let ((v (make-uniform-vector n 1)))
4253 (array-index-map! v (lambda (i) i))
4258 @node Uniform Arrays
4259 @subsection Uniform Arrays
4260 @tpindex Uniform Arrays
4263 @dfn{Uniform arrays} have elements all of the
4264 same type and occupy less storage than conventional
4265 arrays. Uniform arrays with a single zero-based dimension
4266 are also known as @dfn{uniform vectors}. The procedures in
4267 this section can also be used on conventional arrays, vectors,
4268 bit-vectors and strings.
4271 When creating a uniform array, the type of data to be stored
4272 is indicated with a @var{prototype} argument. The following table
4273 lists the types available and example prototypes:
4276 prototype type printing character
4278 #t boolean (bit-vector) b
4280 #\nul byte (integer) y
4281 's short (integer) h
4282 1 unsigned long (integer) u
4283 -1 signed long (integer) e
4284 'l signed long long (integer) l
4285 1.0 float (single precision) s
4286 1/3 double (double precision float) i
4287 0+i complex (double precision) c
4288 () conventional vector
4292 Unshared uniform arrays of characters with a single zero-based dimension
4293 are identical to strings:
4296 (make-uniform-array #\a 3) @result{}
4301 Unshared uniform arrays of booleans with a single zero-based dimension
4302 are identical to @ref{Bit Vectors, bit-vectors}.
4305 (make-uniform-array #t 3) @result{}
4310 Other uniform vectors are written in a form similar to that of vectors,
4311 except that a single character from the above table is put between
4312 @code{#} and @code{(}. For example, a uniform vector of signed
4313 long integers is displayed in the form @code{'#e(3 5 9)}.
4315 @deffn {Scheme Procedure} array? v [prot]
4316 Return @code{#t} if the @var{obj} is an array, and @code{#f} if not.
4318 The @var{prototype} argument is used with uniform arrays and is described
4322 @deffn {Scheme Procedure} make-uniform-array prototype bound1 bound2 @dots{}
4323 Create and return a uniform array of type corresponding to
4324 @var{prototype} that has as many dimensions as there are @var{bound}s
4325 and fill it with @var{prototype}.
4328 @deffn {Scheme Procedure} array-prototype ra
4329 @deffnx {C Function} scm_array_prototype (ra)
4330 Return an object that would produce an array of the same type
4331 as @var{array}, if used as the @var{prototype} for
4332 @code{make-uniform-array}.
4335 @deffn {Scheme Procedure} list->uniform-array ndim prot lst
4336 @deffnx {Scheme Procedure} list->uniform-vector prot lst
4337 @deffnx {C Function} scm_list_to_uniform_array (ndim, prot, lst)
4338 Return a uniform array of the type indicated by prototype
4339 @var{prot} with elements the same as those of @var{lst}.
4340 Elements must be of the appropriate type, no coercions are
4344 @deffn {Scheme Procedure} uniform-vector-fill! uve fill
4345 Store @var{fill} in every element of @var{uve}. The value returned is
4349 @deffn {Scheme Procedure} uniform-vector-length v
4350 @deffnx {C Function} scm_uniform_vector_length (v)
4351 Return the number of elements in @var{uve}.
4354 @deffn {Scheme Procedure} dimensions->uniform-array dims prot [fill]
4355 @deffnx {Scheme Procedure} make-uniform-vector length prototype [fill]
4356 @deffnx {C Function} scm_dimensions_to_uniform_array (dims, prot, fill)
4357 Create and return a uniform array or vector of type
4358 corresponding to @var{prototype} with dimensions @var{dims} or
4359 length @var{length}. If @var{fill} is supplied, it's used to
4360 fill the array, otherwise @var{prototype} is used.
4363 @c Another compiled-closure. -twp
4365 @deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]]
4366 @deffnx {Scheme Procedure} uniform-vector-read! uve [port-or-fdes] [start] [end]
4367 @deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end)
4368 Attempt to read all elements of @var{ura}, in lexicographic order, as
4369 binary objects from @var{port-or-fdes}.
4370 If an end of file is encountered,
4371 the objects up to that point are put into @var{ura}
4372 (starting at the beginning) and the remainder of the array is
4375 The optional arguments @var{start} and @var{end} allow
4376 a specified region of a vector (or linearized array) to be read,
4377 leaving the remainder of the vector unchanged.
4379 @code{uniform-array-read!} returns the number of objects read.
4380 @var{port-or-fdes} may be omitted, in which case it defaults to the value
4381 returned by @code{(current-input-port)}.
4384 @deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]]
4385 @deffnx {Scheme Procedure} uniform-vector-write uve [port-or-fdes] [start] [end]
4386 @deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end)
4387 Writes all elements of @var{ura} as binary objects to
4390 The optional arguments @var{start}
4392 a specified region of a vector (or linearized array) to be written.
4394 The number of objects actually written is returned.
4395 @var{port-or-fdes} may be
4396 omitted, in which case it defaults to the value returned by
4397 @code{(current-output-port)}.
4401 @subsection Bit Vectors
4404 Bit vectors are a specific type of uniform array: an array of booleans
4405 with a single zero-based index.
4408 They are displayed as a sequence of @code{0}s and
4409 @code{1}s prefixed by @code{#*}, e.g.,
4412 (make-uniform-vector 8 #t #f) @result{}
4415 #b(#t #f #t) @result{}
4419 @deffn {Scheme Procedure} bit-count b bitvector
4420 @deffnx {C Function} scm_bit_count (b, bitvector)
4421 Return the number of occurrences of the boolean @var{b} in
4425 @deffn {Scheme Procedure} bit-position item v k
4426 @deffnx {C Function} scm_bit_position (item, v, k)
4427 Return the minimum index of an occurrence of @var{bool} in
4428 @var{bv} which is at least @var{k}. If no @var{bool} occurs
4429 within the specified range @code{#f} is returned.
4432 @deffn {Scheme Procedure} bit-invert! v
4433 @deffnx {C Function} scm_bit_invert_x (v)
4434 Modify @var{bv} by replacing each element with its negation.
4437 @deffn {Scheme Procedure} bit-set*! v kv obj
4438 @deffnx {C Function} scm_bit_set_star_x (v, kv, obj)
4439 If uve is a bit-vector @var{bv} and uve must be of the same
4440 length. If @var{bool} is @code{#t}, uve is OR'ed into
4441 @var{bv}; If @var{bool} is @code{#f}, the inversion of uve is
4442 AND'ed into @var{bv}.
4444 If uve is a unsigned long integer vector all the elements of uve
4445 must be between 0 and the @code{length} of @var{bv}. The bits
4446 of @var{bv} corresponding to the indexes in uve are set to
4447 @var{bool}. The return value is unspecified.
4450 @deffn {Scheme Procedure} bit-count* v kv obj
4451 @deffnx {C Function} scm_bit_count_star (v, kv, obj)
4454 (bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
4456 @var{bv} is not modified.
4460 @node Association Lists and Hash Tables
4461 @section Association Lists and Hash Tables
4463 This chapter discusses dictionary objects: data structures that are
4464 useful for organizing and indexing large bodies of information.
4467 * Dictionary Types:: About dictionary types; what they're good for.
4468 * Association Lists:: List-based dictionaries.
4469 * Hash Tables:: Table-based dictionaries.
4472 @node Dictionary Types
4473 @subsection Dictionary Types
4475 A @dfn{dictionary} object is a data structure used to index
4476 information in a user-defined way. In standard Scheme, the main
4477 aggregate data types are lists and vectors. Lists are not really
4478 indexed at all, and vectors are indexed only by number
4479 (e.g. @code{(vector-ref foo 5)}). Often you will find it useful
4480 to index your data on some other type; for example, in a library
4481 catalog you might want to look up a book by the name of its
4482 author. Dictionaries are used to help you organize information in
4485 An @dfn{association list} (or @dfn{alist} for short) is a list of
4486 key-value pairs. Each pair represents a single quantity or
4487 object; the @code{car} of the pair is a key which is used to
4488 identify the object, and the @code{cdr} is the object's value.
4490 A @dfn{hash table} also permits you to index objects with
4491 arbitrary keys, but in a way that makes looking up any one object
4492 extremely fast. A well-designed hash system makes hash table
4493 lookups almost as fast as conventional array or vector references.
4495 Alists are popular among Lisp programmers because they use only
4496 the language's primitive operations (lists, @dfn{car}, @dfn{cdr}
4497 and the equality primitives). No changes to the language core are
4498 necessary. Therefore, with Scheme's built-in list manipulation
4499 facilities, it is very convenient to handle data stored in an
4500 association list. Also, alists are highly portable and can be
4501 easily implemented on even the most minimal Lisp systems.
4503 However, alists are inefficient, especially for storing large
4504 quantities of data. Because we want Guile to be useful for large
4505 software systems as well as small ones, Guile provides a rich set
4506 of tools for using either association lists or hash tables.
4508 @node Association Lists
4509 @subsection Association Lists
4510 @tpindex Association Lists
4513 @cindex Association List
4517 An association list is a conventional data structure that is often used
4518 to implement simple key-value databases. It consists of a list of
4519 entries in which each entry is a pair. The @dfn{key} of each entry is
4520 the @code{car} of the pair and the @dfn{value} of each entry is the
4524 ASSOCIATION LIST ::= '( (KEY1 . VALUE1)
4532 Association lists are also known, for short, as @dfn{alists}.
4534 The structure of an association list is just one example of the infinite
4535 number of possible structures that can be built using pairs and lists.
4536 As such, the keys and values in an association list can be manipulated
4537 using the general list structure procedures @code{cons}, @code{car},
4538 @code{cdr}, @code{set-car!}, @code{set-cdr!} and so on. However,
4539 because association lists are so useful, Guile also provides specific
4540 procedures for manipulating them.
4543 * Alist Key Equality::
4544 * Adding or Setting Alist Entries::
4545 * Retrieving Alist Entries::
4546 * Removing Alist Entries::
4547 * Sloppy Alist Functions::
4551 @node Alist Key Equality
4552 @subsubsection Alist Key Equality
4554 All of Guile's dedicated association list procedures, apart from
4555 @code{acons}, come in three flavours, depending on the level of equality
4556 that is required to decide whether an existing key in the association
4557 list is the same as the key that the procedure call uses to identify the
4562 Procedures with @dfn{assq} in their name use @code{eq?} to determine key
4566 Procedures with @dfn{assv} in their name use @code{eqv?} to determine
4570 Procedures with @dfn{assoc} in their name use @code{equal?} to
4571 determine key equality.
4574 @code{acons} is an exception because it is used to build association
4575 lists which do not require their entries' keys to be unique.
4577 @node Adding or Setting Alist Entries
4578 @subsubsection Adding or Setting Alist Entries
4580 @code{acons} adds a new entry to an association list and returns the
4581 combined association list. The combined alist is formed by consing the
4582 new entry onto the head of the alist specified in the @code{acons}
4583 procedure call. So the specified alist is not modified, but its
4584 contents become shared with the tail of the combined alist that
4585 @code{acons} returns.
4587 In the most common usage of @code{acons}, a variable holding the
4588 original association list is updated with the combined alist:
4591 (set! address-list (acons name address address-list))
4594 In such cases, it doesn't matter that the old and new values of
4595 @code{address-list} share some of their contents, since the old value is
4596 usually no longer independently accessible.
4598 Note that @code{acons} adds the specified new entry regardless of
4599 whether the alist may already contain entries with keys that are, in
4600 some sense, the same as that of the new entry. Thus @code{acons} is
4601 ideal for building alists where there is no concept of key uniqueness.
4604 (set! task-list (acons 3 "pay gas bill" '()))
4607 ((3 . "pay gas bill"))
4609 (set! task-list (acons 3 "tidy bedroom" task-list))
4612 ((3 . "tidy bedroom") (3 . "pay gas bill"))
4615 @code{assq-set!}, @code{assv-set!} and @code{assoc-set!} are used to add
4616 or replace an entry in an association list where there @emph{is} a
4617 concept of key uniqueness. If the specified association list already
4618 contains an entry whose key is the same as that specified in the
4619 procedure call, the existing entry is replaced by the new one.
4620 Otherwise, the new entry is consed onto the head of the old association
4621 list to create the combined alist. In all cases, these procedures
4622 return the combined alist.
4624 @code{assq-set!} and friends @emph{may} destructively modify the
4625 structure of the old association list in such a way that an existing
4626 variable is correctly updated without having to @code{set!} it to the
4632 (("mary" . "34 Elm Road") ("james" . "16 Bow Street"))
4634 (assoc-set! address-list "james" "1a London Road")
4636 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
4640 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
4646 (assoc-set! address-list "bob" "11 Newington Avenue")
4648 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
4649 ("james" . "1a London Road"))
4653 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
4656 The only safe way to update an association list variable when adding or
4657 replacing an entry like this is to @code{set!} the variable to the
4662 (assoc-set! address-list "bob" "11 Newington Avenue"))
4665 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
4666 ("james" . "1a London Road"))
4669 Because of this slight inconvenience, you may find it more convenient to
4670 use hash tables to store dictionary data. If your application will not
4671 be modifying the contents of an alist very often, this may not make much
4674 If you need to keep the old value of an association list in a form
4675 independent from the list that results from modification by
4676 @code{acons}, @code{assq-set!}, @code{assv-set!} or @code{assoc-set!},
4677 use @code{list-copy} to copy the old association list before modifying
4680 @deffn {Scheme Procedure} acons key value alist
4681 @deffnx {C Function} scm_acons (key, value, alist)
4682 Add a new key-value pair to @var{alist}. A new pair is
4683 created whose car is @var{key} and whose cdr is @var{value}, and the
4684 pair is consed onto @var{alist}, and the new list is returned. This
4685 function is @emph{not} destructive; @var{alist} is not modified.
4688 @deffn {Scheme Procedure} assq-set! alist key val
4689 @deffnx {Scheme Procedure} assv-set! alist key value
4690 @deffnx {Scheme Procedure} assoc-set! alist key value
4691 @deffnx {C Function} scm_assq_set_x (alist, key, val)
4692 @deffnx {C Function} scm_assv_set_x (alist, key, val)
4693 @deffnx {C Function} scm_assoc_set_x (alist, key, val)
4694 Reassociate @var{key} in @var{alist} with @var{value}: find any existing
4695 @var{alist} entry for @var{key} and associate it with the new
4696 @var{value}. If @var{alist} does not contain an entry for @var{key},
4697 add a new one. Return the (possibly new) alist.
4699 These functions do not attempt to verify the structure of @var{alist},
4700 and so may cause unusual results if passed an object that is not an
4704 @node Retrieving Alist Entries
4705 @subsubsection Retrieving Alist Entries
4710 @code{assq}, @code{assv} and @code{assoc} take an alist and a key as
4711 arguments and return the entry for that key if an entry exists, or
4712 @code{#f} if there is no entry for that key. Note that, in the cases
4713 where an entry exists, these procedures return the complete entry, that
4714 is @code{(KEY . VALUE)}, not just the value.
4716 @deffn {Scheme Procedure} assq key alist
4717 @deffnx {Scheme Procedure} assv key alist
4718 @deffnx {Scheme Procedure} assoc key alist
4719 @deffnx {C Function} scm_assq (key, alist)
4720 @deffnx {C Function} scm_assv (key, alist)
4721 @deffnx {C Function} scm_assoc (key, alist)
4722 Fetch the entry in @var{alist} that is associated with @var{key}. To
4723 decide whether the argument @var{key} matches a particular entry in
4724 @var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
4725 uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
4726 cannot be found in @var{alist} (according to whichever equality
4727 predicate is in use), then return @code{#f}. These functions
4728 return the entire alist entry found (i.e. both the key and the value).
4731 @code{assq-ref}, @code{assv-ref} and @code{assoc-ref}, on the other
4732 hand, take an alist and a key and return @emph{just the value} for that
4733 key, if an entry exists. If there is no entry for the specified key,
4734 these procedures return @code{#f}.
4736 This creates an ambiguity: if the return value is @code{#f}, it means
4737 either that there is no entry with the specified key, or that there
4738 @emph{is} an entry for the specified key, with value @code{#f}.
4739 Consequently, @code{assq-ref} and friends should only be used where it
4740 is known that an entry exists, or where the ambiguity doesn't matter
4741 for some other reason.
4743 @deffn {Scheme Procedure} assq-ref alist key
4744 @deffnx {Scheme Procedure} assv-ref alist key
4745 @deffnx {Scheme Procedure} assoc-ref alist key
4746 @deffnx {C Function} scm_assq_ref (alist, key)
4747 @deffnx {C Function} scm_assv_ref (alist, key)
4748 @deffnx {C Function} scm_assoc_ref (alist, key)
4749 Like @code{assq}, @code{assv} and @code{assoc}, except that only the
4750 value associated with @var{key} in @var{alist} is returned. These
4751 functions are equivalent to
4754 (let ((ent (@var{associator} @var{key} @var{alist})))
4755 (and ent (cdr ent)))
4758 where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
4761 @node Removing Alist Entries
4762 @subsubsection Removing Alist Entries
4764 To remove the element from an association list whose key matches a
4765 specified key, use @code{assq-remove!}, @code{assv-remove!} or
4766 @code{assoc-remove!} (depending, as usual, on the level of equality
4767 required between the key that you specify and the keys in the
4770 As with @code{assq-set!} and friends, the specified alist may or may not
4771 be modified destructively, and the only safe way to update a variable
4772 containing the alist is to @code{set!} it to the value that
4773 @code{assq-remove!} and friends return.
4778 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
4779 ("james" . "1a London Road"))
4781 (set! address-list (assoc-remove! address-list "mary"))
4784 (("bob" . "11 Newington Avenue") ("james" . "1a London Road"))
4787 Note that, when @code{assq/v/oc-remove!} is used to modify an
4788 association list that has been constructed only using the corresponding
4789 @code{assq/v/oc-set!}, there can be at most one matching entry in the
4790 alist, so the question of multiple entries being removed in one go does
4791 not arise. If @code{assq/v/oc-remove!} is applied to an association
4792 list that has been constructed using @code{acons}, or an
4793 @code{assq/v/oc-set!} with a different level of equality, or any mixture
4794 of these, it removes only the first matching entry from the alist, even
4795 if the alist might contain further matching entries. For example:
4798 (define address-list '())
4799 (set! address-list (assq-set! address-list "mary" "11 Elm Street"))
4800 (set! address-list (assq-set! address-list "mary" "57 Pine Drive"))
4803 (("mary" . "57 Pine Drive") ("mary" . "11 Elm Street"))
4805 (set! address-list (assoc-remove! address-list "mary"))
4808 (("mary" . "11 Elm Street"))
4811 In this example, the two instances of the string "mary" are not the same
4812 when compared using @code{eq?}, so the two @code{assq-set!} calls add
4813 two distinct entries to @code{address-list}. When compared using
4814 @code{equal?}, both "mary"s in @code{address-list} are the same as the
4815 "mary" in the @code{assoc-remove!} call, but @code{assoc-remove!} stops
4816 after removing the first matching entry that it finds, and so one of the
4817 "mary" entries is left in place.
4819 @deffn {Scheme Procedure} assq-remove! alist key
4820 @deffnx {Scheme Procedure} assv-remove! alist key
4821 @deffnx {Scheme Procedure} assoc-remove! alist key
4822 @deffnx {C Function} scm_assq_remove_x (alist, key)
4823 @deffnx {C Function} scm_assv_remove_x (alist, key)
4824 @deffnx {C Function} scm_assoc_remove_x (alist, key)
4825 Delete the first entry in @var{alist} associated with @var{key}, and return
4826 the resulting alist.
4829 @node Sloppy Alist Functions
4830 @subsubsection Sloppy Alist Functions
4832 @code{sloppy-assq}, @code{sloppy-assv} and @code{sloppy-assoc} behave
4833 like the corresponding non-@code{sloppy-} procedures, except that they
4834 return @code{#f} when the specified association list is not well-formed,
4835 where the non-@code{sloppy-} versions would signal an error.
4837 Specifically, there are two conditions for which the non-@code{sloppy-}
4838 procedures signal an error, which the @code{sloppy-} procedures handle
4839 instead by returning @code{#f}. Firstly, if the specified alist as a
4840 whole is not a proper list:
4843 (assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
4845 ERROR: In procedure assoc in expression (assoc "mary" (quote #)):
4846 ERROR: Wrong type argument in position 2 (expecting NULLP): "open sesame"
4847 ABORT: (wrong-type-arg)
4849 (sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
4855 Secondly, if one of the entries in the specified alist is not a pair:
4858 (assoc 2 '((1 . 1) 2 (3 . 9)))
4860 ERROR: In procedure assoc in expression (assoc 2 (quote #)):
4861 ERROR: Wrong type argument in position 2 (expecting CONSP): 2
4862 ABORT: (wrong-type-arg)
4864 (sloppy-assoc 2 '((1 . 1) 2 (3 . 9)))
4869 Unless you are explicitly working with badly formed association lists,
4870 it is much safer to use the non-@code{sloppy-} procedures, because they
4871 help to highlight coding and data errors that the @code{sloppy-}
4872 versions would silently cover up.
4874 @deffn {Scheme Procedure} sloppy-assq key alist
4875 @deffnx {C Function} scm_sloppy_assq (key, alist)
4876 Behaves like @code{assq} but does not do any error checking.
4877 Recommended only for use in Guile internals.
4880 @deffn {Scheme Procedure} sloppy-assv key alist
4881 @deffnx {C Function} scm_sloppy_assv (key, alist)
4882 Behaves like @code{assv} but does not do any error checking.
4883 Recommended only for use in Guile internals.
4886 @deffn {Scheme Procedure} sloppy-assoc key alist
4887 @deffnx {C Function} scm_sloppy_assoc (key, alist)
4888 Behaves like @code{assoc} but does not do any error checking.
4889 Recommended only for use in Guile internals.
4893 @subsubsection Alist Example
4895 Here is a longer example of how alists may be used in practice.
4898 (define capitals '(("New York" . "Albany")
4899 ("Oregon" . "Salem")
4900 ("Florida" . "Miami")))
4902 ;; What's the capital of Oregon?
4903 (assoc "Oregon" capitals) @result{} ("Oregon" . "Salem")
4904 (assoc-ref capitals "Oregon") @result{} "Salem"
4906 ;; We left out South Dakota.
4908 (assoc-set! capitals "South Dakota" "Bismarck"))
4910 @result{} (("South Dakota" . "Bismarck")
4911 ("New York" . "Albany")
4912 ("Oregon" . "Salem")
4913 ("Florida" . "Miami"))
4915 ;; And we got Florida wrong.
4917 (assoc-set! capitals "Florida" "Tallahassee"))
4919 @result{} (("South Dakota" . "Bismarck")
4920 ("New York" . "Albany")
4921 ("Oregon" . "Salem")
4922 ("Florida" . "Tallahassee"))
4924 ;; After Oregon secedes, we can remove it.
4926 (assoc-remove! capitals "Oregon"))
4928 @result{} (("South Dakota" . "Bismarck")
4929 ("New York" . "Albany")
4930 ("Florida" . "Tallahassee"))
4934 @subsection Hash Tables
4935 @tpindex Hash Tables
4937 @c FIXME::martin: Review me!
4939 Hash tables are dictionaries which offer similar functionality as
4940 association lists: They provide a mapping from keys to values. The
4941 difference is that association lists need time linear in the size of
4942 elements when searching for entries, whereas hash tables can normally
4943 search in constant time. The drawback is that hash tables require a
4944 little bit more memory, and that you can not use the normal list
4945 procedures (@pxref{Lists}) for working with them.
4948 * Hash Table Examples:: Demonstration of hash table usage.
4949 * Hash Table Reference:: Hash table procedure descriptions.
4953 @node Hash Table Examples
4954 @subsubsection Hash Table Examples
4956 @c FIXME::martin: Review me!
4958 For demonstration purposes, this section gives a few usage examples of
4959 some hash table procedures, together with some explanation what they do.
4961 First we start by creating a new hash table with 31 slots, and
4962 populate it with two key/value pairs.
4965 (define h (make-hash-table 31))
4967 (hashq-create-handle! h 'foo "bar")
4971 (hashq-create-handle! h 'braz "zonk")
4975 (hashq-create-handle! h 'frob #f)
4980 You can get the value for a given key with the procedure
4981 @code{hashq-ref}, but the problem with this procedure is that you
4982 cannot reliably determine whether a key does exists in the table. The
4983 reason is that the procedure returns @code{#f} if the key is not in
4984 the table, but it will return the same value if the key is in the
4985 table and just happens to have the value @code{#f}, as you can see in
4986 the following examples.
4997 (hashq-ref h 'not-there)
5002 Better is to use the procedure @code{hashq-get-handle}, which makes a
5003 distinction between the two cases. Just like @code{assq}, this
5004 procedure returns a key/value-pair on success, and @code{#f} if the
5008 (hashq-get-handle h 'foo)
5012 (hashq-get-handle h 'not-there)
5017 There is no procedure for calculating the number of key/value-pairs in
5018 a hash table, but @code{hash-fold} can be used for doing exactly that.
5021 (hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
5026 @node Hash Table Reference
5027 @subsubsection Hash Table Reference
5029 Like the association list functions, the hash table functions come
5030 in several varieties: @code{hashq}, @code{hashv}, and @code{hash}.
5031 The @code{hashq} functions use @code{eq?} to determine whether two
5032 keys match. The @code{hashv} functions use @code{eqv?}, and the
5033 @code{hash} functions use @code{equal?}.
5035 In each of the functions that follow, the @var{table} argument
5036 must be a vector. The @var{key} and @var{value} arguments may be
5039 @deffn {Scheme Procedure} make-hash-table size
5040 Create a new hash table of @var{size} slots. Note that the number of
5041 slots does not limit the size of the table, it just tells how large
5042 the underlying vector will be. The @var{size} should be similar to
5043 the expected number of elements which will be added to the table, but
5044 they need not match. For good performance, it might be a good idea to
5045 use a prime number as the @var{size}.
5048 @deffn {Scheme Procedure} hashq-ref table key [dflt]
5049 @deffnx {C Function} scm_hashq_ref (table, key, dflt)
5050 Look up @var{key} in the hash table @var{table}, and return the
5051 value (if any) associated with it. If @var{key} is not found,
5052 return @var{default} (or @code{#f} if no @var{default} argument
5053 is supplied). Uses @code{eq?} for equality testing.
5056 @deffn {Scheme Procedure} hashv-ref table key [dflt]
5057 @deffnx {C Function} scm_hashv_ref (table, key, dflt)
5058 Look up @var{key} in the hash table @var{table}, and return the
5059 value (if any) associated with it. If @var{key} is not found,
5060 return @var{default} (or @code{#f} if no @var{default} argument
5061 is supplied). Uses @code{eqv?} for equality testing.
5064 @deffn {Scheme Procedure} hash-ref table key [dflt]
5065 @deffnx {C Function} scm_hash_ref (table, key, dflt)
5066 Look up @var{key} in the hash table @var{table}, and return the
5067 value (if any) associated with it. If @var{key} is not found,
5068 return @var{default} (or @code{#f} if no @var{default} argument
5069 is supplied). Uses @code{equal?} for equality testing.
5072 @deffn {Scheme Procedure} hashq-set! table key val
5073 @deffnx {C Function} scm_hashq_set_x (table, key, val)
5074 Find the entry in @var{table} associated with @var{key}, and
5075 store @var{value} there. Uses @code{eq?} for equality testing.
5078 @deffn {Scheme Procedure} hashv-set! table key val
5079 @deffnx {C Function} scm_hashv_set_x (table, key, val)
5080 Find the entry in @var{table} associated with @var{key}, and
5081 store @var{value} there. Uses @code{eqv?} for equality testing.
5084 @deffn {Scheme Procedure} hash-set! table key val
5085 @deffnx {C Function} scm_hash_set_x (table, key, val)
5086 Find the entry in @var{table} associated with @var{key}, and
5087 store @var{value} there. Uses @code{equal?} for equality
5091 @deffn {Scheme Procedure} hashq-remove! table key
5092 @deffnx {C Function} scm_hashq_remove_x (table, key)
5093 Remove @var{key} (and any value associated with it) from
5094 @var{table}. Uses @code{eq?} for equality tests.
5097 @deffn {Scheme Procedure} hashv-remove! table key
5098 @deffnx {C Function} scm_hashv_remove_x (table, key)
5099 Remove @var{key} (and any value associated with it) from
5100 @var{table}. Uses @code{eqv?} for equality tests.
5103 @deffn {Scheme Procedure} hash-remove! table key
5104 @deffnx {C Function} scm_hash_remove_x (table, key)
5105 Remove @var{key} (and any value associated with it) from
5106 @var{table}. Uses @code{equal?} for equality tests.
5109 The standard hash table functions may be too limited for some
5110 applications. For example, you may want a hash table to store
5111 strings in a case-insensitive manner, so that references to keys
5112 named ``foobar'', ``FOOBAR'' and ``FooBaR'' will all yield the
5113 same item. Guile provides you with @dfn{extended} hash tables
5114 that permit you to specify a hash function and associator function
5115 of your choosing. The functions described in the rest of this section
5116 can be used to implement such custom hash table structures.
5118 If you are unfamiliar with the inner workings of hash tables, then
5119 this facility will probably be a little too abstract for you to
5120 use comfortably. If you are interested in learning more, see an
5121 introductory textbook on data structures or algorithms for an
5122 explanation of how hash tables are implemented.
5124 @deffn {Scheme Procedure} hashq key size
5125 @deffnx {C Function} scm_hashq (key, size)
5126 Determine a hash value for @var{key} that is suitable for
5127 lookups in a hashtable of size @var{size}, where @code{eq?} is
5128 used as the equality predicate. The function returns an
5129 integer in the range 0 to @var{size} - 1. Note that
5130 @code{hashq} may use internal addresses. Thus two calls to
5131 hashq where the keys are @code{eq?} are not guaranteed to
5132 deliver the same value if the key object gets garbage collected
5133 in between. This can happen, for example with symbols:
5134 @code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two
5135 different values, since @code{foo} will be garbage collected.
5138 @deffn {Scheme Procedure} hashv key size
5139 @deffnx {C Function} scm_hashv (key, size)
5140 Determine a hash value for @var{key} that is suitable for
5141 lookups in a hashtable of size @var{size}, where @code{eqv?} is
5142 used as the equality predicate. The function returns an
5143 integer in the range 0 to @var{size} - 1. Note that
5144 @code{(hashv key)} may use internal addresses. Thus two calls
5145 to hashv where the keys are @code{eqv?} are not guaranteed to
5146 deliver the same value if the key object gets garbage collected
5147 in between. This can happen, for example with symbols:
5148 @code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two
5149 different values, since @code{foo} will be garbage collected.
5152 @deffn {Scheme Procedure} hash key size
5153 @deffnx {C Function} scm_hash (key, size)
5154 Determine a hash value for @var{key} that is suitable for
5155 lookups in a hashtable of size @var{size}, where @code{equal?}
5156 is used as the equality predicate. The function returns an
5157 integer in the range 0 to @var{size} - 1.
5160 @deffn {Scheme Procedure} hashx-ref hash assoc table key [dflt]
5161 @deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
5162 This behaves the same way as the corresponding @code{ref}
5163 function, but uses @var{hash} as a hash function and
5164 @var{assoc} to compare keys. @code{hash} must be a function
5165 that takes two arguments, a key to be hashed and a table size.
5166 @code{assoc} must be an associator function, like @code{assoc},
5167 @code{assq} or @code{assv}.
5169 By way of illustration, @code{hashq-ref table key} is
5170 equivalent to @code{hashx-ref hashq assq table key}.
5173 @deffn {Scheme Procedure} hashx-set! hash assoc table key val
5174 @deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
5175 This behaves the same way as the corresponding @code{set!}
5176 function, but uses @var{hash} as a hash function and
5177 @var{assoc} to compare keys. @code{hash} must be a function
5178 that takes two arguments, a key to be hashed and a table size.
5179 @code{assoc} must be an associator function, like @code{assoc},
5180 @code{assq} or @code{assv}.
5182 By way of illustration, @code{hashq-set! table key} is
5183 equivalent to @code{hashx-set! hashq assq table key}.
5186 @deffn {Scheme Procedure} hashq-get-handle table key
5187 @deffnx {C Function} scm_hashq_get_handle (table, key)
5188 This procedure returns the @code{(key . value)} pair from the
5189 hash table @var{table}. If @var{table} does not hold an
5190 associated value for @var{key}, @code{#f} is returned.
5191 Uses @code{eq?} for equality testing.
5194 @deffn {Scheme Procedure} hashv-get-handle table key
5195 @deffnx {C Function} scm_hashv_get_handle (table, key)
5196 This procedure returns the @code{(key . value)} pair from the
5197 hash table @var{table}. If @var{table} does not hold an
5198 associated value for @var{key}, @code{#f} is returned.
5199 Uses @code{eqv?} for equality testing.
5202 @deffn {Scheme Procedure} hash-get-handle table key
5203 @deffnx {C Function} scm_hash_get_handle (table, key)
5204 This procedure returns the @code{(key . value)} pair from the
5205 hash table @var{table}. If @var{table} does not hold an
5206 associated value for @var{key}, @code{#f} is returned.
5207 Uses @code{equal?} for equality testing.
5210 @deffn {Scheme Procedure} hashx-get-handle hash assoc table key
5211 @deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key)
5212 This behaves the same way as the corresponding
5213 @code{-get-handle} function, but uses @var{hash} as a hash
5214 function and @var{assoc} to compare keys. @code{hash} must be
5215 a function that takes two arguments, a key to be hashed and a
5216 table size. @code{assoc} must be an associator function, like
5217 @code{assoc}, @code{assq} or @code{assv}.
5220 @deffn {Scheme Procedure} hashq-create-handle! table key init
5221 @deffnx {C Function} scm_hashq_create_handle_x (table, key, init)
5222 This function looks up @var{key} in @var{table} and returns its handle.
5223 If @var{key} is not already present, a new handle is created which
5224 associates @var{key} with @var{init}.
5227 @deffn {Scheme Procedure} hashv-create-handle! table key init
5228 @deffnx {C Function} scm_hashv_create_handle_x (table, key, init)
5229 This function looks up @var{key} in @var{table} and returns its handle.
5230 If @var{key} is not already present, a new handle is created which
5231 associates @var{key} with @var{init}.
5234 @deffn {Scheme Procedure} hash-create-handle! table key init
5235 @deffnx {C Function} scm_hash_create_handle_x (table, key, init)
5236 This function looks up @var{key} in @var{table} and returns its handle.
5237 If @var{key} is not already present, a new handle is created which
5238 associates @var{key} with @var{init}.
5241 @deffn {Scheme Procedure} hashx-create-handle! hash assoc table key init
5242 @deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
5243 This behaves the same way as the corresponding
5244 @code{-create-handle} function, but uses @var{hash} as a hash
5245 function and @var{assoc} to compare keys. @code{hash} must be
5246 a function that takes two arguments, a key to be hashed and a
5247 table size. @code{assoc} must be an associator function, like
5248 @code{assoc}, @code{assq} or @code{assv}.
5251 @deffn {Scheme Procedure} hash-fold proc init table
5252 @deffnx {C Function} scm_hash_fold (proc, init, table)
5253 An iterator over hash-table elements.
5254 Accumulates and returns a result by applying PROC successively.
5255 The arguments to PROC are "(key value prior-result)" where key
5256 and value are successive pairs from the hash table TABLE, and
5257 prior-result is either INIT (for the first application of PROC)
5258 or the return value of the previous application of PROC.
5259 For example, @code{(hash-fold acons '() tab)} will convert a hash
5260 table into an a-list of key-value pairs.
5268 @c FIXME::martin: Review me!
5270 A hook is basically a list of procedures to be called at well defined
5271 points in time. Hooks are used internally for several debugging
5272 facilities, but they can be used in user code, too.
5274 Hooks are created with @code{make-hook}, then procedures can be added to
5275 a hook with @code{add-hook!} or removed with @code{remove-hook!} or
5276 @code{reset-hook!}. The procedures stored in a hook can be invoked with
5280 * Hook Examples:: Hook usage by example.
5281 * Hook Reference:: Reference of all hook procedures.
5285 @subsection Hook Examples
5287 Hook usage is shown by some examples in this section. First, we will
5288 define a hook of arity 2 --- that is, the procedures stored in the hook
5289 will have to accept two arguments.
5292 (define hook (make-hook 2))
5294 @result{} #<hook 2 40286c90>
5297 Now we are ready to add some procedures to the newly created hook with
5298 @code{add-hook!}. In the following example, two procedures are added,
5299 which print different messages and do different things with their
5300 arguments. When the procedures have been added, we can invoke them
5301 using @code{run-hook}.
5304 (add-hook! hook (lambda (x y)
5308 (add-hook! hook (lambda (x y)
5317 Note that the procedures are called in reverse order than they were
5318 added. This can be changed by providing the optional third argument
5319 on the second call to @code{add-hook!}.
5322 (add-hook! hook (lambda (x y)
5326 (add-hook! hook (lambda (x y)
5330 #t) ; @r{<- Change here!}
5336 @node Hook Reference
5337 @subsection Hook Reference
5339 When a hook is created with @code{make-hook}, you can supply the arity
5340 of the procedures which can be added to the hook. The arity defaults to
5341 zero. All procedures of a hook must have the same arity, and when the
5342 procedures are invoked using @code{run-hook}, the number of arguments
5343 must match the arity of the procedures.
5345 The order in which procedures are added to a hook matters. If the third
5346 parameter to @var{add-hook!} is omitted or is equal to @code{#f}, the
5347 procedure is added in front of the procedures which might already be on
5348 that hook, otherwise the procedure is added at the end. The procedures
5349 are always called from first to last when they are invoked via
5352 When calling @code{hook->list}, the procedures in the resulting list are
5353 in the same order as they would have been called by @code{run-hook}.
5355 @deffn {Scheme Procedure} make-hook [n_args]
5356 @deffnx {C Function} scm_make_hook (n_args)
5357 Create a hook for storing procedure of arity @var{n_args}.
5358 @var{n_args} defaults to zero. The returned value is a hook
5359 object to be used with the other hook procedures.
5362 @deffn {Scheme Procedure} hook? x
5363 @deffnx {C Function} scm_hook_p (x)
5364 Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
5367 @deffn {Scheme Procedure} hook-empty? hook
5368 @deffnx {C Function} scm_hook_empty_p (hook)
5369 Return @code{#t} if @var{hook} is an empty hook, @code{#f}
5373 @deffn {Scheme Procedure} add-hook! hook proc [append_p]
5374 @deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
5375 Add the procedure @var{proc} to the hook @var{hook}. The
5376 procedure is added to the end if @var{append_p} is true,
5377 otherwise it is added to the front. The return value of this
5378 procedure is not specified.
5381 @deffn {Scheme Procedure} remove-hook! hook proc
5382 @deffnx {C Function} scm_remove_hook_x (hook, proc)
5383 Remove the procedure @var{proc} from the hook @var{hook}. The
5384 return value of this procedure is not specified.
5387 @deffn {Scheme Procedure} reset-hook! hook
5388 @deffnx {C Function} scm_reset_hook_x (hook)
5389 Remove all procedures from the hook @var{hook}. The return
5390 value of this procedure is not specified.
5393 @deffn {Scheme Procedure} run-hook hook . args
5394 @deffnx {C Function} scm_run_hook (hook, args)
5395 Apply all procedures from the hook @var{hook} to the arguments
5396 @var{args}. The order of the procedure application is first to
5397 last. The return value of this procedure is not specified.
5400 @deffn {Scheme Procedure} hook->list hook
5401 @deffnx {C Function} scm_hook_to_list (hook)
5402 Convert the procedure list of @var{hook} to a list.
5406 @node Other Data Types
5407 @section Other Core Guile Data Types
5410 @c TeX-master: "guile.texi"