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.
56 * Arrays:: Arrays of values.
57 * Association Lists and Hash Tables:: Dictionary data types.
58 * Vectors:: One-dimensional arrays of Scheme objects.
59 * Hooks:: User-customizable event lists.
60 * Other Data Types:: Data types that are documented elsewhere.
67 The two boolean values are @code{#t} for true and @code{#f} for false.
69 Boolean values are returned by predicate procedures, such as the general
70 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
71 (@pxref{Equality}) and numerical and string comparison operators like
72 @code{string=?} (REFFIXME) and @code{<=} (REFFIXME).
83 (equal? "house" "houses")
92 In test condition contexts like @code{if} (REFFIXME) and @code{cond}
93 (REFFIXME), where a group of subexpressions will be evaluated only if a
94 @var{condition} expression evaluates to ``true'', ``true'' means any
95 value at all except @code{#f}.
111 A result of this asymmetry is that typical Scheme source code more often
112 uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
113 represent an @code{if} or @code{cond} false value, whereas @code{#t} is
114 not necessary to represent an @code{if} or @code{cond} true value.
116 It is important to note that @code{#f} is @strong{not} equivalent to any
117 other Scheme value. In particular, @code{#f} is not the same as the
118 number 0 (like in C and C++), and not the same as the ``empty list''
119 (like in some Lisp dialects).
121 The @code{not} procedure returns the boolean inverse of its argument:
124 @deffn primitive not x
125 Return @code{#t} iff @var{x} is @code{#f}, else return @code{#f}.
128 The @code{boolean?} procedure is a predicate that returns @code{#t} if
129 its argument is one of the boolean values, otherwise @code{#f}.
132 @deffn primitive boolean? obj
133 Return @code{#t} iff @var{obj} is either @code{#t} or @code{#f}.
138 @section Numerical data types
140 Guile supports a rich ``tower'' of numerical types --- integer,
141 rational, real and complex --- and provides an extensive set of
142 mathematical and scientific functions for operating on numerical
143 data. This section of the manual documents those types and functions.
145 You may also find it illuminating to read R5RS's presentation of numbers
146 in Scheme, which is particularly clear and accessible: see
147 @xref{Numbers,,,r5rs}.
150 * Numerical Tower:: Scheme's numerical "tower".
151 * Integers:: Whole numbers.
152 * Reals and Rationals:: Real and rational numbers.
153 * Complex Numbers:: Complex numbers.
154 * Exactness:: Exactness and inexactness.
155 * Number Syntax:: Read syntax for numerical data.
156 * Integer Operations:: Operations on integer values.
157 * Comparison:: Comparison predicates.
158 * Conversion:: Converting numbers to and from strings.
159 * Complex:: Complex number operations.
160 * Arithmetic:: Arithmetic functions.
161 * Scientific:: Scientific functions.
162 * Primitive Numerics:: Primitive numeric functions.
163 * Bitwise Operations:: Logical AND, OR, NOT, and so on.
164 * Random:: Random number generation.
168 @node Numerical Tower
169 @subsection Scheme's Numerical ``Tower''
172 Scheme's numerical ``tower'' consists of the following categories of
177 integers (whole numbers)
180 rationals (the set of numbers that can be expressed as P/Q where P and Q
184 real numbers (the set of numbers that describes all possible positions
185 along a one dimensional line)
188 complex numbers (the set of numbers that describes all possible
189 positions in a two dimensional space)
192 It is called a tower because each category ``sits on'' the one that
193 follows it, in the sense that every integer is also a rational, every
194 rational is also real, and every real number is also a complex number
195 (but with zero imaginary part).
197 Of these, Guile implements integers, reals and complex numbers as
198 distinct types. Rationals are implemented as regards the read syntax
199 for rational numbers that is specified by R5RS, but are immediately
200 converted by Guile to the corresponding real number.
202 The @code{number?} predicate may be applied to any Scheme value to
203 discover whether the value is any of the supported numerical types.
205 @deffn primitive number? obj
206 Return @code{#t} if @var{obj} is any kind of number, @code{#f} else.
216 (number? "hello there!")
220 (define pi 3.141592654)
226 The next few subsections document each of Guile's numerical data types
234 Integers are whole numbers, that is numbers with no fractional part,
235 such as 2, 83 and -3789.
237 Integers in Guile can be arbitrarily big, as shown by the following
241 (define (factorial n)
242 (let loop ((n n) (product 1))
245 (loop (- n 1) (* product n)))))
257 -119622220865480194561963161495657715064383733760000000000
260 Readers whose background is in programming languages where integers are
261 limited by the need to fit into just 4 or 8 bytes of memory may find
262 this surprising, or suspect that Guile's representation of integers is
263 inefficient. In fact, Guile achieves a near optimal balance of
264 convenience and efficiency by using the host computer's native
265 representation of integers where possible, and a more general
266 representation where the required number does not fit in the native
267 form. Conversion between these two representations is automatic and
268 completely invisible to the Scheme level programmer.
270 @c REFFIXME Maybe point here to discussion of handling immediates/bignums
271 @c on the C level, where the conversion is not so automatic - NJ
273 @deffn primitive integer? x
274 Return @code{#t} if @var{x} is an integer number, @code{#f} else.
288 @node Reals and Rationals
289 @subsection Real and Rational Numbers
293 Mathematically, the real numbers are the set of numbers that describe
294 all possible points along a continuous, infinite, one-dimensional line.
295 The rational numbers are the set of all numbers that can be written as
296 fractions P/Q, where P and Q are integers. All rational numbers are
297 also real, but there are real numbers that are not rational, for example
298 the square root of 2, and pi.
300 Guile represents both real and rational numbers approximately using a
301 floating point encoding with limited precision. Even though the actual
302 encoding is in binary, it may be helpful to think of it as a decimal
303 number with a limited number of significant figures and a decimal point
304 somewhere, since this corresponds to the standard notation for non-whole
305 numbers. For example:
310 -5648394822220000000000.0
314 The limited precision of Guile's encoding means that any ``real'' number
315 in Guile can be written in a rational form, by multiplying and then dividing
316 by sufficient powers of 10 (or in fact, 2). For example,
317 @code{-0.00000142857931198} is the same as @code{142857931198} divided by
318 @code{100000000000000000}. In Guile's current incarnation, therefore,
319 the @code{rational?} and @code{real?} predicates are equivalent.
321 Another aspect of this equivalence is that Guile currently does not
322 preserve the exactness that is possible with rational arithmetic.
323 If such exactness is needed, it is of course possible to implement
324 exact rational arithmetic at the Scheme level using Guile's arbitrary
327 A planned future revision of Guile's numerical tower will make it
328 possible to implement exact representations and arithmetic for both
329 rational numbers and real irrational numbers such as square roots,
330 and in such a way that the new kinds of number integrate seamlessly
331 with those that are already implemented.
333 @deffn primitive real? obj
334 Return @code{#t} if @var{obj} is a real number, @code{#f} else.
335 Note that the sets of integer and rational values form subsets
336 of the set of real numbers, so the predicate will also be fulfilled
337 if @var{obj} is an integer number or a rational number.
340 @deffn primitive rational? x
341 Return @code{#t} if @var{x} is a rational number, @code{#f}
342 else. Note that the set of integer values forms a subset of
343 the set of rational numbers, i. e. the predicate will also be
344 fulfilled if @var{x} is an integer number. Real numbers
345 will also satisfy this predicate, because of their limited
350 @node Complex Numbers
351 @subsection Complex Numbers
354 Complex numbers are the set of numbers that describe all possible points
355 in a two-dimensional space. The two coordinates of a particular point
356 in this space are known as the @dfn{real} and @dfn{imaginary} parts of
357 the complex number that describes that point.
359 In Guile, complex numbers are written in rectangular form as the sum of
360 their real and imaginary parts, using the symbol @code{i} to indicate
373 Guile represents a complex number as a pair of numbers both of which are
374 real, so the real and imaginary parts of a complex number have the same
375 properties of inexactness and limited precision as single real numbers.
377 @deffn primitive complex? x
378 Return @code{#t} if @var{x} is a complex number, @code{#f}
379 else. Note that the sets of real, rational and integer
380 values form subsets of the set of complex numbers, i. e. the
381 predicate will also be fulfilled if @var{x} is a real,
382 rational or integer number.
387 @subsection Exact and Inexact Numbers
390 @rnindex exact->inexact
391 @rnindex inexact->exact
393 R5RS requires that a calculation involving inexact numbers always
394 produces an inexact result. To meet this requirement, Guile
395 distinguishes between an exact integer value such as @code{5} and the
396 corresponding inexact real value which, to the limited precision
397 available, has no fractional part, and is printed as @code{5.0}. Guile
398 will only convert the latter value to the former when forced to do so by
399 an invocation of the @code{inexact->exact} procedure.
401 @deffn primitive exact? x
402 Return @code{#t} if @var{x} is an exact number, @code{#f}
406 @deffn primitive inexact? x
407 Return @code{#t} if @var{x} is an inexact number, @code{#f}
411 @deffn primitive inexact->exact z
412 Return an exact number that is numerically closest to @var{z}.
415 @c begin (texi-doc-string "guile" "exact->inexact")
416 @deffn primitive exact->inexact z
417 Convert the number @var{z} to its inexact representation.
422 @subsection Read Syntax for Numerical Data
424 The read syntax for integers is a string of digits, optionally
425 preceded by a minus or plus character, a code indicating the
426 base in which the integer is encoded, and a code indicating whether
427 the number is exact or inexact. The supported base codes are:
431 @code{#b}, @code{#B} --- the integer is written in binary (base 2)
434 @code{#o}, @code{#O} --- the integer is written in octal (base 8)
437 @code{#d}, @code{#D} --- the integer is written in decimal (base 10)
440 @code{#x}, @code{#X} --- the integer is written in hexadecimal (base 16).
443 If the base code is omitted, the integer is assumed to be decimal. The
444 following examples show how these base codes are used.
468 The codes for indicating exactness (which can, incidentally, be applied
469 to all numerical values) are:
473 @code{#e}, @code{#E} --- the number is exact
476 @code{#i}, @code{#I} --- the number is inexact.
479 If the exactness indicator is omitted, the integer is assumed to be exact,
480 since Guile's internal representation for integers is always exact.
481 Real numbers have limited precision similar to the precision of the
482 @code{double} type in C. A consequence of the limited precision is that
483 all real numbers in Guile are also rational, since any number R with a
484 limited number of decimal places, say N, can be made into an integer by
488 @node Integer Operations
489 @subsection Operations on Integer Values
498 @deffn primitive odd? n
499 Return @code{#t} if @var{n} is an odd number, @code{#f}
503 @deffn primitive even? n
504 Return @code{#t} if @var{n} is an even number, @code{#f}
508 @c begin (texi-doc-string "guile" "quotient")
509 @deffn primitive quotient
510 Return the quotient of the numbers @var{x} and @var{y}.
513 @c begin (texi-doc-string "guile" "remainder")
514 @deffn primitive remainder
515 Return the remainder of the numbers @var{x} and @var{y}.
517 (remainder 13 4) @result{} 1
518 (remainder -13 4) @result{} -1
522 @c begin (texi-doc-string "guile" "modulo")
523 @deffn primitive modulo
524 Return the modulo of the numbers @var{x} and @var{y}.
526 (modulo 13 4) @result{} 1
527 (modulo -13 4) @result{} 3
531 @c begin (texi-doc-string "guile" "gcd")
533 Return the greatest common divisor of all arguments.
534 If called without arguments, 0 is returned.
537 @c begin (texi-doc-string "guile" "lcm")
539 Return the least common multiple of the arguments.
540 If called without arguments, 1 is returned.
545 @subsection Comparison Predicates
550 @c begin (texi-doc-string "guile" "=")
552 Return @code{#t} if all parameters are numerically equal.
555 @c begin (texi-doc-string "guile" "<")
557 Return @code{#t} if the list of parameters is monotonically
561 @c begin (texi-doc-string "guile" ">")
563 Return @code{#t} if the list of parameters is monotonically
567 @c begin (texi-doc-string "guile" "<=")
569 Return @code{#t} if the list of parameters is monotonically
573 @c begin (texi-doc-string "guile" ">=")
575 Return @code{#t} if the list of parameters is monotonically
579 @c begin (texi-doc-string "guile" "zero?")
580 @deffn primitive zero?
581 Return @code{#t} if @var{z} is an exact or inexact number equal to
585 @c begin (texi-doc-string "guile" "positive?")
586 @deffn primitive positive?
587 Return @code{#t} if @var{x} is an exact or inexact number greater than
591 @c begin (texi-doc-string "guile" "negative?")
592 @deffn primitive negative?
593 Return @code{#t} if @var{x} is an exact or inexact number less than
599 @subsection Converting Numbers To and From Strings
600 @rnindex number->string
601 @rnindex string->number
603 @deffn primitive number->string n [radix]
604 Return a string holding the external representation of the
605 number @var{n} in the given @var{radix}. If @var{n} is
606 inexact, a radix of 10 will be used.
609 @deffn primitive string->number string [radix]
610 Return a number of the maximally precise representation
611 expressed by the given @var{string}. @var{radix} must be an
612 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
613 is a default radix that may be overridden by an explicit radix
614 prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
615 supplied, then the default radix is 10. If string is not a
616 syntactically valid notation for a number, then
617 @code{string->number} returns @code{#f}.
622 @subsection Complex Number Operations
623 @rnindex make-rectangular
630 @deffn primitive make-rectangular real imaginary
631 Return a complex number constructed of the given @var{real} and
632 @var{imaginary} parts.
635 @deffn primitive make-polar x y
636 Return the complex number @var{x} * e^(i * @var{y}).
639 @c begin (texi-doc-string "guile" "real-part")
640 @deffn primitive real-part
641 Return the real part of the number @var{z}.
644 @c begin (texi-doc-string "guile" "imag-part")
645 @deffn primitive imag-part
646 Return the imaginary part of the number @var{z}.
649 @c begin (texi-doc-string "guile" "magnitude")
650 @deffn primitive magnitude
651 Return the magnitude of the number @var{z}. This is the same as
652 @code{abs} for real arguments, but also allows complex numbers.
655 @c begin (texi-doc-string "guile" "angle")
656 @deffn primitive angle
657 Return the angle of the complex number @var{z}.
662 @subsection Arithmetic Functions
675 @c begin (texi-doc-string "guile" "+")
676 @deffn primitive + z1 @dots{}
677 Return the sum of all parameter values. Return 0 if called without any
681 @c begin (texi-doc-string "guile" "-")
682 @deffn primitive - z1 z2 @dots{}
683 If called without arguments, 0 is returned. Otherwise the sum of all but
684 the first argument are subtracted from the first argument.
687 @c begin (texi-doc-string "guile" "*")
688 @deffn primitive * z1 @dots{}
689 Return the product of all arguments. If called without arguments, 1 is
693 @c begin (texi-doc-string "guile" "/")
694 @deffn primitive / z1 z2 @dots{}
695 Divide the first argument by the product of the remaining arguments.
698 @c begin (texi-doc-string "guile" "abs")
699 @deffn primitive abs x
700 Return the absolute value of @var{x}.
703 @c begin (texi-doc-string "guile" "max")
704 @deffn primitive max x1 x2 @dots{}
705 Return the maximum of all parameter values.
708 @c begin (texi-doc-string "guile" "min")
709 @deffn primitive min x1 x2 @dots{}
710 Return the minium of all parameter values.
713 @c begin (texi-doc-string "guile" "truncate")
714 @deffn primitive truncate
715 Round the inexact number @var{x} towards zero.
718 @c begin (texi-doc-string "guile" "round")
719 @deffn primitive round x
720 Round the inexact number @var{x} towards zero.
723 @c begin (texi-doc-string "guile" "floor")
724 @deffn primitive floor x
725 Round the number @var{x} towards minus infinity.
728 @c begin (texi-doc-string "guile" "ceiling")
729 @deffn primitive ceiling x
730 Round the number @var{x} towards infinity.
735 @subsection Scientific Functions
747 The following procedures accept any kind of number as arguments,
748 including complex numbers.
750 @c begin (texi-doc-string "guile" "sqrt")
751 @deffn procedure sqrt z
752 Return the square root of @var{z}.
755 @c begin (texi-doc-string "guile" "expt")
756 @deffn procedure expt z1 z2
757 Return @var{z1} raised to the power of @var{z2}.
760 @c begin (texi-doc-string "guile" "sin")
761 @deffn procedure sin z
762 Return the sine of @var{z}.
765 @c begin (texi-doc-string "guile" "cos")
766 @deffn procedure cos z
767 Return the cosine of @var{z}.
770 @c begin (texi-doc-string "guile" "tan")
771 @deffn procedure tan z
772 Return the tangent of @var{z}.
775 @c begin (texi-doc-string "guile" "asin")
776 @deffn procedure asin z
777 Return the arcsine of @var{z}.
780 @c begin (texi-doc-string "guile" "acos")
781 @deffn procedure acos z
782 Return the arccosine of @var{z}.
785 @c begin (texi-doc-string "guile" "atan")
786 @deffn procedure atan z
787 Return the arctangent of @var{z}.
790 @c begin (texi-doc-string "guile" "exp")
791 @deffn procedure exp z
792 Return e to the power of @var{z}, where e is the base of natural
793 logarithms (2.71828@dots{}).
796 @c begin (texi-doc-string "guile" "log")
797 @deffn procedure log z
798 Return the natural logarithm of @var{z}.
801 @c begin (texi-doc-string "guile" "log10")
802 @deffn procedure log10 z
803 Return the base 10 logarithm of @var{z}.
806 @c begin (texi-doc-string "guile" "sinh")
807 @deffn procedure sinh z
808 Return the hyperbolic sine of @var{z}.
811 @c begin (texi-doc-string "guile" "cosh")
812 @deffn procedure cosh z
813 Return the hyperbolic cosine of @var{z}.
816 @c begin (texi-doc-string "guile" "tanh")
817 @deffn procedure tanh z
818 Return the hyperbolic tangent of @var{z}.
821 @c begin (texi-doc-string "guile" "asinh")
822 @deffn procedure asinh z
823 Return the hyperbolic arcsine of @var{z}.
826 @c begin (texi-doc-string "guile" "acosh")
827 @deffn procedure acosh z
828 Return the hyperbolic arccosine of @var{z}.
831 @c begin (texi-doc-string "guile" "atanh")
832 @deffn procedure atanh z
833 Return the hyperbolic arctangent of @var{z}.
837 @node Primitive Numerics
838 @subsection Primitive Numeric Functions
840 Many of Guile's numeric procedures which accept any kind of numbers as
841 arguments, including complex numbers, are implemented as Scheme
842 procedures that use the following real number-based primitives. These
843 primitives signal an error if they are called with complex arguments.
845 @c begin (texi-doc-string "guile" "$abs")
846 @deffn primitive $abs x
847 Return the absolute value of @var{x}.
850 @c begin (texi-doc-string "guile" "$sqrt")
851 @deffn primitive $sqrt x
852 Return the square root of @var{x}.
855 @deffn primitive $expt x y
856 Return @var{x} raised to the power of @var{y}. This
857 procedure does not accept complex arguments.
860 @c begin (texi-doc-string "guile" "$sin")
861 @deffn primitive $sin x
862 Return the sine of @var{x}.
865 @c begin (texi-doc-string "guile" "$cos")
866 @deffn primitive $cos x
867 Return the cosine of @var{x}.
870 @c begin (texi-doc-string "guile" "$tan")
871 @deffn primitive $tan x
872 Return the tangent of @var{x}.
875 @c begin (texi-doc-string "guile" "$asin")
876 @deffn primitive $asin x
877 Return the arcsine of @var{x}.
880 @c begin (texi-doc-string "guile" "$acos")
881 @deffn primitive $acos x
882 Return the arccosine of @var{x}.
885 @c begin (texi-doc-string "guile" "$atan")
886 @deffn primitive $atan x
887 Return the arctangent of @var{x} in the range -PI/2 to PI/2.
890 @deffn primitive $atan2 x y
891 Return the arc tangent of the two arguments @var{x} and
892 @var{y}. This is similar to calculating the arc tangent of
893 @var{x} / @var{y}, except that the signs of both arguments
894 are used to determine the quadrant of the result. This
895 procedure does not accept complex arguments.
898 @c begin (texi-doc-string "guile" "$exp")
899 @deffn primitive $exp x
900 Return e to the power of @var{x}, where e is the base of natural
901 logarithms (2.71828@dots{}).
904 @c begin (texi-doc-string "guile" "$log")
905 @deffn primitive $log x
906 Return the natural logarithm of @var{x}.
909 @c begin (texi-doc-string "guile" "$sinh")
910 @deffn primitive $sinh x
911 Return the hyperbolic sine of @var{x}.
914 @c begin (texi-doc-string "guile" "$cosh")
915 @deffn primitive $cosh x
916 Return the hyperbolic cosine of @var{x}.
919 @c begin (texi-doc-string "guile" "$tanh")
920 @deffn primitive $tanh x
921 Return the hyperbolic tangent of @var{x}.
924 @c begin (texi-doc-string "guile" "$asinh")
925 @deffn primitive $asinh x
926 Return the hyperbolic arcsine of @var{x}.
929 @c begin (texi-doc-string "guile" "$acosh")
930 @deffn primitive $acosh x
931 Return the hyperbolic arccosine of @var{x}.
934 @c begin (texi-doc-string "guile" "$atanh")
935 @deffn primitive $atanh x
936 Return the hyperbolic arctangent of @var{x}.
940 @node Bitwise Operations
941 @subsection Bitwise Operations
943 @deffn primitive logand n1 n2
944 Return the integer which is the bit-wise AND of the two integer
947 (number->string (logand #b1100 #b1010) 2)
952 @deffn primitive logior n1 n2
953 Return the integer which is the bit-wise OR of the two integer
956 (number->string (logior #b1100 #b1010) 2)
961 @deffn primitive logxor n1 n2
962 Return the integer which is the bit-wise XOR of the two integer
965 (number->string (logxor #b1100 #b1010) 2)
970 @deffn primitive lognot n
971 Return the integer which is the 2s-complement of the integer
974 (number->string (lognot #b10000000) 2)
975 @result{} "-10000001"
976 (number->string (lognot #b0) 2)
981 @deffn primitive logtest j k
983 (logtest j k) @equiv{} (not (zero? (logand j k)))
985 (logtest #b0100 #b1011) @result{} #f
986 (logtest #b0100 #b0111) @result{} #t
990 @deffn primitive logbit? index j
992 (logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
994 (logbit? 0 #b1101) @result{} #t
995 (logbit? 1 #b1101) @result{} #f
996 (logbit? 2 #b1101) @result{} #t
997 (logbit? 3 #b1101) @result{} #t
998 (logbit? 4 #b1101) @result{} #f
1002 @deffn primitive ash n cnt
1003 The function ash performs an arithmetic shift left by @var{cnt}
1004 bits (or shift right, if @var{cnt} is negative). 'Arithmetic'
1005 means, that the function does not guarantee to keep the bit
1006 structure of @var{n}, but rather guarantees that the result
1007 will always be rounded towards minus infinity. Therefore, the
1008 results of ash and a corresponding bitwise shift will differ if
1009 @var{n} is negative.
1010 Formally, the function returns an integer equivalent to
1011 @code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
1013 (number->string (ash #b1 3) 2) @result{} "1000"
1014 (number->string (ash #b1010 -1) 2) @result{} "101"
1018 @deffn primitive logcount n
1019 Return the number of bits in integer @var{n}. If integer is
1020 positive, the 1-bits in its binary representation are counted.
1021 If negative, the 0-bits in its two's-complement binary
1022 representation are counted. If 0, 0 is returned.
1024 (logcount #b10101010)
1033 @deffn primitive integer-length n
1034 Return the number of bits neccessary to represent @var{n}.
1036 (integer-length #b10101010)
1040 (integer-length #b1111)
1045 @deffn primitive integer-expt n k
1046 Return @var{n} raised to the non-negative integer exponent
1056 @deffn primitive bit-extract n start end
1057 Return the integer composed of the @var{start} (inclusive)
1058 through @var{end} (exclusive) bits of @var{n}. The
1059 @var{start}th bit becomes the 0-th bit in the result.
1061 (number->string (bit-extract #b1101101010 0 4) 2)
1063 (number->string (bit-extract #b1101101010 4 9) 2)
1070 @subsection Random Number Generation
1072 @deffn primitive copy-random-state [state]
1073 Return a copy of the random state @var{state}.
1076 @deffn primitive random n [state]
1077 Return a number in [0,N).
1078 Accepts a positive integer or real n and returns a
1079 number of the same type between zero (inclusive) and
1080 N (exclusive). The values returned have a uniform
1082 The optional argument @var{state} must be of the type produced
1083 by @code{seed->random-state}. It defaults to the value of the
1084 variable @var{*random-state*}. This object is used to maintain
1085 the state of the pseudo-random-number generator and is altered
1086 as a side effect of the random operation.
1089 @deffn primitive random:exp [state]
1090 Return an inexact real in an exponential distribution with mean
1091 1. For an exponential distribution with mean u use (* u
1095 @deffn primitive random:hollow-sphere! v [state]
1096 Fills vect with inexact real random numbers
1097 the sum of whose squares is equal to 1.0.
1098 Thinking of vect as coordinates in space of
1099 dimension n = (vector-length vect), the coordinates
1100 are uniformly distributed over the surface of the
1104 @deffn primitive random:normal [state]
1105 Return an inexact real in a normal distribution. The
1106 distribution used has mean 0 and standard deviation 1. For a
1107 normal distribution with mean m and standard deviation d use
1108 @code{(+ m (* d (random:normal)))}.
1111 @deffn primitive random:normal-vector! v [state]
1112 Fills vect with inexact real random numbers that are
1113 independent and standard normally distributed
1114 (i.e., with mean 0 and variance 1).
1117 @deffn primitive random:solid-sphere! v [state]
1118 Fills vect with inexact real random numbers
1119 the sum of whose squares is less than 1.0.
1120 Thinking of vect as coordinates in space of
1121 dimension n = (vector-length vect), the coordinates
1122 are uniformly distributed within the unit n-shere.
1123 The sum of the squares of the numbers is returned.
1126 @deffn primitive random:uniform [state]
1127 Return a uniformly distributed inexact real random number in
1131 @deffn primitive seed->random-state seed
1132 Return a new random state using @var{seed}.
1140 Most of the characters in the ASCII character set may be referred to by
1141 name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and so on.
1142 The following table describes the ASCII names for each character.
1144 @multitable @columnfractions .25 .25 .25 .25
1145 @item 0 = @code{#\nul}
1146 @tab 1 = @code{#\soh}
1147 @tab 2 = @code{#\stx}
1148 @tab 3 = @code{#\etx}
1149 @item 4 = @code{#\eot}
1150 @tab 5 = @code{#\enq}
1151 @tab 6 = @code{#\ack}
1152 @tab 7 = @code{#\bel}
1153 @item 8 = @code{#\bs}
1154 @tab 9 = @code{#\ht}
1155 @tab 10 = @code{#\nl}
1156 @tab 11 = @code{#\vt}
1157 @item 12 = @code{#\np}
1158 @tab 13 = @code{#\cr}
1159 @tab 14 = @code{#\so}
1160 @tab 15 = @code{#\si}
1161 @item 16 = @code{#\dle}
1162 @tab 17 = @code{#\dc1}
1163 @tab 18 = @code{#\dc2}
1164 @tab 19 = @code{#\dc3}
1165 @item 20 = @code{#\dc4}
1166 @tab 21 = @code{#\nak}
1167 @tab 22 = @code{#\syn}
1168 @tab 23 = @code{#\etb}
1169 @item 24 = @code{#\can}
1170 @tab 25 = @code{#\em}
1171 @tab 26 = @code{#\sub}
1172 @tab 27 = @code{#\esc}
1173 @item 28 = @code{#\fs}
1174 @tab 29 = @code{#\gs}
1175 @tab 30 = @code{#\rs}
1176 @tab 31 = @code{#\us}
1177 @item 32 = @code{#\sp}
1180 The @code{delete} character (octal 177) may be referred to with the name
1183 Several characters have more than one name:
1203 @deffn primitive char? x
1204 Return @code{#t} iff @var{x} is a character, else @code{#f}.
1208 @deffn primitive char=? x y
1209 Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
1213 @deffn primitive char<? x y
1214 Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence,
1219 @deffn primitive char<=? x y
1220 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
1221 ASCII sequence, else @code{#f}.
1225 @deffn primitive char>? x y
1226 Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
1227 sequence, else @code{#f}.
1231 @deffn primitive char>=? x y
1232 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
1233 ASCII sequence, else @code{#f}.
1237 @deffn primitive char-ci=? x y
1238 Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
1239 case, else @code{#f}.
1243 @deffn primitive char-ci<? x y
1244 Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence
1245 ignoring case, else @code{#f}.
1249 @deffn primitive char-ci<=? x y
1250 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
1251 ASCII sequence ignoring case, else @code{#f}.
1255 @deffn primitive char-ci>? x y
1256 Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
1257 sequence ignoring case, else @code{#f}.
1261 @deffn primitive char-ci>=? x y
1262 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
1263 ASCII sequence ignoring case, else @code{#f}.
1266 @rnindex char-alphabetic?
1267 @deffn primitive char-alphabetic? chr
1268 Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
1269 Alphabetic means the same thing as the isalpha C library function.
1272 @rnindex char-numeric?
1273 @deffn primitive char-numeric? chr
1274 Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
1275 Numeric means the same thing as the isdigit C library function.
1278 @rnindex char-whitespace?
1279 @deffn primitive char-whitespace? chr
1280 Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
1281 Whitespace means the same thing as the isspace C library function.
1284 @rnindex char-upper-case?
1285 @deffn primitive char-upper-case? chr
1286 Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
1287 Uppercase means the same thing as the isupper C library function.
1290 @rnindex char-lower-case?
1291 @deffn primitive char-lower-case? chr
1292 Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
1293 Lowercase means the same thing as the islower C library function.
1296 @deffn primitive char-is-both? chr
1297 Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}.
1298 Uppercase and lowercase are as defined by the isupper and islower
1299 C library functions.
1302 @rnindex char->integer
1303 @deffn primitive char->integer chr
1304 Return the number corresponding to ordinal position of @var{chr} in the
1308 @rnindex integer->char
1309 @deffn primitive integer->char n
1310 Return the character at position @var{n} in the ASCII sequence.
1313 @rnindex char-upcase
1314 @deffn primitive char-upcase chr
1315 Return the uppercase character version of @var{chr}.
1318 @rnindex char-downcase
1319 @deffn primitive char-downcase chr
1320 Return the lowercase character version of @var{chr}.
1327 Strings are fixed--length sequences of characters. They can be created
1328 by calling constructor procedures, but they can also literally get
1329 entered at the REPL or in Scheme source files.
1331 Guile provides a rich set of string processing procedures, because text
1332 handling is very important when Guile is used as a scripting language.
1334 Strings always carry the information about how many characters they are
1335 composed of with them, so there is no special end--of--string character,
1336 like in C. That means that Scheme strings can contain any character,
1337 even the NUL character @code{'\0'}. But note: Since most operating
1338 system calls dealing with strings (such as for file operations) expect
1339 strings to be zero--terminated, they might do unexpected things when
1340 called with string containing unusal characters.
1343 * String Syntax:: Read syntax for strings.
1344 * String Predicates:: Testing strings for certain properties.
1345 * String Constructors:: Creating new string objects.
1346 * List/String Conversion:: Converting from/to lists of characters.
1347 * String Selection:: Select portions from strings.
1348 * String Modification:: Modify parts or whole strings.
1349 * String Comparison:: Lexicographic ordering predicates.
1350 * String Searching:: Searching in strings.
1351 * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
1352 * Appending Strings:: Appending strings to form a new string.
1353 * String Miscellanea:: Miscellaneous string procedures.
1357 @subsection String Read Syntax
1359 The read syntax for strings is an arbitrarily long sequence of characters
1360 enclosed in double quotes (@code{"}). @footnote{Actually, the current
1361 implementation restricts strings to a length of 2^24 characters.} If
1362 you want to insert a double quote character into a string literal, it
1363 must be prefixed with a backslash @code{\} character (called an
1364 @emph{escape character}).
1366 The following are examples of string literals:
1375 @c FIXME::martin: What about escape sequences like \r, \n etc.?
1377 @node String Predicates
1378 @subsection String Predicates
1380 The following procedures can be used to check whether a given string
1381 fulfills some specified property.
1384 @deffn primitive string? obj
1385 Return @code{#t} iff @var{obj} is a string, else returns
1389 @deffn primitive string-null? str
1390 Return @code{#t} if @var{str}'s length is nonzero, and
1391 @code{#f} otherwise.
1393 (string-null? "") @result{} #t
1395 (string-null? y) @result{} #f
1399 @node String Constructors
1400 @subsection String Constructors
1402 The string constructor procedures create new string objects, possibly
1403 initializing them with some specified character data.
1405 @c FIXME::martin: list->string belongs into `List/String Conversion'
1408 @rnindex list->string
1409 @deffn primitive string . chrs
1410 @deffnx primitive list->string chrs
1411 Return a newly allocated string composed of the arguments,
1415 @rnindex make-string
1416 @deffn primitive make-string k [chr]
1417 Return a newly allocated string of
1418 length @var{k}. If @var{chr} is given, then all elements of
1419 the string are initialized to @var{chr}, otherwise the contents
1420 of the @var{string} are unspecified.
1423 @node List/String Conversion
1424 @subsection List/String conversion
1426 When processing strings, it is often convenient to first convert them
1427 into a list representation by using the procedure @code{string->list},
1428 work with the resulting list, and then convert it back into a string.
1429 These procedures are useful for similar tasks.
1431 @rnindex string->list
1432 @deffn primitive string->list str
1433 Return a newly allocated list of the characters that make up
1434 the given string @var{str}. @code{string->list} and
1435 @code{list->string} are inverses as far as @samp{equal?} is
1439 @node String Selection
1440 @subsection String Selection
1442 Portions of strings can be extracted by these procedures.
1443 @code{string-ref} delivers individual characters whereas
1444 @code{substring} can be used to extract substrings from longer strings.
1446 @rnindex string-length
1447 @deffn primitive string-length string
1448 Return the number of characters in @var{string}.
1452 @deffn primitive string-ref str k
1453 Return character @var{k} of @var{str} using zero-origin
1454 indexing. @var{k} must be a valid index of @var{str}.
1457 @rnindex string-copy
1458 @deffn primitive string-copy str
1459 Return a newly allocated copy of the given @var{string}.
1463 @deffn primitive substring str start [end]
1464 Return a newly allocated string formed from the characters
1465 of @var{str} beginning with index @var{start} (inclusive) and
1466 ending with index @var{end} (exclusive).
1467 @var{str} must be a string, @var{start} and @var{end} must be
1468 exact integers satisfying:
1470 0 <= @var{start} <= @var{end} <= (string-length @var{str}).
1473 @node String Modification
1474 @subsection String Modification
1476 These procedures are for modifying strings in--place. That means, that
1477 not a new string is the result of a string operation, but that the
1478 actual memory representation of a string is modified.
1480 @rnindex string-set!
1481 @deffn primitive string-set! str k chr
1482 Store @var{chr} in element @var{k} of @var{str} and return
1483 an unspecified value. @var{k} must be a valid index of
1487 @rnindex string-fill!
1488 @deffn primitive string-fill! str chr
1489 Store @var{char} in every element of the given @var{string} and
1490 return an unspecified value.
1493 @deffn primitive substring-fill! str start end fill
1494 Change every character in @var{str} between @var{start} and
1495 @var{end} to @var{fill}.
1497 (define y "abcdefg")
1498 (substring-fill! y 1 3 #\r)
1504 @deffn primitive substring-move! str1 start1 end1 str2 start2
1505 @deffnx primitive substring-move-left! str1 start1 end1 str2 start2
1506 @deffnx primitive substring-move-right! str1 start1 end1 str2 start2
1507 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
1508 into @var{str2} beginning at position @var{end2}.
1509 @code{substring-move-right!} begins copying from the rightmost character
1510 and moves left, and @code{substring-move-left!} copies from the leftmost
1511 character moving right.
1513 It is useful to have two functions that copy in different directions so
1514 that substrings can be copied back and forth within a single string. If
1515 you wish to copy text from the left-hand side of a string to the
1516 right-hand side of the same string, and the source and destination
1517 overlap, you must be careful to copy the rightmost characters of the
1518 text first, to avoid clobbering your data. Hence, when @var{str1} and
1519 @var{str2} are the same string, you should use
1520 @code{substring-move-right!} when moving text from left to right, and
1521 @code{substring-move-left!} otherwise. If @code{str1} and @samp{str2}
1522 are different strings, it does not matter which function you use.
1525 @deffn primitive substring-move-left! str1 start1 end1 str2 start2
1527 @deftypefn {C Function} SCM scm_substring_move_left_x (SCM @var{str1}, SCM @var{start1}, SCM @var{end1}, SCM @var{str2}, SCM @var{start2})
1528 [@strong{Note:} this is only valid if you've applied the strop patch].
1530 Moves a substring of @var{str1}, from @var{start1} to @var{end1}
1531 (@var{end1} is exclusive), into @var{str2}, starting at
1532 @var{start2}. Allows overlapping strings.
1535 (define x (make-string 10 #\a))
1537 (substring-move-left! x 2 5 y 0)
1542 @result{} "aaaaaaaaaa"
1545 (substring-move-left! x 2 5 y 0)
1549 (define y "abcdefg")
1550 (substring-move-left! y 2 5 y 3)
1556 @deffn substring-move-right! str1 start1 end1 str2 start2
1558 @deftypefn {C Function} SCM scm_substring_move_right_x (SCM @var{str1}, SCM @var{start1}, SCM @var{end1}, SCM @var{str2}, SCM @var{start2})
1559 [@strong{Note:} this is only valid if you've applied the strop patch, if
1560 it hasn't made it into the guile tree].
1562 Does much the same thing as @code{substring-move-left!}, except it
1563 starts moving at the end of the sequence, rather than the beginning.
1565 (define y "abcdefg")
1566 (substring-move-right! y 2 5 y 0)
1570 (define y "abcdefg")
1571 (substring-move-right! y 2 5 y 3)
1578 @node String Comparison
1579 @subsection String Comparison
1581 The procedures in this section are similar to the character ordering
1582 predicates (REFFIXME), but are defined on character sequences. They all
1583 return @code{#t} on success and @code{#f} on failure. The predicates
1584 ending in @code{-ci} ignore the character case when comparing strings.
1588 @deffn primitive string=? s1 s2
1589 Lexicographic equality predicate; return @code{#t} if the two
1590 strings are the same length and contain the same characters in
1591 the same positions, otherwise return @code{#f}.
1592 The procedure @code{string-ci=?} treats upper and lower case
1593 letters as though they were the same character, but
1594 @code{string=?} treats upper and lower case as distinct
1599 @deffn primitive string<? s1 s2
1600 Lexicographic ordering predicate; return @code{#t} if @var{s1}
1601 is lexicographically less than @var{s2}.
1605 @deffn primitive string<=? s1 s2
1606 Lexicographic ordering predicate; return @code{#t} if @var{s1}
1607 is lexicographically less than or equal to @var{s2}.
1611 @deffn primitive string>? s1 s2
1612 Lexicographic ordering predicate; return @code{#t} if @var{s1}
1613 is lexicographically greater than @var{s2}.
1617 @deffn primitive string>=? s1 s2
1618 Lexicographic ordering predicate; return @code{#t} if @var{s1}
1619 is lexicographically greater than or equal to @var{s2}.
1622 @rnindex string-ci=?
1623 @deffn primitive string-ci=? s1 s2
1624 Case-insensitive string equality predicate; return @code{#t} if
1625 the two strings are the same length and their component
1626 characters match (ignoring case) at each position; otherwise
1631 @deffn primitive string-ci<? s1 s2
1632 Case insensitive lexicographic ordering predicate; return
1633 @code{#t} if @var{s1} is lexicographically less than @var{s2}
1638 @deffn primitive string-ci<=? s1 s2
1639 Case insensitive lexicographic ordering predicate; return
1640 @code{#t} if @var{s1} is lexicographically less than or equal
1641 to @var{s2} regardless of case.
1644 @rnindex string-ci>?
1645 @deffn primitive string-ci>? s1 s2
1646 Case insensitive lexicographic ordering predicate; return
1647 @code{#t} if @var{s1} is lexicographically greater than
1648 @var{s2} regardless of case.
1651 @rnindex string-ci>=?
1652 @deffn primitive string-ci>=? s1 s2
1653 Case insensitive lexicographic ordering predicate; return
1654 @code{#t} if @var{s1} is lexicographically greater than or
1655 equal to @var{s2} regardless of case.
1659 @node String Searching
1660 @subsection String Searching
1662 When searching the index of a character in a string, these procedures
1665 @deffn primitive string-index str chr [frm [to]]
1666 Return the index of the first occurrence of @var{chr} in
1667 @var{str}. The optional integer arguments @var{frm} and
1668 @var{to} limit the search to a portion of the string. This
1669 procedure essentially implements the @code{index} or
1670 @code{strchr} functions from the C library.
1672 (string-index "weiner" #\e)
1675 (string-index "weiner" #\e 2)
1678 (string-index "weiner" #\e 2 4)
1683 @deffn primitive string-rindex str chr [frm [to]]
1684 Like @code{string-index}, but search from the right of the
1685 string rather than from the left. This procedure essentially
1686 implements the @code{rindex} or @code{strrchr} functions from
1689 (string-rindex "weiner" #\e)
1692 (string-rindex "weiner" #\e 2 4)
1695 (string-rindex "weiner" #\e 2 5)
1700 @node Alphabetic Case Mapping
1701 @subsection Alphabetic Case Mapping
1703 These are procedures for mapping strings to their upper-- or lower--case
1704 equivalents, respectively, or for capitalizing strings.
1706 @deffn primitive string-upcase str
1707 Return a freshly allocated string containing the characters of
1708 @var{str} in upper case.
1711 @deffn primitive string-upcase! str
1712 Destructively upcase every character in @var{str} and return
1715 y @result{} "arrdefg"
1716 (string-upcase! y) @result{} "ARRDEFG"
1717 y @result{} "ARRDEFG"
1721 @deffn primitive string-downcase str
1722 Return a freshly allocation string containing the characters in
1723 @var{str} in lower case.
1726 @deffn primitive string-downcase! str
1727 Destructively downcase every character in @var{str} and return
1730 y @result{} "ARRDEFG"
1731 (string-downcase! y) @result{} "arrdefg"
1732 y @result{} "arrdefg"
1736 @deffn primitive string-capitalize str
1737 Return a freshly allocated string with the characters in
1738 @var{str}, where the first character of every word is
1742 @deffn primitive string-capitalize! str
1743 Upcase the first character of every word in @var{str}
1744 destructively and return @var{str}.
1746 y @result{} "hello world"
1747 (string-capitalize! y) @result{} "Hello World"
1748 y @result{} "Hello World"
1753 @node Appending Strings
1754 @subsection Appending Strings
1756 The procedure @code{string-append} appends several strings together to
1757 form a longer result string.
1759 @rnindex string-append
1760 @deffn primitive string-append . args
1761 Return a newly allocated string whose characters form the
1762 concatenation of the given strings, @var{args}.
1766 @node String Miscellanea
1767 @subsection String Miscellanea
1769 This section contains several remaining string procedures.
1771 @deffn primitive string-ci->symbol str
1772 Return the symbol whose name is @var{str}. @var{str} is
1773 converted to lowercase before the conversion is done, if Guile
1774 is currently reading symbols case--insensitively.
1778 @node Regular Expressions
1779 @section Regular Expressions
1781 @cindex regular expressions
1783 @cindex emacs regexp
1785 A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
1786 describes a whole class of strings. A full description of regular
1787 expressions and their syntax is beyond the scope of this manual;
1788 an introduction can be found in the Emacs manual (@pxref{Regexps,
1789 , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, or
1790 in many general Unix reference books.
1792 If your system does not include a POSIX regular expression library, and
1793 you have not linked Guile with a third-party regexp library such as Rx,
1794 these functions will not be available. You can tell whether your Guile
1795 installation includes regular expression support by checking whether the
1796 @code{*features*} list includes the @code{regex} symbol.
1799 * Regexp Functions:: Functions that create and match regexps.
1800 * Match Structures:: Finding what was matched by a regexp.
1801 * Backslash Escapes:: Removing the special meaning of regexp metacharacters.
1802 * Rx Interface:: Tom Lord's Rx library does things differently.
1805 [FIXME: it may be useful to include an Examples section. Parts of this
1806 interface are bewildering on first glance.]
1808 @node Regexp Functions
1809 @subsection Regexp Functions
1811 By default, Guile supports POSIX extended regular expressions.
1812 That means that the characters @samp{(}, @samp{)}, @samp{+} and
1813 @samp{?} are special, and must be escaped if you wish to match the
1816 This regular expression interface was modeled after that
1817 implemented by SCSH, the Scheme Shell. It is intended to be
1818 upwardly compatible with SCSH regular expressions.
1820 @c begin (scm-doc-string "regex.scm" "string-match")
1821 @deffn procedure string-match pattern str [start]
1822 Compile the string @var{pattern} into a regular expression and compare
1823 it with @var{str}. The optional numeric argument @var{start} specifies
1824 the position of @var{str} at which to begin matching.
1826 @code{string-match} returns a @dfn{match structure} which
1827 describes what, if anything, was matched by the regular
1828 expression. @xref{Match Structures}. If @var{str} does not match
1829 @var{pattern} at all, @code{string-match} returns @code{#f}.
1832 Each time @code{string-match} is called, it must compile its
1833 @var{pattern} argument into a regular expression structure. This
1834 operation is expensive, which makes @code{string-match} inefficient if
1835 the same regular expression is used several times (for example, in a
1836 loop). For better performance, you can compile a regular expression in
1837 advance and then match strings against the compiled regexp.
1839 @deffn primitive make-regexp pat . flags
1840 Compile the regular expression described by @var{pat}, and
1841 return the compiled regexp structure. If @var{pat} does not
1842 describe a legal regular expression, @code{make-regexp} throws
1843 a @code{regular-expression-syntax} error.
1844 The @var{flags} arguments change the behavior of the compiled
1845 regular expression. The following flags may be supplied:
1848 Consider uppercase and lowercase letters to be the same when
1850 @item regexp/newline
1851 If a newline appears in the target string, then permit the
1852 @samp{^} and @samp{$} operators to match immediately after or
1853 immediately before the newline, respectively. Also, the
1854 @samp{.} and @samp{[^...]} operators will never match a newline
1855 character. The intent of this flag is to treat the target
1856 string as a buffer containing many lines of text, and the
1857 regular expression as a pattern that may match a single one of
1860 Compile a basic (``obsolete'') regexp instead of the extended
1861 (``modern'') regexps that are the default. Basic regexps do
1862 not consider @samp{|}, @samp{+} or @samp{?} to be special
1863 characters, and require the @samp{@{...@}} and @samp{(...)}
1864 metacharacters to be backslash-escaped (@pxref{Backslash
1865 Escapes}). There are several other differences between basic
1866 and extended regular expressions, but these are the most
1868 @item regexp/extended
1869 Compile an extended regular expression rather than a basic
1870 regexp. This is the default behavior; this flag will not
1871 usually be needed. If a call to @code{make-regexp} includes
1872 both @code{regexp/basic} and @code{regexp/extended} flags, the
1873 one which comes last will override the earlier one.
1877 @deffn primitive regexp-exec rx str [start [flags]]
1878 Match the compiled regular expression @var{rx} against
1879 @code{str}. If the optional integer @var{start} argument is
1880 provided, begin matching from that position in the string.
1881 Return a match structure describing the results of the match,
1882 or @code{#f} if no match could be found.
1885 @deffn primitive regexp? obj
1886 Return @code{#t} if @var{obj} is a compiled regular expression,
1887 or @code{#f} otherwise.
1890 Regular expressions are commonly used to find patterns in one string and
1891 replace them with the contents of another string.
1893 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
1894 @deffn procedure regexp-substitute port match [item@dots{}]
1895 Write to the output port @var{port} selected contents of the match
1896 structure @var{match}. Each @var{item} specifies what should be
1897 written, and may be one of the following arguments:
1901 A string. String arguments are written out verbatim.
1904 An integer. The submatch with that number is written.
1907 The symbol @samp{pre}. The portion of the matched string preceding
1908 the regexp match is written.
1911 The symbol @samp{post}. The portion of the matched string following
1912 the regexp match is written.
1915 @var{port} may be @code{#f}, in which case nothing is written; instead,
1916 @code{regexp-substitute} constructs a string from the specified
1917 @var{item}s and returns that.
1920 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
1921 @deffn procedure regexp-substitute/global port regexp target [item@dots{}]
1922 Similar to @code{regexp-substitute}, but can be used to perform global
1923 substitutions on @var{str}. Instead of taking a match structure as an
1924 argument, @code{regexp-substitute/global} takes two string arguments: a
1925 @var{regexp} string describing a regular expression, and a @var{target}
1926 string which should be matched against this regular expression.
1928 Each @var{item} behaves as in @var{regexp-substitute}, with the
1929 following exceptions:
1933 A function may be supplied. When this function is called, it will be
1934 passed one argument: a match structure for a given regular expression
1935 match. It should return a string to be written out to @var{port}.
1938 The @samp{post} symbol causes @code{regexp-substitute/global} to recurse
1939 on the unmatched portion of @var{str}. This @emph{must} be supplied in
1940 order to perform global search-and-replace on @var{str}; if it is not
1941 present among the @var{item}s, then @code{regexp-substitute/global} will
1942 return after processing a single match.
1946 @node Match Structures
1947 @subsection Match Structures
1949 @cindex match structures
1951 A @dfn{match structure} is the object returned by @code{string-match} and
1952 @code{regexp-exec}. It describes which portion of a string, if any,
1953 matched the given regular expression. Match structures include: a
1954 reference to the string that was checked for matches; the starting and
1955 ending positions of the regexp match; and, if the regexp included any
1956 parenthesized subexpressions, the starting and ending positions of each
1959 In each of the regexp match functions described below, the @code{match}
1960 argument must be a match structure returned by a previous call to
1961 @code{string-match} or @code{regexp-exec}. Most of these functions
1962 return some information about the original target string that was
1963 matched against a regular expression; we will call that string
1964 @var{target} for easy reference.
1966 @c begin (scm-doc-string "regex.scm" "regexp-match?")
1967 @deffn procedure regexp-match? obj
1968 Return @code{#t} if @var{obj} is a match structure returned by a
1969 previous call to @code{regexp-exec}, or @code{#f} otherwise.
1972 @c begin (scm-doc-string "regex.scm" "match:substring")
1973 @deffn procedure match:substring match [n]
1974 Return the portion of @var{target} matched by subexpression number
1975 @var{n}. Submatch 0 (the default) represents the entire regexp match.
1976 If the regular expression as a whole matched, but the subexpression
1977 number @var{n} did not match, return @code{#f}.
1980 @c begin (scm-doc-string "regex.scm" "match:start")
1981 @deffn procedure match:start match [n]
1982 Return the starting position of submatch number @var{n}.
1985 @c begin (scm-doc-string "regex.scm" "match:end")
1986 @deffn procedure match:end match [n]
1987 Return the ending position of submatch number @var{n}.
1990 @c begin (scm-doc-string "regex.scm" "match:prefix")
1991 @deffn procedure match:prefix match
1992 Return the unmatched portion of @var{target} preceding the regexp match.
1995 @c begin (scm-doc-string "regex.scm" "match:suffix")
1996 @deffn procedure match:suffix match
1997 Return the unmatched portion of @var{target} following the regexp match.
2000 @c begin (scm-doc-string "regex.scm" "match:count")
2001 @deffn procedure match:count match
2002 Return the number of parenthesized subexpressions from @var{match}.
2003 Note that the entire regular expression match itself counts as a
2004 subexpression, and failed submatches are included in the count.
2007 @c begin (scm-doc-string "regex.scm" "match:string")
2008 @deffn procedure match:string match
2009 Return the original @var{target} string.
2012 @node Backslash Escapes
2013 @subsection Backslash Escapes
2015 Sometimes you will want a regexp to match characters like @samp{*} or
2016 @samp{$} exactly. For example, to check whether a particular string
2017 represents a menu entry from an Info node, it would be useful to match
2018 it against a regexp like @samp{^* [^:]*::}. However, this won't work;
2019 because the asterisk is a metacharacter, it won't match the @samp{*} at
2020 the beginning of the string. In this case, we want to make the first
2023 You can do this by preceding the metacharacter with a backslash
2024 character @samp{\}. (This is also called @dfn{quoting} the
2025 metacharacter, and is known as a @dfn{backslash escape}.) When Guile
2026 sees a backslash in a regular expression, it considers the following
2027 glyph to be an ordinary character, no matter what special meaning it
2028 would ordinarily have. Therefore, we can make the above example work by
2029 changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells
2030 the regular expression engine to match only a single asterisk in the
2033 Since the backslash is itself a metacharacter, you may force a regexp to
2034 match a backslash in the target string by preceding the backslash with
2035 itself. For example, to find variable references in a @TeX{} program,
2036 you might want to find occurrences of the string @samp{\let\} followed
2037 by any number of alphabetic characters. The regular expression
2038 @samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the
2039 regexp each match a single backslash in the target string.
2041 @c begin (scm-doc-string "regex.scm" "regexp-quote")
2042 @deffn procedure regexp-quote str
2043 Quote each special character found in @var{str} with a backslash, and
2044 return the resulting string.
2047 @strong{Very important:} Using backslash escapes in Guile source code
2048 (as in Emacs Lisp or C) can be tricky, because the backslash character
2049 has special meaning for the Guile reader. For example, if Guile
2050 encounters the character sequence @samp{\n} in the middle of a string
2051 while processing Scheme code, it replaces those characters with a
2052 newline character. Similarly, the character sequence @samp{\t} is
2053 replaced by a horizontal tab. Several of these @dfn{escape sequences}
2054 are processed by the Guile reader before your code is executed.
2055 Unrecognized escape sequences are ignored: if the characters @samp{\*}
2056 appear in a string, they will be translated to the single character
2059 This translation is obviously undesirable for regular expressions, since
2060 we want to be able to include backslashes in a string in order to
2061 escape regexp metacharacters. Therefore, to make sure that a backslash
2062 is preserved in a string in your Guile program, you must use @emph{two}
2063 consecutive backslashes:
2066 (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
2069 The string in this example is preprocessed by the Guile reader before
2070 any code is executed. The resulting argument to @code{make-regexp} is
2071 the string @samp{^\* [^:]*}, which is what we really want.
2073 This also means that in order to write a regular expression that matches
2074 a single backslash character, the regular expression string in the
2075 source code must include @emph{four} backslashes. Each consecutive pair
2076 of backslashes gets translated by the Guile reader to a single
2077 backslash, and the resulting double-backslash is interpreted by the
2078 regexp engine as matching a single backslash character. Hence:
2081 (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
2084 The reason for the unwieldiness of this syntax is historical. Both
2085 regular expression pattern matchers and Unix string processing systems
2086 have traditionally used backslashes with the special meanings
2087 described above. The POSIX regular expression specification and ANSI C
2088 standard both require these semantics. Attempting to abandon either
2089 convention would cause other kinds of compatibility problems, possibly
2090 more severe ones. Therefore, without extending the Scheme reader to
2091 support strings with different quoting conventions (an ungainly and
2092 confusing extension when implemented in other languages), we must adhere
2093 to this cumbersome escape syntax.
2096 @subsection Rx Interface
2098 @c FIXME::martin: Shouldn't this be removed or moved to the
2099 @c ``Guile Modules'' chapter? The functions are not available in
2102 [FIXME: this is taken from Gary and Mark's quick summaries and should be
2103 reviewed and expanded. Rx is pretty stable, so could already be done!]
2106 @cindex finite automaton
2108 Guile includes an interface to Tom Lord's Rx library (currently only to
2109 POSIX regular expressions). Use of the library requires a two step
2110 process: compile a regular expression into an efficient structure, then
2111 use the structure in any number of string comparisons.
2113 For example, given the
2114 regular expression @samp{abc.} (which matches any string containing
2115 @samp{abc} followed by any single character):
2118 guile> @kbd{(define r (regcomp "abc."))}
2121 guile> @kbd{(regexec r "abc")}
2123 guile> @kbd{(regexec r "abcd")}
2128 The definitions of @code{regcomp} and @code{regexec} are as follows:
2130 @c NJFIXME not in libguile!
2131 @deffn primitive regcomp pattern [flags]
2132 Compile the regular expression pattern using POSIX rules. Flags is
2133 optional and should be specified using symbolic names:
2134 @defvar REG_EXTENDED
2135 use extended POSIX syntax
2138 use case-insensitive matching
2141 allow anchors to match after newline characters in the
2142 string and prevents @code{.} or @code{[^...]} from matching newlines.
2145 The @code{logior} procedure can be used to combine multiple flags.
2146 The default is to use
2147 POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+}
2149 operators. Backslashes in @var{pattern} must be escaped if specified in a
2150 literal string e.g., @code{"\\(a\\)\\?"}.
2153 @c NJFIXME not in libguile!
2154 @deffn primitive regexec regex string [match-pick] [flags]
2156 Match @var{string} against the compiled POSIX regular expression
2158 @var{match-pick} and @var{flags} are optional. Possible flags (which can be
2159 combined using the logior procedure) are:
2162 The beginning of line operator won't match the beginning of
2163 @var{string} (presumably because it's not the beginning of a line)
2167 Similar to REG_NOTBOL, but prevents the end of line operator
2168 from matching the end of @var{string}.
2171 If no match is possible, regexec returns #f. Otherwise @var{match-pick}
2172 determines the return value:
2174 @code{#t} or unspecified: a newly-allocated vector is returned,
2175 containing pairs with the indices of the matched part of @var{string} and any
2178 @code{""}: a list is returned: the first element contains a nested list
2179 with the matched part of @var{string} surrounded by the the unmatched parts.
2180 Remaining elements are matched substrings (if any). All returned
2181 substrings share memory with @var{string}.
2183 @code{#f}: regexec returns #t if a match is made, otherwise #f.
2185 vector: the supplied vector is returned, with the first element replaced
2186 by a pair containing the indices of the matched portion of @var{string} and
2187 further elements replaced by pairs containing the indices of matched
2188 substrings (if any).
2190 list: a list will be returned, with each member of the list
2191 specified by a code in the corresponding position of the supplied list:
2193 a number: the numbered matching substring (0 for the entire match).
2195 @code{#\<}: the beginning of @var{string} to the beginning of the part matched
2198 @code{#\>}: the end of the matched part of @var{string} to the end of
2201 @code{#\c}: the "final tag", which seems to be associated with the "cut
2202 operator", which doesn't seem to be available through the posix
2205 e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
2209 Here are some other procedures that might be used when using regular
2212 @c NJFIXME not in libguile!
2213 @deffn primitive compiled-regexp? obj
2214 Test whether obj is a compiled regular expression.
2217 @c NJFIXME not in libguile!
2218 @deffn primitive regexp->dfa regex [flags]
2221 @c NJFIXME not in libguile!
2222 @deffn primitive dfa-fork dfa
2225 @c NJFIXME not in libguile!
2226 @deffn primitive reset-dfa! dfa
2229 @c NJFIXME not in libguile!
2230 @deffn primitive dfa-final-tag dfa
2233 @c NJFIXME not in libguile!
2234 @deffn primitive dfa-continuable? dfa
2237 @c NJFIXME not in libguile!
2238 @deffn primitive advance-dfa! dfa string
2242 @node Symbols and Variables
2243 @section Symbols and Variables
2245 @c FIXME::martin: Review me!
2247 Symbols are a data type with a special property. On the one hand,
2248 symbols are used for denoting variables in a Scheme program, on the
2249 other they can be used as literal data as well.
2251 The association between symbols and values is maintained in special data
2252 structures, the symbol tables.
2254 In addition, Guile offers variables as first--class objects. They can
2255 be used for interacting with the module system.
2258 * Symbols:: All about symbols as a data type.
2259 * Symbol Tables:: Tables for mapping symbols to values.
2260 * Variables:: First--class variables.
2266 @c FIXME::martin: Review me!
2268 Symbols are especially useful because two symbols which are spelled the
2269 same way are equivalent in the sense of @code{eq?}. That means that
2270 they are actually the same Scheme object. The advantage is that symbols
2271 can be compared extremely efficiently, although they carry more
2272 information for the human reader than, say, numbers.
2274 It is very common in Scheme programs to use symbols as keys in
2275 association lists (REFFIXME) or hash tables (REFFIXME), because this
2276 usage improves the readability a lot, and does not cause any performance
2279 The read syntax for symbols is a sequence of letters, digits, and
2280 @emph{extended alphabetic characters} that begins with a character that
2281 cannot begin a number is an identifier. In addition, @code{+},
2282 @code{-}, and @code{...} are identifiers.
2284 Extended alphabetic characters may be used within identifiers as if
2285 they were letters. The following are extended alphabetic characters:
2288 ! $ % & * + - . / : < = > ? @@ ^ _ ~
2291 In addition to the read syntax defined above (which is taken from R5RS
2292 (REFFIXME)), Guile provides a method for writing symbols with unusual
2293 characters, such as space characters. If you (for whatever reason) need
2294 to write a symbol containing characters not mentioned above, you write
2299 Begin the symbol with the two character @code{#@{},
2302 write the characters of the symbol and
2305 finish the symbol with the characters @code{@}#}.
2308 Here are a few examples of this form of read syntax; the first
2309 containing a space character, the second containing a line break and the
2310 last one looks like a number.
2319 Usage of this form of read syntax is discouraged, because it is not
2320 portable at all, and is not very readable.
2323 @deffn primitive symbol? obj
2324 Return @code{#t} if @var{obj} is a symbol, otherwise return
2328 @rnindex string->symbol
2329 @deffn primitive string->symbol string
2330 Return the symbol whose name is @var{string}. This procedure
2331 can create symbols with names containing special characters or
2332 letters in the non-standard case, but it is usually a bad idea
2333 to create such symbols because in some implementations of
2334 Scheme they cannot be read as themselves. See
2335 @code{symbol->string}.
2336 The following examples assume that the implementation's
2337 standard case is lower case:
2339 (eq? 'mISSISSIppi 'mississippi) @result{} #t
2340 (string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
2341 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
2343 (string->symbol (symbol->string 'JollyWog))) @result{} #t
2344 (string=? "K. Harper, M.D."
2346 (string->symbol "K. Harper, M.D."))) @result{}#t
2350 @rnindex symbol->string
2351 @deffn primitive symbol->string s
2352 Return the name of @var{symbol} as a string. If the symbol was
2353 part of an object returned as the value of a literal expression
2354 (section @pxref{Literal expressions,,,r4rs, The Revised^4
2355 Report on Scheme}) or by a call to the @code{read} procedure,
2356 and its name contains alphabetic characters, then the string
2357 returned will contain characters in the implementation's
2358 preferred standard case---some implementations will prefer
2359 upper case, others lower case. If the symbol was returned by
2360 @code{string->symbol}, the case of characters in the string
2361 returned will be the same as the case in the string that was
2362 passed to @code{string->symbol}. It is an error to apply
2363 mutation procedures like @code{string-set!} to strings returned
2365 The following examples assume that the implementation's
2366 standard case is lower case:
2368 (symbol->string 'flying-fish) @result{} "flying-fish"
2369 (symbol->string 'Martin) @result{} "martin"
2371 (string->symbol "Malvina")) @result{} "Malvina"
2376 @subsection Symbol Tables
2378 @c FIXME::martin: Review me!
2380 @c FIXME::martin: Are all these procedures still relevant?
2382 Guile symbol tables are hash tables. Each hash table, also called an
2383 @dfn{obarray} (for `object array'), is a vector of association lists.
2384 Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}). To
2385 @dfn{intern} a symbol in a symbol table means to return its
2386 (@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol
2387 table (with an undefined value) if none is yet present.
2389 @c FIXME::martin: According to NEWS, removed. Remove here too, or
2390 @c leave for compatibility?
2391 @c @c docstring begin (texi-doc-string "guile" "builtin-bindings")
2392 @c @deffn primitive builtin-bindings
2393 @c Create and return a copy of the global symbol table, removing all
2397 @deffn primitive gensym [prefix]
2398 Create a new symbol with a name constructed from a prefix and
2399 a counter value. The string @var{prefix} can be specified as
2400 an optional argument. Default prefix is @code{g}. The counter
2401 is increased by 1 at each call. There is no provision for
2402 resetting the counter.
2405 @deffn primitive gentemp [prefix [obarray]]
2406 Create a new symbol with a name unique in an obarray.
2407 The name is constructed from an optional string @var{prefix}
2408 and a counter value. The default prefix is @code{t}. The
2409 @var{obarray} is specified as a second optional argument.
2410 Default is the system obarray where all normal symbols are
2411 interned. The counter is increased by 1 at each
2412 call. There is no provision for resetting the counter.
2415 @deffn primitive intern-symbol obarray string
2416 Add a new symbol to @var{obarray} with name @var{string}, bound to an
2417 unspecified initial value. The symbol table is not modified if a symbol
2418 with this name is already present.
2421 @deffn primitive string->obarray-symbol obarray string [soft?]
2422 Intern a new symbol in @var{obarray}, a symbol table, with name
2426 @deffn primitive symbol-binding obarray string
2427 Look up in @var{obarray} the symbol whose name is @var{string}, and
2428 return the value to which it is bound. If @var{obarray} is @code{#f},
2429 use the global symbol table. If @var{string} is not interned in
2430 @var{obarray}, an error is signalled.
2433 @deffn primitive symbol-bound? obarray string
2434 Return @code{#t} if @var{obarray} contains a symbol with name
2435 @var{string} bound to a defined value. This differs from
2436 @var{symbol-interned?} in that the mere mention of a symbol
2437 usually causes it to be interned; @code{symbol-bound?}
2438 determines whether a symbol has been given any meaningful
2442 @deffn primitive symbol-fref symbol
2443 Return the contents of @var{symbol}'s @dfn{function slot}.
2446 @deffn primitive symbol-fset! symbol value
2447 Change the binding of @var{symbol}'s function slot.
2450 @deffn primitive symbol-hash symbol
2451 Return a hash value for @var{symbol}.
2454 @deffn primitive symbol-interned? obarray string
2455 Return @code{#t} if @var{obarray} contains a symbol with name
2456 @var{string}, and @code{#f} otherwise.
2459 @deffn primitive symbol-pref symbol
2460 Return the @dfn{property list} currently associated with @var{symbol}.
2463 @deffn primitive symbol-pset! symbol value
2464 Change the binding of @var{symbol}'s property slot.
2467 @deffn primitive symbol-set! obarray string value
2468 Find the symbol in @var{obarray} whose name is @var{string}, and rebind
2469 it to @var{value}. An error is signalled if @var{string} is not present
2473 @deffn primitive unintern-symbol obarray string
2474 Remove the symbol with name @var{string} from @var{obarray}. This
2475 function returns @code{#t} if the symbol was present and @code{#f}
2480 @subsection Variables
2482 @c FIXME::martin: Review me!
2484 Variables are objects with two fields. They contain a value and they
2485 can contain a symbol, which is the name of the variable. A variable is
2486 said to be bound if it does not contain the object denoting unbound
2487 variables in the value slot.
2489 Variables do not have a read syntax, they have to be created by calling
2490 one of the constructor procedures @code{make-variable} or
2491 @code{make-undefined-variable} or retrieved by @code{builtin-variable}.
2493 First--class variables are especially useful for interacting with the
2494 current module system (REFFIXME).
2496 @deffn primitive builtin-variable name
2497 Return the built-in variable with the name @var{name}.
2498 @var{name} must be a symbol (not a string).
2499 Then use @code{variable-ref} to access its value.
2502 @deffn primitive make-undefined-variable [name-hint]
2503 Return a variable object initialized to an undefined value.
2504 If given, uses @var{name-hint} as its internal (debugging)
2505 name, otherwise just treat it as an anonymous variable.
2506 Remember, of course, that multiple bindings to the same
2507 variable may exist, so @var{name-hint} is just that---a hint.
2510 @deffn primitive make-variable init [name-hint]
2511 Return a variable object initialized to value @var{init}.
2512 If given, uses @var{name-hint} as its internal (debugging)
2513 name, otherwise just treat it as an anonymous variable.
2514 Remember, of course, that multiple bindings to the same
2515 variable may exist, so @var{name-hint} is just that---a hint.
2518 @deffn primitive variable-bound? var
2519 Return @code{#t} iff @var{var} is bound to a value.
2520 Throws an error if @var{var} is not a variable object.
2523 @deffn primitive variable-ref var
2524 Dereference @var{var} and return its value.
2525 @var{var} must be a variable object; see @code{make-variable}
2526 and @code{make-undefined-variable}.
2529 @deffn primitive variable-set! var val
2530 Set the value of the variable @var{var} to @var{val}.
2531 @var{var} must be a variable object, @var{val} can be any
2532 value. Return an unspecified value.
2535 @deffn primitive variable? obj
2536 Return @code{#t} iff @var{obj} is a variable object, else
2544 Keywords are self-evaluating objects with a convenient read syntax that
2545 makes them easy to type.
2547 Guile's keyword support conforms to R4RS, and adds a (switchable) read
2548 syntax extension to permit keywords to begin with @code{:} as well as
2552 * Why Use Keywords?:: Motivation for keyword usage.
2553 * Coding With Keywords:: How to use keywords.
2554 * Keyword Read Syntax:: Read syntax for keywords.
2555 * Keyword Primitives:: Procedures for dealing with keywords.
2558 @node Why Use Keywords?
2559 @subsection Why Use Keywords?
2561 Keywords are useful in contexts where a program or procedure wants to be
2562 able to accept a large number of optional arguments without making its
2563 interface unmanageable.
2565 To illustrate this, consider a hypothetical @code{make-window}
2566 procedure, which creates a new window on the screen for drawing into
2567 using some graphical toolkit. There are many parameters that the caller
2568 might like to specify, but which could also be sensibly defaulted, for
2573 colour depth -- Default: the colour depth for the screen
2576 background colour -- Default: white
2579 width -- Default: 600
2582 height -- Default: 400
2585 If @code{make-window} did not use keywords, the caller would have to
2586 pass in a value for each possible argument, remembering the correct
2587 argument order and using a special value to indicate the default value
2591 (make-window 'default ;; Colour depth
2592 'default ;; Background colour
2595 @dots{}) ;; More make-window arguments
2598 With keywords, on the other hand, defaulted arguments are omitted, and
2599 non-default arguments are clearly tagged by the appropriate keyword. As
2600 a result, the invocation becomes much clearer:
2603 (make-window #:width 800 #:height 100)
2606 On the other hand, for a simpler procedure with few arguments, the use
2607 of keywords would be a hindrance rather than a help. The primitive
2608 procedure @code{cons}, for example, would not be improved if it had to
2612 (cons #:car x #:cdr y)
2615 So the decision whether to use keywords or not is purely pragmatic: use
2616 them if they will clarify the procedure invocation at point of call.
2618 @node Coding With Keywords
2619 @subsection Coding With Keywords
2621 If a procedure wants to support keywords, it should take a rest argument
2622 and then use whatever means is convenient to extract keywords and their
2623 corresponding arguments from the contents of that rest argument.
2625 The following example illustrates the principle: the code for
2626 @code{make-window} uses a helper procedure called
2627 @code{get-keyword-value} to extract individual keyword arguments from
2631 (define (get-keyword-value args keyword default)
2632 (let ((kv (memq keyword args)))
2633 (if (and kv (>= (length kv) 2))
2637 (define (make-window . args)
2638 (let ((depth (get-keyword-value args #:depth screen-depth))
2639 (bg (get-keyword-value args #:bg "white"))
2640 (width (get-keyword-value args #:width 800))
2641 (height (get-keyword-value args #:height 100))
2646 But you don't need to write @code{get-keyword-value}. The @code{(ice-9
2647 optargs)} module provides a set of powerful macros that you can use to
2648 implement keyword-supporting procedures like this:
2651 (use-modules (ice-9 optargs))
2653 (define (make-window . args)
2654 (let-keywords args #f ((depth screen-depth)
2662 Or, even more economically, like this:
2665 (use-modules (ice-9 optargs))
2667 (define* (make-window #:key (depth screen-depth)
2674 For further details on @code{let-keywords}, @code{define*} and other
2675 facilities provided by the @code{(ice-9 optargs)} module, @ref{Optional
2679 @node Keyword Read Syntax
2680 @subsection Keyword Read Syntax
2682 Guile, by default, only recognizes the keyword syntax specified by R5RS.
2683 A token of the form @code{#:NAME}, where @code{NAME} has the same syntax
2684 as a Scheme symbol, is the external representation of the keyword named
2685 @code{NAME}. Keyword objects print using this syntax as well, so values
2686 containing keyword objects can be read back into Guile. When used in an
2687 expression, keywords are self-quoting objects.
2689 If the @code{keyword} read option is set to @code{'prefix}, Guile also
2690 recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
2691 of the form @code{:NAME} are read as symbols, as required by R4RS.
2693 To enable and disable the alternative non-R4RS keyword syntax, you use
2694 the @code{read-options} procedure documented in @ref{General option
2695 interface} and @ref{Reader options}.
2698 (read-set! keywords 'prefix)
2708 (read-set! keywords #f)
2716 ERROR: In expression :type:
2717 ERROR: Unbound variable: :type
2718 ABORT: (unbound-variable)
2721 @node Keyword Primitives
2722 @subsection Keyword Primitives
2724 Internally, a keyword is implemented as something like a tagged symbol,
2725 where the tag identifies the keyword as being self-evaluating, and the
2726 symbol, known as the keyword's @dfn{dash symbol} has the same name as
2727 the keyword name but prefixed by a single dash. For example, the
2728 keyword @code{#:name} has the corresponding dash symbol @code{-name}.
2730 Most keyword objects are constructed automatically by the reader when it
2731 reads a token beginning with @code{#:}. However, if you need to
2732 construct a keyword object programmatically, you can do so by calling
2733 @code{make-keyword-from-dash-symbol} with the corresponding dash symbol
2734 (as the reader does). The dash symbol for a keyword object can be
2735 retrieved using the @code{keyword-dash-symbol} procedure.
2737 @deffn primitive make-keyword-from-dash-symbol symbol
2738 Make a keyword object from a @var{symbol} that starts with a dash.
2741 @deffn primitive keyword? obj
2742 Return @code{#t} if the argument @var{obj} is a keyword, else
2746 @deffn primitive keyword-dash-symbol keyword
2747 Return the dash symbol for @var{keyword}.
2748 This is the inverse of @code{make-keyword-from-dash-symbol}.
2755 @c FIXME::martin: Review me!
2757 Pairs are used to combine two Scheme objects into one compound object.
2758 Hence the name: A pair stores a pair of objects.
2760 The data type @emph{pair} is extremely important in Scheme, just like in
2761 any other Lisp dialect. The reason is that pairs are not only used to
2762 make two values available as one object, but that pairs are used for
2763 constructing lists of values. Because lists are so important in Scheme,
2764 they are described in a section of their own (@pxref{Lists}).
2766 Pairs can literally get entered in source code or at the REPL, in the
2767 so-called @dfn{dotted list} syntax. This syntax consists of an opening
2768 parentheses, the first element of the pair, a dot, the second element
2769 and a closing parentheses. The following example shows how a pair
2770 consisting of the two numbers 1 and 2, and a pair containing the symbols
2771 @code{foo} and @code{bar} can be entered. It is very important to write
2772 the whitespace before and after the dot, because otherwise the Scheme
2773 parser whould not be able to figure out where to split the tokens.
2780 But beware, if you want to try out these examples, you have to
2781 @dfn{quote} the expressions. More information about quotation is
2782 available in the section (REFFIXME). The correct way to try these
2783 examples is as follows.
2794 A new pair is made by calling the procedure @code{cons} with two
2795 arguments. Then the argument values are stored into a newly allocated
2796 pair, and the pair is returned. The name @code{cons} stands for
2797 @emph{construct}. Use the procedure @code{pair?} to test whether a
2798 given Scheme object is a pair or not.
2801 @deffn primitive cons x y
2802 Return a newly allocated pair whose car is @var{x} and whose
2803 cdr is @var{y}. The pair is guaranteed to be different (in the
2804 sense of @code{eq?}) from every previously existing object.
2808 @deffn primitive pair? x
2809 Return @code{#t} if @var{x} is a pair; otherwise return
2813 The two parts of a pair are traditionally called @emph{car} and
2814 @emph{cdr}. They can be retrieved with procedures of the same name
2815 (@code{car} and @code{cdr}), and can be modified with the procedures
2816 @code{set-car!} and @code{set-cdr!}. Since a very common operation in
2817 Scheme programs is to access the car of a pair, or the car of the cdr of
2818 a pair, etc., the procedures called @code{caar}, @code{cadr} and so on
2819 are also predefined.
2823 @deffn primitive car pair
2824 @deffnx primitive cdr pair
2825 Return the car or the cdr of @var{pair}, respectively.
2828 @deffn primitive caar pair
2829 @deffnx primitive cadr pair @dots{}
2830 @deffnx primitive cdddar pair
2831 @deffnx primitive cddddr pair
2832 These procedures are compositions of @code{car} and @code{cdr}, where
2833 for example @code{caddr} could be defined by
2836 (define caddr (lambda (x) (car (cdr (cdr x)))))
2841 @deffn primitive set-car! pair value
2842 Stores @var{value} in the car field of @var{pair}. The value returned
2843 by @code{set-car!} is unspecified.
2847 @deffn primitive set-cdr! pair value
2848 Stores @var{value} in the cdr field of @var{pair}. The value returned
2849 by @code{set-cdr!} is unspecified.
2856 @c FIXME::martin: Review me!
2858 A very important data type in Scheme---as well as in all other Lisp
2859 dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
2860 Scheme does not have a real datatype @emph{list}. Lists are made up of
2861 chained @emph{pairs}, and only exist by definition---a list is a chain
2862 of pairs which looks like a list.}
2864 This is the short definition of what a list is:
2868 Either the empty list @code{()},
2871 or a pair which has a list in its cdr.
2874 @c FIXME::martin: Describe the pair chaining in more detail.
2876 @c FIXME::martin: What is a proper, what an improper list?
2877 @c What is a circular list?
2879 @c FIXME::martin: Maybe steal some graphics from the Elisp reference
2883 * List Syntax:: Writing literal lists.
2884 * List Predicates:: Testing lists.
2885 * List Constructors:: Creating new lists.
2886 * List Selection:: Selecting from lists, getting their length.
2887 * Append/Reverse:: Appending and reversing lists.
2888 * List Modifification:: Modifying list structure.
2889 * List Searching:: Searching for list elements
2890 * List Mapping:: Applying procedures to lists.
2894 @subsection List Read Syntax
2896 @c FIXME::martin: Review me!
2898 The syntax for lists is an opening parentheses, then all the elements of
2899 the list (separated by whitespace) and finally a closing
2900 parentheses.@footnote{Note that there is no separation character between
2901 the list elements, like a comma or a semicolon.}.
2904 (1 2 3) ; @r{a list of the numbers 1, 2 and 3}
2905 ("foo" bar 3.1415) ; @r{a string, a symbol and a real number}
2906 () ; @r{the empty list}
2909 The last example needs a bit more explanation. A list with no elements,
2910 called the @dfn{empty list}, is special in some ways. It is used for
2911 terminating lists by storing it into the cdr of the last pair that makes
2912 up a list. An example will clear that up:
2923 This example also shows that lists have to be quoted (REFFIXME) when
2924 written, because they would otherwise be mistakingly taken as procedure
2925 applications (REFFIXME).
2928 @node List Predicates
2929 @subsection List Predicates
2931 @c FIXME::martin: Review me!
2933 Often it is useful to test whether a given Scheme object is a list or
2934 not. List--processing procedures could use this information to test
2935 whether their input is valid, or they could do different things
2936 depending on the datatype of their arguments.
2939 @deffn primitive list? x
2940 Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
2943 The predicate @code{null?} is often used in list--processing code to
2944 tell whether a given list has run out of elements. That is, a loop
2945 somehow deals with the elements of a list until the list satisfies
2946 @code{null?}. Then, teh algorithm terminates.
2949 @deffn primitive null? x
2950 Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
2953 @node List Constructors
2954 @subsection List Constructors
2956 This section describes the procedures for constructing new lists.
2957 @code{list} simply returns a list where the elements are the arguments,
2958 @code{cons*} is similar, but the last argument is stored in the cdr of
2959 the last pair of the list.
2962 @deffn primitive list arg1 @dots{}
2963 Return a list containing @var{objs}, the arguments to
2967 @deffn primitive cons* arg1 arg2 @dots{}
2968 Like @code{list}, but the last arg provides the tail of the
2969 constructed list, returning @code{(cons @var{arg1} (cons
2970 @var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
2971 argument. If given one argument, that argument is returned as
2972 result. This function is called @code{list*} in some other
2973 Schemes and in Common LISP.
2976 @deffn primitive list-copy lst
2977 Return a (newly-created) copy of @var{lst}.
2980 Note that @code{list-copy} only makes a copy of the pairs which make up
2981 the spine of the lists. The list elements are not copied, which means
2982 that modifying the elements of the new list also modyfies the elements
2983 of the old list. On the other hand, applying procedures like
2984 @code{set-cdr!} or @code{delv!} to the new list will not alter the old
2985 list. If you also need to copy the list elements (making a deep copy),
2986 use the procedure @code{copy-tree} (REFFIXME).
2988 @node List Selection
2989 @subsection List Selection
2991 @c FIXME::martin: Review me!
2993 These procedures are used to get some information about a list, or to
2994 retrieve one or more elements of a list.
2997 @deffn primitive length lst
2998 Return the number of elements in list @var{lst}.
3001 @deffn primitive last-pair lst
3002 Return a pointer to the last pair in @var{lst}, signalling an error if
3003 @var{lst} is circular.
3007 @deffn primitive list-ref list k
3008 Return the @var{k}th element from @var{list}.
3012 @deffn primitive list-tail lst k
3013 @deffnx primitive list-cdr-ref lst k
3014 Return the "tail" of @var{lst} beginning with its @var{k}th element.
3015 The first element of the list is considered to be element 0.
3017 @code{list-tail} and @code{list-cdr-ref} are identical. It may help to
3018 think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
3019 or returning the results of cdring @var{k} times down @var{lst}.
3022 @deffn primitive list-head lst k
3023 Copy the first @var{k} elements from @var{lst} into a new list, and
3027 @node Append/Reverse
3028 @subsection Append and Reverse
3030 @c FIXME::martin: Review me!
3032 @code{append} and @code{append!} are used to concatenate two or more
3033 lists in order to form a new list. @code{reverse} and @code{reverse!}
3034 return lists with the same elements as their arguments, but in reverse
3035 order. The procedure variants with an @code{!} directly modify the
3036 pairs which form the list, whereas the other procedures create new
3037 pairs. This is why you should be careful when using the side--effecting
3041 @deffn primitive append . args
3042 Return a list consisting of the elements the lists passed as
3045 (append '(x) '(y)) @result{} (x y)
3046 (append '(a) '(b c d)) @result{} (a b c d)
3047 (append '(a (b)) '((c))) @result{} (a (b) (c))
3049 The resulting list is always newly allocated, except that it
3050 shares structure with the last list argument. The last
3051 argument may actually be any object; an improper list results
3052 if the last argument is not a proper list.
3054 (append '(a b) '(c . d)) @result{} (a b c . d)
3055 (append '() 'a) @result{} a
3059 @deffn primitive append! . lists
3060 A destructive version of @code{append} (@pxref{Pairs and
3061 Lists,,,r4rs, The Revised^4 Report on Scheme}). The cdr field
3062 of each list's final pair is changed to point to the head of
3063 the next list, so no consing is performed. Return a pointer to
3068 @deffn primitive reverse lst
3069 Return a new list that contains the elements of @var{lst} but
3073 @c NJFIXME explain new_tail
3074 @deffn primitive reverse! lst [new_tail]
3075 A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r4rs,
3076 The Revised^4 Report on Scheme}). The cdr of each cell in @var{lst} is
3077 modified to point to the previous list element. Return a pointer to the
3078 head of the reversed list.
3080 Caveat: because the list is modified in place, the tail of the original
3081 list now becomes its head, and the head of the original list now becomes
3082 the tail. Therefore, the @var{lst} symbol to which the head of the
3083 original list was bound now points to the tail. To ensure that the head
3084 of the modified list is not lost, it is wise to save the return value of
3088 @node List Modifification
3089 @subsection List Modification
3091 @c FIXME::martin: Review me!
3093 The following procedures modify existing list. @code{list-set!} and
3094 @code{list-cdr-set!} change which elements a list contains, the various
3095 deletion procedures @code{delq}, @code{delv} etc.
3097 @deffn primitive list-set! list k val
3098 Set the @var{k}th element of @var{list} to @var{val}.
3101 @deffn primitive list-cdr-set! list k val
3102 Set the @var{k}th cdr of @var{list} to @var{val}.
3105 @deffn primitive delq item lst
3106 Return a newly-created copy of @var{lst} with elements
3107 @code{eq?} to @var{item} removed. This procedure mirrors
3108 @code{memq}: @code{delq} compares elements of @var{lst} against
3109 @var{item} with @code{eq?}.
3112 @deffn primitive delv item lst
3113 Return a newly-created copy of @var{lst} with elements
3114 @code{eqv?} to @var{item} removed. This procedure mirrors
3115 @code{memv}: @code{delv} compares elements of @var{lst} against
3116 @var{item} with @code{eqv?}.
3119 @deffn primitive delete item lst
3120 Return a newly-created copy of @var{lst} with elements
3121 @code{equal?} to @var{item} removed. This procedure mirrors
3122 @code{member}: @code{delete} compares elements of @var{lst}
3123 against @var{item} with @code{equal?}.
3126 @deffn primitive delq! item lst
3127 @deffnx primitive delv! item lst
3128 @deffnx primitive delete! item lst
3129 These procedures are destructive versions of @code{delq}, @code{delv}
3130 and @code{delete}: they modify the pointers in the existing @var{lst}
3131 rather than creating a new list. Caveat evaluator: Like other
3132 destructive list functions, these functions cannot modify the binding of
3133 @var{lst}, and so cannot be used to delete the first element of
3134 @var{lst} destructively.
3137 @deffn primitive delq1! item lst
3138 Like @code{delq!}, but only deletes the first occurrence of
3139 @var{item} from @var{lst}. Tests for equality using
3140 @code{eq?}. See also @code{delv1!} and @code{delete1!}.
3143 @deffn primitive delv1! item lst
3144 Like @code{delv!}, but only deletes the first occurrence of
3145 @var{item} from @var{lst}. Tests for equality using
3146 @code{eqv?}. See also @code{delq1!} and @code{delete1!}.
3149 @deffn primitive delete1! item lst
3150 Like @code{delete!}, but only deletes the first occurrence of
3151 @var{item} from @var{lst}. Tests for equality using
3152 @code{equal?}. See also @code{delq1!} and @code{delv1!}.
3155 @node List Searching
3156 @subsection List Searching
3158 @c FIXME::martin: Review me!
3160 The following procedures search lists for particular elements. They use
3161 different comparison predicates for comparing list elements with the
3162 object to be seached. When they fail, they return @code{#f}, otherwise
3163 they return the sublist whose car is equal to the search object, where
3164 equality depends on the equality predicate used.
3167 @deffn primitive memq x lst
3168 Return the first sublist of @var{lst} whose car is @code{eq?}
3169 to @var{x} where the sublists of @var{lst} are the non-empty
3170 lists returned by @code{(list-tail @var{lst} @var{k})} for
3171 @var{k} less than the length of @var{lst}. If @var{x} does not
3172 occur in @var{lst}, then @code{#f} (not the empty list) is
3177 @deffn primitive memv x lst
3178 Return the first sublist of @var{lst} whose car is @code{eqv?}
3179 to @var{x} where the sublists of @var{lst} are the non-empty
3180 lists returned by @code{(list-tail @var{lst} @var{k})} for
3181 @var{k} less than the length of @var{lst}. If @var{x} does not
3182 occur in @var{lst}, then @code{#f} (not the empty list) is
3187 @deffn primitive member x lst
3188 Return the first sublist of @var{lst} whose car is
3189 @code{equal?} to @var{x} where the sublists of @var{lst} are
3190 the non-empty lists returned by @code{(list-tail @var{lst}
3191 @var{k})} for @var{k} less than the length of @var{lst}. If
3192 @var{x} does not occur in @var{lst}, then @code{#f} (not the
3193 empty list) is returned.
3196 [FIXME: is there any reason to have the `sloppy' functions available at
3197 high level at all? Maybe these docs should be relegated to a "Guile
3198 Internals" node or something. -twp]
3200 @deffn primitive sloppy-memq x lst
3201 This procedure behaves like @code{memq}, but does no type or error checking.
3202 Its use is recommended only in writing Guile internals,
3203 not for high-level Scheme programs.
3206 @deffn primitive sloppy-memv x lst
3207 This procedure behaves like @code{memv}, but does no type or error checking.
3208 Its use is recommended only in writing Guile internals,
3209 not for high-level Scheme programs.
3212 @deffn primitive sloppy-member x lst
3213 This procedure behaves like @code{member}, but does no type or error checking.
3214 Its use is recommended only in writing Guile internals,
3215 not for high-level Scheme programs.
3219 @subsection List Mapping
3221 @c FIXME::martin: Review me!
3223 List processing is very convenient in Scheme because the process of
3224 iterating over the elements of a list can be highly abstracted. The
3225 procedures in this section are the most basic iterating procedures for
3226 lists. They take a procedure and one or more lists as arguments, and
3227 apply the procedure to each element of the list. They differ in what
3228 the result of the invocation is.
3231 @c begin (texi-doc-string "guile" "map")
3232 @deffn primitive map proc arg1 arg2 @dots{}
3233 @deffnx primitive map-in-order proc arg1 arg2 @dots{}
3234 Apply @var{proc} to each element of the list @var{arg1} (if only two
3235 arguments are given), or to the corresponding elements of the argument
3236 lists (if more than two arguments are given). The result(s) of the
3237 procedure applications are saved and returned in a list. For
3238 @code{map}, the order of procedure applications is not specified,
3239 @code{map-in-order} applies the procedure from left to right to the list
3244 @c begin (texi-doc-string "guile" "for-each")
3245 @deffn primitive for-each proc arg1 arg2 @dots{}
3246 Like @code{map}, but the procedure is always applied from left to right,
3247 and the result(s) of the procedure applications are thrown away. The
3248 return value is not specified.
3255 [FIXME: this is pasted in from Tom Lord's original guile.texi and should
3258 A @dfn{record type} is a first class object representing a user-defined
3259 data type. A @dfn{record} is an instance of a record type.
3261 @deffn procedure record? obj
3262 Returns @code{#t} if @var{obj} is a record of any type and @code{#f}
3265 Note that @code{record?} may be true of any Scheme value; there is no
3266 promise that records are disjoint with other Scheme types.
3269 @deffn procedure make-record-type type-name field-names
3270 Returns a @dfn{record-type descriptor}, a value representing a new data
3271 type disjoint from all others. The @var{type-name} argument must be a
3272 string, but is only used for debugging purposes (such as the printed
3273 representation of a record of the new type). The @var{field-names}
3274 argument is a list of symbols naming the @dfn{fields} of a record of the
3275 new type. It is an error if the list contains any duplicates. It is
3276 unspecified how record-type descriptors are represented.@refill
3279 @deffn procedure record-constructor rtd [field-names]
3280 Returns a procedure for constructing new members of the type represented
3281 by @var{rtd}. The returned procedure accepts exactly as many arguments
3282 as there are symbols in the given list, @var{field-names}; these are
3283 used, in order, as the initial values of those fields in a new record,
3284 which is returned by the constructor procedure. The values of any
3285 fields not named in that list are unspecified. The @var{field-names}
3286 argument defaults to the list of field names in the call to
3287 @code{make-record-type} that created the type represented by @var{rtd};
3288 if the @var{field-names} argument is provided, it is an error if it
3289 contains any duplicates or any symbols not in the default list.@refill
3292 @deffn procedure record-predicate rtd
3293 Returns a procedure for testing membership in the type represented by
3294 @var{rtd}. The returned procedure accepts exactly one argument and
3295 returns a true value if the argument is a member of the indicated record
3296 type; it returns a false value otherwise.@refill
3299 @deffn procedure record-accessor rtd field-name
3300 Returns a procedure for reading the value of a particular field of a
3301 member of the type represented by @var{rtd}. The returned procedure
3302 accepts exactly one argument which must be a record of the appropriate
3303 type; it returns the current value of the field named by the symbol
3304 @var{field-name} in that record. The symbol @var{field-name} must be a
3305 member of the list of field-names in the call to @code{make-record-type}
3306 that created the type represented by @var{rtd}.@refill
3309 @deffn procedure record-modifier rtd field-name
3310 Returns a procedure for writing the value of a particular field of a
3311 member of the type represented by @var{rtd}. The returned procedure
3312 accepts exactly two arguments: first, a record of the appropriate type,
3313 and second, an arbitrary Scheme value; it modifies the field named by
3314 the symbol @var{field-name} in that record to contain the given value.
3315 The returned value of the modifier procedure is unspecified. The symbol
3316 @var{field-name} must be a member of the list of field-names in the call
3317 to @code{make-record-type} that created the type represented by
3321 @deffn procedure record-type-descriptor record
3322 Returns a record-type descriptor representing the type of the given
3323 record. That is, for example, if the returned descriptor were passed to
3324 @code{record-predicate}, the resulting predicate would return a true
3325 value when passed the given record. Note that it is not necessarily the
3326 case that the returned descriptor is the one that was passed to
3327 @code{record-constructor} in the call that created the constructor
3328 procedure that created the given record.@refill
3331 @deffn procedure record-type-name rtd
3332 Returns the type-name associated with the type represented by rtd. The
3333 returned value is @code{eqv?} to the @var{type-name} argument given in
3334 the call to @code{make-record-type} that created the type represented by
3338 @deffn procedure record-type-fields rtd
3339 Returns a list of the symbols naming the fields in members of the type
3340 represented by @var{rtd}. The returned value is @code{equal?} to the
3341 field-names argument given in the call to @code{make-record-type} that
3342 created the type represented by @var{rtd}.@refill
3349 [FIXME: this is pasted in from Tom Lord's original guile.texi and should
3352 A @dfn{structure type} is a first class user-defined data type. A
3353 @dfn{structure} is an instance of a structure type. A structure type is
3356 Structures are less abstract and more general than traditional records.
3357 In fact, in Guile Scheme, records are implemented using structures.
3360 * Structure Concepts:: The structure of Structures
3361 * Structure Layout:: Defining the layout of structure types
3362 * Structure Basics:: make-, -ref and -set! procedures for structs
3363 * Vtables:: Accessing type-specific data
3366 @node Structure Concepts
3367 @subsection Structure Concepts
3369 A structure object consists of a handle, structure data, and a vtable.
3370 The handle is a Scheme value which points to both the vtable and the
3371 structure's data. Structure data is a dynamically allocated region of
3372 memory, private to the structure, divided up into typed fields. A
3373 vtable is another structure used to hold type-specific data. Multiple
3374 structures can share a common vtable.
3376 Three concepts are key to understanding structures.
3379 @item @dfn{layout specifications}
3381 Layout specifications determine how memory allocated to structures is
3382 divided up into fields. Programmers must write a layout specification
3383 whenever a new type of structure is defined.
3385 @item @dfn{structural accessors}
3387 Structure access is by field number. There is only one set of
3388 accessors common to all structure objects.
3392 Vtables, themselves structures, are first class representations of
3393 disjoint sub-types of structures in general. In most cases, when a
3394 new structure is created, programmers must specifiy a vtable for the
3395 new structure. Each vtable has a field describing the layout of its
3396 instances. Vtables can have additional, user-defined fields as well.
3401 @node Structure Layout
3402 @subsection Structure Layout
3404 When a structure is created, a region of memory is allocated to hold its
3405 state. The @dfn{layout} of the structure's type determines how that
3406 memory is divided into fields.
3408 Each field has a specified type. There are only three types allowed, each
3409 corresponding to a one letter code. The allowed types are:
3412 @item 'u' -- unprotected
3414 The field holds binary data that is not GC protected.
3416 @item 'p' -- protected
3418 The field holds a Scheme value and is GC protected.
3422 The field holds a Scheme value and is GC protected. When a structure is
3423 created with this type of field, the field is initialized to refer to
3424 the structure's own handle. This kind of field is mainly useful when
3425 mixing Scheme and C code in which the C code may need to compute a
3426 structure's handle given only the address of its malloced data.
3430 Each field also has an associated access protection. There are only
3431 three kinds of protection, each corresponding to a one letter code.
3432 The allowed protections are:
3435 @item 'w' -- writable
3437 The field can be read and written.
3439 @item 'r' -- readable
3441 The field can be read, but not written.
3445 The field can be neither read nor written. This kind
3446 of protection is for fields useful only to built-in routines.
3449 A layout specification is described by stringing together pairs
3450 of letters: one to specify a field type and one to specify a field
3451 protection. For example, a traditional cons pair type object could
3455 ; cons pairs have two writable fields of Scheme data
3459 A pair object in which the first field is held constant could be:
3465 Binary fields, (fields of type "u"), hold one @emph{word} each. The
3466 size of a word is a machine dependent value defined to be equal to the
3467 value of the C expression: @code{sizeof (long)}.
3469 The last field of a structure layout may specify a tail array.
3470 A tail array is indicated by capitalizing the field's protection
3471 code ('W', 'R' or 'O'). A tail-array field is replaced by
3472 a read-only binary data field containing an array size. The array
3473 size is determined at the time the structure is created. It is followed
3474 by a corresponding number of fields of the type specified for the
3475 tail array. For example, a conventional Scheme vector can be
3479 ; A vector is an arbitrary number of writable fields holding Scheme
3484 In the above example, field 0 contains the size of the vector and
3485 fields beginning at 1 contain the vector elements.
3487 A kind of tagged vector (a constant tag followed by conventioal
3488 vector elements) might be:
3495 Structure layouts are represented by specially interned symbols whose
3496 name is a string of type and protection codes. To create a new
3497 structure layout, use this procedure:
3499 @deffn primitive make-struct-layout fields
3500 Return a new structure layout object.
3502 @var{fields} must be a string made up of pairs of characters
3503 strung together. The first character of each pair describes a field
3504 type, the second a field protection. Allowed types are 'p' for
3505 GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
3506 a field that points to the structure itself. Allowed protections
3507 are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
3508 fields. The last field protection specification may be capitalized to
3509 indicate that the field is a tail-array.
3514 @node Structure Basics
3515 @subsection Structure Basics
3517 This section describes the basic procedures for creating and accessing
3520 @deffn primitive make-struct vtable tail_array_size . init
3521 Create a new structure.
3523 @var{type} must be a vtable structure (@pxref{Vtables}).
3525 @var{tail-elts} must be a non-negative integer. If the layout
3526 specification indicated by @var{type} includes a tail-array,
3527 this is the number of elements allocated to that array.
3529 The @var{init1}, @dots{} are optional arguments describing how
3530 successive fields of the structure should be initialized. Only fields
3531 with protection 'r' or 'w' can be initialized, except for fields of
3532 type 's', which are automatically initialized to point to the new
3533 structure itself; fields with protection 'o' can not be initialized by
3536 If fewer optional arguments than initializable fields are supplied,
3537 fields of type 'p' get default value #f while fields of type 'u' are
3540 Structs are currently the basic representation for record-like data
3541 structures in Guile. The plan is to eventually replace them with a
3542 new representation which will at the same time be easier to use and
3545 For more information, see the documentation for @code{make-vtable-vtable}.
3548 @deffn primitive struct? x
3549 Return @code{#t} iff @var{obj} is a structure object, else
3554 @deffn primitive struct-ref handle pos
3555 @deffnx primitive struct-set! struct n value
3556 Access (or modify) the @var{n}th field of @var{struct}.
3558 If the field is of type 'p', then it can be set to an arbitrary value.
3560 If the field is of type 'u', then it can only be set to a non-negative
3561 integer value small enough to fit in one machine word.
3569 Vtables are structures that are used to represent structure types. Each
3570 vtable contains a layout specification in field
3571 @code{vtable-index-layout} -- instances of the type are laid out
3572 according to that specification. Vtables contain additional fields
3573 which are used only internally to libguile. The variable
3574 @code{vtable-offset-user} is bound to a field number. Vtable fields
3575 at that position or greater are user definable.
3577 @deffn primitive struct-vtable handle
3578 Return the vtable structure that describes the type of @var{struct}.
3581 @deffn primitive struct-vtable? x
3582 Return @code{#t} iff obj is a vtable structure.
3585 If you have a vtable structure, @code{V}, you can create an instance of
3586 the type it describes by using @code{(make-struct V ...)}. But where
3587 does @code{V} itself come from? One possibility is that @code{V} is an
3588 instance of a user-defined vtable type, @code{V'}, so that @code{V} is
3589 created by using @code{(make-struct V' ...)}. Another possibility is
3590 that @code{V} is an instance of the type it itself describes. Vtable
3591 structures of the second sort are created by this procedure:
3593 @deffn primitive make-vtable-vtable user_fields tail_array_size . init
3594 Return a new, self-describing vtable structure.
3596 @var{user-fields} is a string describing user defined fields of the
3597 vtable beginning at index @code{vtable-offset-user}
3598 (see @code{make-struct-layout}).
3600 @var{tail-size} specifies the size of the tail-array (if any) of
3603 @var{init1}, @dots{} are the optional initializers for the fields of
3606 Vtables have one initializable system field---the struct printer.
3607 This field comes before the user fields in the initializers passed
3608 to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
3609 a third optional argument to @code{make-vtable-vtable} and a fourth to
3610 @code{make-struct} when creating vtables:
3612 If the value is a procedure, it will be called instead of the standard
3613 printer whenever a struct described by this vtable is printed.
3614 The procedure will be called with arguments STRUCT and PORT.
3616 The structure of a struct is described by a vtable, so the vtable is
3617 in essence the type of the struct. The vtable is itself a struct with
3618 a vtable. This could go on forever if it weren't for the
3619 vtable-vtables which are self-describing vtables, and thus terminate
3622 There are several potential ways of using structs, but the standard
3623 one is to use three kinds of structs, together building up a type
3624 sub-system: one vtable-vtable working as the root and one or several
3625 "types", each with a set of "instances". (The vtable-vtable should be
3626 compared to the class <class> which is the class of itself.)
3629 (define ball-root (make-vtable-vtable "pr" 0))
3631 (define (make-ball-type ball-color)
3632 (make-struct ball-root 0
3633 (make-struct-layout "pw")
3635 (format port "#<a ~A ball owned by ~A>"
3639 (define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
3640 (define (owner ball) (struct-ref ball 0))
3642 (define red (make-ball-type 'red))
3643 (define green (make-ball-type 'green))
3645 (define (make-ball type owner) (make-struct type 0 owner))
3647 (define ball (make-ball green 'Nisse))
3648 ball @result{} #<a green ball owned by Nisse>
3652 @deffn primitive struct-vtable-name vtable
3653 Return the name of the vtable @var{vtable}.
3656 @deffn primitive set-struct-vtable-name! vtable name
3657 Set the name of the vtable @var{vtable} to @var{name}.
3660 @deffn primitive struct-vtable-tag handle
3661 Return the vtable tag of the structure @var{handle}.
3669 * Conventional Arrays:: Arrays with arbitrary data.
3670 * Array Mapping:: Applying a procedure to the contents of an array.
3671 * Uniform Arrays:: Arrays with data of a single type.
3672 * Bit Vectors:: Vectors of bits.
3675 @node Conventional Arrays
3676 @subsection Conventional Arrays
3678 @dfn{Conventional arrays} are a collection of cells organised into an
3679 arbitrary number of dimensions. Each cell can hold any kind of Scheme
3680 value and can be accessed in constant time by supplying an index for
3681 each dimension. This contrasts with uniform arrays, which use memory
3682 more efficiently but can hold data of only a single type, and lists
3683 where inserting and deleting cells is more efficient, but more time
3684 is usually required to access a particular cell.
3686 A conventional array is displayed as @code{#} followed by the @dfn{rank}
3687 (number of dimensions) followed by the cells, organised into dimensions
3688 using parentheses. The nesting depth of the parentheses is equal to
3691 When an array is created, the number of dimensions and range of each
3692 dimension must be specified, e.g., to create a 2x3 array with a
3696 (make-array 'ho 2 3) @result{}
3697 #2((ho ho ho) (ho ho ho))
3700 The range of each dimension can also be given explicitly, e.g., another
3701 way to create the same array:
3704 (make-array 'ho '(0 1) '(0 2)) @result{}
3705 #2((ho ho ho) (ho ho ho))
3708 A conventional array with one dimension based at zero is identical to
3712 (make-array 'ho 3) @result{}
3716 The following procedures can be used with conventional arrays (or vectors).
3718 @deffn primitive array? v [prot]
3719 Return @code{#t} if the @var{obj} is an array, and @code{#f} if
3720 not. The @var{prototype} argument is used with uniform arrays
3721 and is described elsewhere.
3724 @deffn procedure make-array initial-value bound1 bound2 @dots{}
3725 Creates and returns an array that has as many dimensions as there are
3726 @var{bound}s and fills it with @var{initial-value}.
3729 @c array-ref's type is `compiled-closure'. There's some weird stuff
3730 @c going on in array.c, too. Let's call it a primitive. -twp
3732 @deffn primitive uniform-vector-ref v args
3733 @deffnx primitive array-ref v . args
3734 Return the element at the @code{(index1, index2)} element in
3738 @deffn primitive array-in-bounds? v . args
3739 Return @code{#t} if its arguments would be acceptable to
3743 @deffn primitive array-set! v obj . args
3744 @deffnx primitive uniform-array-set1! v obj args
3745 Sets the element at the @code{(index1, index2)} element in @var{array} to
3746 @var{new-value}. The value returned by array-set! is unspecified.
3749 @deffn primitive make-shared-array oldra mapfunc . dims
3750 @code{make-shared-array} can be used to create shared subarrays of other
3751 arrays. The @var{mapper} is a function that translates coordinates in
3752 the new array into coordinates in the old array. A @var{mapper} must be
3753 linear, and its range must stay within the bounds of the old array, but
3754 it can be otherwise arbitrary. A simple example:
3756 (define fred (make-array #f 8 8))
3757 (define freds-diagonal
3758 (make-shared-array fred (lambda (i) (list i i)) 8))
3759 (array-set! freds-diagonal 'foo 3)
3760 (array-ref fred 3 3) @result{} foo
3761 (define freds-center
3762 (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
3763 (array-ref freds-center 0 0) @result{} foo
3767 @deffn primitive shared-array-increments ra
3768 For each dimension, return the distance between elements in the root vector.
3771 @deffn primitive shared-array-offset ra
3772 Return the root vector index of the first element in the array.
3775 @deffn primitive shared-array-root ra
3776 Return the root vector of a shared array.
3779 @deffn primitive transpose-array ra . args
3780 Return an array sharing contents with @var{array}, but with
3781 dimensions arranged in a different order. There must be one
3782 @var{dim} argument for each dimension of @var{array}.
3783 @var{dim0}, @var{dim1}, @dots{} should be integers between 0
3784 and the rank of the array to be returned. Each integer in that
3785 range must appear at least once in the argument list.
3786 The values of @var{dim0}, @var{dim1}, @dots{} correspond to
3787 dimensions in the array to be returned, their positions in the
3788 argument list to dimensions of @var{array}. Several @var{dim}s
3789 may have the same value, in which case the returned array will
3790 have smaller rank than @var{array}.
3792 (transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
3793 (transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
3794 (transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
3795 #2((a 4) (b 5) (c 6))
3799 @deffn primitive enclose-array ra . axes
3800 @var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
3801 the rank of @var{array}. @var{enclose-array} returns an array
3802 resembling an array of shared arrays. The dimensions of each shared
3803 array are the same as the @var{dim}th dimensions of the original array,
3804 the dimensions of the outer array are the same as those of the original
3805 array that did not match a @var{dim}.
3807 An enclosed array is not a general Scheme array. Its elements may not
3808 be set using @code{array-set!}. Two references to the same element of
3809 an enclosed array will be @code{equal?} but will not in general be
3810 @code{eq?}. The value returned by @var{array-prototype} when given an
3811 enclosed array is unspecified.
3815 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
3816 #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
3818 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
3819 #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
3823 @deffn procedure array-shape array
3824 Returns a list of inclusive bounds of integers.
3826 (array-shape (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) (0 4))
3830 @deffn primitive array-dimensions ra
3831 @code{Array-dimensions} is similar to @code{array-shape} but replaces
3832 elements with a @code{0} minimum with one greater than the maximum. So:
3834 (array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
3838 @deffn primitive array-rank ra
3839 Return the number of dimensions of @var{obj}. If @var{obj} is
3840 not an array, @code{0} is returned.
3843 @deffn primitive array->list v
3844 Return a list consisting of all the elements, in order, of
3848 @deffn primitive array-copy! src dst
3849 @deffnx primitive array-copy-in-order! src dst
3850 Copies every element from vector or array @var{source} to the
3851 corresponding element of @var{destination}. @var{destination} must have
3852 the same rank as @var{source}, and be at least as large in each
3853 dimension. The order is unspecified.
3856 @deffn primitive array-fill! ra fill
3857 Stores @var{fill} in every element of @var{array}. The value returned
3861 @c begin (texi-doc-string "guile" "array-equal?")
3862 @deffn primitive array-equal? ra0 ra1
3863 Returns @code{#t} iff all arguments are arrays with the same shape, the
3864 same type, and have corresponding elements which are either
3865 @code{equal?} or @code{array-equal?}. This function differs from
3866 @code{equal?} in that a one dimensional shared array may be
3867 @var{array-equal?} but not @var{equal?} to a vector or uniform vector.
3870 @deffn primitive array-contents ra [strict]
3871 @deffnx primitive array-contents array strict
3872 If @var{array} may be @dfn{unrolled} into a one dimensional shared array
3873 without changing their order (last subscript changing fastest), then
3874 @code{array-contents} returns that shared array, otherwise it returns
3875 @code{#f}. All arrays made by @var{make-array} and
3876 @var{make-uniform-array} may be unrolled, some arrays made by
3877 @var{make-shared-array} may not be.
3879 If the optional argument @var{strict} is provided, a shared array will
3880 be returned only if its elements are stored internally contiguous in
3885 @subsection Array Mapping
3887 @deffn primitive array-map! ra0 proc . lra
3888 @deffnx primitive array-map-in-order! ra0 proc . lra
3889 @var{array1}, @dots{} must have the same number of dimensions as
3890 @var{array0} and have a range for each index which includes the range
3891 for the corresponding index in @var{array0}. @var{proc} is applied to
3892 each tuple of elements of @var{array1} @dots{} and the result is stored
3893 as the corresponding element in @var{array0}. The value returned is
3894 unspecified. The order of application is unspecified.
3897 @deffn primitive array-for-each proc ra0 . lra
3898 @var{proc} is applied to each tuple of elements of @var{array0} @dots{}
3899 in row-major order. The value returned is unspecified.
3902 @deffn primitive array-index-map! ra proc
3903 applies @var{proc} to the indices of each element of @var{array} in
3904 turn, storing the result in the corresponding element. The value
3905 returned and the order of application are unspecified.
3907 One can implement @var{array-indexes} as
3909 (define (array-indexes array)
3910 (let ((ra (apply make-array #f (array-shape array))))
3911 (array-index-map! ra (lambda x x))
3916 (define (apl:index-generator n)
3917 (let ((v (make-uniform-vector n 1)))
3918 (array-index-map! v (lambda (i) i))
3923 @node Uniform Arrays
3924 @subsection Uniform Arrays
3927 @dfn{Uniform arrays} have elements all of the
3928 same type and occupy less storage than conventional
3929 arrays. Uniform arrays with a single zero-based dimension
3930 are also known as @dfn{uniform vectors}. The procedures in
3931 this section can also be used on conventional arrays, vectors,
3932 bit-vectors and strings.
3935 When creating a uniform array, the type of data to be stored
3936 is indicated with a @var{prototype} argument. The following table
3937 lists the types available and example prototypes:
3940 prototype type printing character
3942 #t boolean (bit-vector) b
3944 #\nul byte (integer) y
3945 's short (integer) h
3946 1 unsigned long (integer) u
3947 -1 signed long (integer) e
3948 'l signed long long (integer) l
3949 1.0 float (single precision) s
3950 1/3 double (double precision float) i
3951 0+i complex (double precision) c
3952 () conventional vector
3956 Unshared uniform arrays of characters with a single zero-based dimension
3957 are identical to strings:
3960 (make-uniform-array #\a 3) @result{}
3965 Unshared uniform arrays of booleans with a single zero-based dimension
3966 are identical to @ref{Bit Vectors, bit-vectors}.
3969 (make-uniform-array #t 3) @result{}
3974 Other uniform vectors are written in a form similar to that of vectors,
3975 except that a single character from the above table is put between
3976 @code{#} and @code{(}. For example, a uniform vector of signed
3977 long integers is displayed in the form @code{'#e(3 5 9)}.
3979 @deffn primitive array? v [prot]
3980 Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.
3982 The @var{prototype} argument is used with uniform arrays and is described
3986 @deffn procedure make-uniform-array prototype bound1 bound2 @dots{}
3987 Creates and returns a uniform array of type corresponding to
3988 @var{prototype} that has as many dimensions as there are @var{bound}s
3989 and fills it with @var{prototype}.
3992 @deffn primitive array-prototype ra
3993 Return an object that would produce an array of the same type
3994 as @var{array}, if used as the @var{prototype} for
3995 @code{make-uniform-array}.
3998 @deffn primitive list->uniform-array ndim prot lst
3999 @deffnx procedure list->uniform-vector prot lst
4000 Return a uniform array of the type indicated by prototype
4001 @var{prot} with elements the same as those of @var{lst}.
4002 Elements must be of the appropriate type, no coercions are
4006 @deffn primitive uniform-vector-fill! uve fill
4007 Stores @var{fill} in every element of @var{uve}. The value returned is
4011 @deffn primitive uniform-vector-length v
4012 Return the number of elements in @var{uve}.
4015 @deffn primitive dimensions->uniform-array dims prot [fill]
4016 @deffnx primitive make-uniform-vector length prototype [fill]
4017 Create and return a uniform array or vector of type
4018 corresponding to @var{prototype} with dimensions @var{dims} or
4019 length @var{length}. If @var{fill} is supplied, it's used to
4020 fill the array, otherwise @var{prototype} is used.
4023 @c Another compiled-closure. -twp
4025 @deffn primitive uniform-array-read! ra [port_or_fd [start [end]]]
4026 @deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end]
4027 Attempts to read all elements of @var{ura}, in lexicographic order, as
4028 binary objects from @var{port-or-fdes}.
4029 If an end of file is encountered during
4030 uniform-array-read! the objects up to that point only are put into @var{ura}
4031 (starting at the beginning) and the remainder of the array is
4034 The optional arguments @var{start} and @var{end} allow
4035 a specified region of a vector (or linearized array) to be read,
4036 leaving the remainder of the vector unchanged.
4038 @code{uniform-array-read!} returns the number of objects read.
4039 @var{port-or-fdes} may be omitted, in which case it defaults to the value
4040 returned by @code{(current-input-port)}.
4043 @deffn primitive uniform-array-write v [port_or_fd [start [end]]]
4044 @deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end]
4045 Writes all elements of @var{ura} as binary objects to
4048 The optional arguments @var{start}
4050 a specified region of a vector (or linearized array) to be written.
4052 The number of objects actually written is returned.
4053 @var{port-or-fdes} may be
4054 omitted, in which case it defaults to the value returned by
4055 @code{(current-output-port)}.
4059 @subsection Bit Vectors
4062 Bit vectors are a specific type of uniform array: an array of booleans
4063 with a single zero-based index.
4066 They are displayed as a sequence of @code{0}s and
4067 @code{1}s prefixed by @code{#*}, e.g.,
4070 (make-uniform-vector 8 #t #f) @result{}
4073 #b(#t #f #t) @result{}
4077 @deffn primitive bit-count b bitvector
4078 Return the number of occurrences of the boolean @var{b} in
4082 @deffn primitive bit-position item v k
4083 Return the minimum index of an occurrence of @var{bool} in
4084 @var{bv} which is at least @var{k}. If no @var{bool} occurs
4085 within the specified range @code{#f} is returned.
4088 @deffn primitive bit-invert! v
4089 Modifies @var{bv} by replacing each element with its negation.
4092 @deffn primitive bit-set*! v kv obj
4093 If uve is a bit-vector @var{bv} and uve must be of the same
4094 length. If @var{bool} is @code{#t}, uve is OR'ed into
4095 @var{bv}; If @var{bool} is @code{#f}, the inversion of uve is
4096 AND'ed into @var{bv}.
4098 If uve is a unsigned integer vector all the elements of uve
4099 must be between 0 and the @code{length} of @var{bv}. The bits
4100 of @var{bv} corresponding to the indexes in uve are set to
4101 @var{bool}. The return value is unspecified.
4104 @deffn primitive bit-count* v kv obj
4107 (bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
4109 @var{bv} is not modified.
4113 @node Association Lists and Hash Tables
4114 @section Association Lists and Hash Tables
4116 This chapter discusses dictionary objects: data structures that are
4117 useful for organizing and indexing large bodies of information.
4120 * Dictionary Types:: About dictionary types; what they're good for.
4121 * Association Lists::
4125 @node Dictionary Types
4126 @subsection Dictionary Types
4128 A @dfn{dictionary} object is a data structure used to index
4129 information in a user-defined way. In standard Scheme, the main
4130 aggregate data types are lists and vectors. Lists are not really
4131 indexed at all, and vectors are indexed only by number
4132 (e.g. @code{(vector-ref foo 5)}). Often you will find it useful
4133 to index your data on some other type; for example, in a library
4134 catalog you might want to look up a book by the name of its
4135 author. Dictionaries are used to help you organize information in
4138 An @dfn{association list} (or @dfn{alist} for short) is a list of
4139 key-value pairs. Each pair represents a single quantity or
4140 object; the @code{car} of the pair is a key which is used to
4141 identify the object, and the @code{cdr} is the object's value.
4143 A @dfn{hash table} also permits you to index objects with
4144 arbitrary keys, but in a way that makes looking up any one object
4145 extremely fast. A well-designed hash system makes hash table
4146 lookups almost as fast as conventional array or vector references.
4148 Alists are popular among Lisp programmers because they use only
4149 the language's primitive operations (lists, @dfn{car}, @dfn{cdr}
4150 and the equality primitives). No changes to the language core are
4151 necessary. Therefore, with Scheme's built-in list manipulation
4152 facilities, it is very convenient to handle data stored in an
4153 association list. Also, alists are highly portable and can be
4154 easily implemented on even the most minimal Lisp systems.
4156 However, alists are inefficient, especially for storing large
4157 quantities of data. Because we want Guile to be useful for large
4158 software systems as well as small ones, Guile provides a rich set
4159 of tools for using either association lists or hash tables.
4161 @node Association Lists
4162 @subsection Association Lists
4163 @cindex Association List
4167 An association list is a conventional data structure that is often used
4168 to implement simple key-value databases. It consists of a list of
4169 entries in which each entry is a pair. The @dfn{key} of each entry is
4170 the @code{car} of the pair and the @dfn{value} of each entry is the
4174 ASSOCIATION LIST ::= '( (KEY1 . VALUE1)
4182 Association lists are also known, for short, as @dfn{alists}.
4184 The structure of an association list is just one example of the infinite
4185 number of possible structures that can be built using pairs and lists.
4186 As such, the keys and values in an association list can be manipulated
4187 using the general list structure procedures @code{cons}, @code{car},
4188 @code{cdr}, @code{set-car!}, @code{set-cdr!} and so on. However,
4189 because association lists are so useful, Guile also provides specific
4190 procedures for manipulating them.
4193 * Alist Key Equality::
4194 * Adding or Setting Alist Entries::
4195 * Retrieving Alist Entries::
4196 * Removing Alist Entries::
4197 * Sloppy Alist Functions::
4201 @node Alist Key Equality
4202 @subsubsection Alist Key Equality
4204 All of Guile's dedicated association list procedures, apart from
4205 @code{acons}, come in three flavours, depending on the level of equality
4206 that is required to decide whether an existing key in the association
4207 list is the same as the key that the procedure call uses to identify the
4212 Procedures with @dfn{assq} in their name use @code{eq?} to determine key
4216 Procedures with @dfn{assv} in their name use @code{eqv?} to determine
4220 Procedures with @dfn{assoc} in their name use @code{equal?} to
4221 determine key equality.
4224 @code{acons} is an exception because it is used to build association
4225 lists which do not require their entries' keys to be unique.
4227 @node Adding or Setting Alist Entries
4228 @subsubsection Adding or Setting Alist Entries
4230 @code{acons} adds a new entry to an association list and returns the
4231 combined association list. The combined alist is formed by consing the
4232 new entry onto the head of the alist specified in the @code{acons}
4233 procedure call. So the specified alist is not modified, but its
4234 contents become shared with the tail of the combined alist that
4235 @code{acons} returns.
4237 In the most common usage of @code{acons}, a variable holding the
4238 original association list is updated with the combined alist:
4241 (set! address-list (acons name address address-list))
4244 In such cases, it doesn't matter that the old and new values of
4245 @code{address-list} share some of their contents, since the old value is
4246 usually no longer independently accessible.
4248 Note that @code{acons} adds the specified new entry regardless of
4249 whether the alist may already contain entries with keys that are, in
4250 some sense, the same as that of the new entry. Thus @code{acons} is
4251 ideal for building alists where there is no concept of key uniqueness.
4254 (set! task-list (acons 3 "pay gas bill" '()))
4257 ((3 . "pay gas bill"))
4259 (set! task-list (acons 3 "tidy bedroom" task-list))
4262 ((3 . "tidy bedroom") (3 . "pay gas bill"))
4265 @code{assq-set!}, @code{assv-set!} and @code{assoc-set!} are used to add
4266 or replace an entry in an association list where there @emph{is} a
4267 concept of key uniqueness. If the specified association list already
4268 contains an entry whose key is the same as that specified in the
4269 procedure call, the existing entry is replaced by the new one.
4270 Otherwise, the new entry is consed onto the head of the old association
4271 list to create the combined alist. In all cases, these procedures
4272 return the combined alist.
4274 @code{assq-set!} and friends @emph{may} destructively modify the
4275 structure of the old association list in such a way that an existing
4276 variable is correctly updated without having to @code{set!} it to the
4282 (("mary" . "34 Elm Road") ("james" . "16 Bow Street"))
4284 (assoc-set! address-list "james" "1a London Road")
4286 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
4290 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
4296 (assoc-set! address-list "bob" "11 Newington Avenue")
4298 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
4299 ("james" . "1a London Road"))
4303 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
4306 The only safe way to update an association list variable when adding or
4307 replacing an entry like this is to @code{set!} the variable to the
4312 (assoc-set! address-list "bob" "11 Newington Avenue"))
4315 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
4316 ("james" . "1a London Road"))
4319 Because of this slight inconvenience, you may find it more convenient to
4320 use hash tables to store dictionary data. If your application will not
4321 be modifying the contents of an alist very often, this may not make much
4324 If you need to keep the old value of an association list in a form
4325 independent from the list that results from modification by
4326 @code{acons}, @code{assq-set!}, @code{assv-set!} or @code{assoc-set!},
4327 use @code{list-copy} to copy the old association list before modifying
4330 @deffn primitive acons key value alist
4331 Adds a new key-value pair to @var{alist}. A new pair is
4332 created whose car is @var{key} and whose cdr is @var{value}, and the
4333 pair is consed onto @var{alist}, and the new list is returned. This
4334 function is @emph{not} destructive; @var{alist} is not modified.
4337 @deffn primitive assq-set! alist key val
4338 @deffnx primitive assv-set! alist key value
4339 @deffnx primitive assoc-set! alist key value
4340 Reassociate @var{key} in @var{alist} with @var{value}: find any existing
4341 @var{alist} entry for @var{key} and associate it with the new
4342 @var{value}. If @var{alist} does not contain an entry for @var{key},
4343 add a new one. Return the (possibly new) alist.
4345 These functions do not attempt to verify the structure of @var{alist},
4346 and so may cause unusual results if passed an object that is not an
4350 @node Retrieving Alist Entries
4351 @subsubsection Retrieving Alist Entries
4356 @code{assq}, @code{assv} and @code{assoc} take an alist and a key as
4357 arguments and return the entry for that key if an entry exists, or
4358 @code{#f} if there is no entry for that key. Note that, in the cases
4359 where an entry exists, these procedures return the complete entry, that
4360 is @code{(KEY . VALUE)}, not just the value.
4362 @deffn primitive assq key alist
4363 @deffnx primitive assv key alist
4364 @deffnx primitive assoc key alist
4365 Fetches the entry in @var{alist} that is associated with @var{key}. To
4366 decide whether the argument @var{key} matches a particular entry in
4367 @var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
4368 uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
4369 cannot be found in @var{alist} (according to whichever equality
4370 predicate is in use), then @code{#f} is returned. These functions
4371 return the entire alist entry found (i.e. both the key and the value).
4374 @code{assq-ref}, @code{assv-ref} and @code{assoc-ref}, on the other
4375 hand, take an alist and a key and return @emph{just the value} for that
4376 key, if an entry exists. If there is no entry for the specified key,
4377 these procedures return @code{#f}.
4379 This creates an ambiguity: if the return value is @code{#f}, it means
4380 either that there is no entry with the specified key, or that there
4381 @emph{is} an entry for the specified key, with value @code{#f}.
4382 Consequently, @code{assq-ref} and friends should only be used where it
4383 is known that an entry exists, or where the ambiguity doesn't matter
4384 for some other reason.
4386 @deffn primitive assq-ref alist key
4387 @deffnx primitive assv-ref alist key
4388 @deffnx primitive assoc-ref alist key
4389 Like @code{assq}, @code{assv} and @code{assoc}, except that only the
4390 value associated with @var{key} in @var{alist} is returned. These
4391 functions are equivalent to
4394 (let ((ent (@var{associator} @var{key} @var{alist})))
4395 (and ent (cdr ent)))
4398 where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
4401 @node Removing Alist Entries
4402 @subsubsection Removing Alist Entries
4404 To remove the element from an association list whose key matches a
4405 specified key, use @code{assq-remove!}, @code{assv-remove!} or
4406 @code{assoc-remove!} (depending, as usual, on the level of equality
4407 required between the key that you specify and the keys in the
4410 As with @code{assq-set!} and friends, the specified alist may or may not
4411 be modified destructively, and the only safe way to update a variable
4412 containing the alist is to @code{set!} it to the value that
4413 @code{assq-remove!} and friends return.
4418 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
4419 ("james" . "1a London Road"))
4421 (set! address-list (assoc-remove! address-list "mary"))
4424 (("bob" . "11 Newington Avenue") ("james" . "1a London Road"))
4427 Note that, when @code{assq/v/oc-remove!} is used to modify an
4428 association list that has been constructed only using the corresponding
4429 @code{assq/v/oc-set!}, there can be at most one matching entry in the
4430 alist, so the question of multiple entries being removed in one go does
4431 not arise. If @code{assq/v/oc-remove!} is applied to an association
4432 list that has been constructed using @code{acons}, or an
4433 @code{assq/v/oc-set!} with a different level of equality, or any mixture
4434 of these, it removes only the first matching entry from the alist, even
4435 if the alist might contain further matching entries. For example:
4438 (define address-list '())
4439 (set! address-list (assq-set! address-list "mary" "11 Elm Street"))
4440 (set! address-list (assq-set! address-list "mary" "57 Pine Drive"))
4443 (("mary" . "57 Pine Drive") ("mary" . "11 Elm Street"))
4445 (set! address-list (assoc-remove! address-list "mary"))
4448 (("mary" . "11 Elm Street"))
4451 In this example, the two instances of the string "mary" are not the same
4452 when compared using @code{eq?}, so the two @code{assq-set!} calls add
4453 two distinct entries to @code{address-list}. When compared using
4454 @code{equal?}, both "mary"s in @code{address-list} are the same as the
4455 "mary" in the @code{assoc-remove!} call, but @code{assoc-remove!} stops
4456 after removing the first matching entry that it finds, and so one of the
4457 "mary" entries is left in place.
4459 @deffn primitive assq-remove! alist key
4460 @deffnx primitive assv-remove! alist key
4461 @deffnx primitive assoc-remove! alist key
4462 Delete the first entry in @var{alist} associated with @var{key}, and return
4463 the resulting alist.
4466 @node Sloppy Alist Functions
4467 @subsubsection Sloppy Alist Functions
4469 @code{sloppy-assq}, @code{sloppy-assv} and @code{sloppy-assoc} behave
4470 like the corresponding non-@code{sloppy-} procedures, except that they
4471 return @code{#f} when the specified association list is not well-formed,
4472 where the non-@code{sloppy-} versions would signal an error.
4474 Specifically, there are two conditions for which the non-@code{sloppy-}
4475 procedures signal an error, which the @code{sloppy-} procedures handle
4476 instead by returning @code{#f}. Firstly, if the specified alist as a
4477 whole is not a proper list:
4480 (assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
4482 ERROR: In procedure assoc in expression (assoc "mary" (quote #)):
4483 ERROR: Wrong type argument in position 2 (expecting NULLP): "open sesame"
4484 ABORT: (wrong-type-arg)
4486 (sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
4492 Secondly, if one of the entries in the specified alist is not a pair:
4495 (assoc 2 '((1 . 1) 2 (3 . 9)))
4497 ERROR: In procedure assoc in expression (assoc 2 (quote #)):
4498 ERROR: Wrong type argument in position 2 (expecting CONSP): 2
4499 ABORT: (wrong-type-arg)
4501 (sloppy-assoc 2 '((1 . 1) 2 (3 . 9)))
4506 Unless you are explicitly working with badly formed association lists,
4507 it is much safer to use the non-@code{sloppy-} procedures, because they
4508 help to highlight coding and data errors that the @code{sloppy-}
4509 versions would silently cover up.
4511 @deffn primitive sloppy-assq key alist
4512 Behaves like @code{assq} but does not do any error checking.
4513 Recommended only for use in Guile internals.
4516 @deffn primitive sloppy-assv key alist
4517 Behaves like @code{assv} but does not do any error checking.
4518 Recommended only for use in Guile internals.
4521 @deffn primitive sloppy-assoc key alist
4522 Behaves like @code{assoc} but does not do any error checking.
4523 Recommended only for use in Guile internals.
4527 @subsubsection Alist Example
4529 Here is a longer example of how alists may be used in practice.
4532 (define capitals '(("New York" . "Albany")
4533 ("Oregon" . "Salem")
4534 ("Florida" . "Miami")))
4536 ;; What's the capital of Oregon?
4537 (assoc "Oregon" capitals) @result{} ("Oregon" . "Salem")
4538 (assoc-ref capitals "Oregon") @result{} "Salem"
4540 ;; We left out South Dakota.
4542 (assoc-set! capitals "South Dakota" "Bismarck"))
4544 @result{} (("South Dakota" . "Bismarck")
4545 ("New York" . "Albany")
4546 ("Oregon" . "Salem")
4547 ("Florida" . "Miami"))
4549 ;; And we got Florida wrong.
4551 (assoc-set! capitals "Florida" "Tallahassee"))
4553 @result{} (("South Dakota" . "Bismarck")
4554 ("New York" . "Albany")
4555 ("Oregon" . "Salem")
4556 ("Florida" . "Tallahassee"))
4558 ;; After Oregon secedes, we can remove it.
4560 (assoc-remove! capitals "Oregon"))
4562 @result{} (("South Dakota" . "Bismarck")
4563 ("New York" . "Albany")
4564 ("Florida" . "Tallahassee"))
4568 @subsection Hash Tables
4570 Like the association list functions, the hash table functions come
4571 in several varieties: @code{hashq}, @code{hashv}, and @code{hash}.
4572 The @code{hashq} functions use @code{eq?} to determine whether two
4573 keys match. The @code{hashv} functions use @code{eqv?}, and the
4574 @code{hash} functions use @code{equal?}.
4576 In each of the functions that follow, the @var{table} argument
4577 must be a vector. The @var{key} and @var{value} arguments may be
4580 @deffn primitive hashq-ref table key [dflt]
4581 Look up @var{key} in the hash table @var{table}, and return the
4582 value (if any) associated with it. If @var{key} is not found,
4583 return @var{default} (or @code{#f} if no @var{default} argument
4584 is supplied). Uses @code{eq?} for equality testing.
4587 @deffn primitive hashv-ref table key [dflt]
4588 Look up @var{key} in the hash table @var{table}, and return the
4589 value (if any) associated with it. If @var{key} is not found,
4590 return @var{default} (or @code{#f} if no @var{default} argument
4591 is supplied). Uses @code{eqv?} for equality testing.
4594 @deffn primitive hash-ref table key [dflt]
4595 Look up @var{key} in the hash table @var{table}, and return the
4596 value (if any) associated with it. If @var{key} is not found,
4597 return @var{default} (or @code{#f} if no @var{default} argument
4598 is supplied). Uses @code{equal?} for equality testing.
4601 @deffn primitive hashq-set! table key val
4602 Find the entry in @var{table} associated with @var{key}, and
4603 store @var{value} there. Uses @code{eq?} for equality testing.
4606 @deffn primitive hashv-set! table key val
4607 Find the entry in @var{table} associated with @var{key}, and
4608 store @var{value} there. Uses @code{eqv?} for equality testing.
4611 @deffn primitive hash-set! table key val
4612 Find the entry in @var{table} associated with @var{key}, and
4613 store @var{value} there. Uses @code{equal?} for equality
4617 @deffn primitive hashq-remove! table key
4618 Remove @var{key} (and any value associated with it) from
4619 @var{table}. Uses @code{eq?} for equality tests.
4622 @deffn primitive hashv-remove! table key
4623 Remove @var{key} (and any value associated with it) from
4624 @var{table}. Uses @code{eqv?} for equality tests.
4627 @deffn primitive hash-remove! table key
4628 Remove @var{key} (and any value associated with it) from
4629 @var{table}. Uses @code{equal?} for equality tests.
4632 The standard hash table functions may be too limited for some
4633 applications. For example, you may want a hash table to store
4634 strings in a case-insensitive manner, so that references to keys
4635 named ``foobar'', ``FOOBAR'' and ``FooBaR'' will all yield the
4636 same item. Guile provides you with @dfn{extended} hash tables
4637 that permit you to specify a hash function and associator function
4638 of your choosing. The functions described in the rest of this section
4639 can be used to implement such custom hash table structures.
4641 If you are unfamiliar with the inner workings of hash tables, then
4642 this facility will probably be a little too abstract for you to
4643 use comfortably. If you are interested in learning more, see an
4644 introductory textbook on data structures or algorithms for an
4645 explanation of how hash tables are implemented.
4647 @deffn primitive hashq key size
4648 Determine a hash value for @var{key} that is suitable for
4649 lookups in a hashtable of size @var{size}, where @code{eq?} is
4650 used as the equality predicate. The function returns an
4651 integer in the range 0 to @var{size} - 1. Note that
4652 @code{hashq} may use internal addresses. Thus two calls to
4653 hashq where the keys are @code{eq?} are not guaranteed to
4654 deliver the same value if the key object gets garbage collected
4655 in between. This can happen, for example with symbols:
4656 @code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two
4657 different values, since @code{foo} will be garbage collected.
4660 @deffn primitive hashv key size
4661 Determine a hash value for @var{key} that is suitable for
4662 lookups in a hashtable of size @var{size}, where @code{eqv?} is
4663 used as the equality predicate. The function returns an
4664 integer in the range 0 to @var{size} - 1. Note that
4665 @code{(hashv key)} may use internal addresses. Thus two calls
4666 to hashv where the keys are @code{eqv?} are not guaranteed to
4667 deliver the same value if the key object gets garbage collected
4668 in between. This can happen, for example with symbols:
4669 @code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two
4670 different values, since @code{foo} will be garbage collected.
4673 @deffn primitive hash key size
4674 Determine a hash value for @var{key} that is suitable for
4675 lookups in a hashtable of size @var{size}, where @code{equal?}
4676 is used as the equality predicate. The function returns an
4677 integer in the range 0 to @var{size} - 1.
4680 @deffn primitive hashx-ref hash assoc table key [dflt]
4681 This behaves the same way as the corresponding @code{ref}
4682 function, but uses @var{hash} as a hash function and
4683 @var{assoc} to compare keys. @code{hash} must be a function
4684 that takes two arguments, a key to be hashed and a table size.
4685 @code{assoc} must be an associator function, like @code{assoc},
4686 @code{assq} or @code{assv}.
4687 By way of illustration, @code{hashq-ref table key} is
4688 equivalent to @code{hashx-ref hashq assq table key}.
4691 @deffn primitive hashx-set! hash assoc table key val
4692 This behaves the same way as the corresponding @code{set!}
4693 function, but uses @var{hash} as a hash function and
4694 @var{assoc} to compare keys. @code{hash} must be a function
4695 that takes two arguments, a key to be hashed and a table size.
4696 @code{assoc} must be an associator function, like @code{assoc},
4697 @code{assq} or @code{assv}.
4698 By way of illustration, @code{hashq-set! table key} is
4699 equivalent to @code{hashx-set! hashq assq table key}.
4702 @deffn primitive hashq-get-handle table key
4703 This procedure returns the @code{(key . value)} pair from the
4704 hash table @var{table}. If @var{table} does not hold an
4705 associated value for @var{key}, @code{#f} is returned.
4706 Uses @code{eq?} for equality testing.
4709 @deffn primitive hashv-get-handle table key
4710 This procedure returns the @code{(key . value)} pair from the
4711 hash table @var{table}. If @var{table} does not hold an
4712 associated value for @var{key}, @code{#f} is returned.
4713 Uses @code{eqv?} for equality testing.
4716 @deffn primitive hash-get-handle table key
4717 This procedure returns the @code{(key . value)} pair from the
4718 hash table @var{table}. If @var{table} does not hold an
4719 associated value for @var{key}, @code{#f} is returned.
4720 Uses @code{equal?} for equality testing.
4723 @deffn primitive hashx-get-handle hash assoc table key
4724 This behaves the same way as the corresponding
4725 @code{-get-handle} function, but uses @var{hash} as a hash
4726 function and @var{assoc} to compare keys. @code{hash} must be
4727 a function that takes two arguments, a key to be hashed and a
4728 table size. @code{assoc} must be an associator function, like
4729 @code{assoc}, @code{assq} or @code{assv}.
4732 @deffn primitive hashq-create-handle! table key init
4733 This function looks up @var{key} in @var{table} and returns its handle.
4734 If @var{key} is not already present, a new handle is created which
4735 associates @var{key} with @var{init}.
4738 @deffn primitive hashv-create-handle! table key init
4739 This function looks up @var{key} in @var{table} and returns its handle.
4740 If @var{key} is not already present, a new handle is created which
4741 associates @var{key} with @var{init}.
4744 @deffn primitive hash-create-handle! table key init
4745 This function looks up @var{key} in @var{table} and returns its handle.
4746 If @var{key} is not already present, a new handle is created which
4747 associates @var{key} with @var{init}.
4750 @deffn primitive hashx-create-handle! hash assoc table key init
4751 This behaves the same way as the corresponding
4752 @code{-create-handle} function, but uses @var{hash} as a hash
4753 function and @var{assoc} to compare keys. @code{hash} must be
4754 a function that takes two arguments, a key to be hashed and a
4755 table size. @code{assoc} must be an associator function, like
4756 @code{assoc}, @code{assq} or @code{assv}.
4759 @deffn primitive hash-fold proc init table
4760 An iterator over hash-table elements.
4761 Accumulates and returns a result by applying PROC successively.
4762 The arguments to PROC are "(key value prior-result)" where key
4763 and value are successive pairs from the hash table TABLE, and
4764 prior-result is either INIT (for the first application of PROC)
4765 or the return value of the previous application of PROC.
4766 For example, @code{(hash-fold acons () tab)} will convert a hash
4767 table into an a-list of key-value pairs.
4774 @c FIXME::martin: Review me!
4776 @c FIXME::martin: This node should come before the non-standard data types.
4778 @c FIXME::martin: Should the subsections of this section be nodes
4779 @c of their own, or are the resulting nodes too short, then?
4781 Vectors are sequences of Scheme objects. Unlike lists, the length of a
4782 vector, once the vector is created, cannot be changed. The advantage of
4783 vectors over lists is that the time required to access one element of a
4784 vector is constant, whereas lists have an access time linear to the
4785 index of the accessed element in the list.
4787 Note that the vectors documented in this section can contain any kind of
4788 Scheme object, it is even possible to have different types of objects in
4791 @subsection Vector Read Syntax
4793 Vectors can literally be entered in source code, just like strings,
4794 characters or some of the other data types. The read syntax for vectors
4795 is as follows: A sharp sign (@code{#}), followed by an opening
4796 parentheses, all elements of the vector in their respective read syntax,
4797 and finally a closing parentheses. The following are examples of the
4798 read syntax for vectors; where the first vector only contains numbers
4799 and the second three different object types: a string, a symbol and a
4800 number in hexidecimal notation.
4804 #("Hello" foo #xdeadbeef)
4807 @subsection Vector Predicates
4810 @deffn primitive vector? obj
4811 Return @code{#t} if @var{obj} is a vector, otherwise return
4815 @subsection Vector Constructors
4817 @rnindex make-vector
4818 @deffn primitive make-vector k [fill]
4819 Return a newly allocated vector of @var{k} elements. If a
4820 second argument is given, then each element is initialized to
4821 @var{fill}. Otherwise the initial contents of each element is
4826 @rnindex list->vector
4827 @deffn primitive vector . l
4828 @deffnx primitive list->vector l
4829 Return a newly allocated vector whose elements contain the
4830 given arguments. Analogous to @code{list}.
4832 (vector 'a 'b 'c) @result{} #(a b c)
4836 @rnindex vector->list
4837 @deffn primitive vector->list v
4838 Return a newly allocated list of the objects contained in the
4839 elements of @var{vector}.
4841 (vector->list '#(dah dah didah)) @result{} (dah dah didah)
4842 (list->vector '(dididit dah)) @result{} #(dididit dah)
4846 @subsection Vector Modification
4848 A vector created by any of the vector constructor procedures (REFFIXME)
4849 documented above can be modified using the following procedures.
4851 According to R5RS, using any of these procedures on literally entered
4852 vectors is an error, because these vectors are considered to be
4853 constant, although Guile currently does not detect this error.
4855 @rnindex vector-set!
4856 @deffn primitive vector-set! vector k obj
4857 @var{k} must be a valid index of @var{vector}.
4858 @code{Vector-set!} stores @var{obj} in element @var{k} of @var{vector}.
4859 The value returned by @samp{vector-set!} is unspecified.
4861 (let ((vec (vector 0 '(2 2 2 2) "Anna")))
4862 (vector-set! vec 1 '("Sue" "Sue"))
4863 vec) @result{} #(0 ("Sue" "Sue") "Anna")
4864 (vector-set! '#(0 1 2) 1 "doe") @result{} @emph{error} ; constant vector
4868 @rnindex vector-fill!
4869 @deffn primitive vector-fill! v fill
4870 Store @var{fill} in every element of @var{vector}. The value
4871 returned by @code{vector-fill!} is unspecified.
4874 @deffn primitive vector-move-left! vec1 start1 end1 vec2 start2
4875 Vector version of @code{substring-move-left!}.
4878 @deffn primitive vector-move-right! vec1 start1 end1 vec2 start2
4879 Vector version of @code{substring-move-right!}.
4882 @subsection Vector Selection
4884 These procedures return information about a given vector, such as the
4885 size or what elements are contained in the vector.
4887 @rnindex vector-length
4888 @deffn primitive vector-length vector
4889 Returns the number of elements in @var{vector} as an exact integer.
4893 @deffn primitive vector-ref vector k
4894 @var{k} must be a valid index of @var{vector}.
4895 @samp{Vector-ref} returns the contents of element @var{k} of
4898 (vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
4899 (vector-ref '#(1 1 2 3 5 8 13 21)
4900 (let ((i (round (* 2 (acos -1)))))
4910 @c FIXME::martin: Review me!
4912 A hook is basically a list of procedures to be called at well defined
4913 points in time. Hooks are used internally for several debugging
4914 facilities, but they can be used in user code, too.
4916 Hooks are created with @code{make-hook}, then procedures can be added to
4917 a hook with @code{add-hook!} or removed with @code{remove-hook!} or
4918 @code{reset-hook!}. The procedures stored in a hook can be invoked with
4922 * Hook Examples:: Hook usage by example.
4923 * Hook Reference:: Reference of all hook procedures.
4927 @subsection Hook Examples
4929 Hook usage is shown by some examples in this section. First, we will
4930 define a hook of arity 2---that is, the procedures stored in the hook
4931 will have to accept two arguments.
4934 (define hook (make-hook 2))
4936 @result{} #<hook 2 40286c90>
4939 Now we are ready to add some procedures to the newly created hook with
4940 @code{add-hook!}. In the following example, two procedures are added,
4941 which print different messages and do different things with their
4942 arguments. When the procedures have been added, we can invoke them
4943 using @code{run-hook}.
4946 (add-hook! hook (lambda (x y)
4950 (add-hook! hook (lambda (x y)
4959 Note that the procedures are called in reverse order than they were
4960 added. This can be changed by providing the optional third argument
4961 on the second call to @code{add-hook!}.
4964 (add-hook! hook (lambda (x y)
4968 (add-hook! hook (lambda (x y)
4972 #t) ; @r{<- Change here!}
4978 @node Hook Reference
4979 @subsection Hook Reference
4981 When a hook is created with @code{make-hook}, you can supply the arity
4982 of the procedures which can be added to the hook. The arity defaults to
4983 zero. All procedures of a hook must have the same arity, and when the
4984 procedures are invoked using @code{run-hook}, the number of arguments
4985 must match the arity of the procedures.
4987 The order in which procedures are added to a hook matters. If the third
4988 parameter to @var{add-hook!} is omitted or is equal to @code{#f}, the
4989 procedure is added in front of the procedures which might already be on
4990 that hook, otherwise the procedure is added at the end. The procedures
4991 are always called from first to last when they are invoked via
4994 When calling @code{hook->list}, the procedures in the resulting list are
4995 in the same order as they would have been called by @code{run-hook}.
4997 @deffn primitive make-hook-with-name name [n_args]
4998 Create a named hook with the name @var{name} for storing
4999 procedures of arity @var{n_args}. @var{n_args} defaults to
5003 @deffn primitive make-hook [n_args]
5004 Create a hook for storing procedure of arity
5005 @var{n_args}. @var{n_args} defaults to zero.
5008 @deffn primitive hook? x
5009 Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
5012 @deffn primitive hook-empty? hook
5013 Return @code{#t} if @var{hook} is an empty hook, @code{#f}
5017 @deffn primitive add-hook! hook proc [append_p]
5018 Add the procedure @var{proc} to the hook @var{hook}. The
5019 procedure is added to the end if @var{append_p} is true,
5020 otherwise it is added to the front.
5023 @deffn primitive remove-hook! hook proc
5024 Remove the procedure @var{proc} from the hook @var{hook}.
5027 @deffn primitive reset-hook! hook
5028 Remove all procedures from the hook @var{hook}.
5031 @deffn primitive run-hook hook . args
5032 Apply all procedures from the hook @var{hook} to the arguments
5033 @var{args}. The order of the procedure application is first to
5037 @deffn primitive hook->list hook
5038 Convert the procedure list of @var{hook} to a list.
5042 @node Other Data Types
5043 @section Other Core Guile Data Types
5047 @c TeX-master: "guile.texi"