Typos.
[bpt/guile.git] / doc / ref / api-data.texi
1 @c -*-texinfo-*-
2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
6
7 @page
8 @node Simple Data Types
9 @section Simple Generic Data Types
10
11 This chapter describes those of Guile's simple data types which are
12 primarily used for their role as items of generic data. By
13 @dfn{simple} we mean data types that are not primarily used as
14 containers to hold other data --- i.e.@: pairs, lists, vectors and so on.
15 For the documentation of such @dfn{compound} data types, see
16 @ref{Compound Data Types}.
17
18 @c One of the great strengths of Scheme is that there is no straightforward
19 @c distinction between ``data'' and ``functionality''. For example,
20 @c Guile's support for dynamic linking could be described:
21
22 @c @itemize @bullet
23 @c @item
24 @c either in a ``data-centric'' way, as the behaviour and properties of the
25 @c ``dynamically linked object'' data type, and the operations that may be
26 @c applied to instances of this type
27
28 @c @item
29 @c or in a ``functionality-centric'' way, as the set of procedures that
30 @c constitute Guile's support for dynamic linking, in the context of the
31 @c module system.
32 @c @end itemize
33
34 @c The contents of this chapter are, therefore, a matter of judgment. By
35 @c @dfn{generic}, we mean to select those data types whose typical use as
36 @c @emph{data} in a wide variety of programming contexts is more important
37 @c than their use in the implementation of a particular piece of
38 @c @emph{functionality}. The last section of this chapter provides
39 @c references for all the data types that are documented not here but in a
40 @c ``functionality-centric'' way elsewhere in the manual.
41
42 @menu
43 * Booleans:: True/false values.
44 * Numbers:: Numerical data types.
45 * Characters:: New character names.
46 * Strings:: Special things about strings.
47 * Regular Expressions:: Pattern matching and substitution.
48 * Symbols:: Symbols.
49 * Keywords:: Self-quoting, customizable display keywords.
50 * Other Types:: "Functionality-centric" data types.
51 @end menu
52
53
54 @node Booleans
55 @subsection Booleans
56 @tpindex Booleans
57
58 The two boolean values are @code{#t} for true and @code{#f} for false.
59
60 Boolean values are returned by predicate procedures, such as the general
61 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
62 (@pxref{Equality}) and numerical and string comparison operators like
63 @code{string=?} (@pxref{String Comparison}) and @code{<=}
64 (@pxref{Comparison}).
65
66 @lisp
67 (<= 3 8)
68 @result{} #t
69
70 (<= 3 -3)
71 @result{} #f
72
73 (equal? "house" "houses")
74 @result{} #f
75
76 (eq? #f #f)
77 @result{}
78 #t
79 @end lisp
80
81 In test condition contexts like @code{if} and @code{cond} (@pxref{if
82 cond case}), where a group of subexpressions will be evaluated only if a
83 @var{condition} expression evaluates to ``true'', ``true'' means any
84 value at all except @code{#f}.
85
86 @lisp
87 (if #t "yes" "no")
88 @result{} "yes"
89
90 (if 0 "yes" "no")
91 @result{} "yes"
92
93 (if #f "yes" "no")
94 @result{} "no"
95 @end lisp
96
97 A result of this asymmetry is that typical Scheme source code more often
98 uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
99 represent an @code{if} or @code{cond} false value, whereas @code{#t} is
100 not necessary to represent an @code{if} or @code{cond} true value.
101
102 It is important to note that @code{#f} is @strong{not} equivalent to any
103 other Scheme value. In particular, @code{#f} is not the same as the
104 number 0 (like in C and C++), and not the same as the ``empty list''
105 (like in some Lisp dialects).
106
107 In C, the two Scheme boolean values are available as the two constants
108 @code{SCM_BOOL_T} for @code{#t} and @code{SCM_BOOL_F} for @code{#f}.
109 Care must be taken with the false value @code{SCM_BOOL_F}: it is not
110 false when used in C conditionals. In order to test for it, use
111 @code{scm_is_false} or @code{scm_is_true}.
112
113 @rnindex not
114 @deffn {Scheme Procedure} not x
115 @deffnx {C Function} scm_not (x)
116 Return @code{#t} if @var{x} is @code{#f}, else return @code{#f}.
117 @end deffn
118
119 @rnindex boolean?
120 @deffn {Scheme Procedure} boolean? obj
121 @deffnx {C Function} scm_boolean_p (obj)
122 Return @code{#t} if @var{obj} is either @code{#t} or @code{#f}, else
123 return @code{#f}.
124 @end deffn
125
126 @deftypevr {C Macro} SCM SCM_BOOL_T
127 The @code{SCM} representation of the Scheme object @code{#t}.
128 @end deftypevr
129
130 @deftypevr {C Macro} SCM SCM_BOOL_F
131 The @code{SCM} representation of the Scheme object @code{#f}.
132 @end deftypevr
133
134 @deftypefn {C Function} int scm_is_true (SCM obj)
135 Return @code{0} if @var{obj} is @code{#f}, else return @code{1}.
136 @end deftypefn
137
138 @deftypefn {C Function} int scm_is_false (SCM obj)
139 Return @code{1} if @var{obj} is @code{#f}, else return @code{0}.
140 @end deftypefn
141
142 @deftypefn {C Function} int scm_is_bool (SCM obj)
143 Return @code{1} if @var{obj} is either @code{#t} or @code{#f}, else
144 return @code{0}.
145 @end deftypefn
146
147 @deftypefn {C Function} SCM scm_from_bool (int val)
148 Return @code{#f} if @var{val} is @code{0}, else return @code{#t}.
149 @end deftypefn
150
151 @deftypefn {C Function} int scm_to_bool (SCM val)
152 Return @code{1} if @var{val} is @code{SCM_BOOL_T}, return @code{0}
153 when @var{val} is @code{SCM_BOOL_F}, else signal a `wrong type' error.
154
155 You should probably use @code{scm_is_true} instead of this function
156 when you just want to test a @code{SCM} value for trueness.
157 @end deftypefn
158
159 @node Numbers
160 @subsection Numerical data types
161 @tpindex Numbers
162
163 Guile supports a rich ``tower'' of numerical types --- integer,
164 rational, real and complex --- and provides an extensive set of
165 mathematical and scientific functions for operating on numerical
166 data. This section of the manual documents those types and functions.
167
168 You may also find it illuminating to read R5RS's presentation of numbers
169 in Scheme, which is particularly clear and accessible: see
170 @ref{Numbers,,,r5rs,R5RS}.
171
172 @menu
173 * Numerical Tower:: Scheme's numerical "tower".
174 * Integers:: Whole numbers.
175 * Reals and Rationals:: Real and rational numbers.
176 * Complex Numbers:: Complex numbers.
177 * Exactness:: Exactness and inexactness.
178 * Number Syntax:: Read syntax for numerical data.
179 * Integer Operations:: Operations on integer values.
180 * Comparison:: Comparison predicates.
181 * Conversion:: Converting numbers to and from strings.
182 * Complex:: Complex number operations.
183 * Arithmetic:: Arithmetic functions.
184 * Scientific:: Scientific functions.
185 * Primitive Numerics:: Primitive numeric functions.
186 * Bitwise Operations:: Logical AND, OR, NOT, and so on.
187 * Random:: Random number generation.
188 @end menu
189
190
191 @node Numerical Tower
192 @subsubsection Scheme's Numerical ``Tower''
193 @rnindex number?
194
195 Scheme's numerical ``tower'' consists of the following categories of
196 numbers:
197
198 @table @dfn
199 @item integers
200 Whole numbers, positive or negative; e.g.@: --5, 0, 18.
201
202 @item rationals
203 The set of numbers that can be expressed as @math{@var{p}/@var{q}}
204 where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
205 pi (an irrational number) doesn't. These include integers
206 (@math{@var{n}/1}).
207
208 @item real numbers
209 The set of numbers that describes all possible positions along a
210 one-dimensional line. This includes rationals as well as irrational
211 numbers.
212
213 @item complex numbers
214 The set of numbers that describes all possible positions in a two
215 dimensional space. This includes real as well as imaginary numbers
216 (@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
217 @var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
218 @minus{}1.)
219 @end table
220
221 It is called a tower because each category ``sits on'' the one that
222 follows it, in the sense that every integer is also a rational, every
223 rational is also real, and every real number is also a complex number
224 (but with zero imaginary part).
225
226 In addition to the classification into integers, rationals, reals and
227 complex numbers, Scheme also distinguishes between whether a number is
228 represented exactly or not. For example, the result of
229 @m{2\sin(\pi/4),sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)} but Guile
230 can neither represent @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
231 Instead, it stores an inexact approximation, using the C type
232 @code{double}.
233
234 Guile can represent exact rationals of any magnitude, inexact
235 rationals that fit into a C @code{double}, and inexact complex numbers
236 with @code{double} real and imaginary parts.
237
238 The @code{number?} predicate may be applied to any Scheme value to
239 discover whether the value is any of the supported numerical types.
240
241 @deffn {Scheme Procedure} number? obj
242 @deffnx {C Function} scm_number_p (obj)
243 Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
244 @end deffn
245
246 For example:
247
248 @lisp
249 (number? 3)
250 @result{} #t
251
252 (number? "hello there!")
253 @result{} #f
254
255 (define pi 3.141592654)
256 (number? pi)
257 @result{} #t
258 @end lisp
259
260 @deftypefn {C Function} int scm_is_number (SCM obj)
261 This is equivalent to @code{scm_is_true (scm_number_p (obj))}.
262 @end deftypefn
263
264 The next few subsections document each of Guile's numerical data types
265 in detail.
266
267 @node Integers
268 @subsubsection Integers
269
270 @tpindex Integer numbers
271
272 @rnindex integer?
273
274 Integers are whole numbers, that is numbers with no fractional part,
275 such as 2, 83, and @minus{}3789.
276
277 Integers in Guile can be arbitrarily big, as shown by the following
278 example.
279
280 @lisp
281 (define (factorial n)
282 (let loop ((n n) (product 1))
283 (if (= n 0)
284 product
285 (loop (- n 1) (* product n)))))
286
287 (factorial 3)
288 @result{} 6
289
290 (factorial 20)
291 @result{} 2432902008176640000
292
293 (- (factorial 45))
294 @result{} -119622220865480194561963161495657715064383733760000000000
295 @end lisp
296
297 Readers whose background is in programming languages where integers are
298 limited by the need to fit into just 4 or 8 bytes of memory may find
299 this surprising, or suspect that Guile's representation of integers is
300 inefficient. In fact, Guile achieves a near optimal balance of
301 convenience and efficiency by using the host computer's native
302 representation of integers where possible, and a more general
303 representation where the required number does not fit in the native
304 form. Conversion between these two representations is automatic and
305 completely invisible to the Scheme level programmer.
306
307 The infinities @samp{+inf.0} and @samp{-inf.0} are considered to be
308 inexact integers. They are explained in detail in the next section,
309 together with reals and rationals.
310
311 C has a host of different integer types, and Guile offers a host of
312 functions to convert between them and the @code{SCM} representation.
313 For example, a C @code{int} can be handled with @code{scm_to_int} and
314 @code{scm_from_int}. Guile also defines a few C integer types of its
315 own, to help with differences between systems.
316
317 C integer types that are not covered can be handled with the generic
318 @code{scm_to_signed_integer} and @code{scm_from_signed_integer} for
319 signed types, or with @code{scm_to_unsigned_integer} and
320 @code{scm_from_unsigned_integer} for unsigned types.
321
322 Scheme integers can be exact and inexact. For example, a number
323 written as @code{3.0} with an explicit decimal-point is inexact, but
324 it is also an integer. The functions @code{integer?} and
325 @code{scm_is_integer} report true for such a number, but the functions
326 @code{scm_is_signed_integer} and @code{scm_is_unsigned_integer} only
327 allow exact integers and thus report false. Likewise, the conversion
328 functions like @code{scm_to_signed_integer} only accept exact
329 integers.
330
331 The motivation for this behavior is that the inexactness of a number
332 should not be lost silently. If you want to allow inexact integers,
333 you can explicitely insert a call to @code{inexact->exact} or to its C
334 equivalent @code{scm_inexact_to_exact}. (Only inexact integers will
335 be converted by this call into exact integers; inexact non-integers
336 will become exact fractions.)
337
338 @deffn {Scheme Procedure} integer? x
339 @deffnx {C Function} scm_integer_p (x)
340 Return @code{#t} if @var{x} is an exactor inexact integer number, else
341 @code{#f}.
342
343 @lisp
344 (integer? 487)
345 @result{} #t
346
347 (integer? 3.0)
348 @result{} #t
349
350 (integer? -3.4)
351 @result{} #f
352
353 (integer? +inf.0)
354 @result{} #t
355 @end lisp
356 @end deffn
357
358 @deftypefn {C Function} int scm_is_integer (SCM x)
359 This is equivalent to @code{scm_is_true (scm_integer_p (x))}.
360 @end deftypefn
361
362 @defvr {C Type} scm_t_int8
363 @defvrx {C Type} scm_t_uint8
364 @defvrx {C Type} scm_t_int16
365 @defvrx {C Type} scm_t_uint16
366 @defvrx {C Type} scm_t_int32
367 @defvrx {C Type} scm_t_uint32
368 @defvrx {C Type} scm_t_int64
369 @defvrx {C Type} scm_t_uint64
370 @defvrx {C Type} scm_t_intmax
371 @defvrx {C Type} scm_t_uintmax
372 The C types are equivalent to the corresponding ISO C types but are
373 defined on all platforms, with the exception of @code{scm_t_int64} and
374 @code{scm_t_uint64}, which are only defined when a 64-bit type is
375 available. For example, @code{scm_t_int8} is equivalent to
376 @code{int8_t}.
377
378 You can regard these definitions as a stop-gap measure until all
379 platforms provide these types. If you know that all the platforms
380 that you are interested in already provide these types, it is better
381 to use them directly instead of the types provided by Guile.
382 @end defvr
383
384 @deftypefn {C Function} int scm_is_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
385 @deftypefnx {C Function} int scm_is_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
386 Return @code{1} when @var{x} represents an exact integer that is
387 between @var{min} and @var{max}, inclusive.
388
389 These functions can be used to check whether a @code{SCM} value will
390 fit into a given range, such as the range of a given C integer type.
391 If you just want to convert a @code{SCM} value to a given C integer
392 type, use one of the conversion functions directly.
393 @end deftypefn
394
395 @deftypefn {C Function} scm_t_intmax scm_to_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
396 @deftypefnx {C Function} scm_t_uintmax scm_to_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
397 When @var{x} represents an exact integer that is between @var{min} and
398 @var{max} inclusive, return that integer. Else signal an error,
399 either a `wrong-type' error when @var{x} is not an exact integer, or
400 an `out-of-range' error when it doesn't fit the given range.
401 @end deftypefn
402
403 @deftypefn {C Function} SCM scm_from_signed_integer (scm_t_intmax x)
404 @deftypefnx {C Function} SCM scm_from_unsigned_integer (scm_t_uintmax x)
405 Return the @code{SCM} value that represents the integer @var{x}. This
406 function will always succeed and will always return an exact number.
407 @end deftypefn
408
409 @deftypefn {C Function} char scm_to_char (SCM x)
410 @deftypefnx {C Function} {signed char} scm_to_schar (SCM x)
411 @deftypefnx {C Function} {unsigned char} scm_to_uchar (SCM x)
412 @deftypefnx {C Function} short scm_to_short (SCM x)
413 @deftypefnx {C Function} {unsigned short} scm_to_ushort (SCM x)
414 @deftypefnx {C Function} int scm_to_int (SCM x)
415 @deftypefnx {C Function} {unsigned int} scm_to_uint (SCM x)
416 @deftypefnx {C Function} long scm_to_long (SCM x)
417 @deftypefnx {C Function} {unsigned long} scm_to_ulong (SCM x)
418 @deftypefnx {C Function} {long long} scm_to_long_long (SCM x)
419 @deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x)
420 @deftypefnx {C Function} size_t scm_to_size_t (SCM x)
421 @deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x)
422 @deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x)
423 @deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x)
424 @deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x)
425 @deftypefnx {C Function} scm_t_uint16 scm_to_uint16 (SCM x)
426 @deftypefnx {C Function} scm_t_int32 scm_to_int32 (SCM x)
427 @deftypefnx {C Function} scm_t_uint32 scm_to_uint32 (SCM x)
428 @deftypefnx {C Function} scm_t_int64 scm_to_int64 (SCM x)
429 @deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x)
430 @deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x)
431 @deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x)
432 When @var{x} represents an exact integer that fits into the indicated
433 C type, return that integer. Else signal an error, either a
434 `wrong-type' error when @var{x} is not an exact integer, or an
435 `out-of-range' error when it doesn't fit the given range.
436
437 The functions @code{scm_to_long_long}, @code{scm_to_ulong_long},
438 @code{scm_to_int64}, and @code{scm_to_uint64} are only available when
439 the corresponding types are.
440 @end deftypefn
441
442 @deftypefn {C Function} SCM scm_from_char (char x)
443 @deftypefnx {C Function} SCM scm_from_schar (signed char x)
444 @deftypefnx {C Function} SCM scm_from_uchar (unsigned char x)
445 @deftypefnx {C Function} SCM scm_from_short (short x)
446 @deftypefnx {C Function} SCM scm_from_ushort (unsigned short x)
447 @deftypefnx {C Function} SCM scm_from_int (int x)
448 @deftypefnx {C Function} SCM scm_from_uint (unsigned int x)
449 @deftypefnx {C Function} SCM scm_from_long (long x)
450 @deftypefnx {C Function} SCM scm_from_ulong (unsigned long x)
451 @deftypefnx {C Function} SCM scm_from_long_long (long long x)
452 @deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x)
453 @deftypefnx {C Function} SCM scm_from_size_t (size_t x)
454 @deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x)
455 @deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x)
456 @deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x)
457 @deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x)
458 @deftypefnx {C Function} SCM scm_from_uint16 (scm_t_uint16 x)
459 @deftypefnx {C Function} SCM scm_from_int32 (scm_t_int32 x)
460 @deftypefnx {C Function} SCM scm_from_uint32 (scm_t_uint32 x)
461 @deftypefnx {C Function} SCM scm_from_int64 (scm_t_int64 x)
462 @deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x)
463 @deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x)
464 @deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x)
465 Return the @code{SCM} value that represents the integer @var{x}.
466 These functions will always succeed and will always return an exact
467 number.
468 @end deftypefn
469
470 @node Reals and Rationals
471 @subsubsection Real and Rational Numbers
472 @tpindex Real numbers
473 @tpindex Rational numbers
474
475 @rnindex real?
476 @rnindex rational?
477
478 Mathematically, the real numbers are the set of numbers that describe
479 all possible points along a continuous, infinite, one-dimensional line.
480 The rational numbers are the set of all numbers that can be written as
481 fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
482 All rational numbers are also real, but there are real numbers that
483 are not rational, for example the square root of 2, and pi.
484
485 Guile can represent both exact and inexact rational numbers, but it
486 can not represent irrational numbers. Exact rationals are represented
487 by storing the numerator and denominator as two exact integers.
488 Inexact rationals are stored as floating point numbers using the C
489 type @code{double}.
490
491 Exact rationals are written as a fraction of integers. There must be
492 no whitespace around the slash:
493
494 @lisp
495 1/2
496 -22/7
497 @end lisp
498
499 Even though the actual encoding of inexact rationals is in binary, it
500 may be helpful to think of it as a decimal number with a limited
501 number of significant figures and a decimal point somewhere, since
502 this corresponds to the standard notation for non-whole numbers. For
503 example:
504
505 @lisp
506 0.34
507 -0.00000142857931198
508 -5648394822220000000000.0
509 4.0
510 @end lisp
511
512 The limited precision of Guile's encoding means that any ``real'' number
513 in Guile can be written in a rational form, by multiplying and then dividing
514 by sufficient powers of 10 (or in fact, 2). For example,
515 @samp{-0.00000142857931198} is the same as @minus{}142857931198 divided by
516 100000000000000000. In Guile's current incarnation, therefore, the
517 @code{rational?} and @code{real?} predicates are equivalent.
518
519
520 Dividing by an exact zero leads to a error message, as one might
521 expect. However, dividing by an inexact zero does not produce an
522 error. Instead, the result of the division is either plus or minus
523 infinity, depending on the sign of the divided number.
524
525 The infinities are written @samp{+inf.0} and @samp{-inf.0},
526 respectivly. This syntax is also recognized by @code{read} as an
527 extension to the usual Scheme syntax.
528
529 Dividing zero by zero yields something that is not a number at all:
530 @samp{+nan.0}. This is the special `not a number' value.
531
532 On platforms that follow @acronym{IEEE} 754 for their floating point
533 arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
534 are implemented using the corresponding @acronym{IEEE} 754 values.
535 They behave in arithmetic operations like @acronym{IEEE} 754 describes
536 it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
537
538 The infinities are inexact integers and are considered to be both even
539 and odd. While @samp{+nan.0} is not @code{=} to itself, it is
540 @code{eqv?} to itself.
541
542 To test for the special values, use the functions @code{inf?} and
543 @code{nan?}.
544
545 @deffn {Scheme Procedure} real? obj
546 @deffnx {C Function} scm_real_p (obj)
547 Return @code{#t} if @var{obj} is a real number, else @code{#f}. Note
548 that the sets of integer and rational values form subsets of the set
549 of real numbers, so the predicate will also be fulfilled if @var{obj}
550 is an integer number or a rational number.
551 @end deffn
552
553 @deffn {Scheme Procedure} rational? x
554 @deffnx {C Function} scm_rational_p (x)
555 Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise.
556 Note that the set of integer values forms a subset of the set of
557 rational numbers, i. e. the predicate will also be fulfilled if
558 @var{x} is an integer number.
559
560 Since Guile can not represent irrational numbers, every number
561 satisfying @code{real?} also satisfies @code{rational?} in Guile.
562 @end deffn
563
564 @deffn {Scheme Procedure} rationalize x eps
565 @deffnx {C Function} scm_rationalize (x, eps)
566 Returns the @emph{simplest} rational number differing
567 from @var{x} by no more than @var{eps}.
568
569 As required by @acronym{R5RS}, @code{rationalize} only returns an
570 exact result when both its arguments are exact. Thus, you might need
571 to use @code{inexact->exact} on the arguments.
572
573 @lisp
574 (rationalize (inexact->exact 1.2) 1/100)
575 @result{} 6/5
576 @end lisp
577
578 @end deffn
579
580 @deffn {Scheme Procedure} inf? x
581 @deffnx {C Function} scm_inf_p (x)
582 Return @code{#t} if @var{x} is either @samp{+inf.0} or @samp{-inf.0},
583 @code{#f} otherwise.
584 @end deffn
585
586 @deffn {Scheme Procedure} nan? x
587 @deffnx {C Function} scm_nan_p (x)
588 Return @code{#t} if @var{x} is @samp{+nan.0}, @code{#f} otherwise.
589 @end deffn
590
591 @deffn {Scheme Procedure} numerator x
592 @deffnx {C Function} scm_numerator (x)
593 Return the numerator of the rational number @var{x}.
594 @end deffn
595
596 @deffn {Scheme Procedure} denominator x
597 @deffnx {C Function} scm_denominator (x)
598 Return the denominator of the rational number @var{x}.
599 @end deffn
600
601 @deftypefn {C Function} int scm_is_real (SCM val)
602 @deftypefnx {C Function} int scm_is_rational (SCM val)
603 Equivalent to @code{scm_is_true (scm_real_p (val))} and
604 @code{scm_is_true (scm_rational_p (val))}, respectively.
605 @end deftypefn
606
607 @deftypefn {C Function} double scm_to_double (SCM val)
608 Returns the number closest to @var{val} that is representable as a
609 @code{double}. Returns infinity for a @var{val} that is too large in
610 magnitude. The argument @var{val} must be a real number.
611 @end deftypefn
612
613 @deftypefn {C Function} SCM scm_from_double (double val)
614 Return the @code{SCM} value that representats @var{val}. The returned
615 value is inexact according to the predicate @code{inexact?}, but it
616 will be exactly equal to @var{val}.
617 @end deftypefn
618
619 @node Complex Numbers
620 @subsubsection Complex Numbers
621 @tpindex Complex numbers
622
623 @rnindex complex?
624
625 Complex numbers are the set of numbers that describe all possible points
626 in a two-dimensional space. The two coordinates of a particular point
627 in this space are known as the @dfn{real} and @dfn{imaginary} parts of
628 the complex number that describes that point.
629
630 In Guile, complex numbers are written in rectangular form as the sum of
631 their real and imaginary parts, using the symbol @code{i} to indicate
632 the imaginary part.
633
634 @lisp
635 3+4i
636 @result{}
637 3.0+4.0i
638
639 (* 3-8i 2.3+0.3i)
640 @result{}
641 9.3-17.5i
642 @end lisp
643
644 Guile represents a complex number with a non-zero imaginary part as a
645 pair of inexact rationals, so the real and imaginary parts of a
646 complex number have the same properties of inexactness and limited
647 precision as single inexact rational numbers. Guile can not represent
648 exact complex numbers with non-zero imaginary parts.
649
650 @deffn {Scheme Procedure} complex? z
651 @deffnx {C Function} scm_complex_p (z)
652 Return @code{#t} if @var{x} is a complex number, @code{#f}
653 otherwise. Note that the sets of real, rational and integer
654 values form subsets of the set of complex numbers, i. e. the
655 predicate will also be fulfilled if @var{x} is a real,
656 rational or integer number.
657 @end deffn
658
659 @node Exactness
660 @subsubsection Exact and Inexact Numbers
661 @tpindex Exact numbers
662 @tpindex Inexact numbers
663
664 @rnindex exact?
665 @rnindex inexact?
666 @rnindex exact->inexact
667 @rnindex inexact->exact
668
669 R5RS requires that a calculation involving inexact numbers always
670 produces an inexact result. To meet this requirement, Guile
671 distinguishes between an exact integer value such as @samp{5} and the
672 corresponding inexact real value which, to the limited precision
673 available, has no fractional part, and is printed as @samp{5.0}. Guile
674 will only convert the latter value to the former when forced to do so by
675 an invocation of the @code{inexact->exact} procedure.
676
677 @deffn {Scheme Procedure} exact? z
678 @deffnx {C Function} scm_exact_p (z)
679 Return @code{#t} if the number @var{z} is exact, @code{#f}
680 otherwise.
681
682 @lisp
683 (exact? 2)
684 @result{} #t
685
686 (exact? 0.5)
687 @result{} #f
688
689 (exact? (/ 2))
690 @result{} #t
691 @end lisp
692
693 @end deffn
694
695 @deffn {Scheme Procedure} inexact? z
696 @deffnx {C Function} scm_inexact_p (z)
697 Return @code{#t} if the number @var{z} is inexact, @code{#f}
698 else.
699 @end deffn
700
701 @deffn {Scheme Procedure} inexact->exact z
702 @deffnx {C Function} scm_inexact_to_exact (z)
703 Return an exact number that is numerically closest to @var{z}, when
704 there is one. For inexact rationals, Guile returns the exact rational
705 that is numerically equal to the inexact rational. Inexact complex
706 numbers with a non-zero imaginary part can not be made exact.
707
708 @lisp
709 (inexact->exact 0.5)
710 @result{} 1/2
711 @end lisp
712
713 The following happens because 12/10 is not exactly representable as a
714 @code{double} (on most platforms). However, when reading a decimal
715 number that has been marked exact with the ``#e'' prefix, Guile is
716 able to represent it correctly.
717
718 @lisp
719 (inexact->exact 1.2)
720 @result{} 5404319552844595/4503599627370496
721
722 #e1.2
723 @result{} 6/5
724 @end lisp
725
726 @end deffn
727
728 @c begin (texi-doc-string "guile" "exact->inexact")
729 @deffn {Scheme Procedure} exact->inexact z
730 @deffnx {C Function} scm_exact_to_inexact (z)
731 Convert the number @var{z} to its inexact representation.
732 @end deffn
733
734
735 @node Number Syntax
736 @subsubsection Read Syntax for Numerical Data
737
738 The read syntax for integers is a string of digits, optionally
739 preceded by a minus or plus character, a code indicating the
740 base in which the integer is encoded, and a code indicating whether
741 the number is exact or inexact. The supported base codes are:
742
743 @table @code
744 @item #b
745 @itemx #B
746 the integer is written in binary (base 2)
747
748 @item #o
749 @itemx #O
750 the integer is written in octal (base 8)
751
752 @item #d
753 @itemx #D
754 the integer is written in decimal (base 10)
755
756 @item #x
757 @itemx #X
758 the integer is written in hexadecimal (base 16)
759 @end table
760
761 If the base code is omitted, the integer is assumed to be decimal. The
762 following examples show how these base codes are used.
763
764 @lisp
765 -13
766 @result{} -13
767
768 #d-13
769 @result{} -13
770
771 #x-13
772 @result{} -19
773
774 #b+1101
775 @result{} 13
776
777 #o377
778 @result{} 255
779 @end lisp
780
781 The codes for indicating exactness (which can, incidentally, be applied
782 to all numerical values) are:
783
784 @table @code
785 @item #e
786 @itemx #E
787 the number is exact
788
789 @item #i
790 @itemx #I
791 the number is inexact.
792 @end table
793
794 If the exactness indicator is omitted, the number is exact unless it
795 contains a radix point. Since Guile can not represent exact complex
796 numbers, an error is signalled when asking for them.
797
798 @lisp
799 (exact? 1.2)
800 @result{} #f
801
802 (exact? #e1.2)
803 @result{} #t
804
805 (exact? #e+1i)
806 ERROR: Wrong type argument
807 @end lisp
808
809 Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
810 plus and minus infinity, respectively. The value must be written
811 exactly as shown, that is, they always must have a sign and exactly
812 one zero digit after the decimal point. It also understands
813 @samp{+nan.0} and @samp{-nan.0} for the special `not-a-number' value.
814 The sign is ignored for `not-a-number' and the value is always printed
815 as @samp{+nan.0}.
816
817 @node Integer Operations
818 @subsubsection Operations on Integer Values
819 @rnindex odd?
820 @rnindex even?
821 @rnindex quotient
822 @rnindex remainder
823 @rnindex modulo
824 @rnindex gcd
825 @rnindex lcm
826
827 @deffn {Scheme Procedure} odd? n
828 @deffnx {C Function} scm_odd_p (n)
829 Return @code{#t} if @var{n} is an odd number, @code{#f}
830 otherwise.
831 @end deffn
832
833 @deffn {Scheme Procedure} even? n
834 @deffnx {C Function} scm_even_p (n)
835 Return @code{#t} if @var{n} is an even number, @code{#f}
836 otherwise.
837 @end deffn
838
839 @c begin (texi-doc-string "guile" "quotient")
840 @c begin (texi-doc-string "guile" "remainder")
841 @deffn {Scheme Procedure} quotient n d
842 @deffnx {Scheme Procedure} remainder n d
843 @deffnx {C Function} scm_quotient (n, d)
844 @deffnx {C Function} scm_remainder (n, d)
845 Return the quotient or remainder from @var{n} divided by @var{d}. The
846 quotient is rounded towards zero, and the remainder will have the same
847 sign as @var{n}. In all cases quotient and remainder satisfy
848 @math{@var{n} = @var{q}*@var{d} + @var{r}}.
849
850 @lisp
851 (remainder 13 4) @result{} 1
852 (remainder -13 4) @result{} -1
853 @end lisp
854 @end deffn
855
856 @c begin (texi-doc-string "guile" "modulo")
857 @deffn {Scheme Procedure} modulo n d
858 @deffnx {C Function} scm_modulo (n, d)
859 Return the remainder from @var{n} divided by @var{d}, with the same
860 sign as @var{d}.
861
862 @lisp
863 (modulo 13 4) @result{} 1
864 (modulo -13 4) @result{} 3
865 (modulo 13 -4) @result{} -3
866 (modulo -13 -4) @result{} -1
867 @end lisp
868 @end deffn
869
870 @c begin (texi-doc-string "guile" "gcd")
871 @deffn {Scheme Procedure} gcd
872 @deffnx {C Function} scm_gcd (x, y)
873 Return the greatest common divisor of all arguments.
874 If called without arguments, 0 is returned.
875
876 The C function @code{scm_gcd} always takes two arguments, while the
877 Scheme function can take an arbitrary number.
878 @end deffn
879
880 @c begin (texi-doc-string "guile" "lcm")
881 @deffn {Scheme Procedure} lcm
882 @deffnx {C Function} scm_lcm (x, y)
883 Return the least common multiple of the arguments.
884 If called without arguments, 1 is returned.
885
886 The C function @code{scm_lcm} always takes two arguments, while the
887 Scheme function can take an arbitrary number.
888 @end deffn
889
890
891 @node Comparison
892 @subsubsection Comparison Predicates
893 @rnindex zero?
894 @rnindex positive?
895 @rnindex negative?
896
897 The C comparison functions below always takes two arguments, while the
898 Scheme functions can take an arbitrary number. Also keep in mind that
899 the C functions return one of the Scheme boolean values
900 @code{SCM_BOOL_T} or @code{SCM_BOOL_F} which are both true as far as C
901 is concerned. Thus, always write @code{scm_is_true (scm_num_eq_p (x,
902 y))} when testing the two Scheme numbers @code{x} and @code{y} for
903 equality, for example.
904
905 @c begin (texi-doc-string "guile" "=")
906 @deffn {Scheme Procedure} =
907 @deffnx {C Function} scm_num_eq_p (x, y)
908 Return @code{#t} if all parameters are numerically equal.
909 @end deffn
910
911 @c begin (texi-doc-string "guile" "<")
912 @deffn {Scheme Procedure} <
913 @deffnx {C Function} scm_less_p (x, y)
914 Return @code{#t} if the list of parameters is monotonically
915 increasing.
916 @end deffn
917
918 @c begin (texi-doc-string "guile" ">")
919 @deffn {Scheme Procedure} >
920 @deffnx {C Function} scm_gr_p (x, y)
921 Return @code{#t} if the list of parameters is monotonically
922 decreasing.
923 @end deffn
924
925 @c begin (texi-doc-string "guile" "<=")
926 @deffn {Scheme Procedure} <=
927 @deffnx {C Function} scm_leq_p (x, y)
928 Return @code{#t} if the list of parameters is monotonically
929 non-decreasing.
930 @end deffn
931
932 @c begin (texi-doc-string "guile" ">=")
933 @deffn {Scheme Procedure} >=
934 @deffnx {C Function} scm_geq_p (x, y)
935 Return @code{#t} if the list of parameters is monotonically
936 non-increasing.
937 @end deffn
938
939 @c begin (texi-doc-string "guile" "zero?")
940 @deffn {Scheme Procedure} zero? z
941 @deffnx {C Function} scm_zero_p (z)
942 Return @code{#t} if @var{z} is an exact or inexact number equal to
943 zero.
944 @end deffn
945
946 @c begin (texi-doc-string "guile" "positive?")
947 @deffn {Scheme Procedure} positive? x
948 @deffnx {C Function} scm_positive_p (x)
949 Return @code{#t} if @var{x} is an exact or inexact number greater than
950 zero.
951 @end deffn
952
953 @c begin (texi-doc-string "guile" "negative?")
954 @deffn {Scheme Procedure} negative? x
955 @deffnx {C Function} scm_negative_p (x)
956 Return @code{#t} if @var{x} is an exact or inexact number less than
957 zero.
958 @end deffn
959
960
961 @node Conversion
962 @subsubsection Converting Numbers To and From Strings
963 @rnindex number->string
964 @rnindex string->number
965
966 @deffn {Scheme Procedure} number->string n [radix]
967 @deffnx {C Function} scm_number_to_string (n, radix)
968 Return a string holding the external representation of the
969 number @var{n} in the given @var{radix}. If @var{n} is
970 inexact, a radix of 10 will be used.
971 @end deffn
972
973 @deffn {Scheme Procedure} string->number string [radix]
974 @deffnx {C Function} scm_string_to_number (string, radix)
975 Return a number of the maximally precise representation
976 expressed by the given @var{string}. @var{radix} must be an
977 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
978 is a default radix that may be overridden by an explicit radix
979 prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
980 supplied, then the default radix is 10. If string is not a
981 syntactically valid notation for a number, then
982 @code{string->number} returns @code{#f}.
983 @end deffn
984
985
986 @node Complex
987 @subsubsection Complex Number Operations
988 @rnindex make-rectangular
989 @rnindex make-polar
990 @rnindex real-part
991 @rnindex imag-part
992 @rnindex magnitude
993 @rnindex angle
994
995 @deffn {Scheme Procedure} make-rectangular real imaginary
996 @deffnx {C Function} scm_make_rectangular (real, imaginary)
997 Return a complex number constructed of the given @var{real} and
998 @var{imaginary} parts.
999 @end deffn
1000
1001 @deffn {Scheme Procedure} make-polar x y
1002 @deffnx {C Function} scm_make_polar (x, y)
1003 Return the complex number @var{x} * e^(i * @var{y}).
1004 @end deffn
1005
1006 @c begin (texi-doc-string "guile" "real-part")
1007 @deffn {Scheme Procedure} real-part z
1008 @deffnx {C Function} scm_real_part (z)
1009 Return the real part of the number @var{z}.
1010 @end deffn
1011
1012 @c begin (texi-doc-string "guile" "imag-part")
1013 @deffn {Scheme Procedure} imag-part z
1014 @deffnx {C Function} scm_imag_part (z)
1015 Return the imaginary part of the number @var{z}.
1016 @end deffn
1017
1018 @c begin (texi-doc-string "guile" "magnitude")
1019 @deffn {Scheme Procedure} magnitude z
1020 @deffnx {C Function} scm_magnitude (z)
1021 Return the magnitude of the number @var{z}. This is the same as
1022 @code{abs} for real arguments, but also allows complex numbers.
1023 @end deffn
1024
1025 @c begin (texi-doc-string "guile" "angle")
1026 @deffn {Scheme Procedure} angle z
1027 @deffnx {C Function} scm_angle (z)
1028 Return the angle of the complex number @var{z}.
1029 @end deffn
1030
1031 @deftypefn {C Function} SCM scm_c_make_rectangular (double re, double im)
1032 @deftypefnx {C Function} SCM scm_c_make_polar (double x, double y)
1033 Like @code{scm_make_rectangular} or @code{scm_make_polar},
1034 respectively, but these functions take @code{double}s as their
1035 arguments.
1036 @end deftypefn
1037
1038 @deftypefn {C Function} double scm_c_real_part (z)
1039 @deftypefnx {C Function} double scm_c_imag_part (z)
1040 Returns the real or imaginary part of @var{z} as a @code{double}.
1041 @end deftypefn
1042
1043 @deftypefn {C Function} double scm_c_magnitude (z)
1044 @deftypefnx {C Function} double scm_c_angle (z)
1045 Returns the magnitude or angle of @var{z} as a @code{double}.
1046 @end deftypefn
1047
1048
1049 @node Arithmetic
1050 @subsubsection Arithmetic Functions
1051 @rnindex max
1052 @rnindex min
1053 @rnindex +
1054 @rnindex *
1055 @rnindex -
1056 @rnindex /
1057 @rnindex abs
1058 @rnindex floor
1059 @rnindex ceiling
1060 @rnindex truncate
1061 @rnindex round
1062
1063 The C arithmetic functions below always takes two arguments, while the
1064 Scheme functions can take an arbitrary number. When you need to
1065 invoke them with just one argument, for example to compute the
1066 equivalent od @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
1067 one: @code{scm_difference (x, SCM_UNDEFINED)}.
1068
1069 @c begin (texi-doc-string "guile" "+")
1070 @deffn {Scheme Procedure} + z1 @dots{}
1071 @deffnx {C Function} scm_sum (z1, z2)
1072 Return the sum of all parameter values. Return 0 if called without any
1073 parameters.
1074 @end deffn
1075
1076 @c begin (texi-doc-string "guile" "-")
1077 @deffn {Scheme Procedure} - z1 z2 @dots{}
1078 @deffnx {C Function} scm_difference (z1, z2)
1079 If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
1080 the sum of all but the first argument are subtracted from the first
1081 argument.
1082 @end deffn
1083
1084 @c begin (texi-doc-string "guile" "*")
1085 @deffn {Scheme Procedure} * z1 @dots{}
1086 @deffnx {C Function} scm_product (z1, z2)
1087 Return the product of all arguments. If called without arguments, 1 is
1088 returned.
1089 @end deffn
1090
1091 @c begin (texi-doc-string "guile" "/")
1092 @deffn {Scheme Procedure} / z1 z2 @dots{}
1093 @deffnx {C Function} scm_divide (z1, z2)
1094 Divide the first argument by the product of the remaining arguments. If
1095 called with one argument @var{z1}, 1/@var{z1} is returned.
1096 @end deffn
1097
1098 @c begin (texi-doc-string "guile" "abs")
1099 @deffn {Scheme Procedure} abs x
1100 @deffnx {C Function} scm_abs (x)
1101 Return the absolute value of @var{x}.
1102
1103 @var{x} must be a number with zero imaginary part. To calculate the
1104 magnitude of a complex number, use @code{magnitude} instead.
1105 @end deffn
1106
1107 @c begin (texi-doc-string "guile" "max")
1108 @deffn {Scheme Procedure} max x1 x2 @dots{}
1109 @deffnx {C Function} scm_max (x1, x2)
1110 Return the maximum of all parameter values.
1111 @end deffn
1112
1113 @c begin (texi-doc-string "guile" "min")
1114 @deffn {Scheme Procedure} min x1 x2 @dots{}
1115 @deffnx {C Function} scm_min (x1, x2)
1116 Return the minimum of all parameter values.
1117 @end deffn
1118
1119 @c begin (texi-doc-string "guile" "truncate")
1120 @deffn {Scheme Procedure} truncate
1121 @deffnx {C Function} scm_truncate_number (x)
1122 Round the inexact number @var{x} towards zero.
1123 @end deffn
1124
1125 @c begin (texi-doc-string "guile" "round")
1126 @deffn {Scheme Procedure} round x
1127 @deffnx {C Function} scm_round_number (x)
1128 Round the inexact number @var{x} to the nearest integer. When exactly
1129 halfway between two integers, round to the even one.
1130 @end deffn
1131
1132 @c begin (texi-doc-string "guile" "floor")
1133 @deffn {Scheme Procedure} floor x
1134 @deffnx {C Function} scm_floor (x)
1135 Round the number @var{x} towards minus infinity.
1136 @end deffn
1137
1138 @c begin (texi-doc-string "guile" "ceiling")
1139 @deffn {Scheme Procedure} ceiling x
1140 @deffnx {C Function} scm_ceiling (x)
1141 Round the number @var{x} towards infinity.
1142 @end deffn
1143
1144
1145 @node Scientific
1146 @subsubsection Scientific Functions
1147
1148 The following procedures accept any kind of number as arguments,
1149 including complex numbers.
1150
1151 @rnindex sqrt
1152 @c begin (texi-doc-string "guile" "sqrt")
1153 @deffn {Scheme Procedure} sqrt z
1154 Return the square root of @var{z}.
1155 @end deffn
1156
1157 @rnindex expt
1158 @c begin (texi-doc-string "guile" "expt")
1159 @deffn {Scheme Procedure} expt z1 z2
1160 Return @var{z1} raised to the power of @var{z2}.
1161 @end deffn
1162
1163 @rnindex sin
1164 @c begin (texi-doc-string "guile" "sin")
1165 @deffn {Scheme Procedure} sin z
1166 Return the sine of @var{z}.
1167 @end deffn
1168
1169 @rnindex cos
1170 @c begin (texi-doc-string "guile" "cos")
1171 @deffn {Scheme Procedure} cos z
1172 Return the cosine of @var{z}.
1173 @end deffn
1174
1175 @rnindex tan
1176 @c begin (texi-doc-string "guile" "tan")
1177 @deffn {Scheme Procedure} tan z
1178 Return the tangent of @var{z}.
1179 @end deffn
1180
1181 @rnindex asin
1182 @c begin (texi-doc-string "guile" "asin")
1183 @deffn {Scheme Procedure} asin z
1184 Return the arcsine of @var{z}.
1185 @end deffn
1186
1187 @rnindex acos
1188 @c begin (texi-doc-string "guile" "acos")
1189 @deffn {Scheme Procedure} acos z
1190 Return the arccosine of @var{z}.
1191 @end deffn
1192
1193 @rnindex atan
1194 @c begin (texi-doc-string "guile" "atan")
1195 @deffn {Scheme Procedure} atan z
1196 @deffnx {Scheme Procedure} atan y x
1197 Return the arctangent of @var{z}, or of @math{@var{y}/@var{x}}.
1198 @end deffn
1199
1200 @rnindex exp
1201 @c begin (texi-doc-string "guile" "exp")
1202 @deffn {Scheme Procedure} exp z
1203 Return e to the power of @var{z}, where e is the base of natural
1204 logarithms (2.71828@dots{}).
1205 @end deffn
1206
1207 @rnindex log
1208 @c begin (texi-doc-string "guile" "log")
1209 @deffn {Scheme Procedure} log z
1210 Return the natural logarithm of @var{z}.
1211 @end deffn
1212
1213 @c begin (texi-doc-string "guile" "log10")
1214 @deffn {Scheme Procedure} log10 z
1215 Return the base 10 logarithm of @var{z}.
1216 @end deffn
1217
1218 @c begin (texi-doc-string "guile" "sinh")
1219 @deffn {Scheme Procedure} sinh z
1220 Return the hyperbolic sine of @var{z}.
1221 @end deffn
1222
1223 @c begin (texi-doc-string "guile" "cosh")
1224 @deffn {Scheme Procedure} cosh z
1225 Return the hyperbolic cosine of @var{z}.
1226 @end deffn
1227
1228 @c begin (texi-doc-string "guile" "tanh")
1229 @deffn {Scheme Procedure} tanh z
1230 Return the hyperbolic tangent of @var{z}.
1231 @end deffn
1232
1233 @c begin (texi-doc-string "guile" "asinh")
1234 @deffn {Scheme Procedure} asinh z
1235 Return the hyperbolic arcsine of @var{z}.
1236 @end deffn
1237
1238 @c begin (texi-doc-string "guile" "acosh")
1239 @deffn {Scheme Procedure} acosh z
1240 Return the hyperbolic arccosine of @var{z}.
1241 @end deffn
1242
1243 @c begin (texi-doc-string "guile" "atanh")
1244 @deffn {Scheme Procedure} atanh z
1245 Return the hyperbolic arctangent of @var{z}.
1246 @end deffn
1247
1248
1249 @node Primitive Numerics
1250 @subsubsection Primitive Numeric Functions
1251
1252 Many of Guile's numeric procedures which accept any kind of numbers as
1253 arguments, including complex numbers, are implemented as Scheme
1254 procedures that use the following real number-based primitives. These
1255 primitives signal an error if they are called with complex arguments.
1256
1257 @c begin (texi-doc-string "guile" "$abs")
1258 @deffn {Scheme Procedure} $abs x
1259 Return the absolute value of @var{x}.
1260 @end deffn
1261
1262 @c begin (texi-doc-string "guile" "$sqrt")
1263 @deffn {Scheme Procedure} $sqrt x
1264 Return the square root of @var{x}.
1265 @end deffn
1266
1267 @deffn {Scheme Procedure} $expt x y
1268 @deffnx {C Function} scm_sys_expt (x, y)
1269 Return @var{x} raised to the power of @var{y}. This
1270 procedure does not accept complex arguments.
1271 @end deffn
1272
1273 @c begin (texi-doc-string "guile" "$sin")
1274 @deffn {Scheme Procedure} $sin x
1275 Return the sine of @var{x}.
1276 @end deffn
1277
1278 @c begin (texi-doc-string "guile" "$cos")
1279 @deffn {Scheme Procedure} $cos x
1280 Return the cosine of @var{x}.
1281 @end deffn
1282
1283 @c begin (texi-doc-string "guile" "$tan")
1284 @deffn {Scheme Procedure} $tan x
1285 Return the tangent of @var{x}.
1286 @end deffn
1287
1288 @c begin (texi-doc-string "guile" "$asin")
1289 @deffn {Scheme Procedure} $asin x
1290 Return the arcsine of @var{x}.
1291 @end deffn
1292
1293 @c begin (texi-doc-string "guile" "$acos")
1294 @deffn {Scheme Procedure} $acos x
1295 Return the arccosine of @var{x}.
1296 @end deffn
1297
1298 @c begin (texi-doc-string "guile" "$atan")
1299 @deffn {Scheme Procedure} $atan x
1300 Return the arctangent of @var{x} in the range @minus{}@math{PI/2} to
1301 @math{PI/2}.
1302 @end deffn
1303
1304 @deffn {Scheme Procedure} $atan2 x y
1305 @deffnx {C Function} scm_sys_atan2 (x, y)
1306 Return the arc tangent of the two arguments @var{x} and
1307 @var{y}. This is similar to calculating the arc tangent of
1308 @var{x} / @var{y}, except that the signs of both arguments
1309 are used to determine the quadrant of the result. This
1310 procedure does not accept complex arguments.
1311 @end deffn
1312
1313 @c begin (texi-doc-string "guile" "$exp")
1314 @deffn {Scheme Procedure} $exp x
1315 Return e to the power of @var{x}, where e is the base of natural
1316 logarithms (2.71828@dots{}).
1317 @end deffn
1318
1319 @c begin (texi-doc-string "guile" "$log")
1320 @deffn {Scheme Procedure} $log x
1321 Return the natural logarithm of @var{x}.
1322 @end deffn
1323
1324 @c begin (texi-doc-string "guile" "$sinh")
1325 @deffn {Scheme Procedure} $sinh x
1326 Return the hyperbolic sine of @var{x}.
1327 @end deffn
1328
1329 @c begin (texi-doc-string "guile" "$cosh")
1330 @deffn {Scheme Procedure} $cosh x
1331 Return the hyperbolic cosine of @var{x}.
1332 @end deffn
1333
1334 @c begin (texi-doc-string "guile" "$tanh")
1335 @deffn {Scheme Procedure} $tanh x
1336 Return the hyperbolic tangent of @var{x}.
1337 @end deffn
1338
1339 @c begin (texi-doc-string "guile" "$asinh")
1340 @deffn {Scheme Procedure} $asinh x
1341 Return the hyperbolic arcsine of @var{x}.
1342 @end deffn
1343
1344 @c begin (texi-doc-string "guile" "$acosh")
1345 @deffn {Scheme Procedure} $acosh x
1346 Return the hyperbolic arccosine of @var{x}.
1347 @end deffn
1348
1349 @c begin (texi-doc-string "guile" "$atanh")
1350 @deffn {Scheme Procedure} $atanh x
1351 Return the hyperbolic arctangent of @var{x}.
1352 @end deffn
1353
1354 C functions for the above are provided by the standard mathematics
1355 library. Naturally these expect and return @code{double} arguments
1356 (@pxref{Mathematics,,, libc, GNU C Library Reference Manual}).
1357
1358 @multitable {xx} {Scheme Procedure} {C Function}
1359 @item @tab Scheme Procedure @tab C Function
1360
1361 @item @tab @code{$abs} @tab @code{fabs}
1362 @item @tab @code{$sqrt} @tab @code{sqrt}
1363 @item @tab @code{$sin} @tab @code{sin}
1364 @item @tab @code{$cos} @tab @code{cos}
1365 @item @tab @code{$tan} @tab @code{tan}
1366 @item @tab @code{$asin} @tab @code{asin}
1367 @item @tab @code{$acos} @tab @code{acos}
1368 @item @tab @code{$atan} @tab @code{atan}
1369 @item @tab @code{$atan2} @tab @code{atan2}
1370 @item @tab @code{$exp} @tab @code{exp}
1371 @item @tab @code{$expt} @tab @code{pow}
1372 @item @tab @code{$log} @tab @code{log}
1373 @item @tab @code{$sinh} @tab @code{sinh}
1374 @item @tab @code{$cosh} @tab @code{cosh}
1375 @item @tab @code{$tanh} @tab @code{tanh}
1376 @item @tab @code{$asinh} @tab @code{asinh}
1377 @item @tab @code{$acosh} @tab @code{acosh}
1378 @item @tab @code{$atanh} @tab @code{atanh}
1379 @end multitable
1380
1381 @code{asinh}, @code{acosh} and @code{atanh} are C99 standard but might
1382 not be available on older systems. Guile provides the following
1383 equivalents (on all systems).
1384
1385 @deftypefn {C Function} double scm_asinh (double x)
1386 @deftypefnx {C Function} double scm_acosh (double x)
1387 @deftypefnx {C Function} double scm_atanh (double x)
1388 Return the hyperbolic arcsine, arccosine or arctangent of @var{x}
1389 respectively.
1390 @end deftypefn
1391
1392
1393 @node Bitwise Operations
1394 @subsubsection Bitwise Operations
1395
1396 For the following bitwise functions, negative numbers are treated as
1397 infinite precision twos-complements. For instance @math{-6} is bits
1398 @math{@dots{}111010}, with infinitely many ones on the left. It can
1399 be seen that adding 6 (binary 110) to such a bit pattern gives all
1400 zeros.
1401
1402 @deffn {Scheme Procedure} logand n1 n2 @dots{}
1403 @deffnx {C Function} scm_logand (n1, n2)
1404 Return the bitwise @sc{and} of the integer arguments.
1405
1406 @lisp
1407 (logand) @result{} -1
1408 (logand 7) @result{} 7
1409 (logand #b111 #b011 #b001) @result{} 1
1410 @end lisp
1411 @end deffn
1412
1413 @deffn {Scheme Procedure} logior n1 n2 @dots{}
1414 @deffnx {C Function} scm_logior (n1, n2)
1415 Return the bitwise @sc{or} of the integer arguments.
1416
1417 @lisp
1418 (logior) @result{} 0
1419 (logior 7) @result{} 7
1420 (logior #b000 #b001 #b011) @result{} 3
1421 @end lisp
1422 @end deffn
1423
1424 @deffn {Scheme Procedure} logxor n1 n2 @dots{}
1425 @deffnx {C Function} scm_loxor (n1, n2)
1426 Return the bitwise @sc{xor} of the integer arguments. A bit is
1427 set in the result if it is set in an odd number of arguments.
1428
1429 @lisp
1430 (logxor) @result{} 0
1431 (logxor 7) @result{} 7
1432 (logxor #b000 #b001 #b011) @result{} 2
1433 (logxor #b000 #b001 #b011 #b011) @result{} 1
1434 @end lisp
1435 @end deffn
1436
1437 @deffn {Scheme Procedure} lognot n
1438 @deffnx {C Function} scm_lognot (n)
1439 Return the integer which is the ones-complement of the integer
1440 argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
1441
1442 @lisp
1443 (number->string (lognot #b10000000) 2)
1444 @result{} "-10000001"
1445 (number->string (lognot #b0) 2)
1446 @result{} "-1"
1447 @end lisp
1448 @end deffn
1449
1450 @deffn {Scheme Procedure} logtest j k
1451 @deffnx {C Function} scm_logtest (j, k)
1452 @lisp
1453 (logtest j k) @equiv{} (not (zero? (logand j k)))
1454
1455 (logtest #b0100 #b1011) @result{} #f
1456 (logtest #b0100 #b0111) @result{} #t
1457 @end lisp
1458 @end deffn
1459
1460 @deffn {Scheme Procedure} logbit? index j
1461 @deffnx {C Function} scm_logbit_p (index, j)
1462 @lisp
1463 (logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
1464
1465 (logbit? 0 #b1101) @result{} #t
1466 (logbit? 1 #b1101) @result{} #f
1467 (logbit? 2 #b1101) @result{} #t
1468 (logbit? 3 #b1101) @result{} #t
1469 (logbit? 4 #b1101) @result{} #f
1470 @end lisp
1471 @end deffn
1472
1473 @deffn {Scheme Procedure} ash n cnt
1474 @deffnx {C Function} scm_ash (n, cnt)
1475 Return @var{n} shifted left by @var{cnt} bits, or shifted right if
1476 @var{cnt} is negative. This is an ``arithmetic'' shift.
1477
1478 This is effectively a multiplication by @m{2^{cnt}, 2^@var{cnt}}, and
1479 when @var{cnt} is negative it's a division, rounded towards negative
1480 infinity. (Note that this is not the same rounding as @code{quotient}
1481 does.)
1482
1483 With @var{n} viewed as an infinite precision twos complement,
1484 @code{ash} means a left shift introducing zero bits, or a right shift
1485 dropping bits.
1486
1487 @lisp
1488 (number->string (ash #b1 3) 2) @result{} "1000"
1489 (number->string (ash #b1010 -1) 2) @result{} "101"
1490
1491 ;; -23 is bits ...11101001, -6 is bits ...111010
1492 (ash -23 -2) @result{} -6
1493 @end lisp
1494 @end deffn
1495
1496 @deffn {Scheme Procedure} logcount n
1497 @deffnx {C Function} scm_logcount (n)
1498 Return the number of bits in integer @var{n}. If integer is
1499 positive, the 1-bits in its binary representation are counted.
1500 If negative, the 0-bits in its two's-complement binary
1501 representation are counted. If 0, 0 is returned.
1502
1503 @lisp
1504 (logcount #b10101010)
1505 @result{} 4
1506 (logcount 0)
1507 @result{} 0
1508 (logcount -2)
1509 @result{} 1
1510 @end lisp
1511 @end deffn
1512
1513 @deffn {Scheme Procedure} integer-length n
1514 @deffnx {C Function} scm_integer_length (n)
1515 Return the number of bits necessary to represent @var{n}.
1516
1517 For positive @var{n} this is how many bits to the most significant one
1518 bit. For negative @var{n} it's how many bits to the most significant
1519 zero bit in twos complement form.
1520
1521 @lisp
1522 (integer-length #b10101010) @result{} 8
1523 (integer-length #b1111) @result{} 4
1524 (integer-length 0) @result{} 0
1525 (integer-length -1) @result{} 0
1526 (integer-length -256) @result{} 8
1527 (integer-length -257) @result{} 9
1528 @end lisp
1529 @end deffn
1530
1531 @deffn {Scheme Procedure} integer-expt n k
1532 @deffnx {C Function} scm_integer_expt (n, k)
1533 Return @var{n} raised to the non-negative integer exponent
1534 @var{k}.
1535
1536 @lisp
1537 (integer-expt 2 5)
1538 @result{} 32
1539 (integer-expt -3 3)
1540 @result{} -27
1541 @end lisp
1542 @end deffn
1543
1544 @deffn {Scheme Procedure} bit-extract n start end
1545 @deffnx {C Function} scm_bit_extract (n, start, end)
1546 Return the integer composed of the @var{start} (inclusive)
1547 through @var{end} (exclusive) bits of @var{n}. The
1548 @var{start}th bit becomes the 0-th bit in the result.
1549
1550 @lisp
1551 (number->string (bit-extract #b1101101010 0 4) 2)
1552 @result{} "1010"
1553 (number->string (bit-extract #b1101101010 4 9) 2)
1554 @result{} "10110"
1555 @end lisp
1556 @end deffn
1557
1558
1559 @node Random
1560 @subsubsection Random Number Generation
1561
1562 Pseudo-random numbers are generated from a random state object, which
1563 can be created with @code{seed->random-state}. The @var{state}
1564 parameter to the various functions below is optional, it defaults to
1565 the state object in the @code{*random-state*} variable.
1566
1567 @deffn {Scheme Procedure} copy-random-state [state]
1568 @deffnx {C Function} scm_copy_random_state (state)
1569 Return a copy of the random state @var{state}.
1570 @end deffn
1571
1572 @deffn {Scheme Procedure} random n [state]
1573 @deffnx {C Function} scm_random (n, state)
1574 Return a number in [0, @var{n}).
1575
1576 Accepts a positive integer or real n and returns a
1577 number of the same type between zero (inclusive) and
1578 @var{n} (exclusive). The values returned have a uniform
1579 distribution.
1580 @end deffn
1581
1582 @deffn {Scheme Procedure} random:exp [state]
1583 @deffnx {C Function} scm_random_exp (state)
1584 Return an inexact real in an exponential distribution with mean
1585 1. For an exponential distribution with mean @var{u} use @code{(*
1586 @var{u} (random:exp))}.
1587 @end deffn
1588
1589 @deffn {Scheme Procedure} random:hollow-sphere! vect [state]
1590 @deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
1591 Fills @var{vect} with inexact real random numbers the sum of whose
1592 squares is equal to 1.0. Thinking of @var{vect} as coordinates in
1593 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1594 the coordinates are uniformly distributed over the surface of the unit
1595 n-sphere.
1596 @end deffn
1597
1598 @deffn {Scheme Procedure} random:normal [state]
1599 @deffnx {C Function} scm_random_normal (state)
1600 Return an inexact real in a normal distribution. The distribution
1601 used has mean 0 and standard deviation 1. For a normal distribution
1602 with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
1603 (* @var{d} (random:normal)))}.
1604 @end deffn
1605
1606 @deffn {Scheme Procedure} random:normal-vector! vect [state]
1607 @deffnx {C Function} scm_random_normal_vector_x (vect, state)
1608 Fills @var{vect} with inexact real random numbers that are
1609 independent and standard normally distributed
1610 (i.e., with mean 0 and variance 1).
1611 @end deffn
1612
1613 @deffn {Scheme Procedure} random:solid-sphere! vect [state]
1614 @deffnx {C Function} scm_random_solid_sphere_x (vect, state)
1615 Fills @var{vect} with inexact real random numbers the sum of whose
1616 squares is less than 1.0. Thinking of @var{vect} as coordinates in
1617 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1618 the coordinates are uniformly distributed within the unit
1619 @var{n}-sphere. The sum of the squares of the numbers is returned.
1620 @c FIXME: What does this mean, particularly the n-sphere part?
1621 @end deffn
1622
1623 @deffn {Scheme Procedure} random:uniform [state]
1624 @deffnx {C Function} scm_random_uniform (state)
1625 Return a uniformly distributed inexact real random number in
1626 [0,1).
1627 @end deffn
1628
1629 @deffn {Scheme Procedure} seed->random-state seed
1630 @deffnx {C Function} scm_seed_to_random_state (seed)
1631 Return a new random state using @var{seed}.
1632 @end deffn
1633
1634 @defvar *random-state*
1635 The global random state used by the above functions when the
1636 @var{state} parameter is not given.
1637 @end defvar
1638
1639
1640 @node Characters
1641 @subsection Characters
1642 @tpindex Characters
1643
1644 @noindent
1645 [@strong{FIXME}: how do you specify regular (non-control) characters?]
1646
1647 Most of the ``control characters'' (those below codepoint 32) in the
1648 @acronym{ASCII} character set, as well as the space, may be referred
1649 to by name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and
1650 so on. The following table describes the @acronym{ASCII} names for
1651 each character.
1652
1653 @multitable @columnfractions .25 .25 .25 .25
1654 @item 0 = @code{#\nul}
1655 @tab 1 = @code{#\soh}
1656 @tab 2 = @code{#\stx}
1657 @tab 3 = @code{#\etx}
1658 @item 4 = @code{#\eot}
1659 @tab 5 = @code{#\enq}
1660 @tab 6 = @code{#\ack}
1661 @tab 7 = @code{#\bel}
1662 @item 8 = @code{#\bs}
1663 @tab 9 = @code{#\ht}
1664 @tab 10 = @code{#\nl}
1665 @tab 11 = @code{#\vt}
1666 @item 12 = @code{#\np}
1667 @tab 13 = @code{#\cr}
1668 @tab 14 = @code{#\so}
1669 @tab 15 = @code{#\si}
1670 @item 16 = @code{#\dle}
1671 @tab 17 = @code{#\dc1}
1672 @tab 18 = @code{#\dc2}
1673 @tab 19 = @code{#\dc3}
1674 @item 20 = @code{#\dc4}
1675 @tab 21 = @code{#\nak}
1676 @tab 22 = @code{#\syn}
1677 @tab 23 = @code{#\etb}
1678 @item 24 = @code{#\can}
1679 @tab 25 = @code{#\em}
1680 @tab 26 = @code{#\sub}
1681 @tab 27 = @code{#\esc}
1682 @item 28 = @code{#\fs}
1683 @tab 29 = @code{#\gs}
1684 @tab 30 = @code{#\rs}
1685 @tab 31 = @code{#\us}
1686 @item 32 = @code{#\sp}
1687 @end multitable
1688
1689 The ``delete'' character (octal 177) may be referred to with the name
1690 @code{#\del}.
1691
1692 Several characters have more than one name:
1693
1694 @multitable {@code{#\backspace}} {Original}
1695 @item Alias @tab Original
1696 @item @code{#\space} @tab @code{#\sp}
1697 @item @code{#\newline} @tab @code{#\nl}
1698 @item @code{#\tab} @tab @code{#\ht}
1699 @item @code{#\backspace} @tab @code{#\bs}
1700 @item @code{#\return} @tab @code{#\cr}
1701 @item @code{#\page} @tab @code{#\np}
1702 @item @code{#\null} @tab @code{#\nul}
1703 @end multitable
1704
1705 @rnindex char?
1706 @deffn {Scheme Procedure} char? x
1707 @deffnx {C Function} scm_char_p (x)
1708 Return @code{#t} iff @var{x} is a character, else @code{#f}.
1709 @end deffn
1710
1711 @rnindex char=?
1712 @deffn {Scheme Procedure} char=? x y
1713 Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
1714 @end deffn
1715
1716 @rnindex char<?
1717 @deffn {Scheme Procedure} char<? x y
1718 Return @code{#t} iff @var{x} is less than @var{y} in the @acronym{ASCII} sequence,
1719 else @code{#f}.
1720 @end deffn
1721
1722 @rnindex char<=?
1723 @deffn {Scheme Procedure} char<=? x y
1724 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
1725 @acronym{ASCII} sequence, else @code{#f}.
1726 @end deffn
1727
1728 @rnindex char>?
1729 @deffn {Scheme Procedure} char>? x y
1730 Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII}
1731 sequence, else @code{#f}.
1732 @end deffn
1733
1734 @rnindex char>=?
1735 @deffn {Scheme Procedure} char>=? x y
1736 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
1737 @acronym{ASCII} sequence, else @code{#f}.
1738 @end deffn
1739
1740 @rnindex char-ci=?
1741 @deffn {Scheme Procedure} char-ci=? x y
1742 Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
1743 case, else @code{#f}.
1744 @end deffn
1745
1746 @rnindex char-ci<?
1747 @deffn {Scheme Procedure} char-ci<? x y
1748 Return @code{#t} iff @var{x} is less than @var{y} in the @acronym{ASCII} sequence
1749 ignoring case, else @code{#f}.
1750 @end deffn
1751
1752 @rnindex char-ci<=?
1753 @deffn {Scheme Procedure} char-ci<=? x y
1754 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
1755 @acronym{ASCII} sequence ignoring case, else @code{#f}.
1756 @end deffn
1757
1758 @rnindex char-ci>?
1759 @deffn {Scheme Procedure} char-ci>? x y
1760 Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII}
1761 sequence ignoring case, else @code{#f}.
1762 @end deffn
1763
1764 @rnindex char-ci>=?
1765 @deffn {Scheme Procedure} char-ci>=? x y
1766 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
1767 @acronym{ASCII} sequence ignoring case, else @code{#f}.
1768 @end deffn
1769
1770 @rnindex char-alphabetic?
1771 @deffn {Scheme Procedure} char-alphabetic? chr
1772 @deffnx {C Function} scm_char_alphabetic_p (chr)
1773 Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
1774 Alphabetic means the same thing as the @code{isalpha} C library function.
1775 @end deffn
1776
1777 @rnindex char-numeric?
1778 @deffn {Scheme Procedure} char-numeric? chr
1779 @deffnx {C Function} scm_char_numeric_p (chr)
1780 Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
1781 Numeric means the same thing as the @code{isdigit} C library function.
1782 @end deffn
1783
1784 @rnindex char-whitespace?
1785 @deffn {Scheme Procedure} char-whitespace? chr
1786 @deffnx {C Function} scm_char_whitespace_p (chr)
1787 Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
1788 Whitespace means the same thing as the @code{isspace} C library function.
1789 @end deffn
1790
1791 @rnindex char-upper-case?
1792 @deffn {Scheme Procedure} char-upper-case? chr
1793 @deffnx {C Function} scm_char_upper_case_p (chr)
1794 Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
1795 Uppercase means the same thing as the @code{isupper} C library function.
1796 @end deffn
1797
1798 @rnindex char-lower-case?
1799 @deffn {Scheme Procedure} char-lower-case? chr
1800 @deffnx {C Function} scm_char_lower_case_p (chr)
1801 Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
1802 Lowercase means the same thing as the @code{islower} C library function.
1803 @end deffn
1804
1805 @deffn {Scheme Procedure} char-is-both? chr
1806 @deffnx {C Function} scm_char_is_both_p (chr)
1807 Return @code{#t} iff @var{chr} is either uppercase or lowercase, else
1808 @code{#f}. Uppercase and lowercase are as defined by the
1809 @code{isupper} and @code{islower} C library functions.
1810 @end deffn
1811
1812 @rnindex char->integer
1813 @deffn {Scheme Procedure} char->integer chr
1814 @deffnx {C Function} scm_char_to_integer (chr)
1815 Return the number corresponding to ordinal position of @var{chr} in the
1816 @acronym{ASCII} sequence.
1817 @end deffn
1818
1819 @rnindex integer->char
1820 @deffn {Scheme Procedure} integer->char n
1821 @deffnx {C Function} scm_integer_to_char (n)
1822 Return the character at position @var{n} in the @acronym{ASCII} sequence.
1823 @end deffn
1824
1825 @rnindex char-upcase
1826 @deffn {Scheme Procedure} char-upcase chr
1827 @deffnx {C Function} scm_char_upcase (chr)
1828 Return the uppercase character version of @var{chr}.
1829 @end deffn
1830
1831 @rnindex char-downcase
1832 @deffn {Scheme Procedure} char-downcase chr
1833 @deffnx {C Function} scm_char_downcase (chr)
1834 Return the lowercase character version of @var{chr}.
1835 @end deffn
1836
1837 @xref{Classification of Characters,,,libc,GNU C Library Reference
1838 Manual}, for information about the @code{is*} Standard C functions
1839 mentioned above.
1840
1841
1842 @node Strings
1843 @subsection Strings
1844 @tpindex Strings
1845
1846 Strings are fixed-length sequences of characters. They can be created
1847 by calling constructor procedures, but they can also literally get
1848 entered at the @acronym{REPL} or in Scheme source files.
1849
1850 @c Guile provides a rich set of string processing procedures, because text
1851 @c handling is very important when Guile is used as a scripting language.
1852
1853 Strings always carry the information about how many characters they are
1854 composed of with them, so there is no special end-of-string character,
1855 like in C. That means that Scheme strings can contain any character,
1856 even the @samp{NUL} character @samp{\0}. But note: Since most operating
1857 system calls dealing with strings (such as for file operations) expect
1858 strings to be zero-terminated, they might do unexpected things when
1859 called with string containing unusual characters.
1860
1861 @menu
1862 * String Syntax:: Read syntax for strings.
1863 * String Predicates:: Testing strings for certain properties.
1864 * String Constructors:: Creating new string objects.
1865 * List/String Conversion:: Converting from/to lists of characters.
1866 * String Selection:: Select portions from strings.
1867 * String Modification:: Modify parts or whole strings.
1868 * String Comparison:: Lexicographic ordering predicates.
1869 * String Searching:: Searching in strings.
1870 * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
1871 * Appending Strings:: Appending strings to form a new string.
1872 * Conversion to/from C::
1873 @end menu
1874
1875 @node String Syntax
1876 @subsubsection String Read Syntax
1877
1878 @c In the following @code is used to get a good font in TeX etc, but
1879 @c is omitted for Info format, so as not to risk any confusion over
1880 @c whether surrounding ` ' quotes are part of the escape or are
1881 @c special in a string (they're not).
1882
1883 The read syntax for strings is an arbitrarily long sequence of
1884 characters enclosed in double quotes (@nicode{"}). @footnote{Actually,
1885 the current implementation restricts strings to a length of
1886 @math{2^24}, or 16,777,216, characters. Sorry.}
1887
1888 Backslash is an escape character and can be used to insert the
1889 following special characters. @nicode{\"} and @nicode{\\} are R5RS
1890 standard, the rest are Guile extensions, notice they follow C string
1891 syntax.
1892
1893 @table @asis
1894 @item @nicode{\\}
1895 Backslash character.
1896
1897 @item @nicode{\"}
1898 Double quote character (an unescaped @nicode{"} is otherwise the end
1899 of the string).
1900
1901 @item @nicode{\0}
1902 NUL character (ASCII 0).
1903
1904 @item @nicode{\a}
1905 Bell character (ASCII 7).
1906
1907 @item @nicode{\f}
1908 Formfeed character (ASCII 12).
1909
1910 @item @nicode{\n}
1911 Newline character (ASCII 10).
1912
1913 @item @nicode{\r}
1914 Carriage return character (ASCII 13).
1915
1916 @item @nicode{\t}
1917 Tab character (ASCII 9).
1918
1919 @item @nicode{\v}
1920 Vertical tab character (ASCII 11).
1921
1922 @item @nicode{\xHH}
1923 Character code given by two hexadecimal digits. For example
1924 @nicode{\x7f} for an ASCII DEL (127).
1925 @end table
1926
1927 @noindent
1928 The following are examples of string literals:
1929
1930 @lisp
1931 "foo"
1932 "bar plonk"
1933 "Hello World"
1934 "\"Hi\", he said."
1935 @end lisp
1936
1937
1938 @node String Predicates
1939 @subsubsection String Predicates
1940
1941 The following procedures can be used to check whether a given string
1942 fulfills some specified property.
1943
1944 @rnindex string?
1945 @deffn {Scheme Procedure} string? obj
1946 @deffnx {C Function} scm_string_p (obj)
1947 Return @code{#t} if @var{obj} is a string, else @code{#f}.
1948 @end deffn
1949
1950 @deftypefn {C Function} int scm_is_string (SCM obj)
1951 Returns @code{1} if @var{obj} is a string, @code{0} otherwise.
1952 @end deftypefn
1953
1954 @deffn {Scheme Procedure} string-null? str
1955 @deffnx {C Function} scm_string_null_p (str)
1956 Return @code{#t} if @var{str}'s length is zero, and
1957 @code{#f} otherwise.
1958 @lisp
1959 (string-null? "") @result{} #t
1960 y @result{} "foo"
1961 (string-null? y) @result{} #f
1962 @end lisp
1963 @end deffn
1964
1965 @node String Constructors
1966 @subsubsection String Constructors
1967
1968 The string constructor procedures create new string objects, possibly
1969 initializing them with some specified character data.
1970
1971 @c FIXME::martin: list->string belongs into `List/String Conversion'
1972
1973 @rnindex string
1974 @rnindex list->string
1975 @deffn {Scheme Procedure} string . chrs
1976 @deffnx {Scheme Procedure} list->string chrs
1977 @deffnx {C Function} scm_string (chrs)
1978 Return a newly allocated string composed of the arguments,
1979 @var{chrs}.
1980 @end deffn
1981
1982 @rnindex make-string
1983 @deffn {Scheme Procedure} make-string k [chr]
1984 @deffnx {C Function} scm_make_string (k, chr)
1985 Return a newly allocated string of
1986 length @var{k}. If @var{chr} is given, then all elements of
1987 the string are initialized to @var{chr}, otherwise the contents
1988 of the @var{string} are unspecified.
1989 @end deffn
1990
1991 @node List/String Conversion
1992 @subsubsection List/String conversion
1993
1994 When processing strings, it is often convenient to first convert them
1995 into a list representation by using the procedure @code{string->list},
1996 work with the resulting list, and then convert it back into a string.
1997 These procedures are useful for similar tasks.
1998
1999 @rnindex string->list
2000 @deffn {Scheme Procedure} string->list str
2001 @deffnx {C Function} scm_string_to_list (str)
2002 Return a newly allocated list of the characters that make up
2003 the given string @var{str}. @code{string->list} and
2004 @code{list->string} are inverses as far as @samp{equal?} is
2005 concerned.
2006 @end deffn
2007
2008 @deffn {Scheme Procedure} string-split str chr
2009 @deffnx {C Function} scm_string_split (str, chr)
2010 Split the string @var{str} into the a list of the substrings delimited
2011 by appearances of the character @var{chr}. Note that an empty substring
2012 between separator characters will result in an empty string in the
2013 result list.
2014
2015 @lisp
2016 (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
2017 @result{}
2018 ("root" "x" "0" "0" "root" "/root" "/bin/bash")
2019
2020 (string-split "::" #\:)
2021 @result{}
2022 ("" "" "")
2023
2024 (string-split "" #\:)
2025 @result{}
2026 ("")
2027 @end lisp
2028 @end deffn
2029
2030
2031 @node String Selection
2032 @subsubsection String Selection
2033
2034 Portions of strings can be extracted by these procedures.
2035 @code{string-ref} delivers individual characters whereas
2036 @code{substring} can be used to extract substrings from longer strings.
2037
2038 @rnindex string-length
2039 @deffn {Scheme Procedure} string-length string
2040 @deffnx {C Function} scm_string_length (string)
2041 Return the number of characters in @var{string}.
2042 @end deffn
2043
2044 @rnindex string-ref
2045 @deffn {Scheme Procedure} string-ref str k
2046 @deffnx {C Function} scm_string_ref (str, k)
2047 Return character @var{k} of @var{str} using zero-origin
2048 indexing. @var{k} must be a valid index of @var{str}.
2049 @end deffn
2050
2051 @rnindex string-copy
2052 @deffn {Scheme Procedure} string-copy str
2053 @deffnx {C Function} scm_string_copy (str)
2054 Return a newly allocated copy of the given @var{string}.
2055 @end deffn
2056
2057 @rnindex substring
2058 @deffn {Scheme Procedure} substring str start [end]
2059 @deffnx {C Function} scm_substring (str, start, end)
2060 Return a newly allocated string formed from the characters
2061 of @var{str} beginning with index @var{start} (inclusive) and
2062 ending with index @var{end} (exclusive).
2063 @var{str} must be a string, @var{start} and @var{end} must be
2064 exact integers satisfying:
2065
2066 0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
2067 @end deffn
2068
2069 @node String Modification
2070 @subsubsection String Modification
2071
2072 These procedures are for modifying strings in-place. This means that the
2073 result of the operation is not a new string; instead, the original string's
2074 memory representation is modified.
2075
2076 @rnindex string-set!
2077 @deffn {Scheme Procedure} string-set! str k chr
2078 @deffnx {C Function} scm_string_set_x (str, k, chr)
2079 Store @var{chr} in element @var{k} of @var{str} and return
2080 an unspecified value. @var{k} must be a valid index of
2081 @var{str}.
2082 @end deffn
2083
2084 @rnindex string-fill!
2085 @deffn {Scheme Procedure} string-fill! str chr
2086 @deffnx {C Function} scm_string_fill_x (str, chr)
2087 Store @var{char} in every element of the given @var{string} and
2088 return an unspecified value.
2089 @end deffn
2090
2091 @deffn {Scheme Procedure} substring-fill! str start end fill
2092 @deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
2093 Change every character in @var{str} between @var{start} and
2094 @var{end} to @var{fill}.
2095
2096 @lisp
2097 (define y "abcdefg")
2098 (substring-fill! y 1 3 #\r)
2099 y
2100 @result{} "arrdefg"
2101 @end lisp
2102 @end deffn
2103
2104 @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
2105 @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
2106 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
2107 into @var{str2} beginning at position @var{start2}.
2108 @var{str1} and @var{str2} can be the same string.
2109 @end deffn
2110
2111
2112 @node String Comparison
2113 @subsubsection String Comparison
2114
2115 The procedures in this section are similar to the character ordering
2116 predicates (@pxref{Characters}), but are defined on character sequences.
2117 They all return @code{#t} on success and @code{#f} on failure. The
2118 predicates ending in @code{-ci} ignore the character case when comparing
2119 strings.
2120
2121
2122 @rnindex string=?
2123 @deffn {Scheme Procedure} string=? s1 s2
2124 Lexicographic equality predicate; return @code{#t} if the two
2125 strings are the same length and contain the same characters in
2126 the same positions, otherwise return @code{#f}.
2127
2128 The procedure @code{string-ci=?} treats upper and lower case
2129 letters as though they were the same character, but
2130 @code{string=?} treats upper and lower case as distinct
2131 characters.
2132 @end deffn
2133
2134 @rnindex string<?
2135 @deffn {Scheme Procedure} string<? s1 s2
2136 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2137 is lexicographically less than @var{s2}.
2138 @end deffn
2139
2140 @rnindex string<=?
2141 @deffn {Scheme Procedure} string<=? s1 s2
2142 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2143 is lexicographically less than or equal to @var{s2}.
2144 @end deffn
2145
2146 @rnindex string>?
2147 @deffn {Scheme Procedure} string>? s1 s2
2148 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2149 is lexicographically greater than @var{s2}.
2150 @end deffn
2151
2152 @rnindex string>=?
2153 @deffn {Scheme Procedure} string>=? s1 s2
2154 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2155 is lexicographically greater than or equal to @var{s2}.
2156 @end deffn
2157
2158 @rnindex string-ci=?
2159 @deffn {Scheme Procedure} string-ci=? s1 s2
2160 Case-insensitive string equality predicate; return @code{#t} if
2161 the two strings are the same length and their component
2162 characters match (ignoring case) at each position; otherwise
2163 return @code{#f}.
2164 @end deffn
2165
2166 @rnindex string-ci<
2167 @deffn {Scheme Procedure} string-ci<? s1 s2
2168 Case insensitive lexicographic ordering predicate; return
2169 @code{#t} if @var{s1} is lexicographically less than @var{s2}
2170 regardless of case.
2171 @end deffn
2172
2173 @rnindex string<=?
2174 @deffn {Scheme Procedure} string-ci<=? s1 s2
2175 Case insensitive lexicographic ordering predicate; return
2176 @code{#t} if @var{s1} is lexicographically less than or equal
2177 to @var{s2} regardless of case.
2178 @end deffn
2179
2180 @rnindex string-ci>?
2181 @deffn {Scheme Procedure} string-ci>? s1 s2
2182 Case insensitive lexicographic ordering predicate; return
2183 @code{#t} if @var{s1} is lexicographically greater than
2184 @var{s2} regardless of case.
2185 @end deffn
2186
2187 @rnindex string-ci>=?
2188 @deffn {Scheme Procedure} string-ci>=? s1 s2
2189 Case insensitive lexicographic ordering predicate; return
2190 @code{#t} if @var{s1} is lexicographically greater than or
2191 equal to @var{s2} regardless of case.
2192 @end deffn
2193
2194
2195 @node String Searching
2196 @subsubsection String Searching
2197
2198 When searching for the index of a character in a string, these
2199 procedures can be used.
2200
2201 @deffn {Scheme Procedure} string-index str chr [frm [to]]
2202 @deffnx {C Function} scm_string_index (str, chr, frm, to)
2203 Return the index of the first occurrence of @var{chr} in
2204 @var{str}. The optional integer arguments @var{frm} and
2205 @var{to} limit the search to a portion of the string. This
2206 procedure essentially implements the @code{index} or
2207 @code{strchr} functions from the C library.
2208
2209 @lisp
2210 (string-index "weiner" #\e)
2211 @result{} 1
2212
2213 (string-index "weiner" #\e 2)
2214 @result{} 4
2215
2216 (string-index "weiner" #\e 2 4)
2217 @result{} #f
2218 @end lisp
2219 @end deffn
2220
2221 @deffn {Scheme Procedure} string-rindex str chr [frm [to]]
2222 @deffnx {C Function} scm_string_rindex (str, chr, frm, to)
2223 Like @code{string-index}, but search from the right of the
2224 string rather than from the left. This procedure essentially
2225 implements the @code{rindex} or @code{strrchr} functions from
2226 the C library.
2227
2228 @lisp
2229 (string-rindex "weiner" #\e)
2230 @result{} 4
2231
2232 (string-rindex "weiner" #\e 2 4)
2233 @result{} #f
2234
2235 (string-rindex "weiner" #\e 2 5)
2236 @result{} 4
2237 @end lisp
2238 @end deffn
2239
2240 @node Alphabetic Case Mapping
2241 @subsubsection Alphabetic Case Mapping
2242
2243 These are procedures for mapping strings to their upper- or lower-case
2244 equivalents, respectively, or for capitalizing strings.
2245
2246 @deffn {Scheme Procedure} string-upcase str
2247 @deffnx {C Function} scm_string_upcase (str)
2248 Return a freshly allocated string containing the characters of
2249 @var{str} in upper case.
2250 @end deffn
2251
2252 @deffn {Scheme Procedure} string-upcase! str
2253 @deffnx {C Function} scm_string_upcase_x (str)
2254 Destructively upcase every character in @var{str} and return
2255 @var{str}.
2256 @lisp
2257 y @result{} "arrdefg"
2258 (string-upcase! y) @result{} "ARRDEFG"
2259 y @result{} "ARRDEFG"
2260 @end lisp
2261 @end deffn
2262
2263 @deffn {Scheme Procedure} string-downcase str
2264 @deffnx {C Function} scm_string_downcase (str)
2265 Return a freshly allocation string containing the characters in
2266 @var{str} in lower case.
2267 @end deffn
2268
2269 @deffn {Scheme Procedure} string-downcase! str
2270 @deffnx {C Function} scm_string_downcase_x (str)
2271 Destructively downcase every character in @var{str} and return
2272 @var{str}.
2273 @lisp
2274 y @result{} "ARRDEFG"
2275 (string-downcase! y) @result{} "arrdefg"
2276 y @result{} "arrdefg"
2277 @end lisp
2278 @end deffn
2279
2280 @deffn {Scheme Procedure} string-capitalize str
2281 @deffnx {C Function} scm_string_capitalize (str)
2282 Return a freshly allocated string with the characters in
2283 @var{str}, where the first character of every word is
2284 capitalized.
2285 @end deffn
2286
2287 @deffn {Scheme Procedure} string-capitalize! str
2288 @deffnx {C Function} scm_string_capitalize_x (str)
2289 Upcase the first character of every word in @var{str}
2290 destructively and return @var{str}.
2291
2292 @lisp
2293 y @result{} "hello world"
2294 (string-capitalize! y) @result{} "Hello World"
2295 y @result{} "Hello World"
2296 @end lisp
2297 @end deffn
2298
2299
2300 @node Appending Strings
2301 @subsubsection Appending Strings
2302
2303 The procedure @code{string-append} appends several strings together to
2304 form a longer result string.
2305
2306 @rnindex string-append
2307 @deffn {Scheme Procedure} string-append . args
2308 @deffnx {C Function} scm_string_append (args)
2309 Return a newly allocated string whose characters form the
2310 concatenation of the given strings, @var{args}.
2311
2312 @example
2313 (let ((h "hello "))
2314 (string-append h "world"))
2315 @result{} "hello world"
2316 @end example
2317 @end deffn
2318
2319 @node Conversion to/from C
2320 @subsubsection Conversion to/from C
2321
2322 When creating a Scheme string from a C string or when converting a
2323 Scheme string to a C string, the concept of character encoding becomes
2324 important.
2325
2326 In C, a string is just a sequence of bytes, and the character encoding
2327 describes the relation between these bytes and the actual characters
2328 that make up the string. For Scheme strings, character encoding is
2329 not an issue (most of the time), since in Scheme you never get to see
2330 the bytes, only the characters.
2331
2332 Well, ideally, anyway. Right now, Guile simply equates Scheme
2333 characters and bytes, ignoring the possibility of multi-byte encodings
2334 completely. This will change in the future, where Guile will use
2335 Unicode codepoints as its characters and UTF-8 (or maybe UCS-4) as its
2336 internal encoding. When you exclusively use the functions listed in
2337 this section, you are `future-proof'.
2338
2339 Converting a Scheme string to a C string will often allocate fresh
2340 memory to hold the result. You must take care that this memory is
2341 properly freed eventually. In many cases, this can be achieved by
2342 using @code{scm_frame_free} inside an appropriate frame,
2343 @xref{Frames}.
2344
2345 @deftypefn {C Function} SCM scm_from_locale_string (const char *str)
2346 @deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
2347 Creates a new Scheme string that has the same contents as @var{str}
2348 when interpreted in the current locale character encoding.
2349
2350 For @code{scm_from_locale_string}, @var{str} must be null-terminated.
2351
2352 For @code{scm_from_locale_stringn}, @var{len} specifies the length of
2353 @var{str} in bytes, and @var{str} does not need to be null-terminated.
2354 If @var{len} is @code{(size_t)-1}, then @var{str} does need to be
2355 null-terminated and the real length will be found with @code{strlen}.
2356 @end deftypefn
2357
2358 @deftypefn {C Function} SCM scm_take_locale_string (char *str)
2359 @deftypefnx {C Function} SCM scm_take_locale_stringn (char *str, size_t len)
2360 Like @code{scm_from_locale_string} and @code{scm_from_locale_stringn},
2361 respectively, but also frees @var{str} with @code{free} eventually.
2362 Thus, you can use this function when you would free @var{str} anyway
2363 immediately after creating the Scheme string. In certain cases, Guile
2364 can then use @var{str} directly as its internal representation.
2365 @end deftypefn
2366
2367 @deftypefn {C Function} char *scm_to_locale_string (SCM str)
2368 @deftypefnx {C Function} char *scm_to_locale_stringn (SCM str, size_t *lenp)
2369 Returns a C string in the current locale encoding with the same
2370 contents as @var{str}. The C string must be freed with @code{free}
2371 eventually, maybe by using @code{scm_frame_free}, @xref{Frames}.
2372
2373 For @code{scm_to_locale_string}, the returned string is
2374 null-terminated and an error is signalled when @var{str} contains
2375 @code{#\nul} characters.
2376
2377 For @code{scm_to_locale_stringn} and @var{lenp} not @code{NULL},
2378 @var{str} might contain @code{#\nul} characters and the length of the
2379 returned string in bytes is stored in @code{*@var{lenp}}. The
2380 returned string will not be null-terminated in this case. If
2381 @var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
2382 @code{scm_to_locale_string}.
2383 @end deftypefn
2384
2385 @deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
2386 Puts @var{str} as a C string in the current locale encoding into the
2387 memory pointed to by @var{buf}. The buffer at @var{buf} has room for
2388 @var{max_len} bytes and @code{scm_to_local_stringbuf} will never store
2389 more than that. No terminating @code{'\0'} will be stored.
2390
2391 The return value of @code{scm_to_locale_stringbuf} is the number of
2392 bytes that are needed for all of @var{str}, regardless of whether
2393 @var{buf} was large enough to hold them. Thus, when the return value
2394 is larger than @var{max_len}, only @var{max_len} bytes have been
2395 stored and you probably need to try again with a larger buffer.
2396 @end deftypefn
2397
2398 @node Regular Expressions
2399 @subsection Regular Expressions
2400 @tpindex Regular expressions
2401
2402 @cindex regular expressions
2403 @cindex regex
2404 @cindex emacs regexp
2405
2406 A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
2407 describes a whole class of strings. A full description of regular
2408 expressions and their syntax is beyond the scope of this manual;
2409 an introduction can be found in the Emacs manual (@pxref{Regexps,
2410 , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
2411 in many general Unix reference books.
2412
2413 If your system does not include a POSIX regular expression library,
2414 and you have not linked Guile with a third-party regexp library such
2415 as Rx, these functions will not be available. You can tell whether
2416 your Guile installation includes regular expression support by
2417 checking whether @code{(provided? 'regex)} returns true.
2418
2419 The following regexp and string matching features are provided by the
2420 @code{(ice-9 regex)} module. Before using the described functions,
2421 you should load this module by executing @code{(use-modules (ice-9
2422 regex))}.
2423
2424 @menu
2425 * Regexp Functions:: Functions that create and match regexps.
2426 * Match Structures:: Finding what was matched by a regexp.
2427 * Backslash Escapes:: Removing the special meaning of regexp
2428 meta-characters.
2429 @end menu
2430
2431
2432 @node Regexp Functions
2433 @subsubsection Regexp Functions
2434
2435 By default, Guile supports POSIX extended regular expressions.
2436 That means that the characters @samp{(}, @samp{)}, @samp{+} and
2437 @samp{?} are special, and must be escaped if you wish to match the
2438 literal characters.
2439
2440 This regular expression interface was modeled after that
2441 implemented by SCSH, the Scheme Shell. It is intended to be
2442 upwardly compatible with SCSH regular expressions.
2443
2444 @deffn {Scheme Procedure} string-match pattern str [start]
2445 Compile the string @var{pattern} into a regular expression and compare
2446 it with @var{str}. The optional numeric argument @var{start} specifies
2447 the position of @var{str} at which to begin matching.
2448
2449 @code{string-match} returns a @dfn{match structure} which
2450 describes what, if anything, was matched by the regular
2451 expression. @xref{Match Structures}. If @var{str} does not match
2452 @var{pattern} at all, @code{string-match} returns @code{#f}.
2453 @end deffn
2454
2455 Two examples of a match follow. In the first example, the pattern
2456 matches the four digits in the match string. In the second, the pattern
2457 matches nothing.
2458
2459 @example
2460 (string-match "[0-9][0-9][0-9][0-9]" "blah2002")
2461 @result{} #("blah2002" (4 . 8))
2462
2463 (string-match "[A-Za-z]" "123456")
2464 @result{} #f
2465 @end example
2466
2467 Each time @code{string-match} is called, it must compile its
2468 @var{pattern} argument into a regular expression structure. This
2469 operation is expensive, which makes @code{string-match} inefficient if
2470 the same regular expression is used several times (for example, in a
2471 loop). For better performance, you can compile a regular expression in
2472 advance and then match strings against the compiled regexp.
2473
2474 @deffn {Scheme Procedure} make-regexp pat flag@dots{}
2475 @deffnx {C Function} scm_make_regexp (pat, flaglst)
2476 Compile the regular expression described by @var{pat}, and
2477 return the compiled regexp structure. If @var{pat} does not
2478 describe a legal regular expression, @code{make-regexp} throws
2479 a @code{regular-expression-syntax} error.
2480
2481 The @var{flag} arguments change the behavior of the compiled
2482 regular expression. The following values may be supplied:
2483
2484 @defvar regexp/icase
2485 Consider uppercase and lowercase letters to be the same when
2486 matching.
2487 @end defvar
2488
2489 @defvar regexp/newline
2490 If a newline appears in the target string, then permit the
2491 @samp{^} and @samp{$} operators to match immediately after or
2492 immediately before the newline, respectively. Also, the
2493 @samp{.} and @samp{[^...]} operators will never match a newline
2494 character. The intent of this flag is to treat the target
2495 string as a buffer containing many lines of text, and the
2496 regular expression as a pattern that may match a single one of
2497 those lines.
2498 @end defvar
2499
2500 @defvar regexp/basic
2501 Compile a basic (``obsolete'') regexp instead of the extended
2502 (``modern'') regexps that are the default. Basic regexps do
2503 not consider @samp{|}, @samp{+} or @samp{?} to be special
2504 characters, and require the @samp{@{...@}} and @samp{(...)}
2505 metacharacters to be backslash-escaped (@pxref{Backslash
2506 Escapes}). There are several other differences between basic
2507 and extended regular expressions, but these are the most
2508 significant.
2509 @end defvar
2510
2511 @defvar regexp/extended
2512 Compile an extended regular expression rather than a basic
2513 regexp. This is the default behavior; this flag will not
2514 usually be needed. If a call to @code{make-regexp} includes
2515 both @code{regexp/basic} and @code{regexp/extended} flags, the
2516 one which comes last will override the earlier one.
2517 @end defvar
2518 @end deffn
2519
2520 @deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
2521 @deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
2522 Match the compiled regular expression @var{rx} against
2523 @code{str}. If the optional integer @var{start} argument is
2524 provided, begin matching from that position in the string.
2525 Return a match structure describing the results of the match,
2526 or @code{#f} if no match could be found.
2527
2528 The @var{flags} arguments change the matching behavior.
2529 The following flags may be supplied:
2530
2531 @defvar regexp/notbol
2532 Operator @samp{^} always fails (unless @code{regexp/newline}
2533 is used). Use this when the beginning of the string should
2534 not be considered the beginning of a line.
2535 @end defvar
2536
2537 @defvar regexp/noteol
2538 Operator @samp{$} always fails (unless @code{regexp/newline}
2539 is used). Use this when the end of the string should not be
2540 considered the end of a line.
2541 @end defvar
2542 @end deffn
2543
2544 @lisp
2545 ;; Regexp to match uppercase letters
2546 (define r (make-regexp "[A-Z]*"))
2547
2548 ;; Regexp to match letters, ignoring case
2549 (define ri (make-regexp "[A-Z]*" regexp/icase))
2550
2551 ;; Search for bob using regexp r
2552 (match:substring (regexp-exec r "bob"))
2553 @result{} "" ; no match
2554
2555 ;; Search for bob using regexp ri
2556 (match:substring (regexp-exec ri "Bob"))
2557 @result{} "Bob" ; matched case insensitive
2558 @end lisp
2559
2560 @deffn {Scheme Procedure} regexp? obj
2561 @deffnx {C Function} scm_regexp_p (obj)
2562 Return @code{#t} if @var{obj} is a compiled regular expression,
2563 or @code{#f} otherwise.
2564 @end deffn
2565
2566 Regular expressions are commonly used to find patterns in one string and
2567 replace them with the contents of another string.
2568
2569 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
2570 @deffn {Scheme Procedure} regexp-substitute port match [item@dots{}]
2571 Write to the output port @var{port} selected contents of the match
2572 structure @var{match}. Each @var{item} specifies what should be
2573 written, and may be one of the following arguments:
2574
2575 @itemize @bullet
2576 @item
2577 A string. String arguments are written out verbatim.
2578
2579 @item
2580 An integer. The submatch with that number is written.
2581
2582 @item
2583 The symbol @samp{pre}. The portion of the matched string preceding
2584 the regexp match is written.
2585
2586 @item
2587 The symbol @samp{post}. The portion of the matched string following
2588 the regexp match is written.
2589 @end itemize
2590
2591 The @var{port} argument may be @code{#f}, in which case nothing is
2592 written; instead, @code{regexp-substitute} constructs a string from the
2593 specified @var{item}s and returns that.
2594 @end deffn
2595
2596 The following example takes a regular expression that matches a standard
2597 @sc{yyyymmdd}-format date such as @code{"20020828"}. The
2598 @code{regexp-substitute} call returns a string computed from the
2599 information in the match structure, consisting of the fields and text
2600 from the original string reordered and reformatted.
2601
2602 @lisp
2603 (define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
2604 (define s "Date 20020429 12am.")
2605 (define sm (string-match date-regex s))
2606 (regexp-substitute #f sm 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
2607 @result{} "Date 04-29-2002 12am. (20020429)"
2608 @end lisp
2609
2610 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
2611 @deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
2612 Similar to @code{regexp-substitute}, but can be used to perform global
2613 substitutions on @var{str}. Instead of taking a match structure as an
2614 argument, @code{regexp-substitute/global} takes two string arguments: a
2615 @var{regexp} string describing a regular expression, and a @var{target}
2616 string which should be matched against this regular expression.
2617
2618 Each @var{item} behaves as in @code{regexp-substitute}, with the
2619 following exceptions:
2620
2621 @itemize @bullet
2622 @item
2623 A function may be supplied. When this function is called, it will be
2624 passed one argument: a match structure for a given regular expression
2625 match. It should return a string to be written out to @var{port}.
2626
2627 @item
2628 The @samp{post} symbol causes @code{regexp-substitute/global} to recurse
2629 on the unmatched portion of @var{str}. This @emph{must} be supplied in
2630 order to perform global search-and-replace on @var{str}; if it is not
2631 present among the @var{item}s, then @code{regexp-substitute/global} will
2632 return after processing a single match.
2633 @end itemize
2634 @end deffn
2635
2636 The example above for @code{regexp-substitute} could be rewritten as
2637 follows to remove the @code{string-match} stage:
2638
2639 @lisp
2640 (define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
2641 (define s "Date 20020429 12am.")
2642 (regexp-substitute/global #f date-regex s
2643 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
2644 @result{} "Date 04-29-2002 12am. (20020429)"
2645 @end lisp
2646
2647
2648 @node Match Structures
2649 @subsubsection Match Structures
2650
2651 @cindex match structures
2652
2653 A @dfn{match structure} is the object returned by @code{string-match} and
2654 @code{regexp-exec}. It describes which portion of a string, if any,
2655 matched the given regular expression. Match structures include: a
2656 reference to the string that was checked for matches; the starting and
2657 ending positions of the regexp match; and, if the regexp included any
2658 parenthesized subexpressions, the starting and ending positions of each
2659 submatch.
2660
2661 In each of the regexp match functions described below, the @code{match}
2662 argument must be a match structure returned by a previous call to
2663 @code{string-match} or @code{regexp-exec}. Most of these functions
2664 return some information about the original target string that was
2665 matched against a regular expression; we will call that string
2666 @var{target} for easy reference.
2667
2668 @c begin (scm-doc-string "regex.scm" "regexp-match?")
2669 @deffn {Scheme Procedure} regexp-match? obj
2670 Return @code{#t} if @var{obj} is a match structure returned by a
2671 previous call to @code{regexp-exec}, or @code{#f} otherwise.
2672 @end deffn
2673
2674 @c begin (scm-doc-string "regex.scm" "match:substring")
2675 @deffn {Scheme Procedure} match:substring match [n]
2676 Return the portion of @var{target} matched by subexpression number
2677 @var{n}. Submatch 0 (the default) represents the entire regexp match.
2678 If the regular expression as a whole matched, but the subexpression
2679 number @var{n} did not match, return @code{#f}.
2680 @end deffn
2681
2682 @lisp
2683 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2684 (match:substring s)
2685 @result{} "2002"
2686
2687 ;; match starting at offset 6 in the string
2688 (match:substring
2689 (string-match "[0-9][0-9][0-9][0-9]" "blah987654" 6))
2690 @result{} "7654"
2691 @end lisp
2692
2693 @c begin (scm-doc-string "regex.scm" "match:start")
2694 @deffn {Scheme Procedure} match:start match [n]
2695 Return the starting position of submatch number @var{n}.
2696 @end deffn
2697
2698 In the following example, the result is 4, since the match starts at
2699 character index 4:
2700
2701 @lisp
2702 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2703 (match:start s)
2704 @result{} 4
2705 @end lisp
2706
2707 @c begin (scm-doc-string "regex.scm" "match:end")
2708 @deffn {Scheme Procedure} match:end match [n]
2709 Return the ending position of submatch number @var{n}.
2710 @end deffn
2711
2712 In the following example, the result is 8, since the match runs between
2713 characters 4 and 8 (i.e. the ``2002'').
2714
2715 @lisp
2716 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2717 (match:end s)
2718 @result{} 8
2719 @end lisp
2720
2721 @c begin (scm-doc-string "regex.scm" "match:prefix")
2722 @deffn {Scheme Procedure} match:prefix match
2723 Return the unmatched portion of @var{target} preceding the regexp match.
2724
2725 @lisp
2726 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2727 (match:prefix s)
2728 @result{} "blah"
2729 @end lisp
2730 @end deffn
2731
2732 @c begin (scm-doc-string "regex.scm" "match:suffix")
2733 @deffn {Scheme Procedure} match:suffix match
2734 Return the unmatched portion of @var{target} following the regexp match.
2735 @end deffn
2736
2737 @lisp
2738 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2739 (match:suffix s)
2740 @result{} "foo"
2741 @end lisp
2742
2743 @c begin (scm-doc-string "regex.scm" "match:count")
2744 @deffn {Scheme Procedure} match:count match
2745 Return the number of parenthesized subexpressions from @var{match}.
2746 Note that the entire regular expression match itself counts as a
2747 subexpression, and failed submatches are included in the count.
2748 @end deffn
2749
2750 @c begin (scm-doc-string "regex.scm" "match:string")
2751 @deffn {Scheme Procedure} match:string match
2752 Return the original @var{target} string.
2753 @end deffn
2754
2755 @lisp
2756 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
2757 (match:string s)
2758 @result{} "blah2002foo"
2759 @end lisp
2760
2761
2762 @node Backslash Escapes
2763 @subsubsection Backslash Escapes
2764
2765 Sometimes you will want a regexp to match characters like @samp{*} or
2766 @samp{$} exactly. For example, to check whether a particular string
2767 represents a menu entry from an Info node, it would be useful to match
2768 it against a regexp like @samp{^* [^:]*::}. However, this won't work;
2769 because the asterisk is a metacharacter, it won't match the @samp{*} at
2770 the beginning of the string. In this case, we want to make the first
2771 asterisk un-magic.
2772
2773 You can do this by preceding the metacharacter with a backslash
2774 character @samp{\}. (This is also called @dfn{quoting} the
2775 metacharacter, and is known as a @dfn{backslash escape}.) When Guile
2776 sees a backslash in a regular expression, it considers the following
2777 glyph to be an ordinary character, no matter what special meaning it
2778 would ordinarily have. Therefore, we can make the above example work by
2779 changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells
2780 the regular expression engine to match only a single asterisk in the
2781 target string.
2782
2783 Since the backslash is itself a metacharacter, you may force a regexp to
2784 match a backslash in the target string by preceding the backslash with
2785 itself. For example, to find variable references in a @TeX{} program,
2786 you might want to find occurrences of the string @samp{\let\} followed
2787 by any number of alphabetic characters. The regular expression
2788 @samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the
2789 regexp each match a single backslash in the target string.
2790
2791 @c begin (scm-doc-string "regex.scm" "regexp-quote")
2792 @deffn {Scheme Procedure} regexp-quote str
2793 Quote each special character found in @var{str} with a backslash, and
2794 return the resulting string.
2795 @end deffn
2796
2797 @strong{Very important:} Using backslash escapes in Guile source code
2798 (as in Emacs Lisp or C) can be tricky, because the backslash character
2799 has special meaning for the Guile reader. For example, if Guile
2800 encounters the character sequence @samp{\n} in the middle of a string
2801 while processing Scheme code, it replaces those characters with a
2802 newline character. Similarly, the character sequence @samp{\t} is
2803 replaced by a horizontal tab. Several of these @dfn{escape sequences}
2804 are processed by the Guile reader before your code is executed.
2805 Unrecognized escape sequences are ignored: if the characters @samp{\*}
2806 appear in a string, they will be translated to the single character
2807 @samp{*}.
2808
2809 This translation is obviously undesirable for regular expressions, since
2810 we want to be able to include backslashes in a string in order to
2811 escape regexp metacharacters. Therefore, to make sure that a backslash
2812 is preserved in a string in your Guile program, you must use @emph{two}
2813 consecutive backslashes:
2814
2815 @lisp
2816 (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
2817 @end lisp
2818
2819 The string in this example is preprocessed by the Guile reader before
2820 any code is executed. The resulting argument to @code{make-regexp} is
2821 the string @samp{^\* [^:]*}, which is what we really want.
2822
2823 This also means that in order to write a regular expression that matches
2824 a single backslash character, the regular expression string in the
2825 source code must include @emph{four} backslashes. Each consecutive pair
2826 of backslashes gets translated by the Guile reader to a single
2827 backslash, and the resulting double-backslash is interpreted by the
2828 regexp engine as matching a single backslash character. Hence:
2829
2830 @lisp
2831 (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
2832 @end lisp
2833
2834 The reason for the unwieldiness of this syntax is historical. Both
2835 regular expression pattern matchers and Unix string processing systems
2836 have traditionally used backslashes with the special meanings
2837 described above. The POSIX regular expression specification and ANSI C
2838 standard both require these semantics. Attempting to abandon either
2839 convention would cause other kinds of compatibility problems, possibly
2840 more severe ones. Therefore, without extending the Scheme reader to
2841 support strings with different quoting conventions (an ungainly and
2842 confusing extension when implemented in other languages), we must adhere
2843 to this cumbersome escape syntax.
2844
2845
2846 @node Symbols
2847 @subsection Symbols
2848 @tpindex Symbols
2849
2850 Symbols in Scheme are widely used in three ways: as items of discrete
2851 data, as lookup keys for alists and hash tables, and to denote variable
2852 references.
2853
2854 A @dfn{symbol} is similar to a string in that it is defined by a
2855 sequence of characters. The sequence of characters is known as the
2856 symbol's @dfn{name}. In the usual case --- that is, where the symbol's
2857 name doesn't include any characters that could be confused with other
2858 elements of Scheme syntax --- a symbol is written in a Scheme program by
2859 writing the sequence of characters that make up the name, @emph{without}
2860 any quotation marks or other special syntax. For example, the symbol
2861 whose name is ``multiply-by-2'' is written, simply:
2862
2863 @lisp
2864 multiply-by-2
2865 @end lisp
2866
2867 Notice how this differs from a @emph{string} with contents
2868 ``multiply-by-2'', which is written with double quotation marks, like
2869 this:
2870
2871 @lisp
2872 "multiply-by-2"
2873 @end lisp
2874
2875 Looking beyond how they are written, symbols are different from strings
2876 in two important respects.
2877
2878 The first important difference is uniqueness. If the same-looking
2879 string is read twice from two different places in a program, the result
2880 is two @emph{different} string objects whose contents just happen to be
2881 the same. If, on the other hand, the same-looking symbol is read twice
2882 from two different places in a program, the result is the @emph{same}
2883 symbol object both times.
2884
2885 Given two read symbols, you can use @code{eq?} to test whether they are
2886 the same (that is, have the same name). @code{eq?} is the most
2887 efficient comparison operator in Scheme, and comparing two symbols like
2888 this is as fast as comparing, for example, two numbers. Given two
2889 strings, on the other hand, you must use @code{equal?} or
2890 @code{string=?}, which are much slower comparison operators, to
2891 determine whether the strings have the same contents.
2892
2893 @lisp
2894 (define sym1 (quote hello))
2895 (define sym2 (quote hello))
2896 (eq? sym1 sym2) @result{} #t
2897
2898 (define str1 "hello")
2899 (define str2 "hello")
2900 (eq? str1 str2) @result{} #f
2901 (equal? str1 str2) @result{} #t
2902 @end lisp
2903
2904 The second important difference is that symbols, unlike strings, are not
2905 self-evaluating. This is why we need the @code{(quote @dots{})}s in the
2906 example above: @code{(quote hello)} evaluates to the symbol named
2907 "hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
2908 symbol named "hello" and evaluated as a variable reference @dots{} about
2909 which more below (@pxref{Symbol Variables}).
2910
2911 @menu
2912 * Symbol Data:: Symbols as discrete data.
2913 * Symbol Keys:: Symbols as lookup keys.
2914 * Symbol Variables:: Symbols as denoting variables.
2915 * Symbol Primitives:: Operations related to symbols.
2916 * Symbol Props:: Function slots and property lists.
2917 * Symbol Read Syntax:: Extended read syntax for symbols.
2918 * Symbol Uninterned:: Uninterned symbols.
2919 @end menu
2920
2921
2922 @node Symbol Data
2923 @subsubsection Symbols as Discrete Data
2924
2925 Numbers and symbols are similar to the extent that they both lend
2926 themselves to @code{eq?} comparison. But symbols are more descriptive
2927 than numbers, because a symbol's name can be used directly to describe
2928 the concept for which that symbol stands.
2929
2930 For example, imagine that you need to represent some colours in a
2931 computer program. Using numbers, you would have to choose arbitrarily
2932 some mapping between numbers and colours, and then take care to use that
2933 mapping consistently:
2934
2935 @lisp
2936 ;; 1=red, 2=green, 3=purple
2937
2938 (if (eq? (colour-of car) 1)
2939 ...)
2940 @end lisp
2941
2942 @noindent
2943 You can make the mapping more explicit and the code more readable by
2944 defining constants:
2945
2946 @lisp
2947 (define red 1)
2948 (define green 2)
2949 (define purple 3)
2950
2951 (if (eq? (colour-of car) red)
2952 ...)
2953 @end lisp
2954
2955 @noindent
2956 But the simplest and clearest approach is not to use numbers at all, but
2957 symbols whose names specify the colours that they refer to:
2958
2959 @lisp
2960 (if (eq? (colour-of car) 'red)
2961 ...)
2962 @end lisp
2963
2964 The descriptive advantages of symbols over numbers increase as the set
2965 of concepts that you want to describe grows. Suppose that a car object
2966 can have other properties as well, such as whether it has or uses:
2967
2968 @itemize @bullet
2969 @item
2970 automatic or manual transmission
2971 @item
2972 leaded or unleaded fuel
2973 @item
2974 power steering (or not).
2975 @end itemize
2976
2977 @noindent
2978 Then a car's combined property set could be naturally represented and
2979 manipulated as a list of symbols:
2980
2981 @lisp
2982 (properties-of car1)
2983 @result{}
2984 (red manual unleaded power-steering)
2985
2986 (if (memq 'power-steering (properties-of car1))
2987 (display "Unfit people can drive this car.\n")
2988 (display "You'll need strong arms to drive this car!\n"))
2989 @print{}
2990 Unfit people can drive this car.
2991 @end lisp
2992
2993 Remember, the fundamental property of symbols that we are relying on
2994 here is that an occurrence of @code{'red} in one part of a program is an
2995 @emph{indistinguishable} symbol from an occurrence of @code{'red} in
2996 another part of a program; this means that symbols can usefully be
2997 compared using @code{eq?}. At the same time, symbols have naturally
2998 descriptive names. This combination of efficiency and descriptive power
2999 makes them ideal for use as discrete data.
3000
3001
3002 @node Symbol Keys
3003 @subsubsection Symbols as Lookup Keys
3004
3005 Given their efficiency and descriptive power, it is natural to use
3006 symbols as the keys in an association list or hash table.
3007
3008 To illustrate this, consider a more structured representation of the car
3009 properties example from the preceding subsection. Rather than
3010 mixing all the properties up together in a flat list, we could use an
3011 association list like this:
3012
3013 @lisp
3014 (define car1-properties '((colour . red)
3015 (transmission . manual)
3016 (fuel . unleaded)
3017 (steering . power-assisted)))
3018 @end lisp
3019
3020 Notice how this structure is more explicit and extensible than the flat
3021 list. For example it makes clear that @code{manual} refers to the
3022 transmission rather than, say, the windows or the locking of the car.
3023 It also allows further properties to use the same symbols among their
3024 possible values without becoming ambiguous:
3025
3026 @lisp
3027 (define car1-properties '((colour . red)
3028 (transmission . manual)
3029 (fuel . unleaded)
3030 (steering . power-assisted)
3031 (seat-colour . red)
3032 (locking . manual)))
3033 @end lisp
3034
3035 With a representation like this, it is easy to use the efficient
3036 @code{assq-XXX} family of procedures (@pxref{Association Lists}) to
3037 extract or change individual pieces of information:
3038
3039 @lisp
3040 (assq-ref car1-properties 'fuel) @result{} unleaded
3041 (assq-ref car1-properties 'transmission) @result{} manual
3042
3043 (assq-set! car1-properties 'seat-colour 'black)
3044 @result{}
3045 ((colour . red)
3046 (transmission . manual)
3047 (fuel . unleaded)
3048 (steering . power-assisted)
3049 (seat-colour . black)
3050 (locking . manual)))
3051 @end lisp
3052
3053 Hash tables also have keys, and exactly the same arguments apply to the
3054 use of symbols in hash tables as in association lists. The hash value
3055 that Guile uses to decide where to add a symbol-keyed entry to a hash
3056 table can be obtained by calling the @code{symbol-hash} procedure:
3057
3058 @deffn {Scheme Procedure} symbol-hash symbol
3059 @deffnx {C Function} scm_symbol_hash (symbol)
3060 Return a hash value for @var{symbol}.
3061 @end deffn
3062
3063 See @ref{Hash Tables} for information about hash tables in general, and
3064 for why you might choose to use a hash table rather than an association
3065 list.
3066
3067
3068 @node Symbol Variables
3069 @subsubsection Symbols as Denoting Variables
3070
3071 When an unquoted symbol in a Scheme program is evaluated, it is
3072 interpreted as a variable reference, and the result of the evaluation is
3073 the appropriate variable's value.
3074
3075 For example, when the expression @code{(string-length "abcd")} is read
3076 and evaluated, the sequence of characters @code{string-length} is read
3077 as the symbol whose name is "string-length". This symbol is associated
3078 with a variable whose value is the procedure that implements string
3079 length calculation. Therefore evaluation of the @code{string-length}
3080 symbol results in that procedure.
3081
3082 The details of the connection between an unquoted symbol and the
3083 variable to which it refers are explained elsewhere. See @ref{Binding
3084 Constructs}, for how associations between symbols and variables are
3085 created, and @ref{Modules}, for how those associations are affected by
3086 Guile's module system.
3087
3088
3089 @node Symbol Primitives
3090 @subsubsection Operations Related to Symbols
3091
3092 Given any Scheme value, you can determine whether it is a symbol using
3093 the @code{symbol?} primitive:
3094
3095 @rnindex symbol?
3096 @deffn {Scheme Procedure} symbol? obj
3097 @deffnx {C Function} scm_symbol_p (obj)
3098 Return @code{#t} if @var{obj} is a symbol, otherwise return
3099 @code{#f}.
3100 @end deffn
3101
3102 Once you know that you have a symbol, you can obtain its name as a
3103 string by calling @code{symbol->string}. Note that Guile differs by
3104 default from R5RS on the details of @code{symbol->string} as regards
3105 case-sensitivity:
3106
3107 @rnindex symbol->string
3108 @deffn {Scheme Procedure} symbol->string s
3109 @deffnx {C Function} scm_symbol_to_string (s)
3110 Return the name of symbol @var{s} as a string. By default, Guile reads
3111 symbols case-sensitively, so the string returned will have the same case
3112 variation as the sequence of characters that caused @var{s} to be
3113 created.
3114
3115 If Guile is set to read symbols case-insensitively (as specified by
3116 R5RS), and @var{s} comes into being as part of a literal expression
3117 (@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
3118 by a call to the @code{read} or @code{string-ci->symbol} procedures,
3119 Guile converts any alphabetic characters in the symbol's name to
3120 lower case before creating the symbol object, so the string returned
3121 here will be in lower case.
3122
3123 If @var{s} was created by @code{string->symbol}, the case of characters
3124 in the string returned will be the same as that in the string that was
3125 passed to @code{string->symbol}, regardless of Guile's case-sensitivity
3126 setting at the time @var{s} was created.
3127
3128 It is an error to apply mutation procedures like @code{string-set!} to
3129 strings returned by this procedure.
3130 @end deffn
3131
3132 Most symbols are created by writing them literally in code. However it
3133 is also possible to create symbols programmatically using the following
3134 @code{string->symbol} and @code{string-ci->symbol} procedures:
3135
3136 @rnindex string->symbol
3137 @deffn {Scheme Procedure} string->symbol string
3138 @deffnx {C Function} scm_string_to_symbol (string)
3139 Return the symbol whose name is @var{string}. This procedure can create
3140 symbols with names containing special characters or letters in the
3141 non-standard case, but it is usually a bad idea to create such symbols
3142 because in some implementations of Scheme they cannot be read as
3143 themselves.
3144 @end deffn
3145
3146 @deffn {Scheme Procedure} string-ci->symbol str
3147 @deffnx {C Function} scm_string_ci_to_symbol (str)
3148 Return the symbol whose name is @var{str}. If Guile is currently
3149 reading symbols case-insensitively, @var{str} is converted to lowercase
3150 before the returned symbol is looked up or created.
3151 @end deffn
3152
3153 The following examples illustrate Guile's detailed behaviour as regards
3154 the case-sensitivity of symbols:
3155
3156 @lisp
3157 (read-enable 'case-insensitive) ; R5RS compliant behaviour
3158
3159 (symbol->string 'flying-fish) @result{} "flying-fish"
3160 (symbol->string 'Martin) @result{} "martin"
3161 (symbol->string
3162 (string->symbol "Malvina")) @result{} "Malvina"
3163
3164 (eq? 'mISSISSIppi 'mississippi) @result{} #t
3165 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
3166 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
3167 (eq? 'LolliPop
3168 (string->symbol (symbol->string 'LolliPop))) @result{} #t
3169 (string=? "K. Harper, M.D."
3170 (symbol->string
3171 (string->symbol "K. Harper, M.D."))) @result{} #t
3172
3173 (read-disable 'case-insensitive) ; Guile default behaviour
3174
3175 (symbol->string 'flying-fish) @result{} "flying-fish"
3176 (symbol->string 'Martin) @result{} "Martin"
3177 (symbol->string
3178 (string->symbol "Malvina")) @result{} "Malvina"
3179
3180 (eq? 'mISSISSIppi 'mississippi) @result{} #f
3181 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
3182 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
3183 (eq? 'LolliPop
3184 (string->symbol (symbol->string 'LolliPop))) @result{} #t
3185 (string=? "K. Harper, M.D."
3186 (symbol->string
3187 (string->symbol "K. Harper, M.D."))) @result{} #t
3188 @end lisp
3189
3190 From C, there are lower level functions that construct a Scheme symbol
3191 from a null terminated C string or from a sequence of bytes whose length
3192 is specified explicitly.
3193
3194 @deffn {C Function} scm_str2symbol (const char * name)
3195 @deffnx {C Function} scm_mem2symbol (const char * name, size_t len)
3196 Construct and return a Scheme symbol whose name is specified by
3197 @var{name}. For @code{scm_str2symbol} @var{name} must be null
3198 terminated; For @code{scm_mem2symbol} the length of @var{name} is
3199 specified explicitly by @var{len}.
3200 @end deffn
3201
3202 Finally, some applications, especially those that generate new Scheme
3203 code dynamically, need to generate symbols for use in the generated
3204 code. The @code{gensym} primitive meets this need:
3205
3206 @deffn {Scheme Procedure} gensym [prefix]
3207 @deffnx {C Function} scm_gensym (prefix)
3208 Create a new symbol with a name constructed from a prefix and a counter
3209 value. The string @var{prefix} can be specified as an optional
3210 argument. Default prefix is @samp{@w{ g}}. The counter is increased by 1
3211 at each call. There is no provision for resetting the counter.
3212 @end deffn
3213
3214 The symbols generated by @code{gensym} are @emph{likely} to be unique,
3215 since their names begin with a space and it is only otherwise possible
3216 to generate such symbols if a programmer goes out of their way to do
3217 so. Uniqueness can be guaranteed by instead using uninterned symbols
3218 (@pxref{Symbol Uninterned}), though they can't be usefully written out
3219 and read back in.
3220
3221
3222 @node Symbol Props
3223 @subsubsection Function Slots and Property Lists
3224
3225 In traditional Lisp dialects, symbols are often understood as having
3226 three kinds of value at once:
3227
3228 @itemize @bullet
3229 @item
3230 a @dfn{variable} value, which is used when the symbol appears in
3231 code in a variable reference context
3232
3233 @item
3234 a @dfn{function} value, which is used when the symbol appears in
3235 code in a function name position (i.e. as the first element in an
3236 unquoted list)
3237
3238 @item
3239 a @dfn{property list} value, which is used when the symbol is given as
3240 the first argument to Lisp's @code{put} or @code{get} functions.
3241 @end itemize
3242
3243 Although Scheme (as one of its simplifications with respect to Lisp)
3244 does away with the distinction between variable and function namespaces,
3245 Guile currently retains some elements of the traditional structure in
3246 case they turn out to be useful when implementing translators for other
3247 languages, in particular Emacs Lisp.
3248
3249 Specifically, Guile symbols have two extra slots. for a symbol's
3250 property list, and for its ``function value.'' The following procedures
3251 are provided to access these slots.
3252
3253 @deffn {Scheme Procedure} symbol-fref symbol
3254 @deffnx {C Function} scm_symbol_fref (symbol)
3255 Return the contents of @var{symbol}'s @dfn{function slot}.
3256 @end deffn
3257
3258 @deffn {Scheme Procedure} symbol-fset! symbol value
3259 @deffnx {C Function} scm_symbol_fset_x (symbol, value)
3260 Set the contents of @var{symbol}'s function slot to @var{value}.
3261 @end deffn
3262
3263 @deffn {Scheme Procedure} symbol-pref symbol
3264 @deffnx {C Function} scm_symbol_pref (symbol)
3265 Return the @dfn{property list} currently associated with @var{symbol}.
3266 @end deffn
3267
3268 @deffn {Scheme Procedure} symbol-pset! symbol value
3269 @deffnx {C Function} scm_symbol_pset_x (symbol, value)
3270 Set @var{symbol}'s property list to @var{value}.
3271 @end deffn
3272
3273 @deffn {Scheme Procedure} symbol-property sym prop
3274 From @var{sym}'s property list, return the value for property
3275 @var{prop}. The assumption is that @var{sym}'s property list is an
3276 association list whose keys are distinguished from each other using
3277 @code{equal?}; @var{prop} should be one of the keys in that list. If
3278 the property list has no entry for @var{prop}, @code{symbol-property}
3279 returns @code{#f}.
3280 @end deffn
3281
3282 @deffn {Scheme Procedure} set-symbol-property! sym prop val
3283 In @var{sym}'s property list, set the value for property @var{prop} to
3284 @var{val}, or add a new entry for @var{prop}, with value @var{val}, if
3285 none already exists. For the structure of the property list, see
3286 @code{symbol-property}.
3287 @end deffn
3288
3289 @deffn {Scheme Procedure} symbol-property-remove! sym prop
3290 From @var{sym}'s property list, remove the entry for property
3291 @var{prop}, if there is one. For the structure of the property list,
3292 see @code{symbol-property}.
3293 @end deffn
3294
3295 Support for these extra slots may be removed in a future release, and it
3296 is probably better to avoid using them. (In release 1.6, Guile itself
3297 uses the property list slot sparingly, and the function slot not at
3298 all.) For a more modern and Schemely approach to properties, see
3299 @ref{Object Properties}.
3300
3301
3302 @node Symbol Read Syntax
3303 @subsubsection Extended Read Syntax for Symbols
3304
3305 The read syntax for a symbol is a sequence of letters, digits, and
3306 @dfn{extended alphabetic characters}, beginning with a character that
3307 cannot begin a number. In addition, the special cases of @code{+},
3308 @code{-}, and @code{...} are read as symbols even though numbers can
3309 begin with @code{+}, @code{-} or @code{.}.
3310
3311 Extended alphabetic characters may be used within identifiers as if
3312 they were letters. The set of extended alphabetic characters is:
3313
3314 @example
3315 ! $ % & * + - . / : < = > ? @@ ^ _ ~
3316 @end example
3317
3318 In addition to the standard read syntax defined above (which is taken
3319 from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
3320 Scheme})), Guile provides an extended symbol read syntax that allows the
3321 inclusion of unusual characters such as space characters, newlines and
3322 parentheses. If (for whatever reason) you need to write a symbol
3323 containing characters not mentioned above, you can do so as follows.
3324
3325 @itemize @bullet
3326 @item
3327 Begin the symbol with the characters @code{#@{},
3328
3329 @item
3330 write the characters of the symbol and
3331
3332 @item
3333 finish the symbol with the characters @code{@}#}.
3334 @end itemize
3335
3336 Here are a few examples of this form of read syntax. The first symbol
3337 needs to use extended syntax because it contains a space character, the
3338 second because it contains a line break, and the last because it looks
3339 like a number.
3340
3341 @lisp
3342 #@{foo bar@}#
3343
3344 #@{what
3345 ever@}#
3346
3347 #@{4242@}#
3348 @end lisp
3349
3350 Although Guile provides this extended read syntax for symbols,
3351 widespread usage of it is discouraged because it is not portable and not
3352 very readable.
3353
3354
3355 @node Symbol Uninterned
3356 @subsubsection Uninterned Symbols
3357
3358 What makes symbols useful is that they are automatically kept unique.
3359 There are no two symbols that are distinct objects but have the same
3360 name. But of course, there is no rule without exception. In addition
3361 to the normal symbols that have been discussed up to now, you can also
3362 create special @dfn{uninterned} symbols that behave slightly
3363 differently.
3364
3365 To understand what is different about them and why they might be useful,
3366 we look at how normal symbols are actually kept unique.
3367
3368 Whenever Guile wants to find the symbol with a specific name, for
3369 example during @code{read} or when executing @code{string->symbol}, it
3370 first looks into a table of all existing symbols to find out whether a
3371 symbol with the given name already exists. When this is the case, Guile
3372 just returns that symbol. When not, a new symbol with the name is
3373 created and entered into the table so that it can be found later.
3374
3375 Sometimes you might want to create a symbol that is guaranteed `fresh',
3376 i.e. a symbol that did not exist previously. You might also want to
3377 somehow guarantee that no one else will ever unintentionally stumble
3378 across your symbol in the future. These properties of a symbol are
3379 often needed when generating code during macro expansion. When
3380 introducing new temporary variables, you want to guarantee that they
3381 don't conflict with variables in other people's code.
3382
3383 The simplest way to arrange for this is to create a new symbol but
3384 not enter it into the global table of all symbols. That way, no one
3385 will ever get access to your symbol by chance. Symbols that are not in
3386 the table are called @dfn{uninterned}. Of course, symbols that
3387 @emph{are} in the table are called @dfn{interned}.
3388
3389 You create new uninterned symbols with the function @code{make-symbol}.
3390 You can test whether a symbol is interned or not with
3391 @code{symbol-interned?}.
3392
3393 Uninterned symbols break the rule that the name of a symbol uniquely
3394 identifies the symbol object. Because of this, they can not be written
3395 out and read back in like interned symbols. Currently, Guile has no
3396 support for reading uninterned symbols. Note that the function
3397 @code{gensym} does not return uninterned symbols for this reason.
3398
3399 @deffn {Scheme Procedure} make-symbol name
3400 @deffnx {C Function} scm_make_symbol (name)
3401 Return a new uninterned symbol with the name @var{name}. The returned
3402 symbol is guaranteed to be unique and future calls to
3403 @code{string->symbol} will not return it.
3404 @end deffn
3405
3406 @deffn {Scheme Procedure} symbol-interned? symbol
3407 @deffnx {C Function} scm_symbol_interned_p (symbol)
3408 Return @code{#t} if @var{symbol} is interned, otherwise return
3409 @code{#f}.
3410 @end deffn
3411
3412 For example:
3413
3414 @lisp
3415 (define foo-1 (string->symbol "foo"))
3416 (define foo-2 (string->symbol "foo"))
3417 (define foo-3 (make-symbol "foo"))
3418 (define foo-4 (make-symbol "foo"))
3419
3420 (eq? foo-1 foo-2)
3421 @result{} #t
3422 ; Two interned symbols with the same name are the same object,
3423
3424 (eq? foo-1 foo-3)
3425 @result{} #f
3426 ; but a call to make-symbol with the same name returns a
3427 ; distinct object.
3428
3429 (eq? foo-3 foo-4)
3430 @result{} #f
3431 ; A call to make-symbol always returns a new object, even for
3432 ; the same name.
3433
3434 foo-3
3435 @result{} #<uninterned-symbol foo 8085290>
3436 ; Uninterned symbols print differently from interned symbols,
3437
3438 (symbol? foo-3)
3439 @result{} #t
3440 ; but they are still symbols,
3441
3442 (symbol-interned? foo-3)
3443 @result{} #f
3444 ; just not interned.
3445 @end lisp
3446
3447
3448 @node Keywords
3449 @subsection Keywords
3450 @tpindex Keywords
3451
3452 Keywords are self-evaluating objects with a convenient read syntax that
3453 makes them easy to type.
3454
3455 Guile's keyword support conforms to R5RS, and adds a (switchable) read
3456 syntax extension to permit keywords to begin with @code{:} as well as
3457 @code{#:}.
3458
3459 @menu
3460 * Why Use Keywords?:: Motivation for keyword usage.
3461 * Coding With Keywords:: How to use keywords.
3462 * Keyword Read Syntax:: Read syntax for keywords.
3463 * Keyword Procedures:: Procedures for dealing with keywords.
3464 * Keyword Primitives:: The underlying primitive procedures.
3465 @end menu
3466
3467 @node Why Use Keywords?
3468 @subsubsection Why Use Keywords?
3469
3470 Keywords are useful in contexts where a program or procedure wants to be
3471 able to accept a large number of optional arguments without making its
3472 interface unmanageable.
3473
3474 To illustrate this, consider a hypothetical @code{make-window}
3475 procedure, which creates a new window on the screen for drawing into
3476 using some graphical toolkit. There are many parameters that the caller
3477 might like to specify, but which could also be sensibly defaulted, for
3478 example:
3479
3480 @itemize @bullet
3481 @item
3482 color depth -- Default: the color depth for the screen
3483
3484 @item
3485 background color -- Default: white
3486
3487 @item
3488 width -- Default: 600
3489
3490 @item
3491 height -- Default: 400
3492 @end itemize
3493
3494 If @code{make-window} did not use keywords, the caller would have to
3495 pass in a value for each possible argument, remembering the correct
3496 argument order and using a special value to indicate the default value
3497 for that argument:
3498
3499 @lisp
3500 (make-window 'default ;; Color depth
3501 'default ;; Background color
3502 800 ;; Width
3503 100 ;; Height
3504 @dots{}) ;; More make-window arguments
3505 @end lisp
3506
3507 With keywords, on the other hand, defaulted arguments are omitted, and
3508 non-default arguments are clearly tagged by the appropriate keyword. As
3509 a result, the invocation becomes much clearer:
3510
3511 @lisp
3512 (make-window #:width 800 #:height 100)
3513 @end lisp
3514
3515 On the other hand, for a simpler procedure with few arguments, the use
3516 of keywords would be a hindrance rather than a help. The primitive
3517 procedure @code{cons}, for example, would not be improved if it had to
3518 be invoked as
3519
3520 @lisp
3521 (cons #:car x #:cdr y)
3522 @end lisp
3523
3524 So the decision whether to use keywords or not is purely pragmatic: use
3525 them if they will clarify the procedure invocation at point of call.
3526
3527 @node Coding With Keywords
3528 @subsubsection Coding With Keywords
3529
3530 If a procedure wants to support keywords, it should take a rest argument
3531 and then use whatever means is convenient to extract keywords and their
3532 corresponding arguments from the contents of that rest argument.
3533
3534 The following example illustrates the principle: the code for
3535 @code{make-window} uses a helper procedure called
3536 @code{get-keyword-value} to extract individual keyword arguments from
3537 the rest argument.
3538
3539 @lisp
3540 (define (get-keyword-value args keyword default)
3541 (let ((kv (memq keyword args)))
3542 (if (and kv (>= (length kv) 2))
3543 (cadr kv)
3544 default)))
3545
3546 (define (make-window . args)
3547 (let ((depth (get-keyword-value args #:depth screen-depth))
3548 (bg (get-keyword-value args #:bg "white"))
3549 (width (get-keyword-value args #:width 800))
3550 (height (get-keyword-value args #:height 100))
3551 @dots{})
3552 @dots{}))
3553 @end lisp
3554
3555 But you don't need to write @code{get-keyword-value}. The @code{(ice-9
3556 optargs)} module provides a set of powerful macros that you can use to
3557 implement keyword-supporting procedures like this:
3558
3559 @lisp
3560 (use-modules (ice-9 optargs))
3561
3562 (define (make-window . args)
3563 (let-keywords args #f ((depth screen-depth)
3564 (bg "white")
3565 (width 800)
3566 (height 100))
3567 ...))
3568 @end lisp
3569
3570 @noindent
3571 Or, even more economically, like this:
3572
3573 @lisp
3574 (use-modules (ice-9 optargs))
3575
3576 (define* (make-window #:key (depth screen-depth)
3577 (bg "white")
3578 (width 800)
3579 (height 100))
3580 ...)
3581 @end lisp
3582
3583 For further details on @code{let-keywords}, @code{define*} and other
3584 facilities provided by the @code{(ice-9 optargs)} module, see
3585 @ref{Optional Arguments}.
3586
3587
3588 @node Keyword Read Syntax
3589 @subsubsection Keyword Read Syntax
3590
3591 Guile, by default, only recognizes the keyword syntax specified by R5RS.
3592 A token of the form @code{#:NAME}, where @code{NAME} has the same syntax
3593 as a Scheme symbol (@pxref{Symbol Read Syntax}), is the external
3594 representation of the keyword named @code{NAME}. Keyword objects print
3595 using this syntax as well, so values containing keyword objects can be
3596 read back into Guile. When used in an expression, keywords are
3597 self-quoting objects.
3598
3599 If the @code{keyword} read option is set to @code{'prefix}, Guile also
3600 recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
3601 of the form @code{:NAME} are read as symbols, as required by R5RS.
3602
3603 To enable and disable the alternative non-R5RS keyword syntax, you use
3604 the @code{read-set!} procedure documented in @ref{User level options
3605 interfaces} and @ref{Reader options}.
3606
3607 @smalllisp
3608 (read-set! keywords 'prefix)
3609
3610 #:type
3611 @result{}
3612 #:type
3613
3614 :type
3615 @result{}
3616 #:type
3617
3618 (read-set! keywords #f)
3619
3620 #:type
3621 @result{}
3622 #:type
3623
3624 :type
3625 @print{}
3626 ERROR: In expression :type:
3627 ERROR: Unbound variable: :type
3628 ABORT: (unbound-variable)
3629 @end smalllisp
3630
3631 @node Keyword Procedures
3632 @subsubsection Keyword Procedures
3633
3634 The following procedures can be used for converting symbols to keywords
3635 and back.
3636
3637 @deffn {Scheme Procedure} symbol->keyword sym
3638 Return a keyword with the same characters as in @var{sym}.
3639 @end deffn
3640
3641 @deffn {Scheme Procedure} keyword->symbol kw
3642 Return a symbol with the same characters as in @var{kw}.
3643 @end deffn
3644
3645
3646 @node Keyword Primitives
3647 @subsubsection Keyword Primitives
3648
3649 Internally, a keyword is implemented as something like a tagged symbol,
3650 where the tag identifies the keyword as being self-evaluating, and the
3651 symbol, known as the keyword's @dfn{dash symbol} has the same name as
3652 the keyword name but prefixed by a single dash. For example, the
3653 keyword @code{#:name} has the corresponding dash symbol @code{-name}.
3654
3655 Most keyword objects are constructed automatically by the reader when it
3656 reads a token beginning with @code{#:}. However, if you need to
3657 construct a keyword object programmatically, you can do so by calling
3658 @code{make-keyword-from-dash-symbol} with the corresponding dash symbol
3659 (as the reader does). The dash symbol for a keyword object can be
3660 retrieved using the @code{keyword-dash-symbol} procedure.
3661
3662 @deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
3663 @deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
3664 Make a keyword object from a @var{symbol} that starts with a dash.
3665 For example,
3666
3667 @example
3668 (make-keyword-from-dash-symbol '-foo)
3669 @result{} #:foo
3670 @end example
3671 @end deffn
3672
3673 @deffn {Scheme Procedure} keyword? obj
3674 @deffnx {C Function} scm_keyword_p (obj)
3675 Return @code{#t} if the argument @var{obj} is a keyword, else
3676 @code{#f}.
3677 @end deffn
3678
3679 @deffn {Scheme Procedure} keyword-dash-symbol keyword
3680 @deffnx {C Function} scm_keyword_dash_symbol (keyword)
3681 Return the dash symbol for @var{keyword}.
3682 This is the inverse of @code{make-keyword-from-dash-symbol}.
3683 For example,
3684
3685 @example
3686 (keyword-dash-symbol #:foo)
3687 @result{} -foo
3688 @end example
3689 @end deffn
3690
3691 @deftypefn {C Function} SCM scm_c_make_keyword (char *@var{str})
3692 Make a keyword object from a string. For example,
3693
3694 @example
3695 scm_c_make_keyword ("foo")
3696 @result{} #:foo
3697 @end example
3698 @c
3699 @c FIXME: What can be said about the string argument? Currently it's
3700 @c not used after creation, but should that be documented?
3701 @end deftypefn
3702
3703
3704 @node Other Types
3705 @subsection ``Functionality-Centric'' Data Types
3706
3707 Procedures and macros are documented in their own chapter: see
3708 @ref{Procedures and Macros}.
3709
3710 Variable objects are documented as part of the description of Guile's
3711 module system: see @ref{Variables}.
3712
3713 Asyncs, dynamic roots and fluids are described in the chapter on
3714 scheduling: see @ref{Scheduling}.
3715
3716 Hooks are documented in the chapter on general utility functions: see
3717 @ref{Hooks}.
3718
3719 Ports are described in the chapter on I/O: see @ref{Input and Output}.
3720
3721
3722 @c Local Variables:
3723 @c TeX-master: "guile.texi"
3724 @c End: