@chapter Simple Generic Data Types
This chapter describes those of Guile's simple data types which are
-primarily are used for their role as items of generic data. By
+primarily used for their role as items of generic data. By
@dfn{simple} we mean data types that are not primarily used as
-containers to hold other data --- i.e. pairs, lists, vectors and so on.
+containers to hold other data --- i.e.@: pairs, lists, vectors and so on.
For the documentation of such @dfn{compound} data types, see
@ref{Compound Data Types}.
One of the great strengths of Scheme is that there is no straightforward
distinction between ``data'' and ``functionality''. For example,
-Guile's support for dynamic linking could be described
+Guile's support for dynamic linking could be described:
@itemize @bullet
@item
module system.
@end itemize
-The contents of this chapter are, therefore, a matter of judgement. By
+The contents of this chapter are, therefore, a matter of judgment. By
@dfn{generic}, we mean to select those data types whose typical use as
@emph{data} in a wide variety of programming contexts is more important
than their use in the implementation of a particular piece of
@lisp
(<= 3 8)
-@result{}
-#t
+@result{} #t
(<= 3 -3)
-@result{}
-#f
+@result{} #f
(equal? "house" "houses")
-@result{}
-#f
+@result{} #f
(eq? #f #f)
@result{}
@lisp
(if #t "yes" "no")
-@result{}
-"yes"
+@result{} "yes"
(if 0 "yes" "no")
-@result{}
-"yes"
+@result{} "yes"
(if #f "yes" "no")
-@result{}
-"no"
+@result{} "no"
@end lisp
A result of this asymmetry is that typical Scheme source code more often
You may also find it illuminating to read R5RS's presentation of numbers
in Scheme, which is particularly clear and accessible: see
-@xref{Numbers,,,r5rs}.
+@ref{Numbers,,,r5rs,R5RS}.
@menu
* Numerical Tower:: Scheme's numerical "tower".
Scheme's numerical ``tower'' consists of the following categories of
numbers:
-@itemize @bullet
-@item
-integers (whole numbers)
-
-@item
-rationals (the set of numbers that can be expressed as P/Q where P and Q
-are integers)
-
-@item
-real numbers (the set of numbers that describes all possible positions
-along a one dimensional line)
-
-@item
-complex numbers (the set of numbers that describes all possible
-positions in a two dimensional space)
-@end itemize
+@table @dfn
+@item integers
+Whole numbers, positive or negative; e.g.@: --5, 0, 18.
+
+@item rationals
+The set of numbers that can be expressed as @math{@var{p}/@var{q}}
+where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
+pi (an irrational number) doesn't. These include integers
+(@math{@var{n}/1}).
+
+@item real numbers
+The set of numbers that describes all possible positions along a
+one-dimensional line. This includes rationals as well as irrational
+numbers.
+
+@item complex numbers
+The set of numbers that describes all possible positions in a two
+dimensional space. This includes real as well as imaginary numbers
+(@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
+@var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
+@minus{}1.)
+@end table
It is called a tower because each category ``sits on'' the one that
follows it, in the sense that every integer is also a rational, every
@deffn {Scheme Procedure} number? obj
@deffnx {C Function} scm_number_p (obj)
-Return @code{#t} if @var{obj} is any kind of number, @code{#f} else.
-@findex number?
+Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
@end deffn
For example:
@lisp
(number? 3)
-@result{}
-#t
+@result{} #t
(number? "hello there!")
-@result{}
-#f
+@result{} #f
(define pi 3.141592654)
(number? pi)
-@result{}
-#t
+@result{} #t
@end lisp
The next few subsections document each of Guile's numerical data types
@rnindex integer?
Integers are whole numbers, that is numbers with no fractional part,
-such as 2, 83 and -3789.
+such as 2, 83, and @minus{}3789.
Integers in Guile can be arbitrarily big, as shown by the following
example.
(loop (- n 1) (* product n)))))
(factorial 3)
-@result{}
-6
+@result{} 6
(factorial 20)
-@result{}
-2432902008176640000
+@result{} 2432902008176640000
(- (factorial 45))
-@result{}
--119622220865480194561963161495657715064383733760000000000
+@result{} -119622220865480194561963161495657715064383733760000000000
@end lisp
Readers whose background is in programming languages where integers are
form. Conversion between these two representations is automatic and
completely invisible to the Scheme level programmer.
+The infinities @samp{+inf.0} and @samp{-inf.0} are considered to be
+inexact integers. They are explained in detail in the next section,
+together with reals and rationals.
+
@c REFFIXME Maybe point here to discussion of handling immediates/bignums
@c on the C level, where the conversion is not so automatic - NJ
@deffn {Scheme Procedure} integer? x
@deffnx {C Function} scm_integer_p (x)
-Return @code{#t} if @var{x} is an integer number, @code{#f} else.
+Return @code{#t} if @var{x} is an integer number, else @code{#f}.
@lisp
(integer? 487)
-@result{}
-#t
+@result{} #t
(integer? -3.4)
-@result{}
-#f
+@result{} #f
+
+(integer? +inf.0)
+@result{} #t
@end lisp
@end deffn
Mathematically, the real numbers are the set of numbers that describe
all possible points along a continuous, infinite, one-dimensional line.
The rational numbers are the set of all numbers that can be written as
-fractions P/Q, where P and Q are integers. All rational numbers are
-also real, but there are real numbers that are not rational, for example
-the square root of 2, and pi.
+fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
+All rational numbers are also real, but there are real numbers that
+are not rational, for example the square root of 2, and pi.
Guile represents both real and rational numbers approximately using a
floating point encoding with limited precision. Even though the actual
The limited precision of Guile's encoding means that any ``real'' number
in Guile can be written in a rational form, by multiplying and then dividing
by sufficient powers of 10 (or in fact, 2). For example,
-@code{-0.00000142857931198} is the same as @code{142857931198} divided by
-@code{100000000000000000}. In Guile's current incarnation, therefore,
-the @code{rational?} and @code{real?} predicates are equivalent.
+@samp{-0.00000142857931198} is the same as @minus{}142857931198 divided by
+100000000000000000. In Guile's current incarnation, therefore, the
+@code{rational?} and @code{real?} predicates are equivalent.
Another aspect of this equivalence is that Guile currently does not
preserve the exactness that is possible with rational arithmetic.
and in such a way that the new kinds of number integrate seamlessly
with those that are already implemented.
+Dividing by an exact zero leads to a error message, as one might
+expect. However, dividing by an inexact zero does not produce an
+error. Instead, the result of the division is either plus or minus
+infinity, depending on the sign of the divided number.
+
+The infinities are written @samp{+inf.0} and @samp{-inf.0},
+respectibly. This syntax is also recognized by @code{read} as an
+extension to the usual Scheme syntax.
+
+Dividing zero by zero yields something that is not a number at all:
+@samp{+nan.0}. This is the special `not a number' value.
+
+On platforms that follow @acronym{IEEE} 754 for their floating point
+arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
+are implemented using the corresponding @acronym{IEEE} 754 values.
+They behave in arithmetic operations like @acronym{IEEE} 754 describes
+it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
+
+The infinities are inexact integers and are considered to be both even
+and odd. While @samp{+nan.0} is not @code{=} to itself, it is
+@code{eqv?} to itself.
+
+To test for the special values, use the functions @code{inf?} and
+@code{nan?}.
+
@deffn {Scheme Procedure} real? obj
@deffnx {C Function} scm_real_p (obj)
-Return @code{#t} if @var{obj} is a real number, @code{#f} else.
+Return @code{#t} if @var{obj} is a real number, else @code{#f}.
Note that the sets of integer and rational values form subsets
of the set of real numbers, so the predicate will also be fulfilled
if @var{obj} is an integer number or a rational number.
-@findex real?
@end deffn
@deffn {Scheme Procedure} rational? x
@deffnx {C Function} scm_real_p (x)
Return @code{#t} if @var{x} is a rational number, @code{#f}
-else. Note that the set of integer values forms a subset of
+otherwise. Note that the set of integer values forms a subset of
the set of rational numbers, i. e. the predicate will also be
fulfilled if @var{x} is an integer number. Real numbers
will also satisfy this predicate, because of their limited
precision.
@end deffn
+@deffn {Scheme Procedure} inf? x
+Return @code{#t} if @var{x} is either @samp{+inf.0} or @samp{-inf.0},
+@code{#f} otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} nan? x
+Return @code{#t} if @var{x} is @samp{+nan.0}, @code{#f} otherwise.
+@end deffn
@node Complex Numbers
@subsection Complex Numbers
@deffn {Scheme Procedure} complex? x
@deffnx {C Function} scm_number_p (x)
Return @code{#t} if @var{x} is a complex number, @code{#f}
-else. Note that the sets of real, rational and integer
+otherwise. Note that the sets of real, rational and integer
values form subsets of the set of complex numbers, i. e. the
predicate will also be fulfilled if @var{x} is a real,
rational or integer number.
R5RS requires that a calculation involving inexact numbers always
produces an inexact result. To meet this requirement, Guile
-distinguishes between an exact integer value such as @code{5} and the
+distinguishes between an exact integer value such as @samp{5} and the
corresponding inexact real value which, to the limited precision
-available, has no fractional part, and is printed as @code{5.0}. Guile
+available, has no fractional part, and is printed as @samp{5.0}. Guile
will only convert the latter value to the former when forced to do so by
an invocation of the @code{inexact->exact} procedure.
base in which the integer is encoded, and a code indicating whether
the number is exact or inexact. The supported base codes are:
-@itemize @bullet
-@item
-@code{#b}, @code{#B} --- the integer is written in binary (base 2)
+@table @code
+@item #b
+@itemx #B
+the integer is written in binary (base 2)
-@item
-@code{#o}, @code{#O} --- the integer is written in octal (base 8)
+@item #o
+@itemx #O
+the integer is written in octal (base 8)
-@item
-@code{#d}, @code{#D} --- the integer is written in decimal (base 10)
+@item #d
+@itemx #D
+the integer is written in decimal (base 10)
-@item
-@code{#x}, @code{#X} --- the integer is written in hexadecimal (base 16).
-@end itemize
+@item #x
+@itemx #X
+the integer is written in hexadecimal (base 16)
+@end table
If the base code is omitted, the integer is assumed to be decimal. The
following examples show how these base codes are used.
@lisp
-13
-@result{}
--13
+@result{} -13
#d-13
-@result{}
--13
+@result{} -13
#x-13
-@result{}
--19
+@result{} -19
#b+1101
-@result{}
-13
+@result{} 13
#o377
-@result{}
-255
+@result{} 255
@end lisp
The codes for indicating exactness (which can, incidentally, be applied
to all numerical values) are:
-@itemize @bullet
-@item
-@code{#e}, @code{#E} --- the number is exact
+@table @code
+@item #e
+@itemx #E
+the number is exact
-@item
-@code{#i}, @code{#I} --- the number is inexact.
-@end itemize
+@item #i
+@itemx #I
+the number is inexact.
+@end table
If the exactness indicator is omitted, the integer is assumed to be exact,
since Guile's internal representation for integers is always exact.
Real numbers have limited precision similar to the precision of the
@code{double} type in C. A consequence of the limited precision is that
-all real numbers in Guile are also rational, since any number R with a
-limited number of decimal places, say N, can be made into an integer by
-multiplying by 10^N.
+all real numbers in Guile are also rational, since any number @var{r} with a
+limited number of decimal places, say @var{n}, can be made into an integer by
+multiplying by @math{10^n}.
+Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
+plus and minus infinity, respectively. The value must be written
+exactly as shown, that is, the always must have a sign and exactly one
+zero digit after the decimal point. It also understands @samp{+nan.0}
+and @samp{-nan.0} for the special `not-a-number' value. The sign is
+ignored for `not-a-number' and the value is always printed as @samp{+nan.0}.
@node Integer Operations
@subsection Operations on Integer Values
@end deffn
@c begin (texi-doc-string "guile" "quotient")
-@deffn {Scheme Procedure} quotient
-Return the quotient of the numbers @var{x} and @var{y}.
-@end deffn
-
@c begin (texi-doc-string "guile" "remainder")
-@deffn {Scheme Procedure} remainder
-Return the remainder of the numbers @var{x} and @var{y}.
+@deffn {Scheme Procedure} quotient n d
+@deffnx {Scheme Procedure} remainder n d
+Return the quotient or remainder from @var{n} divided by @var{d}. The
+quotient is rounded towards zero, and the remainder will have the same
+sign as @var{n}. In all cases quotient and remainder satisfy
+@math{@var{n} = @var{q}*@var{d} + @var{r}}.
+
@lisp
(remainder 13 4) @result{} 1
(remainder -13 4) @result{} -1
@end deffn
@c begin (texi-doc-string "guile" "modulo")
-@deffn {Scheme Procedure} modulo
-Return the modulo of the numbers @var{x} and @var{y}.
+@deffn {Scheme Procedure} modulo n d
+Return the remainder from @var{n} divided by @var{d}, with the same
+sign as @var{d}.
+
@lisp
(modulo 13 4) @result{} 1
(modulo -13 4) @result{} 3
+(modulo 13 -4) @result{} -3
+(modulo -13 -4) @result{} -1
@end lisp
@end deffn
@end deffn
@c begin (texi-doc-string "guile" "real-part")
-@deffn {Scheme Procedure} real-part
+@deffn {Scheme Procedure} real-part z
Return the real part of the number @var{z}.
@end deffn
@c begin (texi-doc-string "guile" "imag-part")
-@deffn {Scheme Procedure} imag-part
+@deffn {Scheme Procedure} imag-part z
Return the imaginary part of the number @var{z}.
@end deffn
@c begin (texi-doc-string "guile" "magnitude")
-@deffn {Scheme Procedure} magnitude
+@deffn {Scheme Procedure} magnitude z
Return the magnitude of the number @var{z}. This is the same as
@code{abs} for real arguments, but also allows complex numbers.
@end deffn
@c begin (texi-doc-string "guile" "angle")
-@deffn {Scheme Procedure} angle
+@deffn {Scheme Procedure} angle z
Return the angle of the complex number @var{z}.
@end deffn
@c begin (texi-doc-string "guile" "abs")
@deffn {Scheme Procedure} abs x
+@deffnx {C Function} scm_abs (x)
Return the absolute value of @var{x}.
+
+@var{x} must be a number with zero imaginary part. To calculate the
+magnitude of a complex number, use @code{magnitude} instead.
@end deffn
@c begin (texi-doc-string "guile" "max")
@c begin (texi-doc-string "guile" "min")
@deffn {Scheme Procedure} min x1 x2 @dots{}
-Return the minium of all parameter values.
+Return the minimum of all parameter values.
@end deffn
@c begin (texi-doc-string "guile" "truncate")
@c begin (texi-doc-string "guile" "round")
@deffn {Scheme Procedure} round x
-Round the inexact number @var{x} towards zero.
+Round the inexact number @var{x} to the nearest integer. When exactly
+halfway between two integers, round to the even one.
@end deffn
@c begin (texi-doc-string "guile" "floor")
Round the number @var{x} towards infinity.
@end deffn
+C functions for some of the above rounding functions are provided by
+the standard C mathematics library. Naturally these expect and return
+@code{double} arguments (@pxref{Rounding Functions,,, libc, GNU C
+Library Reference Manual}).
+
+@multitable {xx} {Scheme Procedure} {C Function}
+@item @tab Scheme Procedure @tab C Function
+@item @tab @code{floor} @tab @code{floor}
+@item @tab @code{ceiling} @tab @code{ceil}
+@item @tab @code{truncate} @tab @code{trunc}
+@end multitable
+
+@code{trunc} is C99 standard and might not be available on older
+systems. Guile provides an @code{scm_truncate} equivalent (on all
+systems), plus a C level version of the Scheme @code{round} procedure.
+
+@deftypefn {C Function} double scm_truncate (double x)
+@deftypefnx {C Function} double scm_round (double x)
+@end deftypefn
+
@node Scientific
@subsection Scientific Functions
@rnindex atan
@c begin (texi-doc-string "guile" "atan")
@deffn {Scheme Procedure} atan z
-Return the arctangent of @var{z}.
+@deffnx {Scheme Procedure} atan y x
+Return the arctangent of @var{z}, or of @math{@var{y}/@var{x}}.
@end deffn
@rnindex exp
@c begin (texi-doc-string "guile" "$atan")
@deffn {Scheme Procedure} $atan x
-Return the arctangent of @var{x} in the range -PI/2 to PI/2.
+Return the arctangent of @var{x} in the range @minus{}@math{PI/2} to
+@math{PI/2}.
@end deffn
@deffn {Scheme Procedure} $atan2 x y
Return the hyperbolic arctangent of @var{x}.
@end deffn
+C functions for the above are provided by the standard mathematics
+library. Naturally these expect and return @code{double} arguments
+(@pxref{Mathematics,,, libc, GNU C Library Reference Manual}).
+
+@multitable {xx} {Scheme Procedure} {C Function}
+@item @tab Scheme Procedure @tab C Function
+
+@item @tab @code{$abs} @tab @code{fabs}
+@item @tab @code{$sqrt} @tab @code{sqrt}
+@item @tab @code{$sin} @tab @code{sin}
+@item @tab @code{$cos} @tab @code{cos}
+@item @tab @code{$tan} @tab @code{tan}
+@item @tab @code{$asin} @tab @code{asin}
+@item @tab @code{$acos} @tab @code{acos}
+@item @tab @code{$atan} @tab @code{atan}
+@item @tab @code{$atan2} @tab @code{atan2}
+@item @tab @code{$exp} @tab @code{exp}
+@item @tab @code{$expt} @tab @code{pow}
+@item @tab @code{$log} @tab @code{log}
+@item @tab @code{$sinh} @tab @code{sinh}
+@item @tab @code{$cosh} @tab @code{cosh}
+@item @tab @code{$tanh} @tab @code{tanh}
+@item @tab @code{$asinh} @tab @code{asinh}
+@item @tab @code{$acosh} @tab @code{acosh}
+@item @tab @code{$atanh} @tab @code{atanh}
+@end multitable
+
+@code{asinh}, @code{acosh} and @code{atanh} are C99 standard but might
+not be available on older systems. Guile provides the following
+equivalents (on all systems).
+
+@deftypefn {C Function} double scm_asinh (double x)
+@deftypefnx {C Function} double scm_acosh (double x)
+@deftypefnx {C Function} double scm_atanh (double x)
+Return the hyperbolic arcsine, arccosine or arctangent of @var{x}
+respectively.
+@end deftypefn
+
@node Bitwise Operations
@subsection Bitwise Operations
-@deffn {Scheme Procedure} logand n1 n2
-Return the bitwise AND of the integer arguments.
+For the following bitwise functions, negative numbers are treated as
+infinite precision twos-complements. For instance @math{-6} is bits
+@math{@dots{}111010}, with infinitely many ones on the left. It can
+be seen that adding 6 (binary 110) to such a bit pattern gives all
+zeros.
+
+@deffn {Scheme Procedure} logand n1 n2 @dots{}
+Return the bitwise @sc{and} of the integer arguments.
@lisp
(logand) @result{} -1
@end lisp
@end deffn
-@deffn {Scheme Procedure} logior n1 n2
-Return the bitwise OR of the integer arguments.
+@deffn {Scheme Procedure} logior n1 n2 @dots{}
+Return the bitwise @sc{or} of the integer arguments.
@lisp
(logior) @result{} 0
@end lisp
@end deffn
-@deffn {Scheme Procedure} logxor n1 n2
-Return the bitwise XOR of the integer arguments. A bit is
+@deffn {Scheme Procedure} logxor n1 n2 @dots{}
+Return the bitwise @sc{xor} of the integer arguments. A bit is
set in the result if it is set in an odd number of arguments.
+
@lisp
(logxor) @result{} 0
(logxor 7) @result{} 7
@deffn {Scheme Procedure} lognot n
@deffnx {C Function} scm_lognot (n)
-Return the integer which is the 2s-complement of the integer
-argument.
+Return the integer which is the ones-complement of the integer
+argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
@lisp
(number->string (lognot #b10000000) 2)
@deffn {Scheme Procedure} ash n cnt
@deffnx {C Function} scm_ash (n, cnt)
-The function ash performs an arithmetic shift left by @var{cnt}
-bits (or shift right, if @var{cnt} is negative). 'Arithmetic'
-means, that the function does not guarantee to keep the bit
-structure of @var{n}, but rather guarantees that the result
-will always be rounded towards minus infinity. Therefore, the
-results of ash and a corresponding bitwise shift will differ if
-@var{n} is negative.
+Return @var{n} shifted left by @var{cnt} bits, or shifted right if
+@var{cnt} is negative. This is an ``arithmetic'' shift.
-Formally, the function returns an integer equivalent to
-@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
+This is effectively a multiplication by @m{2^{cnt}, 2^@var{cnt}}, and
+when @var{cnt} is negative it's a division, rounded towards negative
+infinity. (Note that this is not the same rounding as @code{quotient}
+does.)
+
+With @var{n} viewed as an infinite precision twos complement,
+@code{ash} means a left shift introducing zero bits, or a right shift
+dropping bits.
@lisp
(number->string (ash #b1 3) 2) @result{} "1000"
(number->string (ash #b1010 -1) 2) @result{} "101"
+
+;; -23 is bits ...11101001, -6 is bits ...111010
+(ash -23 -2) @result{} -6
@end lisp
@end deffn
@deffn {Scheme Procedure} integer-length n
@deffnx {C Function} scm_integer_length (n)
-Return the number of bits neccessary to represent @var{n}.
+Return the number of bits necessary to represent @var{n}.
+
+For positive @var{n} this is how many bits to the most significant one
+bit. For negative @var{n} it's how many bits to the most significant
+zero bit in twos complement form.
@lisp
-(integer-length #b10101010)
- @result{} 8
-(integer-length 0)
- @result{} 0
-(integer-length #b1111)
- @result{} 4
+(integer-length #b10101010) @result{} 8
+(integer-length #b1111) @result{} 4
+(integer-length 0) @result{} 0
+(integer-length -1) @result{} 0
+(integer-length -256) @result{} 8
+(integer-length -257) @result{} 9
@end lisp
@end deffn
@deffn {Scheme Procedure} random n [state]
@deffnx {C Function} scm_random (n, state)
-Return a number in [0,N).
+Return a number in [0, @var{n}).
Accepts a positive integer or real n and returns a
number of the same type between zero (inclusive) and
-N (exclusive). The values returned have a uniform
+@var{n} (exclusive). The values returned have a uniform
distribution.
The optional argument @var{state} must be of the type produced
@deffn {Scheme Procedure} random:exp [state]
@deffnx {C Function} scm_random_exp (state)
Return an inexact real in an exponential distribution with mean
-1. For an exponential distribution with mean u use (* u
-(random:exp)).
+1. For an exponential distribution with mean @var{u} use @code{(*
+@var{u} (random:exp))}.
@end deffn
-@deffn {Scheme Procedure} random:hollow-sphere! v [state]
-@deffnx {C Function} scm_random_hollow_sphere_x (v, state)
-Fills vect with inexact real random numbers
-the sum of whose squares is equal to 1.0.
-Thinking of vect as coordinates in space of
-dimension n = (vector-length vect), the coordinates
-are uniformly distributed over the surface of the
-unit n-sphere.
+@deffn {Scheme Procedure} random:hollow-sphere! vect [state]
+@deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
+Fills @var{vect} with inexact real random numbers the sum of whose
+squares is equal to 1.0. Thinking of @var{vect} as coordinates in
+space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
+the coordinates are uniformly distributed over the surface of the unit
+n-sphere.
@end deffn
@deffn {Scheme Procedure} random:normal [state]
@deffnx {C Function} scm_random_normal (state)
-Return an inexact real in a normal distribution. The
-distribution used has mean 0 and standard deviation 1. For a
-normal distribution with mean m and standard deviation d use
-@code{(+ m (* d (random:normal)))}.
+Return an inexact real in a normal distribution. The distribution
+used has mean 0 and standard deviation 1. For a normal distribution
+with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
+(* @var{d} (random:normal)))}.
@end deffn
-@deffn {Scheme Procedure} random:normal-vector! v [state]
-@deffnx {C Function} scm_random_normal_vector_x (v, state)
-Fills vect with inexact real random numbers that are
+@deffn {Scheme Procedure} random:normal-vector! vect [state]
+@deffnx {C Function} scm_random_normal_vector_x (vect, state)
+Fills @var{vect} with inexact real random numbers that are
independent and standard normally distributed
(i.e., with mean 0 and variance 1).
@end deffn
-@deffn {Scheme Procedure} random:solid-sphere! v [state]
-@deffnx {C Function} scm_random_solid_sphere_x (v, state)
-Fills vect with inexact real random numbers
-the sum of whose squares is less than 1.0.
-Thinking of vect as coordinates in space of
-dimension n = (vector-length vect), the coordinates
-are uniformly distributed within the unit n-sphere.
-The sum of the squares of the numbers is returned.
+@deffn {Scheme Procedure} random:solid-sphere! vect [state]
+@deffnx {C Function} scm_random_solid_sphere_x (vect, state)
+Fills @var{vect} with inexact real random numbers the sum of whose
+squares is less than 1.0. Thinking of @var{vect} as coordinates in
+space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
+the coordinates are uniformly distributed within the unit
+@var{n}-sphere. The sum of the squares of the numbers is returned.
+@c FIXME: What does this mean, particularly the n-sphere part?
@end deffn
@deffn {Scheme Procedure} random:uniform [state]
@section Characters
@tpindex Characters
-Most of the characters in the ASCII character set may be referred to by
-name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and so on.
-The following table describes the ASCII names for each character.
+@noindent
+[@strong{FIXME}: how do you specify regular (non-control) characters?]
+
+Most of the ``control characters'' (those below codepoint 32) in the
+@acronym{ASCII} character set, as well as the space, may be referred
+to by name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and
+so on. The following table describes the @acronym{ASCII} names for
+each character.
@multitable @columnfractions .25 .25 .25 .25
@item 0 = @code{#\nul}
@item 32 = @code{#\sp}
@end multitable
-The @code{delete} character (octal 177) may be referred to with the name
+The ``delete'' character (octal 177) may be referred to with the name
@code{#\del}.
Several characters have more than one name:
-@itemize @bullet
-@item
-@code{#\space}, @code{#\sp}
-@item
-@code{#\newline}, @code{#\nl}
-@item
-@code{#\tab}, @code{#\ht}
-@item
-@code{#\backspace}, @code{#\bs}
-@item
-@code{#\return}, @code{#\cr}
-@item
-@code{#\page}, @code{#\np}
-@item
-@code{#\null}, @code{#\nul}
-@end itemize
+@multitable {@code{#\backspace}} {Original}
+@item Alias @tab Original
+@item @code{#\space} @tab @code{#\sp}
+@item @code{#\newline} @tab @code{#\nl}
+@item @code{#\tab} @tab @code{#\ht}
+@item @code{#\backspace} @tab @code{#\bs}
+@item @code{#\return} @tab @code{#\cr}
+@item @code{#\page} @tab @code{#\np}
+@item @code{#\null} @tab @code{#\nul}
+@end multitable
@rnindex char?
@deffn {Scheme Procedure} char? x
@rnindex char<?
@deffn {Scheme Procedure} char<? x y
-Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence,
+Return @code{#t} iff @var{x} is less than @var{y} in the @acronym{ASCII} sequence,
else @code{#f}.
@end deffn
@rnindex char<=?
@deffn {Scheme Procedure} char<=? x y
Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
-ASCII sequence, else @code{#f}.
+@acronym{ASCII} sequence, else @code{#f}.
@end deffn
@rnindex char>?
@deffn {Scheme Procedure} char>? x y
-Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
+Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII}
sequence, else @code{#f}.
@end deffn
@rnindex char>=?
@deffn {Scheme Procedure} char>=? x y
Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
-ASCII sequence, else @code{#f}.
+@acronym{ASCII} sequence, else @code{#f}.
@end deffn
@rnindex char-ci=?
@rnindex char-ci<?
@deffn {Scheme Procedure} char-ci<? x y
-Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence
+Return @code{#t} iff @var{x} is less than @var{y} in the @acronym{ASCII} sequence
ignoring case, else @code{#f}.
@end deffn
@rnindex char-ci<=?
@deffn {Scheme Procedure} char-ci<=? x y
Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
-ASCII sequence ignoring case, else @code{#f}.
+@acronym{ASCII} sequence ignoring case, else @code{#f}.
@end deffn
@rnindex char-ci>?
@deffn {Scheme Procedure} char-ci>? x y
-Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
+Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII}
sequence ignoring case, else @code{#f}.
@end deffn
@rnindex char-ci>=?
@deffn {Scheme Procedure} char-ci>=? x y
Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
-ASCII sequence ignoring case, else @code{#f}.
+@acronym{ASCII} sequence ignoring case, else @code{#f}.
@end deffn
@rnindex char-alphabetic?
@deffn {Scheme Procedure} char-alphabetic? chr
@deffnx {C Function} scm_char_alphabetic_p (chr)
Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
-Alphabetic means the same thing as the isalpha C library function.
+Alphabetic means the same thing as the @code{isalpha} C library function.
@end deffn
@rnindex char-numeric?
@deffn {Scheme Procedure} char-numeric? chr
@deffnx {C Function} scm_char_numeric_p (chr)
Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
-Numeric means the same thing as the isdigit C library function.
+Numeric means the same thing as the @code{isdigit} C library function.
@end deffn
@rnindex char-whitespace?
@deffn {Scheme Procedure} char-whitespace? chr
@deffnx {C Function} scm_char_whitespace_p (chr)
Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
-Whitespace means the same thing as the isspace C library function.
+Whitespace means the same thing as the @code{isspace} C library function.
@end deffn
@rnindex char-upper-case?
@deffn {Scheme Procedure} char-upper-case? chr
@deffnx {C Function} scm_char_upper_case_p (chr)
Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
-Uppercase means the same thing as the isupper C library function.
+Uppercase means the same thing as the @code{isupper} C library function.
@end deffn
@rnindex char-lower-case?
@deffn {Scheme Procedure} char-lower-case? chr
@deffnx {C Function} scm_char_lower_case_p (chr)
Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
-Lowercase means the same thing as the islower C library function.
+Lowercase means the same thing as the @code{islower} C library function.
@end deffn
@deffn {Scheme Procedure} char-is-both? chr
@deffnx {C Function} scm_char_is_both_p (chr)
-Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}.
-Uppercase and lowercase are as defined by the isupper and islower
-C library functions.
+Return @code{#t} iff @var{chr} is either uppercase or lowercase, else
+@code{#f}. Uppercase and lowercase are as defined by the
+@code{isupper} and @code{islower} C library functions.
@end deffn
@rnindex char->integer
@deffn {Scheme Procedure} char->integer chr
@deffnx {C Function} scm_char_to_integer (chr)
Return the number corresponding to ordinal position of @var{chr} in the
-ASCII sequence.
+@acronym{ASCII} sequence.
@end deffn
@rnindex integer->char
@deffn {Scheme Procedure} integer->char n
@deffnx {C Function} scm_integer_to_char (n)
-Return the character at position @var{n} in the ASCII sequence.
+Return the character at position @var{n} in the @acronym{ASCII} sequence.
@end deffn
@rnindex char-upcase
Return the lowercase character version of @var{chr}.
@end deffn
+@xref{Classification of Characters,,,libc,GNU C Library Reference
+Manual}, for information about the @code{is*} Standard C functions
+mentioned above.
+
@node Strings
@section Strings
Strings are fixed-length sequences of characters. They can be created
by calling constructor procedures, but they can also literally get
-entered at the REPL or in Scheme source files.
+entered at the @acronym{REPL} or in Scheme source files.
Guile provides a rich set of string processing procedures, because text
handling is very important when Guile is used as a scripting language.
Strings always carry the information about how many characters they are
composed of with them, so there is no special end-of-string character,
like in C. That means that Scheme strings can contain any character,
-even the NUL character @code{'\0'}. But note: Since most operating
+even the @samp{NUL} character @samp{\0}. But note: Since most operating
system calls dealing with strings (such as for file operations) expect
strings to be zero-terminated, they might do unexpected things when
-called with string containing unusal characters.
+called with string containing unusual characters.
@menu
* String Syntax:: Read syntax for strings.
@subsection String Read Syntax
The read syntax for strings is an arbitrarily long sequence of
-characters enclosed in double quotes (@code{"}). @footnote{Actually, the
-current implementation restricts strings to a length of 2^24
-characters.} If you want to insert a double quote character into a
-string literal, it must be prefixed with a backslash @code{\} character
-(called an @dfn{escape character}).
+characters enclosed in double quotes (@code{"}).@footnote{Actually,
+the current implementation restricts strings to a length of
+@math{2^24}, or 16,777,216, characters. Sorry.} If you want to
+insert a double quote character into a string literal, it must be
+prefixed with a backslash @samp{\} character (called an @dfn{escape
+character}).
The following are examples of string literals:
@rnindex string?
@deffn {Scheme Procedure} string? obj
@deffnx {C Function} scm_string_p (obj)
-Return @code{#t} iff @var{obj} is a string, else @code{#f}.
+Return @code{#t} if @var{obj} is a string, else @code{#f}.
@end deffn
@deffn {Scheme Procedure} string-null? str
@var{str} must be a string, @var{start} and @var{end} must be
exact integers satisfying:
-0 <= @var{start} <= @var{end} <= (string-length @var{str}).
+0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
@end deffn
@node String Modification
@deffnx {C Function} scm_string_append (args)
Return a newly allocated string whose characters form the
concatenation of the given strings, @var{args}.
+
+@example
+(let ((h "hello "))
+ (string-append h "world"))
+@result{} "hello world"
+@end example
@end deffn
, Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
in many general Unix reference books.
-If your system does not include a POSIX regular expression library, and
-you have not linked Guile with a third-party regexp library such as Rx,
-these functions will not be available. You can tell whether your Guile
-installation includes regular expression support by checking whether the
-@code{*features*} list includes the @code{regex} symbol.
+If your system does not include a POSIX regular expression library,
+and you have not linked Guile with a third-party regexp library such
+as Rx, these functions will not be available. You can tell whether
+your Guile installation includes regular expression support by
+checking whether @code{(provided? 'regex)} returns true.
+
+The following regexp and string matching features are provided by the
+@code{(ice-9 regex)} module. Before using the described functions,
+you should load this module by executing @code{(use-modules (ice-9
+regex))}.
@menu
* Regexp Functions:: Functions that create and match regexps.
* Match Structures:: Finding what was matched by a regexp.
-* Backslash Escapes:: Removing the special meaning of regexp metacharacters.
+* Backslash Escapes:: Removing the special meaning of regexp
+ meta-characters.
@end menu
-[FIXME: it may be useful to include an Examples section. Parts of this
-interface are bewildering on first glance.]
@node Regexp Functions
@subsection Regexp Functions
implemented by SCSH, the Scheme Shell. It is intended to be
upwardly compatible with SCSH regular expressions.
-@c begin (scm-doc-string "regex.scm" "string-match")
@deffn {Scheme Procedure} string-match pattern str [start]
Compile the string @var{pattern} into a regular expression and compare
it with @var{str}. The optional numeric argument @var{start} specifies
@var{pattern} at all, @code{string-match} returns @code{#f}.
@end deffn
+Two examples of a match follow. In the first example, the pattern
+matches the four digits in the match string. In the second, the pattern
+matches nothing.
+
+@example
+(string-match "[0-9][0-9][0-9][0-9]" "blah2002")
+@result{} #("blah2002" (4 . 8))
+
+(string-match "[A-Za-z]" "123456")
+@result{} #f
+@end example
+
Each time @code{string-match} is called, it must compile its
@var{pattern} argument into a regular expression structure. This
operation is expensive, which makes @code{string-match} inefficient if
@end table
@end deffn
+@lisp
+;; Regexp to match uppercase letters
+(define r (make-regexp "[A-Z]*"))
+
+;; Regexp to match letters, ignoring case
+(define ri (make-regexp "[A-Z]*" regexp/icase))
+
+;; Search for bob using regexp r
+(match:substring (regexp-exec r "bob"))
+@result{} "" ; no match
+
+;; Search for bob using regexp ri
+(match:substring (regexp-exec ri "Bob"))
+@result{} "Bob" ; matched case insensitive
+@end lisp
+
@deffn {Scheme Procedure} regexp? obj
@deffnx {C Function} scm_regexp_p (obj)
Return @code{#t} if @var{obj} is a compiled regular expression,
the regexp match is written.
@end itemize
-@var{port} may be @code{#f}, in which case nothing is written; instead,
-@code{regexp-substitute} constructs a string from the specified
-@var{item}s and returns that.
+The @var{port} argument may be @code{#f}, in which case nothing is
+written; instead, @code{regexp-substitute} constructs a string from the
+specified @var{item}s and returns that.
@end deffn
+The following example takes a regular expression that matches a standard
+@sc{yyyymmdd}-format date such as @code{"20020828"}. The
+@code{regexp-substitute} call returns a string computed from the
+information in the match structure, consisting of the fields and text
+from the original string reordered and reformatted.
+
+@lisp
+(define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
+(define s "Date 20020429 12am.")
+(define sm (string-match date-regex s))
+(regexp-substitute #f sm 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
+@result{} "Date 04-29-2002 12am. (20020429)"
+@end lisp
+
@c begin (scm-doc-string "regex.scm" "regexp-substitute")
@deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
Similar to @code{regexp-substitute}, but can be used to perform global
@var{regexp} string describing a regular expression, and a @var{target}
string which should be matched against this regular expression.
-Each @var{item} behaves as in @var{regexp-substitute}, with the
+Each @var{item} behaves as in @code{regexp-substitute}, with the
following exceptions:
@itemize @bullet
@end itemize
@end deffn
+The example above for @code{regexp-substitute} could be rewritten as
+follows to remove the @code{string-match} stage:
+
+@lisp
+(define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
+(define s "Date 20020429 12am.")
+(regexp-substitute/global #f date-regex s
+ 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
+@result{} "Date 04-29-2002 12am. (20020429)"
+@end lisp
+
+
@node Match Structures
@subsection Match Structures
number @var{n} did not match, return @code{#f}.
@end deffn
+@lisp
+(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
+(match:substring s)
+@result{} "2002"
+
+;; match starting at offset 6 in the string
+(match:substring
+ (string-match "[0-9][0-9][0-9][0-9]" "blah987654" 6))
+@result{} "7654"
+@end lisp
+
@c begin (scm-doc-string "regex.scm" "match:start")
@deffn {Scheme Procedure} match:start match [n]
Return the starting position of submatch number @var{n}.
@end deffn
+In the following example, the result is 4, since the match starts at
+character index 4:
+
+@lisp
+(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
+(match:start s)
+@result{} 4
+@end lisp
+
@c begin (scm-doc-string "regex.scm" "match:end")
@deffn {Scheme Procedure} match:end match [n]
Return the ending position of submatch number @var{n}.
@end deffn
+In the following example, the result is 8, since the match runs between
+characters 4 and 8 (i.e. the ``2002'').
+
+@lisp
+(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
+(match:end s)
+@result{} 8
+@end lisp
+
@c begin (scm-doc-string "regex.scm" "match:prefix")
@deffn {Scheme Procedure} match:prefix match
Return the unmatched portion of @var{target} preceding the regexp match.
+
+@lisp
+(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
+(match:prefix s)
+@result{} "blah"
+@end lisp
@end deffn
@c begin (scm-doc-string "regex.scm" "match:suffix")
Return the unmatched portion of @var{target} following the regexp match.
@end deffn
+@lisp
+(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
+(match:suffix s)
+@result{} "foo"
+@end lisp
+
@c begin (scm-doc-string "regex.scm" "match:count")
@deffn {Scheme Procedure} match:count match
Return the number of parenthesized subexpressions from @var{match}.
Return the original @var{target} string.
@end deffn
+@lisp
+(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
+(match:string s)
+@result{} "blah2002foo"
+@end lisp
+
+
@node Backslash Escapes
@subsection Backslash Escapes
@section Symbols
@tpindex Symbols
-Symbols have two main uses. Crucially, they are used for denoting
-variables in a Scheme program. In addition, they are very useful for
-describing discrete literal data.
+Symbols in Scheme are widely used in three ways: as items of discrete
+data, as lookup keys for alists and hash tables, and to denote variable
+references.
-A symbol is an object with a name that consists of a string of
-characters. In the usual case (where the name doesn't include any
-characters that could be confused with other elements of Scheme syntax)
-a symbol can be written in a Scheme program by writing the sequence of
-characters that make up the symbol's name. For example, the read syntax
-for the symbol named "multiply-by-2" is simply
+A @dfn{symbol} is similar to a string in that it is defined by a
+sequence of characters. The sequence of characters is known as the
+symbol's @dfn{name}. In the usual case --- that is, where the symbol's
+name doesn't include any characters that could be confused with other
+elements of Scheme syntax --- a symbol is written in a Scheme program by
+writing the sequence of characters that make up the name, @emph{without}
+any quotation marks or other special syntax. For example, the symbol
+whose name is ``multiply-by-2'' is written, simply:
@lisp
multiply-by-2
@end lisp
-Symbols, then, look rather like strings but without any quotation marks.
-But there are several functional differences between them. The first
-big functional difference between symbols and strings concerns
-uniqueness. If the same-looking string is read twice from two different
-places in a program, the result is two @emph{distinguishable} string
-objects whose contents just happen to be the same. If, on the other
-hand, the same-looking symbol is read twice from two different places in
-a program, the result is the @emph{same} symbol object both times.
+Notice how this differs from a @emph{string} with contents
+``multiply-by-2'', which is written with double quotation marks, like
+this:
@lisp
-(define str1 "hello")
-(define str2 "hello")
-(eq? str1 str2) @result{} #f
+"multiply-by-2"
+@end lisp
+
+Looking beyond how they are written, symbols are different from strings
+in two important respects.
+
+The first important difference is uniqueness. If the same-looking
+string is read twice from two different places in a program, the result
+is two @emph{different} string objects whose contents just happen to be
+the same. If, on the other hand, the same-looking symbol is read twice
+from two different places in a program, the result is the @emph{same}
+symbol object both times.
+Given two read symbols, you can use @code{eq?} to test whether they are
+the same (that is, have the same name). @code{eq?} is the most
+efficient comparison operator in Scheme, and comparing two symbols like
+this is as fast as comparing, for example, two numbers. Given two
+strings, on the other hand, you must use @code{equal?} or
+@code{string=?}, which are much slower comparison operators, to
+determine whether the strings have the same contents.
+
+@lisp
(define sym1 (quote hello))
(define sym2 (quote hello))
(eq? sym1 sym2) @result{} #t
+
+(define str1 "hello")
+(define str2 "hello")
+(eq? str1 str2) @result{} #f
+(equal? str1 str2) @result{} #t
@end lisp
The second important difference is that symbols, unlike strings, are not
-self-evaluating. An unquoted symbol is interpreted as a variable
-reference, and the result of evaluating that symbol is the corresponding
-variable's value. (By the way, this is why we needed the @code{(quote
-@dots{})}s in the example above: @code{(quote hello)} returns the symbol
-object named "hello" itself, whereas an unquoted @code{hello} would try
-to find and dereference a variable associated with that symbol.)
-
-For example, when the expression @code{(string-length "abcd")} is read
-and evaluated, the sequence of characters @code{string-length} is read
-as the symbol whose name is "string-length". This symbol is associated
-with a variable whose value is the procedure that implements string
-length calculation. Therefore evaluation of the @code{string-length}
-symbol results in that procedure.
-
-Although the use of symbols for variable references is undoubtedly their
-most important role in Scheme, it is not documented further here. See
-instead @ref{Binding Constructs}, for how associations between symbols
-and variables are created, and @ref{Modules}, for how those associations
-are affected by Guile's module system. The rest of this section
-explains how symbols can also be used to represent discrete values, and
-documents the procedures available that relate to symbols as data
-objects @i{per se}.
+self-evaluating. This is why we need the @code{(quote @dots{})}s in the
+example above: @code{(quote hello)} evaluates to the symbol named
+"hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
+symbol named "hello" and evaluated as a variable reference @dots{} about
+which more below (@pxref{Symbol Variables}).
@menu
-* Symbol Read Syntax:: Extended read syntax for symbols.
+* Symbol Data:: Symbols as discrete data.
+* Symbol Keys:: Symbols as lookup keys.
+* Symbol Variables:: Symbols as denoting variables.
* Symbol Primitives:: Operations related to symbols.
-* Symbol Discrete:: Using symbols as discrete values.
* Symbol Props:: Function slots and property lists.
+* Symbol Read Syntax:: Extended read syntax for symbols.
+* Symbol Uninterned:: Uninterned symbols.
@end menu
-@node Symbol Read Syntax
-@subsection Extended Read Syntax for Symbols
+@node Symbol Data
+@subsection Symbols as Discrete Data
-The read syntax for symbols is a sequence of letters, digits, and
-@dfn{extended alphabetic characters}, beginning with a character that
-cannot begin a number. In addition, the special cases of @code{+},
-@code{-}, and @code{...} are read as symbols even though numbers can
-begin with @code{+}, @code{-} or @code{.}.
+Numbers and symbols are similar to the extent that they both lend
+themselves to @code{eq?} comparison. But symbols are more descriptive
+than numbers, because a symbol's name can be used directly to describe
+the concept for which that symbol stands.
-Extended alphabetic characters may be used within identifiers as if
-they were letters. The set of extended alphabetic characters is:
+For example, imagine that you need to represent some colours in a
+computer program. Using numbers, you would have to choose arbitrarily
+some mapping between numbers and colours, and then take care to use that
+mapping consistently:
-@example
-! $ % & * + - . / : < = > ? @@ ^ _ ~
-@end example
+@lisp
+;; 1=red, 2=green, 3=purple
-In addition to the standard read syntax defined above (which is taken
-from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
-Scheme})), Guile provides an extended symbol read syntax that allows the
-inclusion of unusual characters such as space characters, newlines and
-parentheses. If (for whatever reason) you need to write a symbol
-containing characters not mentioned above, you can do so as follows.
+(if (eq? (colour-of car) 1)
+ ...)
+@end lisp
+
+@noindent
+You can make the mapping more explicit and the code more readable by
+defining constants:
+
+@lisp
+(define red 1)
+(define green 2)
+(define purple 3)
+
+(if (eq? (colour-of car) red)
+ ...)
+@end lisp
+
+@noindent
+But the simplest and clearest approach is not to use numbers at all, but
+symbols whose names specify the colours that they refer to:
+
+@lisp
+(if (eq? (colour-of car) 'red)
+ ...)
+@end lisp
+
+The descriptive advantages of symbols over numbers increase as the set
+of concepts that you want to describe grows. Suppose that a car object
+can have other properties as well, such as whether it has or uses:
@itemize @bullet
@item
-Begin the symbol with the characters @code{#@{},
-
+automatic or manual transmission
@item
-write the characters of the symbol and
-
+leaded or unleaded fuel
@item
-finish the symbol with the characters @code{@}#}.
+power steering (or not).
@end itemize
-Here are a few examples of this form of read syntax. The first symbol
-needs to use extended syntax because it contains a space character, the
-second because it contains a line break, and the last because it looks
-like a number.
+@noindent
+Then a car's combined property set could be naturally represented and
+manipulated as a list of symbols:
@lisp
-#@{foo bar@}#
+(properties-of car1)
+@result{}
+(red manual unleaded power-steering)
-#@{what
-ever@}#
+(if (memq 'power-steering (properties-of car1))
+ (display "Unfit people can drive this car.\n")
+ (display "You'll need strong arms to drive this car!\n"))
+@print{}
+Unfit people can drive this car.
+@end lisp
-#@{4242@}#
+Remember, the fundamental property of symbols that we are relying on
+here is that an occurrence of @code{'red} in one part of a program is an
+@emph{indistinguishable} symbol from an occurrence of @code{'red} in
+another part of a program; this means that symbols can usefully be
+compared using @code{eq?}. At the same time, symbols have naturally
+descriptive names. This combination of efficiency and descriptive power
+makes them ideal for use as discrete data.
+
+
+@node Symbol Keys
+@subsection Symbols as Lookup Keys
+
+Given their efficiency and descriptive power, it is natural to use
+symbols as the keys in an association list or hash table.
+
+To illustrate this, consider a more structured representation of the car
+properties example from the preceding subsection. Rather than
+mixing all the properties up together in a flat list, we could use an
+association list like this:
+
+@lisp
+(define car1-properties '((colour . red)
+ (transmission . manual)
+ (fuel . unleaded)
+ (steering . power-assisted)))
@end lisp
-Although Guile provides this extended read syntax for symbols,
-widespread usage of it is discouraged because it is not portable and not
-very readable.
+Notice how this structure is more explicit and extensible than the flat
+list. For example it makes clear that @code{manual} refers to the
+transmission rather than, say, the windows or the locking of the car.
+It also allows further properties to use the same symbols among their
+possible values without becoming ambiguous:
+
+@lisp
+(define car1-properties '((colour . red)
+ (transmission . manual)
+ (fuel . unleaded)
+ (steering . power-assisted)
+ (seat-colour . red)
+ (locking . manual)))
+@end lisp
+
+With a representation like this, it is easy to use the efficient
+@code{assq-XXX} family of procedures (@pxref{Association Lists}) to
+extract or change individual pieces of information:
+
+@lisp
+(assq-ref car1-properties 'fuel) @result{} unleaded
+(assq-ref car1-properties 'transmission) @result{} manual
+
+(assq-set! car1-properties 'seat-colour 'black)
+@result{}
+((colour . red)
+ (transmission . manual)
+ (fuel . unleaded)
+ (steering . power-assisted)
+ (seat-colour . black)
+ (locking . manual)))
+@end lisp
+
+Hash tables also have keys, and exactly the same arguments apply to the
+use of symbols in hash tables as in association lists. The hash value
+that Guile uses to decide where to add a symbol-keyed entry to a hash
+table can be obtained by calling the @code{symbol-hash} procedure:
+
+@deffn {Scheme Procedure} symbol-hash symbol
+@deffnx {C Function} scm_symbol_hash (symbol)
+Return a hash value for @var{symbol}.
+@end deffn
+
+See @ref{Hash Tables} for information about hash tables in general, and
+for why you might choose to use a hash table rather than an association
+list.
+
+
+@node Symbol Variables
+@subsection Symbols as Denoting Variables
+
+When an unquoted symbol in a Scheme program is evaluated, it is
+interpreted as a variable reference, and the result of the evaluation is
+the appropriate variable's value.
+
+For example, when the expression @code{(string-length "abcd")} is read
+and evaluated, the sequence of characters @code{string-length} is read
+as the symbol whose name is "string-length". This symbol is associated
+with a variable whose value is the procedure that implements string
+length calculation. Therefore evaluation of the @code{string-length}
+symbol results in that procedure.
+
+The details of the connection between an unquoted symbol and the
+variable to which it refers are explained elsewhere. See @ref{Binding
+Constructs}, for how associations between symbols and variables are
+created, and @ref{Modules}, for how those associations are affected by
+Guile's module system.
@node Symbol Primitives
@subsection Operations Related to Symbols
+Given any Scheme value, you can determine whether it is a symbol using
+the @code{symbol?} primitive:
+
@rnindex symbol?
@deffn {Scheme Procedure} symbol? obj
@deffnx {C Function} scm_symbol_p (obj)
@code{#f}.
@end deffn
+Once you know that you have a symbol, you can obtain its name as a
+string by calling @code{symbol->string}. Note that Guile differs by
+default from R5RS on the details of @code{symbol->string} as regards
+case-sensitivity:
+
+@rnindex symbol->string
+@deffn {Scheme Procedure} symbol->string s
+@deffnx {C Function} scm_symbol_to_string (s)
+Return the name of symbol @var{s} as a string. By default, Guile reads
+symbols case-sensitively, so the string returned will have the same case
+variation as the sequence of characters that caused @var{s} to be
+created.
+
+If Guile is set to read symbols case-insensitively (as specified by
+R5RS), and @var{s} comes into being as part of a literal expression
+(@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
+by a call to the @code{read} or @code{string-ci->symbol} procedures,
+Guile converts any alphabetic characters in the symbol's name to
+lower case before creating the symbol object, so the string returned
+here will be in lower case.
+
+If @var{s} was created by @code{string->symbol}, the case of characters
+in the string returned will be the same as that in the string that was
+passed to @code{string->symbol}, regardless of Guile's case-sensitivity
+setting at the time @var{s} was created.
+
+It is an error to apply mutation procedures like @code{string-set!} to
+strings returned by this procedure.
+@end deffn
+
+Most symbols are created by writing them literally in code. However it
+is also possible to create symbols programmatically using the following
+@code{string->symbol} and @code{string-ci->symbol} procedures:
+
@rnindex string->symbol
@deffn {Scheme Procedure} string->symbol string
@deffnx {C Function} scm_string_to_symbol (string)
-Return the symbol whose name is @var{string}. This procedure
-can create symbols with names containing special characters or
-letters in the non-standard case, but it is usually a bad idea
-to create such symbols because in some implementations of
-Scheme they cannot be read as themselves. See
-@code{symbol->string}.
-
-The following examples assume that the implementation's
-standard case is lower case:
-
-@lisp
-(eq? 'mISSISSIppi 'mississippi) @result{} #t
-(string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
-(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
-(eq? 'JollyWog
- (string->symbol (symbol->string 'JollyWog))) @result{} #t
-(string=? "K. Harper, M.D."
- (symbol->string
- (string->symbol "K. Harper, M.D."))) @result{}#t
-@end lisp
+Return the symbol whose name is @var{string}. This procedure can create
+symbols with names containing special characters or letters in the
+non-standard case, but it is usually a bad idea to create such symbols
+because in some implementations of Scheme they cannot be read as
+themselves.
@end deffn
@deffn {Scheme Procedure} string-ci->symbol str
@deffnx {C Function} scm_string_ci_to_symbol (str)
-Return the symbol whose name is @var{str}. @var{str} is
-converted to lowercase before the conversion is done, if Guile
-is currently reading symbols case-insensitively.
+Return the symbol whose name is @var{str}. If Guile is currently
+reading symbols case-insensitively, @var{str} is converted to lowercase
+before the returned symbol is looked up or created.
@end deffn
-@rnindex symbol->string
-@deffn {Scheme Procedure} symbol->string s
-@deffnx {C Function} scm_symbol_to_string (s)
-Return the name of @var{symbol} as a string. If the symbol was
-part of an object returned as the value of a literal expression
-(section @pxref{Literal expressions,,,r5rs, The Revised^5
-Report on Scheme}) or by a call to the @code{read} procedure,
-and its name contains alphabetic characters, then the string
-returned will contain characters in the implementation's
-preferred standard case---some implementations will prefer
-upper case, others lower case. If the symbol was returned by
-@code{string->symbol}, the case of characters in the string
-returned will be the same as the case in the string that was
-passed to @code{string->symbol}. It is an error to apply
-mutation procedures like @code{string-set!} to strings returned
-by this procedure.
-
-The following examples assume that the implementation's
-standard case is lower case:
+The following examples illustrate Guile's detailed behaviour as regards
+the case-sensitivity of symbols:
@lisp
+(read-enable 'case-insensitive) ; R5RS compliant behaviour
+
+(symbol->string 'flying-fish) @result{} "flying-fish"
+(symbol->string 'Martin) @result{} "martin"
+(symbol->string
+ (string->symbol "Malvina")) @result{} "Malvina"
+
+(eq? 'mISSISSIppi 'mississippi) @result{} #t
+(string->symbol "mISSISSIppi") @result{} mISSISSIppi
+(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
+(eq? 'LolliPop
+ (string->symbol (symbol->string 'LolliPop))) @result{} #t
+(string=? "K. Harper, M.D."
+ (symbol->string
+ (string->symbol "K. Harper, M.D."))) @result{} #t
+
+(read-disable 'case-insensitive) ; Guile default behaviour
+
(symbol->string 'flying-fish) @result{} "flying-fish"
-(symbol->string 'Martin) @result{} "martin"
+(symbol->string 'Martin) @result{} "Martin"
(symbol->string
- (string->symbol "Malvina")) @result{} "Malvina"
+ (string->symbol "Malvina")) @result{} "Malvina"
+
+(eq? 'mISSISSIppi 'mississippi) @result{} #f
+(string->symbol "mISSISSIppi") @result{} mISSISSIppi
+(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
+(eq? 'LolliPop
+ (string->symbol (symbol->string 'LolliPop))) @result{} #t
+(string=? "K. Harper, M.D."
+ (symbol->string
+ (string->symbol "K. Harper, M.D."))) @result{} #t
@end lisp
-@end deffn
-@deffn {Scheme Procedure} symbol-hash symbol
-@deffnx {C Function} scm_symbol_hash (symbol)
-Return a hash value for @var{symbol}.
+From C, there are lower level functions that construct a Scheme symbol
+from a null terminated C string or from a sequence of bytes whose length
+is specified explicitly.
+
+@deffn {C Function} scm_str2symbol (const char * name)
+@deffnx {C Function} scm_mem2symbol (const char * name, size_t len)
+Construct and return a Scheme symbol whose name is specified by
+@var{name}. For @code{scm_str2symbol} @var{name} must be null
+terminated; For @code{scm_mem2symbol} the length of @var{name} is
+specified explicitly by @var{len}.
@end deffn
+Finally, some applications, especially those that generate new Scheme
+code dynamically, need to generate symbols for use in the generated
+code. The @code{gensym} primitive meets this need:
+
@deffn {Scheme Procedure} gensym [prefix]
@deffnx {C Function} scm_gensym (prefix)
-Create a new symbol with a name constructed from a prefix and
-a counter value. The string @var{prefix} can be specified as
-an optional argument. Default prefix is @code{g}. The counter
-is increased by 1 at each call. There is no provision for
-resetting the counter.
+Create a new symbol with a name constructed from a prefix and a counter
+value. The string @var{prefix} can be specified as an optional
+argument. Default prefix is @samp{@w{ g}}. The counter is increased by 1
+at each call. There is no provision for resetting the counter.
@end deffn
+The symbols generated by @code{gensym} are @emph{likely} to be unique,
+since their names begin with a space and it is only otherwise possible
+to generate such symbols if a programmer goes out of their way to do
+so. Uniqueness can be guaranteed by instead using uninterned symbols
+(@pxref{Symbol Uninterned}), though they can't be usefully written out
+and read back in.
-@node Symbol Discrete
-@subsection Using Symbols as Discrete Values
-Symbols are especially useful because two symbols which are spelled the
-same way are equivalent in the sense of @code{eq?}. That means that
-they are actually the same Scheme object. The advantage is that symbols
-can be compared extremely efficiently, although they carry more
-information for the human reader than, say, numbers.
+@node Symbol Props
+@subsection Function Slots and Property Lists
-It is very common in Scheme programs to use symbols as keys in
-association lists (@pxref{Association Lists}) or hash tables
-(@pxref{Hash Tables}), because this usage improves the readability a
-lot, and does not cause any performance loss.
+In traditional Lisp dialects, symbols are often understood as having
+three kinds of value at once:
+@itemize @bullet
+@item
+a @dfn{variable} value, which is used when the symbol appears in
+code in a variable reference context
-@node Symbol Props
-@subsection Function Slots and Property Lists
+@item
+a @dfn{function} value, which is used when the symbol appears in
+code in a function name position (i.e. as the first element in an
+unquoted list)
+
+@item
+a @dfn{property list} value, which is used when the symbol is given as
+the first argument to Lisp's @code{put} or @code{get} functions.
+@end itemize
+
+Although Scheme (as one of its simplifications with respect to Lisp)
+does away with the distinction between variable and function namespaces,
+Guile currently retains some elements of the traditional structure in
+case they turn out to be useful when implementing translators for other
+languages, in particular Emacs Lisp.
+
+Specifically, Guile symbols have two extra slots. for a symbol's
+property list, and for its ``function value.'' The following procedures
+are provided to access these slots.
@deffn {Scheme Procedure} symbol-fref symbol
@deffnx {C Function} scm_symbol_fref (symbol)
@deffn {Scheme Procedure} symbol-fset! symbol value
@deffnx {C Function} scm_symbol_fset_x (symbol, value)
-Change the binding of @var{symbol}'s function slot.
+Set the contents of @var{symbol}'s function slot to @var{value}.
@end deffn
@deffn {Scheme Procedure} symbol-pref symbol
@deffn {Scheme Procedure} symbol-pset! symbol value
@deffnx {C Function} scm_symbol_pset_x (symbol, value)
-Change the binding of @var{symbol}'s property slot.
+Set @var{symbol}'s property list to @var{value}.
@end deffn
+@deffn {Scheme Procedure} symbol-property sym prop
+From @var{sym}'s property list, return the value for property
+@var{prop}. The assumption is that @var{sym}'s property list is an
+association list whose keys are distinguished from each other using
+@code{equal?}; @var{prop} should be one of the keys in that list. If
+the property list has no entry for @var{prop}, @code{symbol-property}
+returns @code{#f}.
+@end deffn
+
+@deffn {Scheme Procedure} set-symbol-property! sym prop val
+In @var{sym}'s property list, set the value for property @var{prop} to
+@var{val}, or add a new entry for @var{prop}, with value @var{val}, if
+none already exists. For the structure of the property list, see
+@code{symbol-property}.
+@end deffn
+
+@deffn {Scheme Procedure} symbol-property-remove! sym prop
+From @var{sym}'s property list, remove the entry for property
+@var{prop}, if there is one. For the structure of the property list,
+see @code{symbol-property}.
+@end deffn
+
+Support for these extra slots may be removed in a future release, and it
+is probably better to avoid using them. (In release 1.6, Guile itself
+uses the property list slot sparingly, and the function slot not at
+all.) For a more modern and Schemely approach to properties, see
+@ref{Object Properties}.
+
+
+@node Symbol Read Syntax
+@subsection Extended Read Syntax for Symbols
+
+The read syntax for a symbol is a sequence of letters, digits, and
+@dfn{extended alphabetic characters}, beginning with a character that
+cannot begin a number. In addition, the special cases of @code{+},
+@code{-}, and @code{...} are read as symbols even though numbers can
+begin with @code{+}, @code{-} or @code{.}.
+
+Extended alphabetic characters may be used within identifiers as if
+they were letters. The set of extended alphabetic characters is:
+
+@example
+! $ % & * + - . / : < = > ? @@ ^ _ ~
+@end example
+
+In addition to the standard read syntax defined above (which is taken
+from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
+Scheme})), Guile provides an extended symbol read syntax that allows the
+inclusion of unusual characters such as space characters, newlines and
+parentheses. If (for whatever reason) you need to write a symbol
+containing characters not mentioned above, you can do so as follows.
+
+@itemize @bullet
+@item
+Begin the symbol with the characters @code{#@{},
+
+@item
+write the characters of the symbol and
+
+@item
+finish the symbol with the characters @code{@}#}.
+@end itemize
+
+Here are a few examples of this form of read syntax. The first symbol
+needs to use extended syntax because it contains a space character, the
+second because it contains a line break, and the last because it looks
+like a number.
+
+@lisp
+#@{foo bar@}#
+
+#@{what
+ever@}#
+
+#@{4242@}#
+@end lisp
+
+Although Guile provides this extended read syntax for symbols,
+widespread usage of it is discouraged because it is not portable and not
+very readable.
+
+
+@node Symbol Uninterned
+@subsection Uninterned Symbols
+
+What makes symbols useful is that they are automatically kept unique.
+There are no two symbols that are distinct objects but have the same
+name. But of course, there is no rule without exception. In addition
+to the normal symbols that have been discussed up to now, you can also
+create special @dfn{uninterned} symbols that behave slightly
+differently.
+
+To understand what is different about them and why they might be useful,
+we look at how normal symbols are actually kept unique.
+
+Whenever Guile wants to find the symbol with a specific name, for
+example during @code{read} or when executing @code{string->symbol}, it
+first looks into a table of all existing symbols to find out whether a
+symbol with the given name already exists. When this is the case, Guile
+just returns that symbol. When not, a new symbol with the name is
+created and entered into the table so that it can be found later.
+
+Sometimes you might want to create a symbol that is guaranteed `fresh',
+i.e. a symbol that did not exist previously. You might also want to
+somehow guarantee that no one else will ever unintentionally stumble
+across your symbol in the future. These properties of a symbol are
+often needed when generating code during macro expansion. When
+introducing new temporary variables, you want to guarantee that they
+don't conflict with variables in other people's code.
+
+The simplest way to arrange for this is to create a new symbol but
+not enter it into the global table of all symbols. That way, no one
+will ever get access to your symbol by chance. Symbols that are not in
+the table are called @dfn{uninterned}. Of course, symbols that
+@emph{are} in the table are called @dfn{interned}.
+
+You create new uninterned symbols with the function @code{make-symbol}.
+You can test whether a symbol is interned or not with
+@code{symbol-interned?}.
+
+Uninterned symbols break the rule that the name of a symbol uniquely
+identifies the symbol object. Because of this, they can not be written
+out and read back in like interned symbols. Currently, Guile has no
+support for reading uninterned symbols. Note that the function
+@code{gensym} does not return uninterned symbols for this reason.
+
+@deffn {Scheme Procedure} make-symbol name
+@deffnx {C Function} scm_make_symbol (name)
+Return a new uninterned symbol with the name @var{name}. The returned
+symbol is guaranteed to be unique and future calls to
+@code{string->symbol} will not return it.
+@end deffn
+
+@deffn {Scheme Procedure} symbol-interned? symbol
+@deffnx {C Function} scm_symbol_interned_p (symbol)
+Return @code{#t} if @var{symbol} is interned, otherwise return
+@code{#f}.
+@end deffn
+
+For example:
+
+@lisp
+(define foo-1 (string->symbol "foo"))
+(define foo-2 (string->symbol "foo"))
+(define foo-3 (make-symbol "foo"))
+(define foo-4 (make-symbol "foo"))
+
+(eq? foo-1 foo-2)
+@result{} #t
+; Two interned symbols with the same name are the same object,
+
+(eq? foo-1 foo-3)
+@result{} #f
+; but a call to make-symbol with the same name returns a
+; distinct object.
+
+(eq? foo-3 foo-4)
+@result{} #f
+; A call to make-symbol always returns a new object, even for
+; the same name.
+
+foo-3
+@result{} #<uninterned-symbol foo 8085290>
+; Uninterned symbols print differently from interned symbols,
+
+(symbol? foo-3)
+@result{} #t
+; but they are still symbols,
+
+(symbol-interned? foo-3)
+@result{} #f
+; just not interned.
+@end lisp
+
@node Keywords
@section Keywords
@itemize @bullet
@item
-colour depth -- Default: the colour depth for the screen
+color depth -- Default: the color depth for the screen
@item
-background colour -- Default: white
+background color -- Default: white
@item
width -- Default: 600
for that argument:
@lisp
-(make-window 'default ;; Colour depth
- 'default ;; Background colour
+(make-window 'default ;; Color depth
+ 'default ;; Background color
800 ;; Width
100 ;; Height
@dots{}) ;; More make-window arguments
of the form @code{:NAME} are read as symbols, as required by R5RS.
To enable and disable the alternative non-R5RS keyword syntax, you use
-the @code{read-options} procedure documented in @ref{General option
-interface} and @ref{Reader options}.
+the @code{read-set!} procedure documented in @ref{User level options
+interfaces} and @ref{Reader options}.
@smalllisp
(read-set! keywords 'prefix)
@node Keyword Procedures
@subsection Keyword Procedures
-@c FIXME::martin: Review me!
-
The following procedures can be used for converting symbols to keywords
and back.
@deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
@deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
Make a keyword object from a @var{symbol} that starts with a dash.
+For example,
+
+@example
+(make-keyword-from-dash-symbol '-foo)
+@result{} #:foo
+@end example
@end deffn
@deffn {Scheme Procedure} keyword? obj
@deffnx {C Function} scm_keyword_dash_symbol (keyword)
Return the dash symbol for @var{keyword}.
This is the inverse of @code{make-keyword-from-dash-symbol}.
+For example,
+
+@example
+(keyword-dash-symbol #:foo)
+@result{} -foo
+@end example
@end deffn
+@deftypefn {C Function} SCM scm_c_make_keyword (char *@var{str})
+Make a keyword object from a string. For example,
+
+@example
+scm_c_make_keyword ("foo")
+@result{} #:foo
+@end example
+@c
+@c FIXME: What can be said about the string argument? Currently it's
+@c not used after creation, but should that be documented?
+@end deftypefn
+
@node Other Types
@section ``Functionality-Centric'' Data Types
HCoop / bpt / guile.git / blobdiff