Renamed the "frames" that are related to dynamic-wind to "dynamic
[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:: Single characters.
46 * Character Sets:: Sets of characters.
47 * Strings:: Sequences of characters.
48 * Regular Expressions:: Pattern matching and substitution.
49 * Symbols:: Symbols.
50 * Keywords:: Self-quoting, customizable display keywords.
51 * Other Types:: "Functionality-centric" data types.
52 @end menu
53
54
55 @node Booleans
56 @subsection Booleans
57 @tpindex Booleans
58
59 The two boolean values are @code{#t} for true and @code{#f} for false.
60
61 Boolean values are returned by predicate procedures, such as the general
62 equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
63 (@pxref{Equality}) and numerical and string comparison operators like
64 @code{string=?} (@pxref{String Comparison}) and @code{<=}
65 (@pxref{Comparison}).
66
67 @lisp
68 (<= 3 8)
69 @result{} #t
70
71 (<= 3 -3)
72 @result{} #f
73
74 (equal? "house" "houses")
75 @result{} #f
76
77 (eq? #f #f)
78 @result{}
79 #t
80 @end lisp
81
82 In test condition contexts like @code{if} and @code{cond} (@pxref{if
83 cond case}), where a group of subexpressions will be evaluated only if a
84 @var{condition} expression evaluates to ``true'', ``true'' means any
85 value at all except @code{#f}.
86
87 @lisp
88 (if #t "yes" "no")
89 @result{} "yes"
90
91 (if 0 "yes" "no")
92 @result{} "yes"
93
94 (if #f "yes" "no")
95 @result{} "no"
96 @end lisp
97
98 A result of this asymmetry is that typical Scheme source code more often
99 uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
100 represent an @code{if} or @code{cond} false value, whereas @code{#t} is
101 not necessary to represent an @code{if} or @code{cond} true value.
102
103 It is important to note that @code{#f} is @strong{not} equivalent to any
104 other Scheme value. In particular, @code{#f} is not the same as the
105 number 0 (like in C and C++), and not the same as the ``empty list''
106 (like in some Lisp dialects).
107
108 In C, the two Scheme boolean values are available as the two constants
109 @code{SCM_BOOL_T} for @code{#t} and @code{SCM_BOOL_F} for @code{#f}.
110 Care must be taken with the false value @code{SCM_BOOL_F}: it is not
111 false when used in C conditionals. In order to test for it, use
112 @code{scm_is_false} or @code{scm_is_true}.
113
114 @rnindex not
115 @deffn {Scheme Procedure} not x
116 @deffnx {C Function} scm_not (x)
117 Return @code{#t} if @var{x} is @code{#f}, else return @code{#f}.
118 @end deffn
119
120 @rnindex boolean?
121 @deffn {Scheme Procedure} boolean? obj
122 @deffnx {C Function} scm_boolean_p (obj)
123 Return @code{#t} if @var{obj} is either @code{#t} or @code{#f}, else
124 return @code{#f}.
125 @end deffn
126
127 @deftypevr {C Macro} SCM SCM_BOOL_T
128 The @code{SCM} representation of the Scheme object @code{#t}.
129 @end deftypevr
130
131 @deftypevr {C Macro} SCM SCM_BOOL_F
132 The @code{SCM} representation of the Scheme object @code{#f}.
133 @end deftypevr
134
135 @deftypefn {C Function} int scm_is_true (SCM obj)
136 Return @code{0} if @var{obj} is @code{#f}, else return @code{1}.
137 @end deftypefn
138
139 @deftypefn {C Function} int scm_is_false (SCM obj)
140 Return @code{1} if @var{obj} is @code{#f}, else return @code{0}.
141 @end deftypefn
142
143 @deftypefn {C Function} int scm_is_bool (SCM obj)
144 Return @code{1} if @var{obj} is either @code{#t} or @code{#f}, else
145 return @code{0}.
146 @end deftypefn
147
148 @deftypefn {C Function} SCM scm_from_bool (int val)
149 Return @code{#f} if @var{val} is @code{0}, else return @code{#t}.
150 @end deftypefn
151
152 @deftypefn {C Function} int scm_to_bool (SCM val)
153 Return @code{1} if @var{val} is @code{SCM_BOOL_T}, return @code{0}
154 when @var{val} is @code{SCM_BOOL_F}, else signal a `wrong type' error.
155
156 You should probably use @code{scm_is_true} instead of this function
157 when you just want to test a @code{SCM} value for trueness.
158 @end deftypefn
159
160 @node Numbers
161 @subsection Numerical data types
162 @tpindex Numbers
163
164 Guile supports a rich ``tower'' of numerical types --- integer,
165 rational, real and complex --- and provides an extensive set of
166 mathematical and scientific functions for operating on numerical
167 data. This section of the manual documents those types and functions.
168
169 You may also find it illuminating to read R5RS's presentation of numbers
170 in Scheme, which is particularly clear and accessible: see
171 @ref{Numbers,,,r5rs,R5RS}.
172
173 @menu
174 * Numerical Tower:: Scheme's numerical "tower".
175 * Integers:: Whole numbers.
176 * Reals and Rationals:: Real and rational numbers.
177 * Complex Numbers:: Complex numbers.
178 * Exactness:: Exactness and inexactness.
179 * Number Syntax:: Read syntax for numerical data.
180 * Integer Operations:: Operations on integer values.
181 * Comparison:: Comparison predicates.
182 * Conversion:: Converting numbers to and from strings.
183 * Complex:: Complex number operations.
184 * Arithmetic:: Arithmetic functions.
185 * Scientific:: Scientific functions.
186 * Primitive Numerics:: Primitive numeric functions.
187 * Bitwise Operations:: Logical AND, OR, NOT, and so on.
188 * Random:: Random number generation.
189 @end menu
190
191
192 @node Numerical Tower
193 @subsubsection Scheme's Numerical ``Tower''
194 @rnindex number?
195
196 Scheme's numerical ``tower'' consists of the following categories of
197 numbers:
198
199 @table @dfn
200 @item integers
201 Whole numbers, positive or negative; e.g.@: --5, 0, 18.
202
203 @item rationals
204 The set of numbers that can be expressed as @math{@var{p}/@var{q}}
205 where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
206 pi (an irrational number) doesn't. These include integers
207 (@math{@var{n}/1}).
208
209 @item real numbers
210 The set of numbers that describes all possible positions along a
211 one-dimensional line. This includes rationals as well as irrational
212 numbers.
213
214 @item complex numbers
215 The set of numbers that describes all possible positions in a two
216 dimensional space. This includes real as well as imaginary numbers
217 (@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
218 @var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
219 @minus{}1.)
220 @end table
221
222 It is called a tower because each category ``sits on'' the one that
223 follows it, in the sense that every integer is also a rational, every
224 rational is also real, and every real number is also a complex number
225 (but with zero imaginary part).
226
227 In addition to the classification into integers, rationals, reals and
228 complex numbers, Scheme also distinguishes between whether a number is
229 represented exactly or not. For example, the result of
230 @m{2\sin(\pi/4),sin(pi/4)} is exactly @m{\sqrt{2},2^(1/2)} but Guile
231 can neither represent @m{\pi/4,pi/4} nor @m{\sqrt{2},2^(1/2)} exactly.
232 Instead, it stores an inexact approximation, using the C type
233 @code{double}.
234
235 Guile can represent exact rationals of any magnitude, inexact
236 rationals that fit into a C @code{double}, and inexact complex numbers
237 with @code{double} real and imaginary parts.
238
239 The @code{number?} predicate may be applied to any Scheme value to
240 discover whether the value is any of the supported numerical types.
241
242 @deffn {Scheme Procedure} number? obj
243 @deffnx {C Function} scm_number_p (obj)
244 Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
245 @end deffn
246
247 For example:
248
249 @lisp
250 (number? 3)
251 @result{} #t
252
253 (number? "hello there!")
254 @result{} #f
255
256 (define pi 3.141592654)
257 (number? pi)
258 @result{} #t
259 @end lisp
260
261 @deftypefn {C Function} int scm_is_number (SCM obj)
262 This is equivalent to @code{scm_is_true (scm_number_p (obj))}.
263 @end deftypefn
264
265 The next few subsections document each of Guile's numerical data types
266 in detail.
267
268 @node Integers
269 @subsubsection Integers
270
271 @tpindex Integer numbers
272
273 @rnindex integer?
274
275 Integers are whole numbers, that is numbers with no fractional part,
276 such as 2, 83, and @minus{}3789.
277
278 Integers in Guile can be arbitrarily big, as shown by the following
279 example.
280
281 @lisp
282 (define (factorial n)
283 (let loop ((n n) (product 1))
284 (if (= n 0)
285 product
286 (loop (- n 1) (* product n)))))
287
288 (factorial 3)
289 @result{} 6
290
291 (factorial 20)
292 @result{} 2432902008176640000
293
294 (- (factorial 45))
295 @result{} -119622220865480194561963161495657715064383733760000000000
296 @end lisp
297
298 Readers whose background is in programming languages where integers are
299 limited by the need to fit into just 4 or 8 bytes of memory may find
300 this surprising, or suspect that Guile's representation of integers is
301 inefficient. In fact, Guile achieves a near optimal balance of
302 convenience and efficiency by using the host computer's native
303 representation of integers where possible, and a more general
304 representation where the required number does not fit in the native
305 form. Conversion between these two representations is automatic and
306 completely invisible to the Scheme level programmer.
307
308 The infinities @samp{+inf.0} and @samp{-inf.0} are considered to be
309 inexact integers. They are explained in detail in the next section,
310 together with reals and rationals.
311
312 C has a host of different integer types, and Guile offers a host of
313 functions to convert between them and the @code{SCM} representation.
314 For example, a C @code{int} can be handled with @code{scm_to_int} and
315 @code{scm_from_int}. Guile also defines a few C integer types of its
316 own, to help with differences between systems.
317
318 C integer types that are not covered can be handled with the generic
319 @code{scm_to_signed_integer} and @code{scm_from_signed_integer} for
320 signed types, or with @code{scm_to_unsigned_integer} and
321 @code{scm_from_unsigned_integer} for unsigned types.
322
323 Scheme integers can be exact and inexact. For example, a number
324 written as @code{3.0} with an explicit decimal-point is inexact, but
325 it is also an integer. The functions @code{integer?} and
326 @code{scm_is_integer} report true for such a number, but the functions
327 @code{scm_is_signed_integer} and @code{scm_is_unsigned_integer} only
328 allow exact integers and thus report false. Likewise, the conversion
329 functions like @code{scm_to_signed_integer} only accept exact
330 integers.
331
332 The motivation for this behavior is that the inexactness of a number
333 should not be lost silently. If you want to allow inexact integers,
334 you can explicitely insert a call to @code{inexact->exact} or to its C
335 equivalent @code{scm_inexact_to_exact}. (Only inexact integers will
336 be converted by this call into exact integers; inexact non-integers
337 will become exact fractions.)
338
339 @deffn {Scheme Procedure} integer? x
340 @deffnx {C Function} scm_integer_p (x)
341 Return @code{#t} if @var{x} is an exact or inexact integer number, else
342 @code{#f}.
343
344 @lisp
345 (integer? 487)
346 @result{} #t
347
348 (integer? 3.0)
349 @result{} #t
350
351 (integer? -3.4)
352 @result{} #f
353
354 (integer? +inf.0)
355 @result{} #t
356 @end lisp
357 @end deffn
358
359 @deftypefn {C Function} int scm_is_integer (SCM x)
360 This is equivalent to @code{scm_is_true (scm_integer_p (x))}.
361 @end deftypefn
362
363 @defvr {C Type} scm_t_int8
364 @defvrx {C Type} scm_t_uint8
365 @defvrx {C Type} scm_t_int16
366 @defvrx {C Type} scm_t_uint16
367 @defvrx {C Type} scm_t_int32
368 @defvrx {C Type} scm_t_uint32
369 @defvrx {C Type} scm_t_int64
370 @defvrx {C Type} scm_t_uint64
371 @defvrx {C Type} scm_t_intmax
372 @defvrx {C Type} scm_t_uintmax
373 The C types are equivalent to the corresponding ISO C types but are
374 defined on all platforms, with the exception of @code{scm_t_int64} and
375 @code{scm_t_uint64}, which are only defined when a 64-bit type is
376 available. For example, @code{scm_t_int8} is equivalent to
377 @code{int8_t}.
378
379 You can regard these definitions as a stop-gap measure until all
380 platforms provide these types. If you know that all the platforms
381 that you are interested in already provide these types, it is better
382 to use them directly instead of the types provided by Guile.
383 @end defvr
384
385 @deftypefn {C Function} int scm_is_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
386 @deftypefnx {C Function} int scm_is_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
387 Return @code{1} when @var{x} represents an exact integer that is
388 between @var{min} and @var{max}, inclusive.
389
390 These functions can be used to check whether a @code{SCM} value will
391 fit into a given range, such as the range of a given C integer type.
392 If you just want to convert a @code{SCM} value to a given C integer
393 type, use one of the conversion functions directly.
394 @end deftypefn
395
396 @deftypefn {C Function} scm_t_intmax scm_to_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max)
397 @deftypefnx {C Function} scm_t_uintmax scm_to_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max)
398 When @var{x} represents an exact integer that is between @var{min} and
399 @var{max} inclusive, return that integer. Else signal an error,
400 either a `wrong-type' error when @var{x} is not an exact integer, or
401 an `out-of-range' error when it doesn't fit the given range.
402 @end deftypefn
403
404 @deftypefn {C Function} SCM scm_from_signed_integer (scm_t_intmax x)
405 @deftypefnx {C Function} SCM scm_from_unsigned_integer (scm_t_uintmax x)
406 Return the @code{SCM} value that represents the integer @var{x}. This
407 function will always succeed and will always return an exact number.
408 @end deftypefn
409
410 @deftypefn {C Function} char scm_to_char (SCM x)
411 @deftypefnx {C Function} {signed char} scm_to_schar (SCM x)
412 @deftypefnx {C Function} {unsigned char} scm_to_uchar (SCM x)
413 @deftypefnx {C Function} short scm_to_short (SCM x)
414 @deftypefnx {C Function} {unsigned short} scm_to_ushort (SCM x)
415 @deftypefnx {C Function} int scm_to_int (SCM x)
416 @deftypefnx {C Function} {unsigned int} scm_to_uint (SCM x)
417 @deftypefnx {C Function} long scm_to_long (SCM x)
418 @deftypefnx {C Function} {unsigned long} scm_to_ulong (SCM x)
419 @deftypefnx {C Function} {long long} scm_to_long_long (SCM x)
420 @deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x)
421 @deftypefnx {C Function} size_t scm_to_size_t (SCM x)
422 @deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x)
423 @deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x)
424 @deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x)
425 @deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x)
426 @deftypefnx {C Function} scm_t_uint16 scm_to_uint16 (SCM x)
427 @deftypefnx {C Function} scm_t_int32 scm_to_int32 (SCM x)
428 @deftypefnx {C Function} scm_t_uint32 scm_to_uint32 (SCM x)
429 @deftypefnx {C Function} scm_t_int64 scm_to_int64 (SCM x)
430 @deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x)
431 @deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x)
432 @deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x)
433 When @var{x} represents an exact integer that fits into the indicated
434 C type, return that integer. Else signal an error, either a
435 `wrong-type' error when @var{x} is not an exact integer, or an
436 `out-of-range' error when it doesn't fit the given range.
437
438 The functions @code{scm_to_long_long}, @code{scm_to_ulong_long},
439 @code{scm_to_int64}, and @code{scm_to_uint64} are only available when
440 the corresponding types are.
441 @end deftypefn
442
443 @deftypefn {C Function} SCM scm_from_char (char x)
444 @deftypefnx {C Function} SCM scm_from_schar (signed char x)
445 @deftypefnx {C Function} SCM scm_from_uchar (unsigned char x)
446 @deftypefnx {C Function} SCM scm_from_short (short x)
447 @deftypefnx {C Function} SCM scm_from_ushort (unsigned short x)
448 @deftypefnx {C Function} SCM scm_from_int (int x)
449 @deftypefnx {C Function} SCM scm_from_uint (unsigned int x)
450 @deftypefnx {C Function} SCM scm_from_long (long x)
451 @deftypefnx {C Function} SCM scm_from_ulong (unsigned long x)
452 @deftypefnx {C Function} SCM scm_from_long_long (long long x)
453 @deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x)
454 @deftypefnx {C Function} SCM scm_from_size_t (size_t x)
455 @deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x)
456 @deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x)
457 @deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x)
458 @deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x)
459 @deftypefnx {C Function} SCM scm_from_uint16 (scm_t_uint16 x)
460 @deftypefnx {C Function} SCM scm_from_int32 (scm_t_int32 x)
461 @deftypefnx {C Function} SCM scm_from_uint32 (scm_t_uint32 x)
462 @deftypefnx {C Function} SCM scm_from_int64 (scm_t_int64 x)
463 @deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x)
464 @deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x)
465 @deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x)
466 Return the @code{SCM} value that represents the integer @var{x}.
467 These functions will always succeed and will always return an exact
468 number.
469 @end deftypefn
470
471 @deftypefn {C Function} void scm_to_mpz (SCM val, mpz_t rop)
472 Assign @var{val} to the multiple precision integer @var{rop}.
473 @var{val} must be an exact integer, otherwise an error will be
474 signalled. @var{rop} must have been initialized with @code{mpz_init}
475 before this function is called. When @var{rop} is no longer needed
476 the occupied space must be freed with @code{mpz_clear}.
477 @xref{Initializing Integers,,, gmp, GNU MP Manual}, for details.
478 @end deftypefn
479
480 @deftypefn {C Function} SCM scm_from_mpz_t (mpz_t val)
481 Return the @code{SCM} value that represents @var{val}.
482 @end deftypefn
483
484 @node Reals and Rationals
485 @subsubsection Real and Rational Numbers
486 @tpindex Real numbers
487 @tpindex Rational numbers
488
489 @rnindex real?
490 @rnindex rational?
491
492 Mathematically, the real numbers are the set of numbers that describe
493 all possible points along a continuous, infinite, one-dimensional line.
494 The rational numbers are the set of all numbers that can be written as
495 fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
496 All rational numbers are also real, but there are real numbers that
497 are not rational, for example @m{\sqrt2, the square root of 2}, and
498 @m{\pi,pi}.
499
500 Guile can represent both exact and inexact rational numbers, but it
501 can not represent irrational numbers. Exact rationals are represented
502 by storing the numerator and denominator as two exact integers.
503 Inexact rationals are stored as floating point numbers using the C
504 type @code{double}.
505
506 Exact rationals are written as a fraction of integers. There must be
507 no whitespace around the slash:
508
509 @lisp
510 1/2
511 -22/7
512 @end lisp
513
514 Even though the actual encoding of inexact rationals is in binary, it
515 may be helpful to think of it as a decimal number with a limited
516 number of significant figures and a decimal point somewhere, since
517 this corresponds to the standard notation for non-whole numbers. For
518 example:
519
520 @lisp
521 0.34
522 -0.00000142857931198
523 -5648394822220000000000.0
524 4.0
525 @end lisp
526
527 The limited precision of Guile's encoding means that any ``real'' number
528 in Guile can be written in a rational form, by multiplying and then dividing
529 by sufficient powers of 10 (or in fact, 2). For example,
530 @samp{-0.00000142857931198} is the same as @minus{}142857931198 divided by
531 100000000000000000. In Guile's current incarnation, therefore, the
532 @code{rational?} and @code{real?} predicates are equivalent.
533
534
535 Dividing by an exact zero leads to a error message, as one might
536 expect. However, dividing by an inexact zero does not produce an
537 error. Instead, the result of the division is either plus or minus
538 infinity, depending on the sign of the divided number.
539
540 The infinities are written @samp{+inf.0} and @samp{-inf.0},
541 respectivly. This syntax is also recognized by @code{read} as an
542 extension to the usual Scheme syntax.
543
544 Dividing zero by zero yields something that is not a number at all:
545 @samp{+nan.0}. This is the special `not a number' value.
546
547 On platforms that follow @acronym{IEEE} 754 for their floating point
548 arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
549 are implemented using the corresponding @acronym{IEEE} 754 values.
550 They behave in arithmetic operations like @acronym{IEEE} 754 describes
551 it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
552
553 The infinities are inexact integers and are considered to be both even
554 and odd. While @samp{+nan.0} is not @code{=} to itself, it is
555 @code{eqv?} to itself.
556
557 To test for the special values, use the functions @code{inf?} and
558 @code{nan?}.
559
560 @deffn {Scheme Procedure} real? obj
561 @deffnx {C Function} scm_real_p (obj)
562 Return @code{#t} if @var{obj} is a real number, else @code{#f}. Note
563 that the sets of integer and rational values form subsets of the set
564 of real numbers, so the predicate will also be fulfilled if @var{obj}
565 is an integer number or a rational number.
566 @end deffn
567
568 @deffn {Scheme Procedure} rational? x
569 @deffnx {C Function} scm_rational_p (x)
570 Return @code{#t} if @var{x} is a rational number, @code{#f} otherwise.
571 Note that the set of integer values forms a subset of the set of
572 rational numbers, i. e. the predicate will also be fulfilled if
573 @var{x} is an integer number.
574
575 Since Guile can not represent irrational numbers, every number
576 satisfying @code{real?} also satisfies @code{rational?} in Guile.
577 @end deffn
578
579 @deffn {Scheme Procedure} rationalize x eps
580 @deffnx {C Function} scm_rationalize (x, eps)
581 Returns the @emph{simplest} rational number differing
582 from @var{x} by no more than @var{eps}.
583
584 As required by @acronym{R5RS}, @code{rationalize} only returns an
585 exact result when both its arguments are exact. Thus, you might need
586 to use @code{inexact->exact} on the arguments.
587
588 @lisp
589 (rationalize (inexact->exact 1.2) 1/100)
590 @result{} 6/5
591 @end lisp
592
593 @end deffn
594
595 @deffn {Scheme Procedure} inf? x
596 @deffnx {C Function} scm_inf_p (x)
597 Return @code{#t} if @var{x} is either @samp{+inf.0} or @samp{-inf.0},
598 @code{#f} otherwise.
599 @end deffn
600
601 @deffn {Scheme Procedure} nan? x
602 @deffnx {C Function} scm_nan_p (x)
603 Return @code{#t} if @var{x} is @samp{+nan.0}, @code{#f} otherwise.
604 @end deffn
605
606 @deffn {Scheme Procedure} nan
607 @deffnx {C Function} scm_nan ()
608 Return NaN.
609 @end deffn
610
611 @deffn {Scheme Procedure} inf
612 @deffnx {C Function} scm_inf ()
613 Return Inf.
614 @end deffn
615
616 @deffn {Scheme Procedure} numerator x
617 @deffnx {C Function} scm_numerator (x)
618 Return the numerator of the rational number @var{x}.
619 @end deffn
620
621 @deffn {Scheme Procedure} denominator x
622 @deffnx {C Function} scm_denominator (x)
623 Return the denominator of the rational number @var{x}.
624 @end deffn
625
626 @deftypefn {C Function} int scm_is_real (SCM val)
627 @deftypefnx {C Function} int scm_is_rational (SCM val)
628 Equivalent to @code{scm_is_true (scm_real_p (val))} and
629 @code{scm_is_true (scm_rational_p (val))}, respectively.
630 @end deftypefn
631
632 @deftypefn {C Function} double scm_to_double (SCM val)
633 Returns the number closest to @var{val} that is representable as a
634 @code{double}. Returns infinity for a @var{val} that is too large in
635 magnitude. The argument @var{val} must be a real number.
636 @end deftypefn
637
638 @deftypefn {C Function} SCM scm_from_double (double val)
639 Return the @code{SCM} value that representats @var{val}. The returned
640 value is inexact according to the predicate @code{inexact?}, but it
641 will be exactly equal to @var{val}.
642 @end deftypefn
643
644 @node Complex Numbers
645 @subsubsection Complex Numbers
646 @tpindex Complex numbers
647
648 @rnindex complex?
649
650 Complex numbers are the set of numbers that describe all possible points
651 in a two-dimensional space. The two coordinates of a particular point
652 in this space are known as the @dfn{real} and @dfn{imaginary} parts of
653 the complex number that describes that point.
654
655 In Guile, complex numbers are written in rectangular form as the sum of
656 their real and imaginary parts, using the symbol @code{i} to indicate
657 the imaginary part.
658
659 @lisp
660 3+4i
661 @result{}
662 3.0+4.0i
663
664 (* 3-8i 2.3+0.3i)
665 @result{}
666 9.3-17.5i
667 @end lisp
668
669 @cindex polar form
670 @noindent
671 Polar form can also be used, with an @samp{@@} between magnitude and
672 angle,
673
674 @lisp
675 1@@3.141592 @result{} -1.0 (approx)
676 -1@@1.57079 @result{} 0.0-1.0i (approx)
677 @end lisp
678
679 Guile represents a complex number with a non-zero imaginary part as a
680 pair of inexact rationals, so the real and imaginary parts of a
681 complex number have the same properties of inexactness and limited
682 precision as single inexact rational numbers. Guile can not represent
683 exact complex numbers with non-zero imaginary parts.
684
685 @deffn {Scheme Procedure} complex? z
686 @deffnx {C Function} scm_complex_p (z)
687 Return @code{#t} if @var{x} is a complex number, @code{#f}
688 otherwise. Note that the sets of real, rational and integer
689 values form subsets of the set of complex numbers, i. e. the
690 predicate will also be fulfilled if @var{x} is a real,
691 rational or integer number.
692 @end deffn
693
694 @deftypefn {C Function} int scm_is_complex (SCM val)
695 Equivalent to @code{scm_is_true (scm_complex_p (val))}.
696 @end deftypefn
697
698 @node Exactness
699 @subsubsection Exact and Inexact Numbers
700 @tpindex Exact numbers
701 @tpindex Inexact numbers
702
703 @rnindex exact?
704 @rnindex inexact?
705 @rnindex exact->inexact
706 @rnindex inexact->exact
707
708 R5RS requires that a calculation involving inexact numbers always
709 produces an inexact result. To meet this requirement, Guile
710 distinguishes between an exact integer value such as @samp{5} and the
711 corresponding inexact real value which, to the limited precision
712 available, has no fractional part, and is printed as @samp{5.0}. Guile
713 will only convert the latter value to the former when forced to do so by
714 an invocation of the @code{inexact->exact} procedure.
715
716 @deffn {Scheme Procedure} exact? z
717 @deffnx {C Function} scm_exact_p (z)
718 Return @code{#t} if the number @var{z} is exact, @code{#f}
719 otherwise.
720
721 @lisp
722 (exact? 2)
723 @result{} #t
724
725 (exact? 0.5)
726 @result{} #f
727
728 (exact? (/ 2))
729 @result{} #t
730 @end lisp
731
732 @end deffn
733
734 @deffn {Scheme Procedure} inexact? z
735 @deffnx {C Function} scm_inexact_p (z)
736 Return @code{#t} if the number @var{z} is inexact, @code{#f}
737 else.
738 @end deffn
739
740 @deffn {Scheme Procedure} inexact->exact z
741 @deffnx {C Function} scm_inexact_to_exact (z)
742 Return an exact number that is numerically closest to @var{z}, when
743 there is one. For inexact rationals, Guile returns the exact rational
744 that is numerically equal to the inexact rational. Inexact complex
745 numbers with a non-zero imaginary part can not be made exact.
746
747 @lisp
748 (inexact->exact 0.5)
749 @result{} 1/2
750 @end lisp
751
752 The following happens because 12/10 is not exactly representable as a
753 @code{double} (on most platforms). However, when reading a decimal
754 number that has been marked exact with the ``#e'' prefix, Guile is
755 able to represent it correctly.
756
757 @lisp
758 (inexact->exact 1.2)
759 @result{} 5404319552844595/4503599627370496
760
761 #e1.2
762 @result{} 6/5
763 @end lisp
764
765 @end deffn
766
767 @c begin (texi-doc-string "guile" "exact->inexact")
768 @deffn {Scheme Procedure} exact->inexact z
769 @deffnx {C Function} scm_exact_to_inexact (z)
770 Convert the number @var{z} to its inexact representation.
771 @end deffn
772
773
774 @node Number Syntax
775 @subsubsection Read Syntax for Numerical Data
776
777 The read syntax for integers is a string of digits, optionally
778 preceded by a minus or plus character, a code indicating the
779 base in which the integer is encoded, and a code indicating whether
780 the number is exact or inexact. The supported base codes are:
781
782 @table @code
783 @item #b
784 @itemx #B
785 the integer is written in binary (base 2)
786
787 @item #o
788 @itemx #O
789 the integer is written in octal (base 8)
790
791 @item #d
792 @itemx #D
793 the integer is written in decimal (base 10)
794
795 @item #x
796 @itemx #X
797 the integer is written in hexadecimal (base 16)
798 @end table
799
800 If the base code is omitted, the integer is assumed to be decimal. The
801 following examples show how these base codes are used.
802
803 @lisp
804 -13
805 @result{} -13
806
807 #d-13
808 @result{} -13
809
810 #x-13
811 @result{} -19
812
813 #b+1101
814 @result{} 13
815
816 #o377
817 @result{} 255
818 @end lisp
819
820 The codes for indicating exactness (which can, incidentally, be applied
821 to all numerical values) are:
822
823 @table @code
824 @item #e
825 @itemx #E
826 the number is exact
827
828 @item #i
829 @itemx #I
830 the number is inexact.
831 @end table
832
833 If the exactness indicator is omitted, the number is exact unless it
834 contains a radix point. Since Guile can not represent exact complex
835 numbers, an error is signalled when asking for them.
836
837 @lisp
838 (exact? 1.2)
839 @result{} #f
840
841 (exact? #e1.2)
842 @result{} #t
843
844 (exact? #e+1i)
845 ERROR: Wrong type argument
846 @end lisp
847
848 Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
849 plus and minus infinity, respectively. The value must be written
850 exactly as shown, that is, they always must have a sign and exactly
851 one zero digit after the decimal point. It also understands
852 @samp{+nan.0} and @samp{-nan.0} for the special `not-a-number' value.
853 The sign is ignored for `not-a-number' and the value is always printed
854 as @samp{+nan.0}.
855
856 @node Integer Operations
857 @subsubsection Operations on Integer Values
858 @rnindex odd?
859 @rnindex even?
860 @rnindex quotient
861 @rnindex remainder
862 @rnindex modulo
863 @rnindex gcd
864 @rnindex lcm
865
866 @deffn {Scheme Procedure} odd? n
867 @deffnx {C Function} scm_odd_p (n)
868 Return @code{#t} if @var{n} is an odd number, @code{#f}
869 otherwise.
870 @end deffn
871
872 @deffn {Scheme Procedure} even? n
873 @deffnx {C Function} scm_even_p (n)
874 Return @code{#t} if @var{n} is an even number, @code{#f}
875 otherwise.
876 @end deffn
877
878 @c begin (texi-doc-string "guile" "quotient")
879 @c begin (texi-doc-string "guile" "remainder")
880 @deffn {Scheme Procedure} quotient n d
881 @deffnx {Scheme Procedure} remainder n d
882 @deffnx {C Function} scm_quotient (n, d)
883 @deffnx {C Function} scm_remainder (n, d)
884 Return the quotient or remainder from @var{n} divided by @var{d}. The
885 quotient is rounded towards zero, and the remainder will have the same
886 sign as @var{n}. In all cases quotient and remainder satisfy
887 @math{@var{n} = @var{q}*@var{d} + @var{r}}.
888
889 @lisp
890 (remainder 13 4) @result{} 1
891 (remainder -13 4) @result{} -1
892 @end lisp
893 @end deffn
894
895 @c begin (texi-doc-string "guile" "modulo")
896 @deffn {Scheme Procedure} modulo n d
897 @deffnx {C Function} scm_modulo (n, d)
898 Return the remainder from @var{n} divided by @var{d}, with the same
899 sign as @var{d}.
900
901 @lisp
902 (modulo 13 4) @result{} 1
903 (modulo -13 4) @result{} 3
904 (modulo 13 -4) @result{} -3
905 (modulo -13 -4) @result{} -1
906 @end lisp
907 @end deffn
908
909 @c begin (texi-doc-string "guile" "gcd")
910 @deffn {Scheme Procedure} gcd x@dots{}
911 @deffnx {C Function} scm_gcd (x, y)
912 Return the greatest common divisor of all arguments.
913 If called without arguments, 0 is returned.
914
915 The C function @code{scm_gcd} always takes two arguments, while the
916 Scheme function can take an arbitrary number.
917 @end deffn
918
919 @c begin (texi-doc-string "guile" "lcm")
920 @deffn {Scheme Procedure} lcm x@dots{}
921 @deffnx {C Function} scm_lcm (x, y)
922 Return the least common multiple of the arguments.
923 If called without arguments, 1 is returned.
924
925 The C function @code{scm_lcm} always takes two arguments, while the
926 Scheme function can take an arbitrary number.
927 @end deffn
928
929 @deffn {Scheme Procedure} modulo-expt n k m
930 @deffnx {C Function} scm_modulo_expt (n, k, m)
931 Return @var{n} raised to the integer exponent
932 @var{k}, modulo @var{m}.
933
934 @lisp
935 (modulo-expt 2 3 5)
936 @result{} 3
937 @end lisp
938 @end deffn
939
940 @node Comparison
941 @subsubsection Comparison Predicates
942 @rnindex zero?
943 @rnindex positive?
944 @rnindex negative?
945
946 The C comparison functions below always takes two arguments, while the
947 Scheme functions can take an arbitrary number. Also keep in mind that
948 the C functions return one of the Scheme boolean values
949 @code{SCM_BOOL_T} or @code{SCM_BOOL_F} which are both true as far as C
950 is concerned. Thus, always write @code{scm_is_true (scm_num_eq_p (x,
951 y))} when testing the two Scheme numbers @code{x} and @code{y} for
952 equality, for example.
953
954 @c begin (texi-doc-string "guile" "=")
955 @deffn {Scheme Procedure} =
956 @deffnx {C Function} scm_num_eq_p (x, y)
957 Return @code{#t} if all parameters are numerically equal.
958 @end deffn
959
960 @c begin (texi-doc-string "guile" "<")
961 @deffn {Scheme Procedure} <
962 @deffnx {C Function} scm_less_p (x, y)
963 Return @code{#t} if the list of parameters is monotonically
964 increasing.
965 @end deffn
966
967 @c begin (texi-doc-string "guile" ">")
968 @deffn {Scheme Procedure} >
969 @deffnx {C Function} scm_gr_p (x, y)
970 Return @code{#t} if the list of parameters is monotonically
971 decreasing.
972 @end deffn
973
974 @c begin (texi-doc-string "guile" "<=")
975 @deffn {Scheme Procedure} <=
976 @deffnx {C Function} scm_leq_p (x, y)
977 Return @code{#t} if the list of parameters is monotonically
978 non-decreasing.
979 @end deffn
980
981 @c begin (texi-doc-string "guile" ">=")
982 @deffn {Scheme Procedure} >=
983 @deffnx {C Function} scm_geq_p (x, y)
984 Return @code{#t} if the list of parameters is monotonically
985 non-increasing.
986 @end deffn
987
988 @c begin (texi-doc-string "guile" "zero?")
989 @deffn {Scheme Procedure} zero? z
990 @deffnx {C Function} scm_zero_p (z)
991 Return @code{#t} if @var{z} is an exact or inexact number equal to
992 zero.
993 @end deffn
994
995 @c begin (texi-doc-string "guile" "positive?")
996 @deffn {Scheme Procedure} positive? x
997 @deffnx {C Function} scm_positive_p (x)
998 Return @code{#t} if @var{x} is an exact or inexact number greater than
999 zero.
1000 @end deffn
1001
1002 @c begin (texi-doc-string "guile" "negative?")
1003 @deffn {Scheme Procedure} negative? x
1004 @deffnx {C Function} scm_negative_p (x)
1005 Return @code{#t} if @var{x} is an exact or inexact number less than
1006 zero.
1007 @end deffn
1008
1009
1010 @node Conversion
1011 @subsubsection Converting Numbers To and From Strings
1012 @rnindex number->string
1013 @rnindex string->number
1014
1015 @deffn {Scheme Procedure} number->string n [radix]
1016 @deffnx {C Function} scm_number_to_string (n, radix)
1017 Return a string holding the external representation of the
1018 number @var{n} in the given @var{radix}. If @var{n} is
1019 inexact, a radix of 10 will be used.
1020 @end deffn
1021
1022 @deffn {Scheme Procedure} string->number string [radix]
1023 @deffnx {C Function} scm_string_to_number (string, radix)
1024 Return a number of the maximally precise representation
1025 expressed by the given @var{string}. @var{radix} must be an
1026 exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
1027 is a default radix that may be overridden by an explicit radix
1028 prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
1029 supplied, then the default radix is 10. If string is not a
1030 syntactically valid notation for a number, then
1031 @code{string->number} returns @code{#f}.
1032 @end deffn
1033
1034
1035 @node Complex
1036 @subsubsection Complex Number Operations
1037 @rnindex make-rectangular
1038 @rnindex make-polar
1039 @rnindex real-part
1040 @rnindex imag-part
1041 @rnindex magnitude
1042 @rnindex angle
1043
1044 @deffn {Scheme Procedure} make-rectangular real imaginary
1045 @deffnx {C Function} scm_make_rectangular (real, imaginary)
1046 Return a complex number constructed of the given @var{real} and
1047 @var{imaginary} parts.
1048 @end deffn
1049
1050 @deffn {Scheme Procedure} make-polar x y
1051 @deffnx {C Function} scm_make_polar (x, y)
1052 @cindex polar form
1053 Return the complex number @var{x} * e^(i * @var{y}).
1054 @end deffn
1055
1056 @c begin (texi-doc-string "guile" "real-part")
1057 @deffn {Scheme Procedure} real-part z
1058 @deffnx {C Function} scm_real_part (z)
1059 Return the real part of the number @var{z}.
1060 @end deffn
1061
1062 @c begin (texi-doc-string "guile" "imag-part")
1063 @deffn {Scheme Procedure} imag-part z
1064 @deffnx {C Function} scm_imag_part (z)
1065 Return the imaginary part of the number @var{z}.
1066 @end deffn
1067
1068 @c begin (texi-doc-string "guile" "magnitude")
1069 @deffn {Scheme Procedure} magnitude z
1070 @deffnx {C Function} scm_magnitude (z)
1071 Return the magnitude of the number @var{z}. This is the same as
1072 @code{abs} for real arguments, but also allows complex numbers.
1073 @end deffn
1074
1075 @c begin (texi-doc-string "guile" "angle")
1076 @deffn {Scheme Procedure} angle z
1077 @deffnx {C Function} scm_angle (z)
1078 Return the angle of the complex number @var{z}.
1079 @end deffn
1080
1081 @deftypefn {C Function} SCM scm_c_make_rectangular (double re, double im)
1082 @deftypefnx {C Function} SCM scm_c_make_polar (double x, double y)
1083 Like @code{scm_make_rectangular} or @code{scm_make_polar},
1084 respectively, but these functions take @code{double}s as their
1085 arguments.
1086 @end deftypefn
1087
1088 @deftypefn {C Function} double scm_c_real_part (z)
1089 @deftypefnx {C Function} double scm_c_imag_part (z)
1090 Returns the real or imaginary part of @var{z} as a @code{double}.
1091 @end deftypefn
1092
1093 @deftypefn {C Function} double scm_c_magnitude (z)
1094 @deftypefnx {C Function} double scm_c_angle (z)
1095 Returns the magnitude or angle of @var{z} as a @code{double}.
1096 @end deftypefn
1097
1098
1099 @node Arithmetic
1100 @subsubsection Arithmetic Functions
1101 @rnindex max
1102 @rnindex min
1103 @rnindex +
1104 @rnindex *
1105 @rnindex -
1106 @rnindex /
1107 @rnindex abs
1108 @rnindex floor
1109 @rnindex ceiling
1110 @rnindex truncate
1111 @rnindex round
1112
1113 The C arithmetic functions below always takes two arguments, while the
1114 Scheme functions can take an arbitrary number. When you need to
1115 invoke them with just one argument, for example to compute the
1116 equivalent od @code{(- x)}, pass @code{SCM_UNDEFINED} as the second
1117 one: @code{scm_difference (x, SCM_UNDEFINED)}.
1118
1119 @c begin (texi-doc-string "guile" "+")
1120 @deffn {Scheme Procedure} + z1 @dots{}
1121 @deffnx {C Function} scm_sum (z1, z2)
1122 Return the sum of all parameter values. Return 0 if called without any
1123 parameters.
1124 @end deffn
1125
1126 @c begin (texi-doc-string "guile" "-")
1127 @deffn {Scheme Procedure} - z1 z2 @dots{}
1128 @deffnx {C Function} scm_difference (z1, z2)
1129 If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
1130 the sum of all but the first argument are subtracted from the first
1131 argument.
1132 @end deffn
1133
1134 @c begin (texi-doc-string "guile" "*")
1135 @deffn {Scheme Procedure} * z1 @dots{}
1136 @deffnx {C Function} scm_product (z1, z2)
1137 Return the product of all arguments. If called without arguments, 1 is
1138 returned.
1139 @end deffn
1140
1141 @c begin (texi-doc-string "guile" "/")
1142 @deffn {Scheme Procedure} / z1 z2 @dots{}
1143 @deffnx {C Function} scm_divide (z1, z2)
1144 Divide the first argument by the product of the remaining arguments. If
1145 called with one argument @var{z1}, 1/@var{z1} is returned.
1146 @end deffn
1147
1148 @c begin (texi-doc-string "guile" "abs")
1149 @deffn {Scheme Procedure} abs x
1150 @deffnx {C Function} scm_abs (x)
1151 Return the absolute value of @var{x}.
1152
1153 @var{x} must be a number with zero imaginary part. To calculate the
1154 magnitude of a complex number, use @code{magnitude} instead.
1155 @end deffn
1156
1157 @c begin (texi-doc-string "guile" "max")
1158 @deffn {Scheme Procedure} max x1 x2 @dots{}
1159 @deffnx {C Function} scm_max (x1, x2)
1160 Return the maximum of all parameter values.
1161 @end deffn
1162
1163 @c begin (texi-doc-string "guile" "min")
1164 @deffn {Scheme Procedure} min x1 x2 @dots{}
1165 @deffnx {C Function} scm_min (x1, x2)
1166 Return the minimum of all parameter values.
1167 @end deffn
1168
1169 @c begin (texi-doc-string "guile" "truncate")
1170 @deffn {Scheme Procedure} truncate x
1171 @deffnx {C Function} scm_truncate_number (x)
1172 Round the inexact number @var{x} towards zero.
1173 @end deffn
1174
1175 @c begin (texi-doc-string "guile" "round")
1176 @deffn {Scheme Procedure} round x
1177 @deffnx {C Function} scm_round_number (x)
1178 Round the inexact number @var{x} to the nearest integer. When exactly
1179 halfway between two integers, round to the even one.
1180 @end deffn
1181
1182 @c begin (texi-doc-string "guile" "floor")
1183 @deffn {Scheme Procedure} floor x
1184 @deffnx {C Function} scm_floor (x)
1185 Round the number @var{x} towards minus infinity.
1186 @end deffn
1187
1188 @c begin (texi-doc-string "guile" "ceiling")
1189 @deffn {Scheme Procedure} ceiling x
1190 @deffnx {C Function} scm_ceiling (x)
1191 Round the number @var{x} towards infinity.
1192 @end deffn
1193
1194 @deftypefn {C Function} double scm_c_truncate (double x)
1195 @deftypefnx {C Function} double scm_c_round (double x)
1196 Like @code{scm_truncate_number} or @code{scm_round_number},
1197 respectively, but these functions take and return @code{double}
1198 values.
1199 @end deftypefn
1200
1201 @node Scientific
1202 @subsubsection Scientific Functions
1203
1204 The following procedures accept any kind of number as arguments,
1205 including complex numbers.
1206
1207 @rnindex sqrt
1208 @c begin (texi-doc-string "guile" "sqrt")
1209 @deffn {Scheme Procedure} sqrt z
1210 Return the square root of @var{z}.
1211 @end deffn
1212
1213 @rnindex expt
1214 @c begin (texi-doc-string "guile" "expt")
1215 @deffn {Scheme Procedure} expt z1 z2
1216 Return @var{z1} raised to the power of @var{z2}.
1217 @end deffn
1218
1219 @rnindex sin
1220 @c begin (texi-doc-string "guile" "sin")
1221 @deffn {Scheme Procedure} sin z
1222 Return the sine of @var{z}.
1223 @end deffn
1224
1225 @rnindex cos
1226 @c begin (texi-doc-string "guile" "cos")
1227 @deffn {Scheme Procedure} cos z
1228 Return the cosine of @var{z}.
1229 @end deffn
1230
1231 @rnindex tan
1232 @c begin (texi-doc-string "guile" "tan")
1233 @deffn {Scheme Procedure} tan z
1234 Return the tangent of @var{z}.
1235 @end deffn
1236
1237 @rnindex asin
1238 @c begin (texi-doc-string "guile" "asin")
1239 @deffn {Scheme Procedure} asin z
1240 Return the arcsine of @var{z}.
1241 @end deffn
1242
1243 @rnindex acos
1244 @c begin (texi-doc-string "guile" "acos")
1245 @deffn {Scheme Procedure} acos z
1246 Return the arccosine of @var{z}.
1247 @end deffn
1248
1249 @rnindex atan
1250 @c begin (texi-doc-string "guile" "atan")
1251 @deffn {Scheme Procedure} atan z
1252 @deffnx {Scheme Procedure} atan y x
1253 Return the arctangent of @var{z}, or of @math{@var{y}/@var{x}}.
1254 @end deffn
1255
1256 @rnindex exp
1257 @c begin (texi-doc-string "guile" "exp")
1258 @deffn {Scheme Procedure} exp z
1259 Return e to the power of @var{z}, where e is the base of natural
1260 logarithms (2.71828@dots{}).
1261 @end deffn
1262
1263 @rnindex log
1264 @c begin (texi-doc-string "guile" "log")
1265 @deffn {Scheme Procedure} log z
1266 Return the natural logarithm of @var{z}.
1267 @end deffn
1268
1269 @c begin (texi-doc-string "guile" "log10")
1270 @deffn {Scheme Procedure} log10 z
1271 Return the base 10 logarithm of @var{z}.
1272 @end deffn
1273
1274 @c begin (texi-doc-string "guile" "sinh")
1275 @deffn {Scheme Procedure} sinh z
1276 Return the hyperbolic sine of @var{z}.
1277 @end deffn
1278
1279 @c begin (texi-doc-string "guile" "cosh")
1280 @deffn {Scheme Procedure} cosh z
1281 Return the hyperbolic cosine of @var{z}.
1282 @end deffn
1283
1284 @c begin (texi-doc-string "guile" "tanh")
1285 @deffn {Scheme Procedure} tanh z
1286 Return the hyperbolic tangent of @var{z}.
1287 @end deffn
1288
1289 @c begin (texi-doc-string "guile" "asinh")
1290 @deffn {Scheme Procedure} asinh z
1291 Return the hyperbolic arcsine of @var{z}.
1292 @end deffn
1293
1294 @c begin (texi-doc-string "guile" "acosh")
1295 @deffn {Scheme Procedure} acosh z
1296 Return the hyperbolic arccosine of @var{z}.
1297 @end deffn
1298
1299 @c begin (texi-doc-string "guile" "atanh")
1300 @deffn {Scheme Procedure} atanh z
1301 Return the hyperbolic arctangent of @var{z}.
1302 @end deffn
1303
1304
1305 @node Primitive Numerics
1306 @subsubsection Primitive Numeric Functions
1307
1308 Many of Guile's numeric procedures which accept any kind of numbers as
1309 arguments, including complex numbers, are implemented as Scheme
1310 procedures that use the following real number-based primitives. These
1311 primitives signal an error if they are called with complex arguments.
1312
1313 @c begin (texi-doc-string "guile" "$abs")
1314 @deffn {Scheme Procedure} $abs x
1315 Return the absolute value of @var{x}.
1316 @end deffn
1317
1318 @c begin (texi-doc-string "guile" "$sqrt")
1319 @deffn {Scheme Procedure} $sqrt x
1320 Return the square root of @var{x}.
1321 @end deffn
1322
1323 @deffn {Scheme Procedure} $expt x y
1324 @deffnx {C Function} scm_sys_expt (x, y)
1325 Return @var{x} raised to the power of @var{y}. This
1326 procedure does not accept complex arguments.
1327 @end deffn
1328
1329 @c begin (texi-doc-string "guile" "$sin")
1330 @deffn {Scheme Procedure} $sin x
1331 Return the sine of @var{x}.
1332 @end deffn
1333
1334 @c begin (texi-doc-string "guile" "$cos")
1335 @deffn {Scheme Procedure} $cos x
1336 Return the cosine of @var{x}.
1337 @end deffn
1338
1339 @c begin (texi-doc-string "guile" "$tan")
1340 @deffn {Scheme Procedure} $tan x
1341 Return the tangent of @var{x}.
1342 @end deffn
1343
1344 @c begin (texi-doc-string "guile" "$asin")
1345 @deffn {Scheme Procedure} $asin x
1346 Return the arcsine of @var{x}.
1347 @end deffn
1348
1349 @c begin (texi-doc-string "guile" "$acos")
1350 @deffn {Scheme Procedure} $acos x
1351 Return the arccosine of @var{x}.
1352 @end deffn
1353
1354 @c begin (texi-doc-string "guile" "$atan")
1355 @deffn {Scheme Procedure} $atan x
1356 Return the arctangent of @var{x} in the range @minus{}@math{PI/2} to
1357 @math{PI/2}.
1358 @end deffn
1359
1360 @deffn {Scheme Procedure} $atan2 x y
1361 @deffnx {C Function} scm_sys_atan2 (x, y)
1362 Return the arc tangent of the two arguments @var{x} and
1363 @var{y}. This is similar to calculating the arc tangent of
1364 @var{x} / @var{y}, except that the signs of both arguments
1365 are used to determine the quadrant of the result. This
1366 procedure does not accept complex arguments.
1367 @end deffn
1368
1369 @c begin (texi-doc-string "guile" "$exp")
1370 @deffn {Scheme Procedure} $exp x
1371 Return e to the power of @var{x}, where e is the base of natural
1372 logarithms (2.71828@dots{}).
1373 @end deffn
1374
1375 @c begin (texi-doc-string "guile" "$log")
1376 @deffn {Scheme Procedure} $log x
1377 Return the natural logarithm of @var{x}.
1378 @end deffn
1379
1380 @c begin (texi-doc-string "guile" "$sinh")
1381 @deffn {Scheme Procedure} $sinh x
1382 Return the hyperbolic sine of @var{x}.
1383 @end deffn
1384
1385 @c begin (texi-doc-string "guile" "$cosh")
1386 @deffn {Scheme Procedure} $cosh x
1387 Return the hyperbolic cosine of @var{x}.
1388 @end deffn
1389
1390 @c begin (texi-doc-string "guile" "$tanh")
1391 @deffn {Scheme Procedure} $tanh x
1392 Return the hyperbolic tangent of @var{x}.
1393 @end deffn
1394
1395 @c begin (texi-doc-string "guile" "$asinh")
1396 @deffn {Scheme Procedure} $asinh x
1397 Return the hyperbolic arcsine of @var{x}.
1398 @end deffn
1399
1400 @c begin (texi-doc-string "guile" "$acosh")
1401 @deffn {Scheme Procedure} $acosh x
1402 Return the hyperbolic arccosine of @var{x}.
1403 @end deffn
1404
1405 @c begin (texi-doc-string "guile" "$atanh")
1406 @deffn {Scheme Procedure} $atanh x
1407 Return the hyperbolic arctangent of @var{x}.
1408 @end deffn
1409
1410 C functions for the above are provided by the standard mathematics
1411 library. Naturally these expect and return @code{double} arguments
1412 (@pxref{Mathematics,,, libc, GNU C Library Reference Manual}).
1413
1414 @multitable {xx} {Scheme Procedure} {C Function}
1415 @item @tab Scheme Procedure @tab C Function
1416
1417 @item @tab @code{$abs} @tab @code{fabs}
1418 @item @tab @code{$sqrt} @tab @code{sqrt}
1419 @item @tab @code{$sin} @tab @code{sin}
1420 @item @tab @code{$cos} @tab @code{cos}
1421 @item @tab @code{$tan} @tab @code{tan}
1422 @item @tab @code{$asin} @tab @code{asin}
1423 @item @tab @code{$acos} @tab @code{acos}
1424 @item @tab @code{$atan} @tab @code{atan}
1425 @item @tab @code{$atan2} @tab @code{atan2}
1426 @item @tab @code{$exp} @tab @code{exp}
1427 @item @tab @code{$expt} @tab @code{pow}
1428 @item @tab @code{$log} @tab @code{log}
1429 @item @tab @code{$sinh} @tab @code{sinh}
1430 @item @tab @code{$cosh} @tab @code{cosh}
1431 @item @tab @code{$tanh} @tab @code{tanh}
1432 @item @tab @code{$asinh} @tab @code{asinh}
1433 @item @tab @code{$acosh} @tab @code{acosh}
1434 @item @tab @code{$atanh} @tab @code{atanh}
1435 @end multitable
1436
1437 @code{asinh}, @code{acosh} and @code{atanh} are C99 standard but might
1438 not be available on older systems. Guile provides the following
1439 equivalents (on all systems).
1440
1441 @deftypefn {C Function} double scm_asinh (double x)
1442 @deftypefnx {C Function} double scm_acosh (double x)
1443 @deftypefnx {C Function} double scm_atanh (double x)
1444 Return the hyperbolic arcsine, arccosine or arctangent of @var{x}
1445 respectively.
1446 @end deftypefn
1447
1448
1449 @node Bitwise Operations
1450 @subsubsection Bitwise Operations
1451
1452 For the following bitwise functions, negative numbers are treated as
1453 infinite precision twos-complements. For instance @math{-6} is bits
1454 @math{@dots{}111010}, with infinitely many ones on the left. It can
1455 be seen that adding 6 (binary 110) to such a bit pattern gives all
1456 zeros.
1457
1458 @deffn {Scheme Procedure} logand n1 n2 @dots{}
1459 @deffnx {C Function} scm_logand (n1, n2)
1460 Return the bitwise @sc{and} of the integer arguments.
1461
1462 @lisp
1463 (logand) @result{} -1
1464 (logand 7) @result{} 7
1465 (logand #b111 #b011 #b001) @result{} 1
1466 @end lisp
1467 @end deffn
1468
1469 @deffn {Scheme Procedure} logior n1 n2 @dots{}
1470 @deffnx {C Function} scm_logior (n1, n2)
1471 Return the bitwise @sc{or} of the integer arguments.
1472
1473 @lisp
1474 (logior) @result{} 0
1475 (logior 7) @result{} 7
1476 (logior #b000 #b001 #b011) @result{} 3
1477 @end lisp
1478 @end deffn
1479
1480 @deffn {Scheme Procedure} logxor n1 n2 @dots{}
1481 @deffnx {C Function} scm_loxor (n1, n2)
1482 Return the bitwise @sc{xor} of the integer arguments. A bit is
1483 set in the result if it is set in an odd number of arguments.
1484
1485 @lisp
1486 (logxor) @result{} 0
1487 (logxor 7) @result{} 7
1488 (logxor #b000 #b001 #b011) @result{} 2
1489 (logxor #b000 #b001 #b011 #b011) @result{} 1
1490 @end lisp
1491 @end deffn
1492
1493 @deffn {Scheme Procedure} lognot n
1494 @deffnx {C Function} scm_lognot (n)
1495 Return the integer which is the ones-complement of the integer
1496 argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
1497
1498 @lisp
1499 (number->string (lognot #b10000000) 2)
1500 @result{} "-10000001"
1501 (number->string (lognot #b0) 2)
1502 @result{} "-1"
1503 @end lisp
1504 @end deffn
1505
1506 @deffn {Scheme Procedure} logtest j k
1507 @deffnx {C Function} scm_logtest (j, k)
1508 Test whether @var{j} and @var{k} have any 1 bits in common. This is
1509 equivalent to @code{(not (zero? (logand j k)))}, but without actually
1510 calculating the @code{logand}, just testing for non-zero.
1511
1512 @lisp
1513 (logtest #b0100 #b1011) @result{} #f
1514 (logtest #b0100 #b0111) @result{} #t
1515 @end lisp
1516 @end deffn
1517
1518 @deffn {Scheme Procedure} logbit? index j
1519 @deffnx {C Function} scm_logbit_p (index, j)
1520 Test whether bit number @var{index} in @var{j} is set. @var{index}
1521 starts from 0 for the least significant bit.
1522
1523 @lisp
1524 (logbit? 0 #b1101) @result{} #t
1525 (logbit? 1 #b1101) @result{} #f
1526 (logbit? 2 #b1101) @result{} #t
1527 (logbit? 3 #b1101) @result{} #t
1528 (logbit? 4 #b1101) @result{} #f
1529 @end lisp
1530 @end deffn
1531
1532 @deffn {Scheme Procedure} ash n cnt
1533 @deffnx {C Function} scm_ash (n, cnt)
1534 Return @var{n} shifted left by @var{cnt} bits, or shifted right if
1535 @var{cnt} is negative. This is an ``arithmetic'' shift.
1536
1537 This is effectively a multiplication by @m{2^{cnt}, 2^@var{cnt}}, and
1538 when @var{cnt} is negative it's a division, rounded towards negative
1539 infinity. (Note that this is not the same rounding as @code{quotient}
1540 does.)
1541
1542 With @var{n} viewed as an infinite precision twos complement,
1543 @code{ash} means a left shift introducing zero bits, or a right shift
1544 dropping bits.
1545
1546 @lisp
1547 (number->string (ash #b1 3) 2) @result{} "1000"
1548 (number->string (ash #b1010 -1) 2) @result{} "101"
1549
1550 ;; -23 is bits ...11101001, -6 is bits ...111010
1551 (ash -23 -2) @result{} -6
1552 @end lisp
1553 @end deffn
1554
1555 @deffn {Scheme Procedure} logcount n
1556 @deffnx {C Function} scm_logcount (n)
1557 Return the number of bits in integer @var{n}. If @var{n} is
1558 positive, the 1-bits in its binary representation are counted.
1559 If negative, the 0-bits in its two's-complement binary
1560 representation are counted. If zero, 0 is returned.
1561
1562 @lisp
1563 (logcount #b10101010)
1564 @result{} 4
1565 (logcount 0)
1566 @result{} 0
1567 (logcount -2)
1568 @result{} 1
1569 @end lisp
1570 @end deffn
1571
1572 @deffn {Scheme Procedure} integer-length n
1573 @deffnx {C Function} scm_integer_length (n)
1574 Return the number of bits necessary to represent @var{n}.
1575
1576 For positive @var{n} this is how many bits to the most significant one
1577 bit. For negative @var{n} it's how many bits to the most significant
1578 zero bit in twos complement form.
1579
1580 @lisp
1581 (integer-length #b10101010) @result{} 8
1582 (integer-length #b1111) @result{} 4
1583 (integer-length 0) @result{} 0
1584 (integer-length -1) @result{} 0
1585 (integer-length -256) @result{} 8
1586 (integer-length -257) @result{} 9
1587 @end lisp
1588 @end deffn
1589
1590 @deffn {Scheme Procedure} integer-expt n k
1591 @deffnx {C Function} scm_integer_expt (n, k)
1592 Return @var{n} raised to the power @var{k}. @var{k} must be an exact
1593 integer, @var{n} can be any number.
1594
1595 Negative @var{k} is supported, and results in @m{1/n^|k|, 1/n^abs(k)}
1596 in the usual way. @math{@var{n}^0} is 1, as usual, and that includes
1597 @math{0^0} is 1.
1598
1599 @lisp
1600 (integer-expt 2 5) @result{} 32
1601 (integer-expt -3 3) @result{} -27
1602 (integer-expt 5 -3) @result{} 1/125
1603 (integer-expt 0 0) @result{} 1
1604 @end lisp
1605 @end deffn
1606
1607 @deffn {Scheme Procedure} bit-extract n start end
1608 @deffnx {C Function} scm_bit_extract (n, start, end)
1609 Return the integer composed of the @var{start} (inclusive)
1610 through @var{end} (exclusive) bits of @var{n}. The
1611 @var{start}th bit becomes the 0-th bit in the result.
1612
1613 @lisp
1614 (number->string (bit-extract #b1101101010 0 4) 2)
1615 @result{} "1010"
1616 (number->string (bit-extract #b1101101010 4 9) 2)
1617 @result{} "10110"
1618 @end lisp
1619 @end deffn
1620
1621
1622 @node Random
1623 @subsubsection Random Number Generation
1624
1625 Pseudo-random numbers are generated from a random state object, which
1626 can be created with @code{seed->random-state}. The @var{state}
1627 parameter to the various functions below is optional, it defaults to
1628 the state object in the @code{*random-state*} variable.
1629
1630 @deffn {Scheme Procedure} copy-random-state [state]
1631 @deffnx {C Function} scm_copy_random_state (state)
1632 Return a copy of the random state @var{state}.
1633 @end deffn
1634
1635 @deffn {Scheme Procedure} random n [state]
1636 @deffnx {C Function} scm_random (n, state)
1637 Return a number in [0, @var{n}).
1638
1639 Accepts a positive integer or real n and returns a
1640 number of the same type between zero (inclusive) and
1641 @var{n} (exclusive). The values returned have a uniform
1642 distribution.
1643 @end deffn
1644
1645 @deffn {Scheme Procedure} random:exp [state]
1646 @deffnx {C Function} scm_random_exp (state)
1647 Return an inexact real in an exponential distribution with mean
1648 1. For an exponential distribution with mean @var{u} use @code{(*
1649 @var{u} (random:exp))}.
1650 @end deffn
1651
1652 @deffn {Scheme Procedure} random:hollow-sphere! vect [state]
1653 @deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
1654 Fills @var{vect} with inexact real random numbers the sum of whose
1655 squares is equal to 1.0. Thinking of @var{vect} as coordinates in
1656 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1657 the coordinates are uniformly distributed over the surface of the unit
1658 n-sphere.
1659 @end deffn
1660
1661 @deffn {Scheme Procedure} random:normal [state]
1662 @deffnx {C Function} scm_random_normal (state)
1663 Return an inexact real in a normal distribution. The distribution
1664 used has mean 0 and standard deviation 1. For a normal distribution
1665 with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
1666 (* @var{d} (random:normal)))}.
1667 @end deffn
1668
1669 @deffn {Scheme Procedure} random:normal-vector! vect [state]
1670 @deffnx {C Function} scm_random_normal_vector_x (vect, state)
1671 Fills @var{vect} with inexact real random numbers that are
1672 independent and standard normally distributed
1673 (i.e., with mean 0 and variance 1).
1674 @end deffn
1675
1676 @deffn {Scheme Procedure} random:solid-sphere! vect [state]
1677 @deffnx {C Function} scm_random_solid_sphere_x (vect, state)
1678 Fills @var{vect} with inexact real random numbers the sum of whose
1679 squares is less than 1.0. Thinking of @var{vect} as coordinates in
1680 space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
1681 the coordinates are uniformly distributed within the unit
1682 @var{n}-sphere.
1683 @c FIXME: What does this mean, particularly the n-sphere part?
1684 @end deffn
1685
1686 @deffn {Scheme Procedure} random:uniform [state]
1687 @deffnx {C Function} scm_random_uniform (state)
1688 Return a uniformly distributed inexact real random number in
1689 [0,1).
1690 @end deffn
1691
1692 @deffn {Scheme Procedure} seed->random-state seed
1693 @deffnx {C Function} scm_seed_to_random_state (seed)
1694 Return a new random state using @var{seed}.
1695 @end deffn
1696
1697 @defvar *random-state*
1698 The global random state used by the above functions when the
1699 @var{state} parameter is not given.
1700 @end defvar
1701
1702
1703 @node Characters
1704 @subsection Characters
1705 @tpindex Characters
1706
1707 In Scheme, a character literal is written as @code{#\@var{name}} where
1708 @var{name} is the name of the character that you want. Printable
1709 characters have their usual single character name; for example,
1710 @code{#\a} is a lower case @code{a}.
1711
1712 Most of the ``control characters'' (those below codepoint 32) in the
1713 @acronym{ASCII} character set, as well as the space, may be referred
1714 to by longer names: for example, @code{#\tab}, @code{#\esc},
1715 @code{#\stx}, and so on. The following table describes the
1716 @acronym{ASCII} names for each character.
1717
1718 @multitable @columnfractions .25 .25 .25 .25
1719 @item 0 = @code{#\nul}
1720 @tab 1 = @code{#\soh}
1721 @tab 2 = @code{#\stx}
1722 @tab 3 = @code{#\etx}
1723 @item 4 = @code{#\eot}
1724 @tab 5 = @code{#\enq}
1725 @tab 6 = @code{#\ack}
1726 @tab 7 = @code{#\bel}
1727 @item 8 = @code{#\bs}
1728 @tab 9 = @code{#\ht}
1729 @tab 10 = @code{#\nl}
1730 @tab 11 = @code{#\vt}
1731 @item 12 = @code{#\np}
1732 @tab 13 = @code{#\cr}
1733 @tab 14 = @code{#\so}
1734 @tab 15 = @code{#\si}
1735 @item 16 = @code{#\dle}
1736 @tab 17 = @code{#\dc1}
1737 @tab 18 = @code{#\dc2}
1738 @tab 19 = @code{#\dc3}
1739 @item 20 = @code{#\dc4}
1740 @tab 21 = @code{#\nak}
1741 @tab 22 = @code{#\syn}
1742 @tab 23 = @code{#\etb}
1743 @item 24 = @code{#\can}
1744 @tab 25 = @code{#\em}
1745 @tab 26 = @code{#\sub}
1746 @tab 27 = @code{#\esc}
1747 @item 28 = @code{#\fs}
1748 @tab 29 = @code{#\gs}
1749 @tab 30 = @code{#\rs}
1750 @tab 31 = @code{#\us}
1751 @item 32 = @code{#\sp}
1752 @end multitable
1753
1754 The ``delete'' character (octal 177) may be referred to with the name
1755 @code{#\del}.
1756
1757 Several characters have more than one name:
1758
1759 @multitable {@code{#\backspace}} {Original}
1760 @item Alias @tab Original
1761 @item @code{#\space} @tab @code{#\sp}
1762 @item @code{#\newline} @tab @code{#\nl}
1763 @item @code{#\tab} @tab @code{#\ht}
1764 @item @code{#\backspace} @tab @code{#\bs}
1765 @item @code{#\return} @tab @code{#\cr}
1766 @item @code{#\page} @tab @code{#\np}
1767 @item @code{#\null} @tab @code{#\nul}
1768 @end multitable
1769
1770 @rnindex char?
1771 @deffn {Scheme Procedure} char? x
1772 @deffnx {C Function} scm_char_p (x)
1773 Return @code{#t} iff @var{x} is a character, else @code{#f}.
1774 @end deffn
1775
1776 @rnindex char=?
1777 @deffn {Scheme Procedure} char=? x y
1778 Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
1779 @end deffn
1780
1781 @rnindex char<?
1782 @deffn {Scheme Procedure} char<? x y
1783 Return @code{#t} iff @var{x} is less than @var{y} in the @acronym{ASCII} sequence,
1784 else @code{#f}.
1785 @end deffn
1786
1787 @rnindex char<=?
1788 @deffn {Scheme Procedure} char<=? x y
1789 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
1790 @acronym{ASCII} sequence, else @code{#f}.
1791 @end deffn
1792
1793 @rnindex char>?
1794 @deffn {Scheme Procedure} char>? x y
1795 Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII}
1796 sequence, else @code{#f}.
1797 @end deffn
1798
1799 @rnindex char>=?
1800 @deffn {Scheme Procedure} char>=? x y
1801 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
1802 @acronym{ASCII} sequence, else @code{#f}.
1803 @end deffn
1804
1805 @rnindex char-ci=?
1806 @deffn {Scheme Procedure} char-ci=? x y
1807 Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
1808 case, else @code{#f}.
1809 @end deffn
1810
1811 @rnindex char-ci<?
1812 @deffn {Scheme Procedure} char-ci<? x y
1813 Return @code{#t} iff @var{x} is less than @var{y} in the @acronym{ASCII} sequence
1814 ignoring case, else @code{#f}.
1815 @end deffn
1816
1817 @rnindex char-ci<=?
1818 @deffn {Scheme Procedure} char-ci<=? x y
1819 Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
1820 @acronym{ASCII} sequence ignoring case, else @code{#f}.
1821 @end deffn
1822
1823 @rnindex char-ci>?
1824 @deffn {Scheme Procedure} char-ci>? x y
1825 Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII}
1826 sequence ignoring case, else @code{#f}.
1827 @end deffn
1828
1829 @rnindex char-ci>=?
1830 @deffn {Scheme Procedure} char-ci>=? x y
1831 Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
1832 @acronym{ASCII} sequence ignoring case, else @code{#f}.
1833 @end deffn
1834
1835 @rnindex char-alphabetic?
1836 @deffn {Scheme Procedure} char-alphabetic? chr
1837 @deffnx {C Function} scm_char_alphabetic_p (chr)
1838 Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
1839 @end deffn
1840
1841 @rnindex char-numeric?
1842 @deffn {Scheme Procedure} char-numeric? chr
1843 @deffnx {C Function} scm_char_numeric_p (chr)
1844 Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
1845 @end deffn
1846
1847 @rnindex char-whitespace?
1848 @deffn {Scheme Procedure} char-whitespace? chr
1849 @deffnx {C Function} scm_char_whitespace_p (chr)
1850 Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
1851 @end deffn
1852
1853 @rnindex char-upper-case?
1854 @deffn {Scheme Procedure} char-upper-case? chr
1855 @deffnx {C Function} scm_char_upper_case_p (chr)
1856 Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
1857 @end deffn
1858
1859 @rnindex char-lower-case?
1860 @deffn {Scheme Procedure} char-lower-case? chr
1861 @deffnx {C Function} scm_char_lower_case_p (chr)
1862 Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
1863 @end deffn
1864
1865 @deffn {Scheme Procedure} char-is-both? chr
1866 @deffnx {C Function} scm_char_is_both_p (chr)
1867 Return @code{#t} iff @var{chr} is either uppercase or lowercase, else
1868 @code{#f}.
1869 @end deffn
1870
1871 @rnindex char->integer
1872 @deffn {Scheme Procedure} char->integer chr
1873 @deffnx {C Function} scm_char_to_integer (chr)
1874 Return the number corresponding to ordinal position of @var{chr} in the
1875 @acronym{ASCII} sequence.
1876 @end deffn
1877
1878 @rnindex integer->char
1879 @deffn {Scheme Procedure} integer->char n
1880 @deffnx {C Function} scm_integer_to_char (n)
1881 Return the character at position @var{n} in the @acronym{ASCII} sequence.
1882 @end deffn
1883
1884 @rnindex char-upcase
1885 @deffn {Scheme Procedure} char-upcase chr
1886 @deffnx {C Function} scm_char_upcase (chr)
1887 Return the uppercase character version of @var{chr}.
1888 @end deffn
1889
1890 @rnindex char-downcase
1891 @deffn {Scheme Procedure} char-downcase chr
1892 @deffnx {C Function} scm_char_downcase (chr)
1893 Return the lowercase character version of @var{chr}.
1894 @end deffn
1895
1896 @node Character Sets
1897 @subsection Character Sets
1898
1899 The features described in this section correspond directly to SRFI-14.
1900
1901 The data type @dfn{charset} implements sets of characters
1902 (@pxref{Characters}). Because the internal representation of
1903 character sets is not visible to the user, a lot of procedures for
1904 handling them are provided.
1905
1906 Character sets can be created, extended, tested for the membership of a
1907 characters and be compared to other character sets.
1908
1909 The Guile implementation of character sets currently deals only with
1910 8-bit characters. In the future, when Guile gets support for
1911 international character sets, this will change, but the functions
1912 provided here will always then be able to efficiently cope with very
1913 large character sets.
1914
1915 @menu
1916 * Character Set Predicates/Comparison::
1917 * Iterating Over Character Sets:: Enumerate charset elements.
1918 * Creating Character Sets:: Making new charsets.
1919 * Querying Character Sets:: Test charsets for membership etc.
1920 * Character-Set Algebra:: Calculating new charsets.
1921 * Standard Character Sets:: Variables containing predefined charsets.
1922 @end menu
1923
1924 @node Character Set Predicates/Comparison
1925 @subsubsection Character Set Predicates/Comparison
1926
1927 Use these procedures for testing whether an object is a character set,
1928 or whether several character sets are equal or subsets of each other.
1929 @code{char-set-hash} can be used for calculating a hash value, maybe for
1930 usage in fast lookup procedures.
1931
1932 @deffn {Scheme Procedure} char-set? obj
1933 @deffnx {C Function} scm_char_set_p (obj)
1934 Return @code{#t} if @var{obj} is a character set, @code{#f}
1935 otherwise.
1936 @end deffn
1937
1938 @deffn {Scheme Procedure} char-set= . char_sets
1939 @deffnx {C Function} scm_char_set_eq (char_sets)
1940 Return @code{#t} if all given character sets are equal.
1941 @end deffn
1942
1943 @deffn {Scheme Procedure} char-set<= . char_sets
1944 @deffnx {C Function} scm_char_set_leq (char_sets)
1945 Return @code{#t} if every character set @var{cs}i is a subset
1946 of character set @var{cs}i+1.
1947 @end deffn
1948
1949 @deffn {Scheme Procedure} char-set-hash cs [bound]
1950 @deffnx {C Function} scm_char_set_hash (cs, bound)
1951 Compute a hash value for the character set @var{cs}. If
1952 @var{bound} is given and non-zero, it restricts the
1953 returned value to the range 0 @dots{} @var{bound - 1}.
1954 @end deffn
1955
1956 @c ===================================================================
1957
1958 @node Iterating Over Character Sets
1959 @subsubsection Iterating Over Character Sets
1960
1961 Character set cursors are a means for iterating over the members of a
1962 character sets. After creating a character set cursor with
1963 @code{char-set-cursor}, a cursor can be dereferenced with
1964 @code{char-set-ref}, advanced to the next member with
1965 @code{char-set-cursor-next}. Whether a cursor has passed past the last
1966 element of the set can be checked with @code{end-of-char-set?}.
1967
1968 Additionally, mapping and (un-)folding procedures for character sets are
1969 provided.
1970
1971 @deffn {Scheme Procedure} char-set-cursor cs
1972 @deffnx {C Function} scm_char_set_cursor (cs)
1973 Return a cursor into the character set @var{cs}.
1974 @end deffn
1975
1976 @deffn {Scheme Procedure} char-set-ref cs cursor
1977 @deffnx {C Function} scm_char_set_ref (cs, cursor)
1978 Return the character at the current cursor position
1979 @var{cursor} in the character set @var{cs}. It is an error to
1980 pass a cursor for which @code{end-of-char-set?} returns true.
1981 @end deffn
1982
1983 @deffn {Scheme Procedure} char-set-cursor-next cs cursor
1984 @deffnx {C Function} scm_char_set_cursor_next (cs, cursor)
1985 Advance the character set cursor @var{cursor} to the next
1986 character in the character set @var{cs}. It is an error if the
1987 cursor given satisfies @code{end-of-char-set?}.
1988 @end deffn
1989
1990 @deffn {Scheme Procedure} end-of-char-set? cursor
1991 @deffnx {C Function} scm_end_of_char_set_p (cursor)
1992 Return @code{#t} if @var{cursor} has reached the end of a
1993 character set, @code{#f} otherwise.
1994 @end deffn
1995
1996 @deffn {Scheme Procedure} char-set-fold kons knil cs
1997 @deffnx {C Function} scm_char_set_fold (kons, knil, cs)
1998 Fold the procedure @var{kons} over the character set @var{cs},
1999 initializing it with @var{knil}.
2000 @end deffn
2001
2002 @deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
2003 @deffnx {C Function} scm_char_set_unfold (p, f, g, seed, base_cs)
2004 This is a fundamental constructor for character sets.
2005 @itemize @bullet
2006 @item @var{g} is used to generate a series of ``seed'' values
2007 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2008 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2009 @item @var{p} tells us when to stop -- when it returns true
2010 when applied to one of the seed values.
2011 @item @var{f} maps each seed value to a character. These
2012 characters are added to the base character set @var{base_cs} to
2013 form the result; @var{base_cs} defaults to the empty set.
2014 @end itemize
2015 @end deffn
2016
2017 @deffn {Scheme Procedure} char-set-unfold! p f g seed base_cs
2018 @deffnx {C Function} scm_char_set_unfold_x (p, f, g, seed, base_cs)
2019 This is a fundamental constructor for character sets.
2020 @itemize @bullet
2021 @item @var{g} is used to generate a series of ``seed'' values
2022 from the initial seed: @var{seed}, (@var{g} @var{seed}),
2023 (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
2024 @item @var{p} tells us when to stop -- when it returns true
2025 when applied to one of the seed values.
2026 @item @var{f} maps each seed value to a character. These
2027 characters are added to the base character set @var{base_cs} to
2028 form the result; @var{base_cs} defaults to the empty set.
2029 @end itemize
2030 @end deffn
2031
2032 @deffn {Scheme Procedure} char-set-for-each proc cs
2033 @deffnx {C Function} scm_char_set_for_each (proc, cs)
2034 Apply @var{proc} to every character in the character set
2035 @var{cs}. The return value is not specified.
2036 @end deffn
2037
2038 @deffn {Scheme Procedure} char-set-map proc cs
2039 @deffnx {C Function} scm_char_set_map (proc, cs)
2040 Map the procedure @var{proc} over every character in @var{cs}.
2041 @var{proc} must be a character -> character procedure.
2042 @end deffn
2043
2044 @c ===================================================================
2045
2046 @node Creating Character Sets
2047 @subsubsection Creating Character Sets
2048
2049 New character sets are produced with these procedures.
2050
2051 @deffn {Scheme Procedure} char-set-copy cs
2052 @deffnx {C Function} scm_char_set_copy (cs)
2053 Return a newly allocated character set containing all
2054 characters in @var{cs}.
2055 @end deffn
2056
2057 @deffn {Scheme Procedure} char-set . rest
2058 @deffnx {C Function} scm_char_set (rest)
2059 Return a character set containing all given characters.
2060 @end deffn
2061
2062 @deffn {Scheme Procedure} list->char-set list [base_cs]
2063 @deffnx {C Function} scm_list_to_char_set (list, base_cs)
2064 Convert the character list @var{list} to a character set. If
2065 the character set @var{base_cs} is given, the character in this
2066 set are also included in the result.
2067 @end deffn
2068
2069 @deffn {Scheme Procedure} list->char-set! list base_cs
2070 @deffnx {C Function} scm_list_to_char_set_x (list, base_cs)
2071 Convert the character list @var{list} to a character set. The
2072 characters are added to @var{base_cs} and @var{base_cs} is
2073 returned.
2074 @end deffn
2075
2076 @deffn {Scheme Procedure} string->char-set str [base_cs]
2077 @deffnx {C Function} scm_string_to_char_set (str, base_cs)
2078 Convert the string @var{str} to a character set. If the
2079 character set @var{base_cs} is given, the characters in this
2080 set are also included in the result.
2081 @end deffn
2082
2083 @deffn {Scheme Procedure} string->char-set! str base_cs
2084 @deffnx {C Function} scm_string_to_char_set_x (str, base_cs)
2085 Convert the string @var{str} to a character set. The
2086 characters from the string are added to @var{base_cs}, and
2087 @var{base_cs} is returned.
2088 @end deffn
2089
2090 @deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
2091 @deffnx {C Function} scm_char_set_filter (pred, cs, base_cs)
2092 Return a character set containing every character from @var{cs}
2093 so that it satisfies @var{pred}. If provided, the characters
2094 from @var{base_cs} are added to the result.
2095 @end deffn
2096
2097 @deffn {Scheme Procedure} char-set-filter! pred cs base_cs
2098 @deffnx {C Function} scm_char_set_filter_x (pred, cs, base_cs)
2099 Return a character set containing every character from @var{cs}
2100 so that it satisfies @var{pred}. The characters are added to
2101 @var{base_cs} and @var{base_cs} is returned.
2102 @end deffn
2103
2104 @deffn {Scheme Procedure} ucs-range->char-set lower upper [error [base_cs]]
2105 @deffnx {C Function} scm_ucs_range_to_char_set (lower, upper, error, base_cs)
2106 Return a character set containing all characters whose
2107 character codes lie in the half-open range
2108 [@var{lower},@var{upper}).
2109
2110 If @var{error} is a true value, an error is signalled if the
2111 specified range contains characters which are not contained in
2112 the implemented character range. If @var{error} is @code{#f},
2113 these characters are silently left out of the resultung
2114 character set.
2115
2116 The characters in @var{base_cs} are added to the result, if
2117 given.
2118 @end deffn
2119
2120 @deffn {Scheme Procedure} ucs-range->char-set! lower upper error base_cs
2121 @deffnx {C Function} scm_ucs_range_to_char_set_x (lower, upper, error, base_cs)
2122 Return a character set containing all characters whose
2123 character codes lie in the half-open range
2124 [@var{lower},@var{upper}).
2125
2126 If @var{error} is a true value, an error is signalled if the
2127 specified range contains characters which are not contained in
2128 the implemented character range. If @var{error} is @code{#f},
2129 these characters are silently left out of the resultung
2130 character set.
2131
2132 The characters are added to @var{base_cs} and @var{base_cs} is
2133 returned.
2134 @end deffn
2135
2136 @deffn {Scheme Procedure} ->char-set x
2137 @deffnx {C Function} scm_to_char_set (x)
2138 Coerces x into a char-set. @var{x} may be a string, character or char-set. A string is converted to the set of its constituent characters; a character is converted to a singleton set; a char-set is returned as-is.
2139 @end deffn
2140
2141 @c ===================================================================
2142
2143 @node Querying Character Sets
2144 @subsubsection Querying Character Sets
2145
2146 Access the elements and other information of a character set with these
2147 procedures.
2148
2149 @deffn {Scheme Procedure} char-set-size cs
2150 @deffnx {C Function} scm_char_set_size (cs)
2151 Return the number of elements in character set @var{cs}.
2152 @end deffn
2153
2154 @deffn {Scheme Procedure} char-set-count pred cs
2155 @deffnx {C Function} scm_char_set_count (pred, cs)
2156 Return the number of the elements int the character set
2157 @var{cs} which satisfy the predicate @var{pred}.
2158 @end deffn
2159
2160 @deffn {Scheme Procedure} char-set->list cs
2161 @deffnx {C Function} scm_char_set_to_list (cs)
2162 Return a list containing the elements of the character set
2163 @var{cs}.
2164 @end deffn
2165
2166 @deffn {Scheme Procedure} char-set->string cs
2167 @deffnx {C Function} scm_char_set_to_string (cs)
2168 Return a string containing the elements of the character set
2169 @var{cs}. The order in which the characters are placed in the
2170 string is not defined.
2171 @end deffn
2172
2173 @deffn {Scheme Procedure} char-set-contains? cs ch
2174 @deffnx {C Function} scm_char_set_contains_p (cs, ch)
2175 Return @code{#t} iff the character @var{ch} is contained in the
2176 character set @var{cs}.
2177 @end deffn
2178
2179 @deffn {Scheme Procedure} char-set-every pred cs
2180 @deffnx {C Function} scm_char_set_every (pred, cs)
2181 Return a true value if every character in the character set
2182 @var{cs} satisfies the predicate @var{pred}.
2183 @end deffn
2184
2185 @deffn {Scheme Procedure} char-set-any pred cs
2186 @deffnx {C Function} scm_char_set_any (pred, cs)
2187 Return a true value if any character in the character set
2188 @var{cs} satisfies the predicate @var{pred}.
2189 @end deffn
2190
2191 @c ===================================================================
2192
2193 @node Character-Set Algebra
2194 @subsubsection Character-Set Algebra
2195
2196 Character sets can be manipulated with the common set algebra operation,
2197 such as union, complement, intersection etc. All of these procedures
2198 provide side-effecting variants, which modify their character set
2199 argument(s).
2200
2201 @deffn {Scheme Procedure} char-set-adjoin cs . rest
2202 @deffnx {C Function} scm_char_set_adjoin (cs, rest)
2203 Add all character arguments to the first argument, which must
2204 be a character set.
2205 @end deffn
2206
2207 @deffn {Scheme Procedure} char-set-delete cs . rest
2208 @deffnx {C Function} scm_char_set_delete (cs, rest)
2209 Delete all character arguments from the first argument, which
2210 must be a character set.
2211 @end deffn
2212
2213 @deffn {Scheme Procedure} char-set-adjoin! cs . rest
2214 @deffnx {C Function} scm_char_set_adjoin_x (cs, rest)
2215 Add all character arguments to the first argument, which must
2216 be a character set.
2217 @end deffn
2218
2219 @deffn {Scheme Procedure} char-set-delete! cs . rest
2220 @deffnx {C Function} scm_char_set_delete_x (cs, rest)
2221 Delete all character arguments from the first argument, which
2222 must be a character set.
2223 @end deffn
2224
2225 @deffn {Scheme Procedure} char-set-complement cs
2226 @deffnx {C Function} scm_char_set_complement (cs)
2227 Return the complement of the character set @var{cs}.
2228 @end deffn
2229
2230 @deffn {Scheme Procedure} char-set-union . rest
2231 @deffnx {C Function} scm_char_set_union (rest)
2232 Return the union of all argument character sets.
2233 @end deffn
2234
2235 @deffn {Scheme Procedure} char-set-intersection . rest
2236 @deffnx {C Function} scm_char_set_intersection (rest)
2237 Return the intersection of all argument character sets.
2238 @end deffn
2239
2240 @deffn {Scheme Procedure} char-set-difference cs1 . rest
2241 @deffnx {C Function} scm_char_set_difference (cs1, rest)
2242 Return the difference of all argument character sets.
2243 @end deffn
2244
2245 @deffn {Scheme Procedure} char-set-xor . rest
2246 @deffnx {C Function} scm_char_set_xor (rest)
2247 Return the exclusive-or of all argument character sets.
2248 @end deffn
2249
2250 @deffn {Scheme Procedure} char-set-diff+intersection cs1 . rest
2251 @deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, rest)
2252 Return the difference and the intersection of all argument
2253 character sets.
2254 @end deffn
2255
2256 @deffn {Scheme Procedure} char-set-complement! cs
2257 @deffnx {C Function} scm_char_set_complement_x (cs)
2258 Return the complement of the character set @var{cs}.
2259 @end deffn
2260
2261 @deffn {Scheme Procedure} char-set-union! cs1 . rest
2262 @deffnx {C Function} scm_char_set_union_x (cs1, rest)
2263 Return the union of all argument character sets.
2264 @end deffn
2265
2266 @deffn {Scheme Procedure} char-set-intersection! cs1 . rest
2267 @deffnx {C Function} scm_char_set_intersection_x (cs1, rest)
2268 Return the intersection of all argument character sets.
2269 @end deffn
2270
2271 @deffn {Scheme Procedure} char-set-difference! cs1 . rest
2272 @deffnx {C Function} scm_char_set_difference_x (cs1, rest)
2273 Return the difference of all argument character sets.
2274 @end deffn
2275
2276 @deffn {Scheme Procedure} char-set-xor! cs1 . rest
2277 @deffnx {C Function} scm_char_set_xor_x (cs1, rest)
2278 Return the exclusive-or of all argument character sets.
2279 @end deffn
2280
2281 @deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 . rest
2282 @deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, rest)
2283 Return the difference and the intersection of all argument
2284 character sets.
2285 @end deffn
2286
2287 @c ===================================================================
2288
2289 @node Standard Character Sets
2290 @subsubsection Standard Character Sets
2291
2292 In order to make the use of the character set data type and procedures
2293 useful, several predefined character set variables exist.
2294
2295 @defvr {Scheme Variable} char-set:lower-case
2296 @defvrx {C Variable} scm_char_set_lower_case
2297 All lower-case characters.
2298 @end defvr
2299
2300 @defvr {Scheme Variable} char-set:upper-case
2301 @defvrx {C Variable} scm_char_set_upper_case
2302 All upper-case characters.
2303 @end defvr
2304
2305 @defvr {Scheme Variable} char-set:title-case
2306 @defvrx {C Variable} scm_char_set_title_case
2307 This is empty, because ASCII has no titlecase characters.
2308 @end defvr
2309
2310 @defvr {Scheme Variable} char-set:letter
2311 @defvrx {C Variable} scm_char_set_letter
2312 All letters, e.g. the union of @code{char-set:lower-case} and
2313 @code{char-set:upper-case}.
2314 @end defvr
2315
2316 @defvr {Scheme Variable} char-set:digit
2317 @defvrx {C Variable} scm_char_set_digit
2318 All digits.
2319 @end defvr
2320
2321 @defvr {Scheme Variable} char-set:letter+digit
2322 @defvrx {C Variable} scm_char_set_letter_and_digit
2323 The union of @code{char-set:letter} and @code{char-set:digit}.
2324 @end defvr
2325
2326 @defvr {Scheme Variable} char-set:graphic
2327 @defvrx {C Variable} scm_char_set_graphic
2328 All characters which would put ink on the paper.
2329 @end defvr
2330
2331 @defvr {Scheme Variable} char-set:printing
2332 @defvrx {C Variable} scm_char_set_printing
2333 The union of @code{char-set:graphic} and @code{char-set:whitespace}.
2334 @end defvr
2335
2336 @defvr {Scheme Variable} char-set:whitespace
2337 @defvrx {C Variable} scm_char_set_whitespace
2338 All whitespace characters.
2339 @end defvr
2340
2341 @defvr {Scheme Variable} char-set:blank
2342 @defvrx {C Variable} scm_char_set_blank
2343 All horizontal whitespace characters, that is @code{#\space} and
2344 @code{#\tab}.
2345 @end defvr
2346
2347 @defvr {Scheme Variable} char-set:iso-control
2348 @defvrx {C Variable} scm_char_set_iso_control
2349 The ISO control characters with the codes 0--31 and 127.
2350 @end defvr
2351
2352 @defvr {Scheme Variable} char-set:punctuation
2353 @defvrx {C Variable} scm_char_set_punctuation
2354 The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
2355 @end defvr
2356
2357 @defvr {Scheme Variable} char-set:symbol
2358 @defvrx {C Variable} scm_char_set_symbol
2359 The characters @code{$+<=>^`|~}.
2360 @end defvr
2361
2362 @defvr {Scheme Variable} char-set:hex-digit
2363 @defvrx {C Variable} scm_char_set_hex_digit
2364 The hexadecimal digits @code{0123456789abcdefABCDEF}.
2365 @end defvr
2366
2367 @defvr {Scheme Variable} char-set:ascii
2368 @defvrx {C Variable} scm_char_set_ascii
2369 All ASCII characters.
2370 @end defvr
2371
2372 @defvr {Scheme Variable} char-set:empty
2373 @defvrx {C Variable} scm_char_set_empty
2374 The empty character set.
2375 @end defvr
2376
2377 @defvr {Scheme Variable} char-set:full
2378 @defvrx {C Variable} scm_char_set_full
2379 This character set contains all possible characters.
2380 @end defvr
2381
2382 @node Strings
2383 @subsection Strings
2384 @tpindex Strings
2385
2386 Strings are fixed-length sequences of characters. They can be created
2387 by calling constructor procedures, but they can also literally get
2388 entered at the @acronym{REPL} or in Scheme source files.
2389
2390 @c Guile provides a rich set of string processing procedures, because text
2391 @c handling is very important when Guile is used as a scripting language.
2392
2393 Strings always carry the information about how many characters they are
2394 composed of with them, so there is no special end-of-string character,
2395 like in C. That means that Scheme strings can contain any character,
2396 even the @samp{#\nul} character @samp{\0}.
2397
2398 To use strings efficiently, you need to know a bit about how Guile
2399 implements them. In Guile, a string consists of two parts, a head and
2400 the actual memory where the characters are stored. When a string (or
2401 a substring of it) is copied, only a new head gets created, the memory
2402 is usually not copied. The two heads start out pointing to the same
2403 memory.
2404
2405 When one of these two strings is modified, as with @code{string-set!},
2406 their common memory does get copied so that each string has its own
2407 memory and modifying one does not accidently modify the other as well.
2408 Thus, Guile's strings are `copy on write'; the actual copying of their
2409 memory is delayed until one string is written to.
2410
2411 This implementation makes functions like @code{substring} very
2412 efficient in the common case that no modifications are done to the
2413 involved strings.
2414
2415 If you do know that your strings are getting modified right away, you
2416 can use @code{substring/copy} instead of @code{substring}. This
2417 function performs the copy immediately at the time of creation. This
2418 is more efficient, especially in a multi-threaded program. Also,
2419 @code{substring/copy} can avoid the problem that a short substring
2420 holds on to the memory of a very large original string that could
2421 otherwise be recycled.
2422
2423 If you want to avoid the copy altogether, so that modifications of one
2424 string show up in the other, you can use @code{substring/shared}. The
2425 strings created by this procedure are called @dfn{mutation sharing
2426 substrings} since the substring and the original string share
2427 modifications to each other.
2428
2429 If you want to prevent modifications, use @code{substring/read-only}.
2430
2431 Guile provides all procedures of SRFI-13 and a few more.
2432
2433 @menu
2434 * String Syntax:: Read syntax for strings.
2435 * String Predicates:: Testing strings for certain properties.
2436 * String Constructors:: Creating new string objects.
2437 * List/String Conversion:: Converting from/to lists of characters.
2438 * String Selection:: Select portions from strings.
2439 * String Modification:: Modify parts or whole strings.
2440 * String Comparison:: Lexicographic ordering predicates.
2441 * String Searching:: Searching in strings.
2442 * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
2443 * Reversing and Appending Strings:: Appending strings to form a new string.
2444 * Mapping Folding and Unfolding:: Iterating over strings.
2445 * Miscellaneous String Operations:: Replicating, insertion, parsing, ...
2446 * Conversion to/from C::
2447 @end menu
2448
2449 @node String Syntax
2450 @subsubsection String Read Syntax
2451
2452 @c In the following @code is used to get a good font in TeX etc, but
2453 @c is omitted for Info format, so as not to risk any confusion over
2454 @c whether surrounding ` ' quotes are part of the escape or are
2455 @c special in a string (they're not).
2456
2457 The read syntax for strings is an arbitrarily long sequence of
2458 characters enclosed in double quotes (@nicode{"}).
2459
2460 Backslash is an escape character and can be used to insert the
2461 following special characters. @nicode{\"} and @nicode{\\} are R5RS
2462 standard, the rest are Guile extensions, notice they follow C string
2463 syntax.
2464
2465 @table @asis
2466 @item @nicode{\\}
2467 Backslash character.
2468
2469 @item @nicode{\"}
2470 Double quote character (an unescaped @nicode{"} is otherwise the end
2471 of the string).
2472
2473 @item @nicode{\0}
2474 NUL character (ASCII 0).
2475
2476 @item @nicode{\a}
2477 Bell character (ASCII 7).
2478
2479 @item @nicode{\f}
2480 Formfeed character (ASCII 12).
2481
2482 @item @nicode{\n}
2483 Newline character (ASCII 10).
2484
2485 @item @nicode{\r}
2486 Carriage return character (ASCII 13).
2487
2488 @item @nicode{\t}
2489 Tab character (ASCII 9).
2490
2491 @item @nicode{\v}
2492 Vertical tab character (ASCII 11).
2493
2494 @item @nicode{\xHH}
2495 Character code given by two hexadecimal digits. For example
2496 @nicode{\x7f} for an ASCII DEL (127).
2497 @end table
2498
2499 @noindent
2500 The following are examples of string literals:
2501
2502 @lisp
2503 "foo"
2504 "bar plonk"
2505 "Hello World"
2506 "\"Hi\", he said."
2507 @end lisp
2508
2509
2510 @node String Predicates
2511 @subsubsection String Predicates
2512
2513 The following procedures can be used to check whether a given string
2514 fulfills some specified property.
2515
2516 @rnindex string?
2517 @deffn {Scheme Procedure} string? obj
2518 @deffnx {C Function} scm_string_p (obj)
2519 Return @code{#t} if @var{obj} is a string, else @code{#f}.
2520 @end deffn
2521
2522 @deftypefn {C Function} int scm_is_string (SCM obj)
2523 Returns @code{1} if @var{obj} is a string, @code{0} otherwise.
2524 @end deftypefn
2525
2526 @deffn {Scheme Procedure} string-null? str
2527 @deffnx {C Function} scm_string_null_p (str)
2528 Return @code{#t} if @var{str}'s length is zero, and
2529 @code{#f} otherwise.
2530 @lisp
2531 (string-null? "") @result{} #t
2532 y @result{} "foo"
2533 (string-null? y) @result{} #f
2534 @end lisp
2535 @end deffn
2536
2537 @deffn {Scheme Procedure} string-any char_pred s [start [end]]
2538 @deffnx {C Function} scm_string_any (char_pred, s, start, end)
2539 Check if @var{char_pred} is true for any character in string @var{s}.
2540
2541 @var{char_pred} can be a character to check for any equal to that, or
2542 a character set (@pxref{Character Sets}) to check for any in that set,
2543 or a predicate procedure to call.
2544
2545 For a procedure, calls @code{(@var{char_pred} c)} are made
2546 successively on the characters from @var{start} to @var{end}. If
2547 @var{char_pred} returns true (ie.@: non-@code{#f}), @code{string-any}
2548 stops and that return value is the return from @code{string-any}. The
2549 call on the last character (ie.@: at @math{@var{end}-1}), if that
2550 point is reached, is a tail call.
2551
2552 If there are no characters in @var{s} (ie.@: @var{start} equals
2553 @var{end}) then the return is @code{#f}.
2554 @end deffn
2555
2556 @deffn {Scheme Procedure} string-every char_pred s [start [end]]
2557 @deffnx {C Function} scm_string_every (char_pred, s, start, end)
2558 Check if @var{char_pred} is true for every character in string
2559 @var{s}.
2560
2561 @var{char_pred} can be a character to check for every character equal
2562 to that, or a character set (@pxref{Character Sets}) to check for
2563 every character being in that set, or a predicate procedure to call.
2564
2565 For a procedure, calls @code{(@var{char_pred} c)} are made
2566 successively on the characters from @var{start} to @var{end}. If
2567 @var{char_pred} returns @code{#f}, @code{string-every} stops and
2568 returns @code{#f}. The call on the last character (ie.@: at
2569 @math{@var{end}-1}), if that point is reached, is a tail call and the
2570 return from that call is the return from @code{string-every}.
2571
2572 If there are no characters in @var{s} (ie.@: @var{start} equals
2573 @var{end}) then the return is @code{#t}.
2574 @end deffn
2575
2576 @node String Constructors
2577 @subsubsection String Constructors
2578
2579 The string constructor procedures create new string objects, possibly
2580 initializing them with some specified character data. See also
2581 @xref{String Selection}, for ways to create strings from existing
2582 strings.
2583
2584 @c FIXME::martin: list->string belongs into `List/String Conversion'
2585
2586 @deffn {Scheme Procedure} string char@dots{}
2587 @rnindex string
2588 Return a newly allocated string made from the given character
2589 arguments.
2590
2591 @example
2592 (string #\x #\y #\z) @result{} "xyz"
2593 (string) @result{} ""
2594 @end example
2595 @end deffn
2596
2597 @deffn {Scheme Procedure} list->string lst
2598 @deffnx {C Function} scm_string (lst)
2599 @rnindex list->string
2600 Return a newly allocated string made from a list of characters.
2601
2602 @example
2603 (list->string '(#\a #\b #\c)) @result{} "abc"
2604 @end example
2605 @end deffn
2606
2607 @deffn {Scheme Procedure} reverse-list->string lst
2608 @deffnx {C Function} scm_reverse_list_to_string (lst)
2609 Return a newly allocated string made from a list of characters, in
2610 reverse order.
2611
2612 @example
2613 (reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
2614 @end example
2615 @end deffn
2616
2617 @rnindex make-string
2618 @deffn {Scheme Procedure} make-string k [chr]
2619 @deffnx {C Function} scm_make_string (k, chr)
2620 Return a newly allocated string of
2621 length @var{k}. If @var{chr} is given, then all elements of
2622 the string are initialized to @var{chr}, otherwise the contents
2623 of the @var{string} are unspecified.
2624 @end deffn
2625
2626 @deftypefn {C Function} SCM scm_c_make_string (size_t len, SCM chr)
2627 Like @code{scm_make_string}, but expects the length as a
2628 @code{size_t}.
2629 @end deftypefn
2630
2631 @deffn {Scheme Procedure} string-tabulate proc len
2632 @deffnx {C Function} scm_string_tabulate (proc, len)
2633 @var{proc} is an integer->char procedure. Construct a string
2634 of size @var{len} by applying @var{proc} to each index to
2635 produce the corresponding string element. The order in which
2636 @var{proc} is applied to the indices is not specified.
2637 @end deffn
2638
2639 @deffn {Scheme Procedure} string-join ls [delimiter [grammar]]
2640 @deffnx {C Function} scm_string_join (ls, delimiter, grammar)
2641 Append the string in the string list @var{ls}, using the string
2642 @var{delim} as a delimiter between the elements of @var{ls}.
2643 @var{grammar} is a symbol which specifies how the delimiter is
2644 placed between the strings, and defaults to the symbol
2645 @code{infix}.
2646
2647 @table @code
2648 @item infix
2649 Insert the separator between list elements. An empty string
2650 will produce an empty list.
2651 @item string-infix
2652 Like @code{infix}, but will raise an error if given the empty
2653 list.
2654 @item suffix
2655 Insert the separator after every list element.
2656 @item prefix
2657 Insert the separator before each list element.
2658 @end table
2659 @end deffn
2660
2661 @node List/String Conversion
2662 @subsubsection List/String conversion
2663
2664 When processing strings, it is often convenient to first convert them
2665 into a list representation by using the procedure @code{string->list},
2666 work with the resulting list, and then convert it back into a string.
2667 These procedures are useful for similar tasks.
2668
2669 @rnindex string->list
2670 @deffn {Scheme Procedure} string->list str [start [end]]
2671 @deffnx {C Function} scm_substring_to_list (str, start, end)
2672 @deffnx {C Function} scm_string_to_list (str)
2673 Convert the string @var{str} into a list of characters.
2674 @end deffn
2675
2676 @deffn {Scheme Procedure} string-split str chr
2677 @deffnx {C Function} scm_string_split (str, chr)
2678 Split the string @var{str} into the a list of the substrings delimited
2679 by appearances of the character @var{chr}. Note that an empty substring
2680 between separator characters will result in an empty string in the
2681 result list.
2682
2683 @lisp
2684 (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
2685 @result{}
2686 ("root" "x" "0" "0" "root" "/root" "/bin/bash")
2687
2688 (string-split "::" #\:)
2689 @result{}
2690 ("" "" "")
2691
2692 (string-split "" #\:)
2693 @result{}
2694 ("")
2695 @end lisp
2696 @end deffn
2697
2698
2699 @node String Selection
2700 @subsubsection String Selection
2701
2702 Portions of strings can be extracted by these procedures.
2703 @code{string-ref} delivers individual characters whereas
2704 @code{substring} can be used to extract substrings from longer strings.
2705
2706 @rnindex string-length
2707 @deffn {Scheme Procedure} string-length string
2708 @deffnx {C Function} scm_string_length (string)
2709 Return the number of characters in @var{string}.
2710 @end deffn
2711
2712 @deftypefn {C Function} size_t scm_c_string_length (SCM str)
2713 Return the number of characters in @var{str} as a @code{size_t}.
2714 @end deftypefn
2715
2716 @rnindex string-ref
2717 @deffn {Scheme Procedure} string-ref str k
2718 @deffnx {C Function} scm_string_ref (str, k)
2719 Return character @var{k} of @var{str} using zero-origin
2720 indexing. @var{k} must be a valid index of @var{str}.
2721 @end deffn
2722
2723 @deftypefn {C Function} SCM scm_c_string_ref (SCM str, size_t k)
2724 Return character @var{k} of @var{str} using zero-origin
2725 indexing. @var{k} must be a valid index of @var{str}.
2726 @end deftypefn
2727
2728 @rnindex string-copy
2729 @deffn {Scheme Procedure} string-copy str [start [end]]
2730 @deffnx {C Function} scm_substring_copy (str, start, end)
2731 @deffnx {C Function} scm_string_copy (str)
2732 Return a copy of the given string @var{str}.
2733
2734 The returned string shares storage with @var{str} initially, but it is
2735 copied as soon as one of the two strings is modified.
2736 @end deffn
2737
2738 @rnindex substring
2739 @deffn {Scheme Procedure} substring str start [end]
2740 @deffnx {C Function} scm_substring (str, start, end)
2741 Return a new string formed from the characters
2742 of @var{str} beginning with index @var{start} (inclusive) and
2743 ending with index @var{end} (exclusive).
2744 @var{str} must be a string, @var{start} and @var{end} must be
2745 exact integers satisfying:
2746
2747 0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
2748
2749 The returned string shares storage with @var{str} initially, but it is
2750 copied as soon as one of the two strings is modified.
2751 @end deffn
2752
2753 @deffn {Scheme Procedure} substring/shared str start [end]
2754 @deffnx {C Function} scm_substring_shared (str, start, end)
2755 Like @code{substring}, but the strings continue to share their storage
2756 even if they are modified. Thus, modifications to @var{str} show up
2757 in the new string, and vice versa.
2758 @end deffn
2759
2760 @deffn {Scheme Procedure} substring/copy str start [end]
2761 @deffnx {C Function} scm_substring_copy (str, start, end)
2762 Like @code{substring}, but the storage for the new string is copied
2763 immediately.
2764 @end deffn
2765
2766 @deffn {Scheme Procedure} substring/read-only str start [end]
2767 @deffnx {C Function} scm_substring_read_only (str, start, end)
2768 Like @code{substring}, but the resulting string can not be modified.
2769 @end deffn
2770
2771 @deftypefn {C Function} SCM scm_c_substring (SCM str, size_t start, size_t end)
2772 @deftypefnx {C Function} SCM scm_c_substring_shared (SCM str, size_t start, size_t end)
2773 @deftypefnx {C Function} SCM scm_c_substring_copy (SCM str, size_t start, size_t end)
2774 @deftypefnx {C Function} SCM scm_c_substring_read_only (SCM str, size_t start, size_t end)
2775 Like @code{scm_substring}, etc. but the bounds are given as a @code{size_t}.
2776 @end deftypefn
2777
2778 @deffn {Scheme Procedure} string-take s n
2779 @deffnx {C Function} scm_string_take (s, n)
2780 Return the @var{n} first characters of @var{s}.
2781 @end deffn
2782
2783 @deffn {Scheme Procedure} string-drop s n
2784 @deffnx {C Function} scm_string_drop (s, n)
2785 Return all but the first @var{n} characters of @var{s}.
2786 @end deffn
2787
2788 @deffn {Scheme Procedure} string-take-right s n
2789 @deffnx {C Function} scm_string_take_right (s, n)
2790 Return the @var{n} last characters of @var{s}.
2791 @end deffn
2792
2793 @deffn {Scheme Procedure} string-drop-right s n
2794 @deffnx {C Function} scm_string_drop_right (s, n)
2795 Return all but the last @var{n} characters of @var{s}.
2796 @end deffn
2797
2798 @deffn {Scheme Procedure} string-pad s len [chr [start [end]]]
2799 @deffnx {Scheme Procedure} string-pad-right s len [chr [start [end]]]
2800 @deffnx {C Function} scm_string_pad (s, len, chr, start, end)
2801 @deffnx {C Function} scm_string_pad_right (s, len, chr, start, end)
2802 Take characters @var{start} to @var{end} from the string @var{s} and
2803 either pad with @var{char} or truncate them to give @var{len}
2804 characters.
2805
2806 @code{string-pad} pads or truncates on the left, so for example
2807
2808 @example
2809 (string-pad "x" 3) @result{} " x"
2810 (string-pad "abcde" 3) @result{} "cde"
2811 @end example
2812
2813 @code{string-pad-right} pads or truncates on the right, so for example
2814
2815 @example
2816 (string-pad-right "x" 3) @result{} "x "
2817 (string-pad-right "abcde" 3) @result{} "abc"
2818 @end example
2819 @end deffn
2820
2821 @deffn {Scheme Procedure} string-trim s [char_pred [start [end]]]
2822 @deffnx {Scheme Procedure} string-trim-right s [char_pred [start [end]]]
2823 @deffnx {Scheme Procedure} string-trim-both s [char_pred [start [end]]]
2824 @deffnx {C Function} scm_string_trim (s, char_pred, start, end)
2825 @deffnx {C Function} scm_string_trim_right (s, char_pred, start, end)
2826 @deffnx {C Function} scm_string_trim_both (s, char_pred, start, end)
2827 Trim occurrances of @var{char_pred} from the ends of @var{s}.
2828
2829 @code{string-trim} trims @var{char_pred} characters from the left
2830 (start) of the string, @code{string-trim-right} trims them from the
2831 right (end) of the string, @code{string-trim-both} trims from both
2832 ends.
2833
2834 @var{char_pred} can be a character, a character set, or a predicate
2835 procedure to call on each character. If @var{char_pred} is not given
2836 the default is whitespace as per @code{char-set:whitespace}
2837 (@pxref{Standard Character Sets}).
2838
2839 @example
2840 (string-trim " x ") @result{} "x "
2841 (string-trim-right "banana" #\a) @result{} "banan"
2842 (string-trim-both ".,xy:;" char-set:punctuation)
2843 @result{} "xy"
2844 (string-trim-both "xyzzy" (lambda (c)
2845 (or (eqv? c #\x)
2846 (eqv? c #\y))))
2847 @result{} "zz"
2848 @end example
2849 @end deffn
2850
2851 @node String Modification
2852 @subsubsection String Modification
2853
2854 These procedures are for modifying strings in-place. This means that the
2855 result of the operation is not a new string; instead, the original string's
2856 memory representation is modified.
2857
2858 @rnindex string-set!
2859 @deffn {Scheme Procedure} string-set! str k chr
2860 @deffnx {C Function} scm_string_set_x (str, k, chr)
2861 Store @var{chr} in element @var{k} of @var{str} and return
2862 an unspecified value. @var{k} must be a valid index of
2863 @var{str}.
2864 @end deffn
2865
2866 @deftypefn {C Function} void scm_c_string_set_x (SCM str, size_t k, SCM chr)
2867 Like @code{scm_string_set_x}, but the index is given as a @code{size_t}.
2868 @end deftypefn
2869
2870 @rnindex string-fill!
2871 @deffn {Scheme Procedure} string-fill! str chr [start [end]]
2872 @deffnx {C Function} scm_substring_fill_x (str, chr, start, end)
2873 @deffnx {C Function} scm_string_fill_x (str, chr)
2874 Stores @var{chr} in every element of the given @var{str} and
2875 returns an unspecified value.
2876 @end deffn
2877
2878 @deffn {Scheme Procedure} substring-fill! str start end fill
2879 @deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
2880 Change every character in @var{str} between @var{start} and
2881 @var{end} to @var{fill}.
2882
2883 @lisp
2884 (define y "abcdefg")
2885 (substring-fill! y 1 3 #\r)
2886 y
2887 @result{} "arrdefg"
2888 @end lisp
2889 @end deffn
2890
2891 @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
2892 @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
2893 Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
2894 into @var{str2} beginning at position @var{start2}.
2895 @var{str1} and @var{str2} can be the same string.
2896 @end deffn
2897
2898 @deffn {Scheme Procedure} string-copy! target tstart s [start [end]]
2899 @deffnx {C Function} scm_string_copy_x (target, tstart, s, start, end)
2900 Copy the sequence of characters from index range [@var{start},
2901 @var{end}) in string @var{s} to string @var{target}, beginning
2902 at index @var{tstart}. The characters are copied left-to-right
2903 or right-to-left as needed -- the copy is guaranteed to work,
2904 even if @var{target} and @var{s} are the same string. It is an
2905 error if the copy operation runs off the end of the target
2906 string.
2907 @end deffn
2908
2909
2910 @node String Comparison
2911 @subsubsection String Comparison
2912
2913 The procedures in this section are similar to the character ordering
2914 predicates (@pxref{Characters}), but are defined on character sequences.
2915
2916 The first set is specified in R5RS and has names that end in @code{?}.
2917 The second set is specified in SRFI-13 and the names have no ending
2918 @code{?}. The predicates ending in @code{-ci} ignore the character case
2919 when comparing strings.
2920
2921 @rnindex string=?
2922 @deffn {Scheme Procedure} string=? s1 s2
2923 Lexicographic equality predicate; return @code{#t} if the two
2924 strings are the same length and contain the same characters in
2925 the same positions, otherwise return @code{#f}.
2926
2927 The procedure @code{string-ci=?} treats upper and lower case
2928 letters as though they were the same character, but
2929 @code{string=?} treats upper and lower case as distinct
2930 characters.
2931 @end deffn
2932
2933 @rnindex string<?
2934 @deffn {Scheme Procedure} string<? s1 s2
2935 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2936 is lexicographically less than @var{s2}.
2937 @end deffn
2938
2939 @rnindex string<=?
2940 @deffn {Scheme Procedure} string<=? s1 s2
2941 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2942 is lexicographically less than or equal to @var{s2}.
2943 @end deffn
2944
2945 @rnindex string>?
2946 @deffn {Scheme Procedure} string>? s1 s2
2947 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2948 is lexicographically greater than @var{s2}.
2949 @end deffn
2950
2951 @rnindex string>=?
2952 @deffn {Scheme Procedure} string>=? s1 s2
2953 Lexicographic ordering predicate; return @code{#t} if @var{s1}
2954 is lexicographically greater than or equal to @var{s2}.
2955 @end deffn
2956
2957 @rnindex string-ci=?
2958 @deffn {Scheme Procedure} string-ci=? s1 s2
2959 Case-insensitive string equality predicate; return @code{#t} if
2960 the two strings are the same length and their component
2961 characters match (ignoring case) at each position; otherwise
2962 return @code{#f}.
2963 @end deffn
2964
2965 @rnindex string-ci<?
2966 @deffn {Scheme Procedure} string-ci<? s1 s2
2967 Case insensitive lexicographic ordering predicate; return
2968 @code{#t} if @var{s1} is lexicographically less than @var{s2}
2969 regardless of case.
2970 @end deffn
2971
2972 @rnindex string<=?
2973 @deffn {Scheme Procedure} string-ci<=? s1 s2
2974 Case insensitive lexicographic ordering predicate; return
2975 @code{#t} if @var{s1} is lexicographically less than or equal
2976 to @var{s2} regardless of case.
2977 @end deffn
2978
2979 @rnindex string-ci>?
2980 @deffn {Scheme Procedure} string-ci>? s1 s2
2981 Case insensitive lexicographic ordering predicate; return
2982 @code{#t} if @var{s1} is lexicographically greater than
2983 @var{s2} regardless of case.
2984 @end deffn
2985
2986 @rnindex string-ci>=?
2987 @deffn {Scheme Procedure} string-ci>=? s1 s2
2988 Case insensitive lexicographic ordering predicate; return
2989 @code{#t} if @var{s1} is lexicographically greater than or
2990 equal to @var{s2} regardless of case.
2991 @end deffn
2992
2993 @deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
2994 @deffnx {C Function} scm_string_compare (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
2995 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
2996 mismatch index, depending upon whether @var{s1} is less than,
2997 equal to, or greater than @var{s2}. The mismatch index is the
2998 largest index @var{i} such that for every 0 <= @var{j} <
2999 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3000 @var{i} is the first position that does not match.
3001 @end deffn
3002
3003 @deffn {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]]
3004 @deffnx {C Function} scm_string_compare_ci (s1, s2, proc_lt, proc_eq, proc_gt, start1, end1, start2, end2)
3005 Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
3006 mismatch index, depending upon whether @var{s1} is less than,
3007 equal to, or greater than @var{s2}. The mismatch index is the
3008 largest index @var{i} such that for every 0 <= @var{j} <
3009 @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
3010 @var{i} is the first position that does not match. The
3011 character comparison is done case-insensitively.
3012 @end deffn
3013
3014 @deffn {Scheme Procedure} string= s1 s2 [start1 [end1 [start2 [end2]]]]
3015 @deffnx {C Function} scm_string_eq (s1, s2, start1, end1, start2, end2)
3016 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3017 value otherwise.
3018 @end deffn
3019
3020 @deffn {Scheme Procedure} string<> s1 s2 [start1 [end1 [start2 [end2]]]]
3021 @deffnx {C Function} scm_string_neq (s1, s2, start1, end1, start2, end2)
3022 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3023 value otherwise.
3024 @end deffn
3025
3026 @deffn {Scheme Procedure} string< s1 s2 [start1 [end1 [start2 [end2]]]]
3027 @deffnx {C Function} scm_string_lt (s1, s2, start1, end1, start2, end2)
3028 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3029 true value otherwise.
3030 @end deffn
3031
3032 @deffn {Scheme Procedure} string> s1 s2 [start1 [end1 [start2 [end2]]]]
3033 @deffnx {C Function} scm_string_gt (s1, s2, start1, end1, start2, end2)
3034 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3035 true value otherwise.
3036 @end deffn
3037
3038 @deffn {Scheme Procedure} string<= s1 s2 [start1 [end1 [start2 [end2]]]]
3039 @deffnx {C Function} scm_string_le (s1, s2, start1, end1, start2, end2)
3040 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3041 value otherwise.
3042 @end deffn
3043
3044 @deffn {Scheme Procedure} string>= s1 s2 [start1 [end1 [start2 [end2]]]]
3045 @deffnx {C Function} scm_string_ge (s1, s2, start1, end1, start2, end2)
3046 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3047 otherwise.
3048 @end deffn
3049
3050 @deffn {Scheme Procedure} string-ci= s1 s2 [start1 [end1 [start2 [end2]]]]
3051 @deffnx {C Function} scm_string_ci_eq (s1, s2, start1, end1, start2, end2)
3052 Return @code{#f} if @var{s1} and @var{s2} are not equal, a true
3053 value otherwise. The character comparison is done
3054 case-insensitively.
3055 @end deffn
3056
3057 @deffn {Scheme Procedure} string-ci<> s1 s2 [start1 [end1 [start2 [end2]]]]
3058 @deffnx {C Function} scm_string_ci_neq (s1, s2, start1, end1, start2, end2)
3059 Return @code{#f} if @var{s1} and @var{s2} are equal, a true
3060 value otherwise. The character comparison is done
3061 case-insensitively.
3062 @end deffn
3063
3064 @deffn {Scheme Procedure} string-ci< s1 s2 [start1 [end1 [start2 [end2]]]]
3065 @deffnx {C Function} scm_string_ci_lt (s1, s2, start1, end1, start2, end2)
3066 Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a
3067 true value otherwise. The character comparison is done
3068 case-insensitively.
3069 @end deffn
3070
3071 @deffn {Scheme Procedure} string-ci> s1 s2 [start1 [end1 [start2 [end2]]]]
3072 @deffnx {C Function} scm_string_ci_gt (s1, s2, start1, end1, start2, end2)
3073 Return @code{#f} if @var{s1} is less or equal to @var{s2}, a
3074 true value otherwise. The character comparison is done
3075 case-insensitively.
3076 @end deffn
3077
3078 @deffn {Scheme Procedure} string-ci<= s1 s2 [start1 [end1 [start2 [end2]]]]
3079 @deffnx {C Function} scm_string_ci_le (s1, s2, start1, end1, start2, end2)
3080 Return @code{#f} if @var{s1} is greater to @var{s2}, a true
3081 value otherwise. The character comparison is done
3082 case-insensitively.
3083 @end deffn
3084
3085 @deffn {Scheme Procedure} string-ci>= s1 s2 [start1 [end1 [start2 [end2]]]]
3086 @deffnx {C Function} scm_string_ci_ge (s1, s2, start1, end1, start2, end2)
3087 Return @code{#f} if @var{s1} is less to @var{s2}, a true value
3088 otherwise. The character comparison is done
3089 case-insensitively.
3090 @end deffn
3091
3092 @deffn {Scheme Procedure} string-hash s [bound [start [end]]]
3093 @deffnx {C Function} scm_substring_hash (s, bound, start, end)
3094 Compute a hash value for @var{S}. the optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound).
3095 @end deffn
3096
3097 @deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
3098 @deffnx {C Function} scm_substring_hash_ci (s, bound, start, end)
3099 Compute a hash value for @var{S}. the optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound).
3100 @end deffn
3101
3102 @node String Searching
3103 @subsubsection String Searching
3104
3105 @deffn {Scheme Procedure} string-index s char_pred [start [end]]
3106 @deffnx {C Function} scm_string_index (s, char_pred, start, end)
3107 Search through the string @var{s} from left to right, returning
3108 the index of the first occurence of a character which
3109
3110 @itemize @bullet
3111 @item
3112 equals @var{char_pred}, if it is character,
3113
3114 @item
3115 satisifies the predicate @var{char_pred}, if it is a procedure,
3116
3117 @item
3118 is in the set @var{char_pred}, if it is a character set.
3119 @end itemize
3120 @end deffn
3121
3122 @deffn {Scheme Procedure} string-rindex s char_pred [start [end]]
3123 @deffnx {C Function} scm_string_rindex (s, char_pred, start, end)
3124 Search through the string @var{s} from right to left, returning
3125 the index of the last occurence of a character which
3126
3127 @itemize @bullet
3128 @item
3129 equals @var{char_pred}, if it is character,
3130
3131 @item
3132 satisifies the predicate @var{char_pred}, if it is a procedure,
3133
3134 @item
3135 is in the set if @var{char_pred} is a character set.
3136 @end itemize
3137 @end deffn
3138
3139 @deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3140 @deffnx {C Function} scm_string_prefix_length (s1, s2, start1, end1, start2, end2)
3141 Return the length of the longest common prefix of the two
3142 strings.
3143 @end deffn
3144
3145 @deffn {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3146 @deffnx {C Function} scm_string_prefix_length_ci (s1, s2, start1, end1, start2, end2)
3147 Return the length of the longest common prefix of the two
3148 strings, ignoring character case.
3149 @end deffn
3150
3151 @deffn {Scheme Procedure} string-suffix-length s1 s2 [start1 [end1 [start2 [end2]]]]
3152 @deffnx {C Function} scm_string_suffix_length (s1, s2, start1, end1, start2, end2)
3153 Return the length of the longest common suffix of the two
3154 strings.
3155 @end deffn
3156
3157 @deffn {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3158 @deffnx {C Function} scm_string_suffix_length_ci (s1, s2, start1, end1, start2, end2)
3159 Return the length of the longest common suffix of the two
3160 strings, ignoring character case.
3161 @end deffn
3162
3163 @deffn {Scheme Procedure} string-prefix? s1 s2 [start1 [end1 [start2 [end2]]]]
3164 @deffnx {C Function} scm_string_prefix_p (s1, s2, start1, end1, start2, end2)
3165 Is @var{s1} a prefix of @var{s2}?
3166 @end deffn
3167
3168 @deffn {Scheme Procedure} string-prefix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3169 @deffnx {C Function} scm_string_prefix_ci_p (s1, s2, start1, end1, start2, end2)
3170 Is @var{s1} a prefix of @var{s2}, ignoring character case?
3171 @end deffn
3172
3173 @deffn {Scheme Procedure} string-suffix? s1 s2 [start1 [end1 [start2 [end2]]]]
3174 @deffnx {C Function} scm_string_suffix_p (s1, s2, start1, end1, start2, end2)
3175 Is @var{s1} a suffix of @var{s2}?
3176 @end deffn
3177
3178 @deffn {Scheme Procedure} string-suffix-ci? s1 s2 [start1 [end1 [start2 [end2]]]]
3179 @deffnx {C Function} scm_string_suffix_ci_p (s1, s2, start1, end1, start2, end2)
3180 Is @var{s1} a suffix of @var{s2}, ignoring character case?
3181 @end deffn
3182
3183 @deffn {Scheme Procedure} string-index-right s char_pred [start [end]]
3184 @deffnx {C Function} scm_string_index_right (s, char_pred, start, end)
3185 Search through the string @var{s} from right to left, returning
3186 the index of the last occurence of a character which
3187
3188 @itemize @bullet
3189 @item
3190 equals @var{char_pred}, if it is character,
3191
3192 @item
3193 satisifies the predicate @var{char_pred}, if it is a procedure,
3194
3195 @item
3196 is in the set if @var{char_pred} is a character set.
3197 @end itemize
3198 @end deffn
3199
3200 @deffn {Scheme Procedure} string-skip s char_pred [start [end]]
3201 @deffnx {C Function} scm_string_skip (s, char_pred, start, end)
3202 Search through the string @var{s} from left to right, returning
3203 the index of the first occurence of a character which
3204
3205 @itemize @bullet
3206 @item
3207 does not equal @var{char_pred}, if it is character,
3208
3209 @item
3210 does not satisify the predicate @var{char_pred}, if it is a
3211 procedure,
3212
3213 @item
3214 is not in the set if @var{char_pred} is a character set.
3215 @end itemize
3216 @end deffn
3217
3218 @deffn {Scheme Procedure} string-skip-right s char_pred [start [end]]
3219 @deffnx {C Function} scm_string_skip_right (s, char_pred, start, end)
3220 Search through the string @var{s} from right to left, returning
3221 the index of the last occurence of a character which
3222
3223 @itemize @bullet
3224 @item
3225 does not equal @var{char_pred}, if it is character,
3226
3227 @item
3228 does not satisfy the predicate @var{char_pred}, if it is a
3229 procedure,
3230
3231 @item
3232 is not in the set if @var{char_pred} is a character set.
3233 @end itemize
3234 @end deffn
3235
3236 @deffn {Scheme Procedure} string-count s char_pred [start [end]]
3237 @deffnx {C Function} scm_string_count (s, char_pred, start, end)
3238 Return the count of the number of characters in the string
3239 @var{s} which
3240
3241 @itemize @bullet
3242 @item
3243 equals @var{char_pred}, if it is character,
3244
3245 @item
3246 satisifies the predicate @var{char_pred}, if it is a procedure.
3247
3248 @item
3249 is in the set @var{char_pred}, if it is a character set.
3250 @end itemize
3251 @end deffn
3252
3253 @deffn {Scheme Procedure} string-contains s1 s2 [start1 [end1 [start2 [end2]]]]
3254 @deffnx {C Function} scm_string_contains (s1, s2, start1, end1, start2, end2)
3255 Does string @var{s1} contain string @var{s2}? Return the index
3256 in @var{s1} where @var{s2} occurs as a substring, or false.
3257 The optional start/end indices restrict the operation to the
3258 indicated substrings.
3259 @end deffn
3260
3261 @deffn {Scheme Procedure} string-contains-ci s1 s2 [start1 [end1 [start2 [end2]]]]
3262 @deffnx {C Function} scm_string_contains_ci (s1, s2, start1, end1, start2, end2)
3263 Does string @var{s1} contain string @var{s2}? Return the index
3264 in @var{s1} where @var{s2} occurs as a substring, or false.
3265 The optional start/end indices restrict the operation to the
3266 indicated substrings. Character comparison is done
3267 case-insensitively.
3268 @end deffn
3269
3270 @node Alphabetic Case Mapping
3271 @subsubsection Alphabetic Case Mapping
3272
3273 These are procedures for mapping strings to their upper- or lower-case
3274 equivalents, respectively, or for capitalizing strings.
3275
3276 @deffn {Scheme Procedure} string-upcase str [start [end]]
3277 @deffnx {C Function} scm_substring_upcase (str, start, end)
3278 @deffnx {C Function} scm_string_upcase (str)
3279 Upcase every character in @code{str}.
3280 @end deffn
3281
3282 @deffn {Scheme Procedure} string-upcase! str [start [end]]
3283 @deffnx {C Function} scm_substring_upcase_x (str, start, end)
3284 @deffnx {C Function} scm_string_upcase_x (str)
3285 Destructively upcase every character in @code{str}.
3286
3287 @lisp
3288 (string-upcase! y)
3289 @result{} "ARRDEFG"
3290 y
3291 @result{} "ARRDEFG"
3292 @end lisp
3293 @end deffn
3294
3295 @deffn {Scheme Procedure} string-downcase str [start [end]]
3296 @deffnx {C Function} scm_substring_downcase (str, start, end)
3297 @deffnx {C Function} scm_string_downcase (str)
3298 Downcase every character in @var{str}.
3299 @end deffn
3300
3301 @deffn {Scheme Procedure} string-downcase! str [start [end]]
3302 @deffnx {C Function} scm_substring_downcase_x (str, start, end)
3303 @deffnx {C Function} scm_string_downcase_x (str)
3304 Destructively downcase every character in @var{str}.
3305
3306 @lisp
3307 y
3308 @result{} "ARRDEFG"
3309 (string-downcase! y)
3310 @result{} "arrdefg"
3311 y
3312 @result{} "arrdefg"
3313 @end lisp
3314 @end deffn
3315
3316 @deffn {Scheme Procedure} string-capitalize str
3317 @deffnx {C Function} scm_string_capitalize (str)
3318 Return a freshly allocated string with the characters in
3319 @var{str}, where the first character of every word is
3320 capitalized.
3321 @end deffn
3322
3323 @deffn {Scheme Procedure} string-capitalize! str
3324 @deffnx {C Function} scm_string_capitalize_x (str)
3325 Upcase the first character of every word in @var{str}
3326 destructively and return @var{str}.
3327
3328 @lisp
3329 y @result{} "hello world"
3330 (string-capitalize! y) @result{} "Hello World"
3331 y @result{} "Hello World"
3332 @end lisp
3333 @end deffn
3334
3335 @deffn {Scheme Procedure} string-titlecase str [start [end]]
3336 @deffnx {C Function} scm_string_titlecase (str, start, end)
3337 Titlecase every first character in a word in @var{str}.
3338 @end deffn
3339
3340 @deffn {Scheme Procedure} string-titlecase! str [start [end]]
3341 @deffnx {C Function} scm_string_titlecase_x (str, start, end)
3342 Destructively titlecase every first character in a word in
3343 @var{str}.
3344 @end deffn
3345
3346 @node Reversing and Appending Strings
3347 @subsubsection Reversing and Appending Strings
3348
3349 @deffn {Scheme Procedure} string-reverse str [start [end]]
3350 @deffnx {C Function} scm_string_reverse (str, start, end)
3351 Reverse the string @var{str}. The optional arguments
3352 @var{start} and @var{end} delimit the region of @var{str} to
3353 operate on.
3354 @end deffn
3355
3356 @deffn {Scheme Procedure} string-reverse! str [start [end]]
3357 @deffnx {C Function} scm_string_reverse_x (str, start, end)
3358 Reverse the string @var{str} in-place. The optional arguments
3359 @var{start} and @var{end} delimit the region of @var{str} to
3360 operate on. The return value is unspecified.
3361 @end deffn
3362
3363 @rnindex string-append
3364 @deffn {Scheme Procedure} string-append . args
3365 @deffnx {C Function} scm_string_append (args)
3366 Return a newly allocated string whose characters form the
3367 concatenation of the given strings, @var{args}.
3368
3369 @example
3370 (let ((h "hello "))
3371 (string-append h "world"))
3372 @result{} "hello world"
3373 @end example
3374 @end deffn
3375
3376 @deffn {Scheme Procedure} string-append/shared . ls
3377 @deffnx {C Function} scm_string_append_shared (ls)
3378 Like @code{string-append}, but the result may share memory
3379 with the argument strings.
3380 @end deffn
3381
3382 @deffn {Scheme Procedure} string-concatenate ls
3383 @deffnx {C Function} scm_string_concatenate (ls)
3384 Append the elements of @var{ls} (which must be strings)
3385 together into a single string. Guaranteed to return a freshly
3386 allocated string.
3387 @end deffn
3388
3389 @deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]]
3390 @deffnx {C Function} scm_string_concatenate_reverse (ls, final_string, end)
3391 Without optional arguments, this procedure is equivalent to
3392
3393 @smalllisp
3394 (string-concatenate (reverse ls))
3395 @end smalllisp
3396
3397 If the optional argument @var{final_string} is specified, it is
3398 consed onto the beginning to @var{ls} before performing the
3399 list-reverse and string-concatenate operations. If @var{end}
3400 is given, only the characters of @var{final_string} up to index
3401 @var{end} are used.
3402
3403 Guaranteed to return a freshly allocated string.
3404 @end deffn
3405
3406 @deffn {Scheme Procedure} string-concatenate/shared ls
3407 @deffnx {C Function} scm_string_concatenate_shared (ls)
3408 Like @code{string-concatenate}, but the result may share memory
3409 with the strings in the list @var{ls}.
3410 @end deffn
3411
3412 @deffn {Scheme Procedure} string-concatenate-reverse/shared ls [final_string [end]]
3413 @deffnx {C Function} scm_string_concatenate_reverse_shared (ls, final_string, end)
3414 Like @code{string-concatenate-reverse}, but the result may
3415 share memory with the the strings in the @var{ls} arguments.
3416 @end deffn
3417
3418 @node Mapping Folding and Unfolding
3419 @subsubsection Mapping, Folding, and Unfolding
3420
3421 @deffn {Scheme Procedure} string-map proc s [start [end]]
3422 @deffnx {C Function} scm_string_map (proc, s, start, end)
3423 @var{proc} is a char->char procedure, it is mapped over
3424 @var{s}. The order in which the procedure is applied to the
3425 string elements is not specified.
3426 @end deffn
3427
3428 @deffn {Scheme Procedure} string-map! proc s [start [end]]
3429 @deffnx {C Function} scm_string_map_x (proc, s, start, end)
3430 @var{proc} is a char->char procedure, it is mapped over
3431 @var{s}. The order in which the procedure is applied to the
3432 string elements is not specified. The string @var{s} is
3433 modified in-place, the return value is not specified.
3434 @end deffn
3435
3436 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
3437 @deffnx {C Function} scm_string_for_each (proc, s, start, end)
3438 @var{proc} is mapped over @var{s} in left-to-right order. The
3439 return value is not specified.
3440 @end deffn
3441
3442 @deffn {Scheme Procedure} string-for-each-index proc s [start [end]]
3443 @deffnx {C Function} scm_string_for_each_index (proc, s, start, end)
3444 Call @code{(@var{proc} i)} for each index i in @var{s}, from left to
3445 right.
3446
3447 For example, to change characters to alternately upper and lower case,
3448
3449 @example
3450 (define str (string-copy "studly"))
3451 (string-for-each-index (lambda (i)
3452 (string-set! str i
3453 ((if (even? i) char-upcase char-downcase)
3454 (string-ref str i))))
3455 str)
3456 str @result{} "StUdLy"
3457 @end example
3458 @end deffn
3459
3460 @deffn {Scheme Procedure} string-fold kons knil s [start [end]]
3461 @deffnx {C Function} scm_string_fold (kons, knil, s, start, end)
3462 Fold @var{kons} over the characters of @var{s}, with @var{knil}
3463 as the terminating element, from left to right. @var{kons}
3464 must expect two arguments: The actual character and the last
3465 result of @var{kons}' application.
3466 @end deffn
3467
3468 @deffn {Scheme Procedure} string-fold-right kons knil s [start [end]]
3469 @deffnx {C Function} scm_string_fold_right (kons, knil, s, start, end)
3470 Fold @var{kons} over the characters of @var{s}, with @var{knil}
3471 as the terminating element, from right to left. @var{kons}
3472 must expect two arguments: The actual character and the last
3473 result of @var{kons}' application.
3474 @end deffn
3475
3476 @deffn {Scheme Procedure} string-unfold p f g seed [base [make_final]]
3477 @deffnx {C Function} scm_string_unfold (p, f, g, seed, base, make_final)
3478 @itemize @bullet
3479 @item @var{g} is used to generate a series of @emph{seed}
3480 values from the initial @var{seed}: @var{seed}, (@var{g}
3481 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
3482 @dots{}
3483 @item @var{p} tells us when to stop -- when it returns true
3484 when applied to one of these seed values.
3485 @item @var{f} maps each seed value to the corresponding
3486 character in the result string. These chars are assembled
3487 into the string in a left-to-right order.
3488 @item @var{base} is the optional initial/leftmost portion
3489 of the constructed string; it default to the empty
3490 string.
3491 @item @var{make_final} is applied to the terminal seed
3492 value (on which @var{p} returns true) to produce
3493 the final/rightmost portion of the constructed string.
3494 It defaults to @code{(lambda (x) )}.
3495 @end itemize
3496 @end deffn
3497
3498 @deffn {Scheme Procedure} string-unfold-right p f g seed [base [make_final]]
3499 @deffnx {C Function} scm_string_unfold_right (p, f, g, seed, base, make_final)
3500 @itemize @bullet
3501 @item @var{g} is used to generate a series of @emph{seed}
3502 values from the initial @var{seed}: @var{seed}, (@var{g}
3503 @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
3504 @dots{}
3505 @item @var{p} tells us when to stop -- when it returns true
3506 when applied to one of these seed values.
3507 @item @var{f} maps each seed value to the corresponding
3508 character in the result string. These chars are assembled
3509 into the string in a right-to-left order.
3510 @item @var{base} is the optional initial/rightmost portion
3511 of the constructed string; it default to the empty
3512 string.
3513 @item @var{make_final} is applied to the terminal seed
3514 value (on which @var{p} returns true) to produce
3515 the final/leftmost portion of the constructed string.
3516 It defaults to @code{(lambda (x) )}.
3517 @end itemize
3518 @end deffn
3519
3520 @node Miscellaneous String Operations
3521 @subsubsection Miscellaneous String Operations
3522
3523 @deffn {Scheme Procedure} xsubstring s from [to [start [end]]]
3524 @deffnx {C Function} scm_xsubstring (s, from, to, start, end)
3525 This is the @emph{extended substring} procedure that implements
3526 replicated copying of a substring of some string.
3527
3528 @var{s} is a string, @var{start} and @var{end} are optional
3529 arguments that demarcate a substring of @var{s}, defaulting to
3530 0 and the length of @var{s}. Replicate this substring up and
3531 down index space, in both the positive and negative directions.
3532 @code{xsubstring} returns the substring of this string
3533 beginning at index @var{from}, and ending at @var{to}, which
3534 defaults to @var{from} + (@var{end} - @var{start}).
3535 @end deffn
3536
3537 @deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto [start [end]]]
3538 @deffnx {C Function} scm_string_xcopy_x (target, tstart, s, sfrom, sto, start, end)
3539 Exactly the same as @code{xsubstring}, but the extracted text
3540 is written into the string @var{target} starting at index
3541 @var{tstart}. The operation is not defined if @code{(eq?
3542 @var{target} @var{s})} or these arguments share storage -- you
3543 cannot copy a string on top of itself.
3544 @end deffn
3545
3546 @deffn {Scheme Procedure} string-replace s1 s2 [start1 [end1 [start2 [end2]]]]
3547 @deffnx {C Function} scm_string_replace (s1, s2, start1, end1, start2, end2)
3548 Return the string @var{s1}, but with the characters
3549 @var{start1} @dots{} @var{end1} replaced by the characters
3550 @var{start2} @dots{} @var{end2} from @var{s2}.
3551 @end deffn
3552
3553 @deffn {Scheme Procedure} string-tokenize s [token_set [start [end]]]
3554 @deffnx {C Function} scm_string_tokenize (s, token_set, start, end)
3555 Split the string @var{s} into a list of substrings, where each
3556 substring is a maximal non-empty contiguous sequence of
3557 characters from the character set @var{token_set}, which
3558 defaults to @code{char-set:graphic}.
3559 If @var{start} or @var{end} indices are provided, they restrict
3560 @code{string-tokenize} to operating on the indicated substring
3561 of @var{s}.
3562 @end deffn
3563
3564 @deffn {Scheme Procedure} string-filter s char_pred [start [end]]
3565 @deffnx {C Function} scm_string_filter (s, char_pred, start, end)
3566 Filter the string @var{s}, retaining only those characters which
3567 satisfy @var{char_pred}.
3568
3569 If @var{char_pred} is a procedure, it is applied to each character as
3570 a predicate, if it is a character, it is tested for equality and if it
3571 is a character set, it is tested for membership.
3572 @end deffn
3573
3574 @deffn {Scheme Procedure} string-delete s char_pred [start [end]]
3575 @deffnx {C Function} scm_string_delete (s, char_pred, start, end)
3576 Delete characters satisfying @var{char_pred} from @var{s}.
3577
3578 If @var{char_pred} is a procedure, it is applied to each character as
3579 a predicate, if it is a character, it is tested for equality and if it
3580 is a character set, it is tested for membership.
3581 @end deffn
3582
3583 @node Conversion to/from C
3584 @subsubsection Conversion to/from C
3585
3586 When creating a Scheme string from a C string or when converting a
3587 Scheme string to a C string, the concept of character encoding becomes
3588 important.
3589
3590 In C, a string is just a sequence of bytes, and the character encoding
3591 describes the relation between these bytes and the actual characters
3592 that make up the string. For Scheme strings, character encoding is
3593 not an issue (most of the time), since in Scheme you never get to see
3594 the bytes, only the characters.
3595
3596 Well, ideally, anyway. Right now, Guile simply equates Scheme
3597 characters and bytes, ignoring the possibility of multi-byte encodings
3598 completely. This will change in the future, where Guile will use
3599 Unicode codepoints as its characters and UTF-8 or some other encoding
3600 as its internal encoding. When you exclusively use the functions
3601 listed in this section, you are `future-proof'.
3602
3603 Converting a Scheme string to a C string will often allocate fresh
3604 memory to hold the result. You must take care that this memory is
3605 properly freed eventually. In many cases, this can be achieved by
3606 using @code{scm_dynwind_free} inside an appropriate dynwind context,
3607 @xref{Dynamic Wind}.
3608
3609 @deftypefn {C Function} SCM scm_from_locale_string (const char *str)
3610 @deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
3611 Creates a new Scheme string that has the same contents as @var{str}
3612 when interpreted in the current locale character encoding.
3613
3614 For @code{scm_from_locale_string}, @var{str} must be null-terminated.
3615
3616 For @code{scm_from_locale_stringn}, @var{len} specifies the length of
3617 @var{str} in bytes, and @var{str} does not need to be null-terminated.
3618 If @var{len} is @code{(size_t)-1}, then @var{str} does need to be
3619 null-terminated and the real length will be found with @code{strlen}.
3620 @end deftypefn
3621
3622 @deftypefn {C Function} SCM scm_take_locale_string (char *str)
3623 @deftypefnx {C Function} SCM scm_take_locale_stringn (char *str, size_t len)
3624 Like @code{scm_from_locale_string} and @code{scm_from_locale_stringn},
3625 respectively, but also frees @var{str} with @code{free} eventually.
3626 Thus, you can use this function when you would free @var{str} anyway
3627 immediately after creating the Scheme string. In certain cases, Guile
3628 can then use @var{str} directly as its internal representation.
3629 @end deftypefn
3630
3631 @deftypefn {C Function} {char *} scm_to_locale_string (SCM str)
3632 @deftypefnx {C Function} {char *} scm_to_locale_stringn (SCM str, size_t *lenp)
3633 Returns a C string in the current locale encoding with the same
3634 contents as @var{str}. The C string must be freed with @code{free}
3635 eventually, maybe by using @code{scm_dynwind_free}, @xref{Dynamic
3636 Wind}.
3637
3638 For @code{scm_to_locale_string}, the returned string is
3639 null-terminated and an error is signalled when @var{str} contains
3640 @code{#\nul} characters.
3641
3642 For @code{scm_to_locale_stringn} and @var{lenp} not @code{NULL},
3643 @var{str} might contain @code{#\nul} characters and the length of the
3644 returned string in bytes is stored in @code{*@var{lenp}}. The
3645 returned string will not be null-terminated in this case. If
3646 @var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
3647 @code{scm_to_locale_string}.
3648 @end deftypefn
3649
3650 @deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
3651 Puts @var{str} as a C string in the current locale encoding into the
3652 memory pointed to by @var{buf}. The buffer at @var{buf} has room for
3653 @var{max_len} bytes and @code{scm_to_local_stringbuf} will never store
3654 more than that. No terminating @code{'\0'} will be stored.
3655
3656 The return value of @code{scm_to_locale_stringbuf} is the number of
3657 bytes that are needed for all of @var{str}, regardless of whether
3658 @var{buf} was large enough to hold them. Thus, when the return value
3659 is larger than @var{max_len}, only @var{max_len} bytes have been
3660 stored and you probably need to try again with a larger buffer.
3661 @end deftypefn
3662
3663 @node Regular Expressions
3664 @subsection Regular Expressions
3665 @tpindex Regular expressions
3666
3667 @cindex regular expressions
3668 @cindex regex
3669 @cindex emacs regexp
3670
3671 A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
3672 describes a whole class of strings. A full description of regular
3673 expressions and their syntax is beyond the scope of this manual;
3674 an introduction can be found in the Emacs manual (@pxref{Regexps,
3675 , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
3676 in many general Unix reference books.
3677
3678 If your system does not include a POSIX regular expression library,
3679 and you have not linked Guile with a third-party regexp library such
3680 as Rx, these functions will not be available. You can tell whether
3681 your Guile installation includes regular expression support by
3682 checking whether @code{(provided? 'regex)} returns true.
3683
3684 The following regexp and string matching features are provided by the
3685 @code{(ice-9 regex)} module. Before using the described functions,
3686 you should load this module by executing @code{(use-modules (ice-9
3687 regex))}.
3688
3689 @menu
3690 * Regexp Functions:: Functions that create and match regexps.
3691 * Match Structures:: Finding what was matched by a regexp.
3692 * Backslash Escapes:: Removing the special meaning of regexp
3693 meta-characters.
3694 @end menu
3695
3696
3697 @node Regexp Functions
3698 @subsubsection Regexp Functions
3699
3700 By default, Guile supports POSIX extended regular expressions.
3701 That means that the characters @samp{(}, @samp{)}, @samp{+} and
3702 @samp{?} are special, and must be escaped if you wish to match the
3703 literal characters.
3704
3705 This regular expression interface was modeled after that
3706 implemented by SCSH, the Scheme Shell. It is intended to be
3707 upwardly compatible with SCSH regular expressions.
3708
3709 Zero bytes (@code{#\nul}) cannot be used in regex patterns or input
3710 strings, since the underlying C functions treat that as the end of
3711 string. If there's a zero byte an error is thrown.
3712
3713 Patterns and input strings are treated as being in the locale
3714 character set if @code{setlocale} has been called (@pxref{Locales}),
3715 and in a multibyte locale this includes treating multi-byte sequences
3716 as a single character. (Guile strings are currently merely bytes,
3717 though this may change in the future, @xref{Conversion to/from C}.)
3718
3719 @deffn {Scheme Procedure} string-match pattern str [start]
3720 Compile the string @var{pattern} into a regular expression and compare
3721 it with @var{str}. The optional numeric argument @var{start} specifies
3722 the position of @var{str} at which to begin matching.
3723
3724 @code{string-match} returns a @dfn{match structure} which
3725 describes what, if anything, was matched by the regular
3726 expression. @xref{Match Structures}. If @var{str} does not match
3727 @var{pattern} at all, @code{string-match} returns @code{#f}.
3728 @end deffn
3729
3730 Two examples of a match follow. In the first example, the pattern
3731 matches the four digits in the match string. In the second, the pattern
3732 matches nothing.
3733
3734 @example
3735 (string-match "[0-9][0-9][0-9][0-9]" "blah2002")
3736 @result{} #("blah2002" (4 . 8))
3737
3738 (string-match "[A-Za-z]" "123456")
3739 @result{} #f
3740 @end example
3741
3742 Each time @code{string-match} is called, it must compile its
3743 @var{pattern} argument into a regular expression structure. This
3744 operation is expensive, which makes @code{string-match} inefficient if
3745 the same regular expression is used several times (for example, in a
3746 loop). For better performance, you can compile a regular expression in
3747 advance and then match strings against the compiled regexp.
3748
3749 @deffn {Scheme Procedure} make-regexp pat flag@dots{}
3750 @deffnx {C Function} scm_make_regexp (pat, flaglst)
3751 Compile the regular expression described by @var{pat}, and
3752 return the compiled regexp structure. If @var{pat} does not
3753 describe a legal regular expression, @code{make-regexp} throws
3754 a @code{regular-expression-syntax} error.
3755
3756 The @var{flag} arguments change the behavior of the compiled
3757 regular expression. The following values may be supplied:
3758
3759 @defvar regexp/icase
3760 Consider uppercase and lowercase letters to be the same when
3761 matching.
3762 @end defvar
3763
3764 @defvar regexp/newline
3765 If a newline appears in the target string, then permit the
3766 @samp{^} and @samp{$} operators to match immediately after or
3767 immediately before the newline, respectively. Also, the
3768 @samp{.} and @samp{[^...]} operators will never match a newline
3769 character. The intent of this flag is to treat the target
3770 string as a buffer containing many lines of text, and the
3771 regular expression as a pattern that may match a single one of
3772 those lines.
3773 @end defvar
3774
3775 @defvar regexp/basic
3776 Compile a basic (``obsolete'') regexp instead of the extended
3777 (``modern'') regexps that are the default. Basic regexps do
3778 not consider @samp{|}, @samp{+} or @samp{?} to be special
3779 characters, and require the @samp{@{...@}} and @samp{(...)}
3780 metacharacters to be backslash-escaped (@pxref{Backslash
3781 Escapes}). There are several other differences between basic
3782 and extended regular expressions, but these are the most
3783 significant.
3784 @end defvar
3785
3786 @defvar regexp/extended
3787 Compile an extended regular expression rather than a basic
3788 regexp. This is the default behavior; this flag will not
3789 usually be needed. If a call to @code{make-regexp} includes
3790 both @code{regexp/basic} and @code{regexp/extended} flags, the
3791 one which comes last will override the earlier one.
3792 @end defvar
3793 @end deffn
3794
3795 @deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
3796 @deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
3797 Match the compiled regular expression @var{rx} against
3798 @code{str}. If the optional integer @var{start} argument is
3799 provided, begin matching from that position in the string.
3800 Return a match structure describing the results of the match,
3801 or @code{#f} if no match could be found.
3802
3803 The @var{flags} argument changes the matching behavior. The following
3804 flag values may be supplied, use @code{logior} (@pxref{Bitwise
3805 Operations}) to combine them,
3806
3807 @defvar regexp/notbol
3808 Consider that the @var{start} offset into @var{str} is not the
3809 beginning of a line and should not match operator @samp{^}.
3810
3811 If @var{rx} was created with the @code{regexp/newline} option above,
3812 @samp{^} will still match after a newline in @var{str}.
3813 @end defvar
3814
3815 @defvar regexp/noteol
3816 Consider that the end of @var{str} is not the end of a line and should
3817 not match operator @samp{$}.
3818
3819 If @var{rx} was created with the @code{regexp/newline} option above,
3820 @samp{$} will still match before a newline in @var{str}.
3821 @end defvar
3822 @end deffn
3823
3824 @lisp
3825 ;; Regexp to match uppercase letters
3826 (define r (make-regexp "[A-Z]*"))
3827
3828 ;; Regexp to match letters, ignoring case
3829 (define ri (make-regexp "[A-Z]*" regexp/icase))
3830
3831 ;; Search for bob using regexp r
3832 (match:substring (regexp-exec r "bob"))
3833 @result{} "" ; no match
3834
3835 ;; Search for bob using regexp ri
3836 (match:substring (regexp-exec ri "Bob"))
3837 @result{} "Bob" ; matched case insensitive
3838 @end lisp
3839
3840 @deffn {Scheme Procedure} regexp? obj
3841 @deffnx {C Function} scm_regexp_p (obj)
3842 Return @code{#t} if @var{obj} is a compiled regular expression,
3843 or @code{#f} otherwise.
3844 @end deffn
3845
3846 @sp 1
3847 @deffn {Scheme Procedure} list-matches regexp str [flags]
3848 Return a list of match structures which are the non-overlapping
3849 matches of @var{regexp} in @var{str}. @var{regexp} can be either a
3850 pattern string or a compiled regexp. The @var{flags} argument is as
3851 per @code{regexp-exec} above.
3852
3853 @example
3854 (map match:substring (list-matches "[a-z]+" "abc 42 def 78"))
3855 @result{} ("abc" "def")
3856 @end example
3857 @end deffn
3858
3859 @deffn {Scheme Procedure} fold-matches regexp str init proc [flags]
3860 Apply @var{proc} to the non-overlapping matches of @var{regexp} in
3861 @var{str}, to build a result. @var{regexp} can be either a pattern
3862 string or a compiled regexp. The @var{flags} argument is as per
3863 @code{regexp-exec} above.
3864
3865 @var{proc} is called as @code{(@var{proc} match prev)} where
3866 @var{match} is a match structure and @var{prev} is the previous return
3867 from @var{proc}. For the first call @var{prev} is the given
3868 @var{init} parameter. @code{fold-matches} returns the final value
3869 from @var{proc}.
3870
3871 For example to count matches,
3872
3873 @example
3874 (fold-matches "[a-z][0-9]" "abc x1 def y2" 0
3875 (lambda (match count)
3876 (1+ count)))
3877 @result{} 2
3878 @end example
3879 @end deffn
3880
3881 @sp 1
3882 Regular expressions are commonly used to find patterns in one string
3883 and replace them with the contents of another string. The following
3884 functions are convenient ways to do this.
3885
3886 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
3887 @deffn {Scheme Procedure} regexp-substitute port match [item@dots{}]
3888 Write to @var{port} selected parts of the match structure @var{match}.
3889 Or if @var{port} is @code{#f} then form a string from those parts and
3890 return that.
3891
3892 Each @var{item} specifies a part to be written, and may be one of the
3893 following,
3894
3895 @itemize @bullet
3896 @item
3897 A string. String arguments are written out verbatim.
3898
3899 @item
3900 An integer. The submatch with that number is written
3901 (@code{match:substring}). Zero is the entire match.
3902
3903 @item
3904 The symbol @samp{pre}. The portion of the matched string preceding
3905 the regexp match is written (@code{match:prefix}).
3906
3907 @item
3908 The symbol @samp{post}. The portion of the matched string following
3909 the regexp match is written (@code{match:suffix}).
3910 @end itemize
3911
3912 For example, changing a match and retaining the text before and after,
3913
3914 @example
3915 (regexp-substitute #f (string-match "[0-9]+" "number 25 is good")
3916 'pre "37" 'post)
3917 @result{} "number 37 is good"
3918 @end example
3919
3920 Or matching a @sc{yyyymmdd} format date such as @samp{20020828} and
3921 re-ordering and hyphenating the fields.
3922
3923 @lisp
3924 (define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
3925 (define s "Date 20020429 12am.")
3926 (regexp-substitute #f (string-match date-regex s)
3927 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
3928 @result{} "Date 04-29-2002 12am. (20020429)"
3929 @end lisp
3930 @end deffn
3931
3932
3933 @c begin (scm-doc-string "regex.scm" "regexp-substitute")
3934 @deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
3935 @cindex search and replace
3936 Write to @var{port} selected parts of matches of @var{regexp} in
3937 @var{target}. If @var{port} is @code{#f} then form a string from
3938 those parts and return that. @var{regexp} can be a string or a
3939 compiled regex.
3940
3941 This is similar to @code{regexp-substitute}, but allows global
3942 substitutions on @var{target}. Each @var{item} behaves as per
3943 @code{regexp-substitute}, with the following differences,
3944
3945 @itemize @bullet
3946 @item
3947 A function. Called as @code{(@var{item} match)} with the match
3948 structure for the @var{regexp} match, it should return a string to be
3949 written to @var{port}.
3950
3951 @item
3952 The symbol @samp{post}. This doesn't output anything, but instead
3953 causes @code{regexp-substitute/global} to recurse on the unmatched
3954 portion of @var{target}.
3955
3956 This @emph{must} be supplied to perform a global search and replace on
3957 @var{target}; without it @code{regexp-substitute/global} returns after
3958 a single match and output.
3959 @end itemize
3960
3961 For example, to collapse runs of tabs and spaces to a single hyphen
3962 each,
3963
3964 @example
3965 (regexp-substitute/global #f "[ \t]+" "this is the text"
3966 'pre "-" 'post)
3967 @result{} "this-is-the-text"
3968 @end example
3969
3970 Or using a function to reverse the letters in each word,
3971
3972 @example
3973 (regexp-substitute/global #f "[a-z]+" "to do and not-do"
3974 'pre (lambda (m) (string-reverse (match:substring m))) 'post)
3975 @result{} "ot od dna ton-od"
3976 @end example
3977
3978 Without the @code{post} symbol, just one regexp match is made. For
3979 example the following is the date example from
3980 @code{regexp-substitute} above, without the need for the separate
3981 @code{string-match} call.
3982
3983 @lisp
3984 (define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
3985 (define s "Date 20020429 12am.")
3986 (regexp-substitute/global #f date-regex s
3987 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
3988
3989 @result{} "Date 04-29-2002 12am. (20020429)"
3990 @end lisp
3991 @end deffn
3992
3993
3994 @node Match Structures
3995 @subsubsection Match Structures
3996
3997 @cindex match structures
3998
3999 A @dfn{match structure} is the object returned by @code{string-match} and
4000 @code{regexp-exec}. It describes which portion of a string, if any,
4001 matched the given regular expression. Match structures include: a
4002 reference to the string that was checked for matches; the starting and
4003 ending positions of the regexp match; and, if the regexp included any
4004 parenthesized subexpressions, the starting and ending positions of each
4005 submatch.
4006
4007 In each of the regexp match functions described below, the @code{match}
4008 argument must be a match structure returned by a previous call to
4009 @code{string-match} or @code{regexp-exec}. Most of these functions
4010 return some information about the original target string that was
4011 matched against a regular expression; we will call that string
4012 @var{target} for easy reference.
4013
4014 @c begin (scm-doc-string "regex.scm" "regexp-match?")
4015 @deffn {Scheme Procedure} regexp-match? obj
4016 Return @code{#t} if @var{obj} is a match structure returned by a
4017 previous call to @code{regexp-exec}, or @code{#f} otherwise.
4018 @end deffn
4019
4020 @c begin (scm-doc-string "regex.scm" "match:substring")
4021 @deffn {Scheme Procedure} match:substring match [n]
4022 Return the portion of @var{target} matched by subexpression number
4023 @var{n}. Submatch 0 (the default) represents the entire regexp match.
4024 If the regular expression as a whole matched, but the subexpression
4025 number @var{n} did not match, return @code{#f}.
4026 @end deffn
4027
4028 @lisp
4029 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4030 (match:substring s)
4031 @result{} "2002"
4032
4033 ;; match starting at offset 6 in the string
4034 (match:substring
4035 (string-match "[0-9][0-9][0-9][0-9]" "blah987654" 6))
4036 @result{} "7654"
4037 @end lisp
4038
4039 @c begin (scm-doc-string "regex.scm" "match:start")
4040 @deffn {Scheme Procedure} match:start match [n]
4041 Return the starting position of submatch number @var{n}.
4042 @end deffn
4043
4044 In the following example, the result is 4, since the match starts at
4045 character index 4:
4046
4047 @lisp
4048 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4049 (match:start s)
4050 @result{} 4
4051 @end lisp
4052
4053 @c begin (scm-doc-string "regex.scm" "match:end")
4054 @deffn {Scheme Procedure} match:end match [n]
4055 Return the ending position of submatch number @var{n}.
4056 @end deffn
4057
4058 In the following example, the result is 8, since the match runs between
4059 characters 4 and 8 (i.e. the ``2002'').
4060
4061 @lisp
4062 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4063 (match:end s)
4064 @result{} 8
4065 @end lisp
4066
4067 @c begin (scm-doc-string "regex.scm" "match:prefix")
4068 @deffn {Scheme Procedure} match:prefix match
4069 Return the unmatched portion of @var{target} preceding the regexp match.
4070
4071 @lisp
4072 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4073 (match:prefix s)
4074 @result{} "blah"
4075 @end lisp
4076 @end deffn
4077
4078 @c begin (scm-doc-string "regex.scm" "match:suffix")
4079 @deffn {Scheme Procedure} match:suffix match
4080 Return the unmatched portion of @var{target} following the regexp match.
4081 @end deffn
4082
4083 @lisp
4084 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4085 (match:suffix s)
4086 @result{} "foo"
4087 @end lisp
4088
4089 @c begin (scm-doc-string "regex.scm" "match:count")
4090 @deffn {Scheme Procedure} match:count match
4091 Return the number of parenthesized subexpressions from @var{match}.
4092 Note that the entire regular expression match itself counts as a
4093 subexpression, and failed submatches are included in the count.
4094 @end deffn
4095
4096 @c begin (scm-doc-string "regex.scm" "match:string")
4097 @deffn {Scheme Procedure} match:string match
4098 Return the original @var{target} string.
4099 @end deffn
4100
4101 @lisp
4102 (define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
4103 (match:string s)
4104 @result{} "blah2002foo"
4105 @end lisp
4106
4107
4108 @node Backslash Escapes
4109 @subsubsection Backslash Escapes
4110
4111 Sometimes you will want a regexp to match characters like @samp{*} or
4112 @samp{$} exactly. For example, to check whether a particular string
4113 represents a menu entry from an Info node, it would be useful to match
4114 it against a regexp like @samp{^* [^:]*::}. However, this won't work;
4115 because the asterisk is a metacharacter, it won't match the @samp{*} at
4116 the beginning of the string. In this case, we want to make the first
4117 asterisk un-magic.
4118
4119 You can do this by preceding the metacharacter with a backslash
4120 character @samp{\}. (This is also called @dfn{quoting} the
4121 metacharacter, and is known as a @dfn{backslash escape}.) When Guile
4122 sees a backslash in a regular expression, it considers the following
4123 glyph to be an ordinary character, no matter what special meaning it
4124 would ordinarily have. Therefore, we can make the above example work by
4125 changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells
4126 the regular expression engine to match only a single asterisk in the
4127 target string.
4128
4129 Since the backslash is itself a metacharacter, you may force a regexp to
4130 match a backslash in the target string by preceding the backslash with
4131 itself. For example, to find variable references in a @TeX{} program,
4132 you might want to find occurrences of the string @samp{\let\} followed
4133 by any number of alphabetic characters. The regular expression
4134 @samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the
4135 regexp each match a single backslash in the target string.
4136
4137 @c begin (scm-doc-string "regex.scm" "regexp-quote")
4138 @deffn {Scheme Procedure} regexp-quote str
4139 Quote each special character found in @var{str} with a backslash, and
4140 return the resulting string.
4141 @end deffn
4142
4143 @strong{Very important:} Using backslash escapes in Guile source code
4144 (as in Emacs Lisp or C) can be tricky, because the backslash character
4145 has special meaning for the Guile reader. For example, if Guile
4146 encounters the character sequence @samp{\n} in the middle of a string
4147 while processing Scheme code, it replaces those characters with a
4148 newline character. Similarly, the character sequence @samp{\t} is
4149 replaced by a horizontal tab. Several of these @dfn{escape sequences}
4150 are processed by the Guile reader before your code is executed.
4151 Unrecognized escape sequences are ignored: if the characters @samp{\*}
4152 appear in a string, they will be translated to the single character
4153 @samp{*}.
4154
4155 This translation is obviously undesirable for regular expressions, since
4156 we want to be able to include backslashes in a string in order to
4157 escape regexp metacharacters. Therefore, to make sure that a backslash
4158 is preserved in a string in your Guile program, you must use @emph{two}
4159 consecutive backslashes:
4160
4161 @lisp
4162 (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
4163 @end lisp
4164
4165 The string in this example is preprocessed by the Guile reader before
4166 any code is executed. The resulting argument to @code{make-regexp} is
4167 the string @samp{^\* [^:]*}, which is what we really want.
4168
4169 This also means that in order to write a regular expression that matches
4170 a single backslash character, the regular expression string in the
4171 source code must include @emph{four} backslashes. Each consecutive pair
4172 of backslashes gets translated by the Guile reader to a single
4173 backslash, and the resulting double-backslash is interpreted by the
4174 regexp engine as matching a single backslash character. Hence:
4175
4176 @lisp
4177 (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
4178 @end lisp
4179
4180 The reason for the unwieldiness of this syntax is historical. Both
4181 regular expression pattern matchers and Unix string processing systems
4182 have traditionally used backslashes with the special meanings
4183 described above. The POSIX regular expression specification and ANSI C
4184 standard both require these semantics. Attempting to abandon either
4185 convention would cause other kinds of compatibility problems, possibly
4186 more severe ones. Therefore, without extending the Scheme reader to
4187 support strings with different quoting conventions (an ungainly and
4188 confusing extension when implemented in other languages), we must adhere
4189 to this cumbersome escape syntax.
4190
4191
4192 @node Symbols
4193 @subsection Symbols
4194 @tpindex Symbols
4195
4196 Symbols in Scheme are widely used in three ways: as items of discrete
4197 data, as lookup keys for alists and hash tables, and to denote variable
4198 references.
4199
4200 A @dfn{symbol} is similar to a string in that it is defined by a
4201 sequence of characters. The sequence of characters is known as the
4202 symbol's @dfn{name}. In the usual case --- that is, where the symbol's
4203 name doesn't include any characters that could be confused with other
4204 elements of Scheme syntax --- a symbol is written in a Scheme program by
4205 writing the sequence of characters that make up the name, @emph{without}
4206 any quotation marks or other special syntax. For example, the symbol
4207 whose name is ``multiply-by-2'' is written, simply:
4208
4209 @lisp
4210 multiply-by-2
4211 @end lisp
4212
4213 Notice how this differs from a @emph{string} with contents
4214 ``multiply-by-2'', which is written with double quotation marks, like
4215 this:
4216
4217 @lisp
4218 "multiply-by-2"
4219 @end lisp
4220
4221 Looking beyond how they are written, symbols are different from strings
4222 in two important respects.
4223
4224 The first important difference is uniqueness. If the same-looking
4225 string is read twice from two different places in a program, the result
4226 is two @emph{different} string objects whose contents just happen to be
4227 the same. If, on the other hand, the same-looking symbol is read twice
4228 from two different places in a program, the result is the @emph{same}
4229 symbol object both times.
4230
4231 Given two read symbols, you can use @code{eq?} to test whether they are
4232 the same (that is, have the same name). @code{eq?} is the most
4233 efficient comparison operator in Scheme, and comparing two symbols like
4234 this is as fast as comparing, for example, two numbers. Given two
4235 strings, on the other hand, you must use @code{equal?} or
4236 @code{string=?}, which are much slower comparison operators, to
4237 determine whether the strings have the same contents.
4238
4239 @lisp
4240 (define sym1 (quote hello))
4241 (define sym2 (quote hello))
4242 (eq? sym1 sym2) @result{} #t
4243
4244 (define str1 "hello")
4245 (define str2 "hello")
4246 (eq? str1 str2) @result{} #f
4247 (equal? str1 str2) @result{} #t
4248 @end lisp
4249
4250 The second important difference is that symbols, unlike strings, are not
4251 self-evaluating. This is why we need the @code{(quote @dots{})}s in the
4252 example above: @code{(quote hello)} evaluates to the symbol named
4253 "hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
4254 symbol named "hello" and evaluated as a variable reference @dots{} about
4255 which more below (@pxref{Symbol Variables}).
4256
4257 @menu
4258 * Symbol Data:: Symbols as discrete data.
4259 * Symbol Keys:: Symbols as lookup keys.
4260 * Symbol Variables:: Symbols as denoting variables.
4261 * Symbol Primitives:: Operations related to symbols.
4262 * Symbol Props:: Function slots and property lists.
4263 * Symbol Read Syntax:: Extended read syntax for symbols.
4264 * Symbol Uninterned:: Uninterned symbols.
4265 @end menu
4266
4267
4268 @node Symbol Data
4269 @subsubsection Symbols as Discrete Data
4270
4271 Numbers and symbols are similar to the extent that they both lend
4272 themselves to @code{eq?} comparison. But symbols are more descriptive
4273 than numbers, because a symbol's name can be used directly to describe
4274 the concept for which that symbol stands.
4275
4276 For example, imagine that you need to represent some colours in a
4277 computer program. Using numbers, you would have to choose arbitrarily
4278 some mapping between numbers and colours, and then take care to use that
4279 mapping consistently:
4280
4281 @lisp
4282 ;; 1=red, 2=green, 3=purple
4283
4284 (if (eq? (colour-of car) 1)
4285 ...)
4286 @end lisp
4287
4288 @noindent
4289 You can make the mapping more explicit and the code more readable by
4290 defining constants:
4291
4292 @lisp
4293 (define red 1)
4294 (define green 2)
4295 (define purple 3)
4296
4297 (if (eq? (colour-of car) red)
4298 ...)
4299 @end lisp
4300
4301 @noindent
4302 But the simplest and clearest approach is not to use numbers at all, but
4303 symbols whose names specify the colours that they refer to:
4304
4305 @lisp
4306 (if (eq? (colour-of car) 'red)
4307 ...)
4308 @end lisp
4309
4310 The descriptive advantages of symbols over numbers increase as the set
4311 of concepts that you want to describe grows. Suppose that a car object
4312 can have other properties as well, such as whether it has or uses:
4313
4314 @itemize @bullet
4315 @item
4316 automatic or manual transmission
4317 @item
4318 leaded or unleaded fuel
4319 @item
4320 power steering (or not).
4321 @end itemize
4322
4323 @noindent
4324 Then a car's combined property set could be naturally represented and
4325 manipulated as a list of symbols:
4326
4327 @lisp
4328 (properties-of car1)
4329 @result{}
4330 (red manual unleaded power-steering)
4331
4332 (if (memq 'power-steering (properties-of car1))
4333 (display "Unfit people can drive this car.\n")
4334 (display "You'll need strong arms to drive this car!\n"))
4335 @print{}
4336 Unfit people can drive this car.
4337 @end lisp
4338
4339 Remember, the fundamental property of symbols that we are relying on
4340 here is that an occurrence of @code{'red} in one part of a program is an
4341 @emph{indistinguishable} symbol from an occurrence of @code{'red} in
4342 another part of a program; this means that symbols can usefully be
4343 compared using @code{eq?}. At the same time, symbols have naturally
4344 descriptive names. This combination of efficiency and descriptive power
4345 makes them ideal for use as discrete data.
4346
4347
4348 @node Symbol Keys
4349 @subsubsection Symbols as Lookup Keys
4350
4351 Given their efficiency and descriptive power, it is natural to use
4352 symbols as the keys in an association list or hash table.
4353
4354 To illustrate this, consider a more structured representation of the car
4355 properties example from the preceding subsection. Rather than
4356 mixing all the properties up together in a flat list, we could use an
4357 association list like this:
4358
4359 @lisp
4360 (define car1-properties '((colour . red)
4361 (transmission . manual)
4362 (fuel . unleaded)
4363 (steering . power-assisted)))
4364 @end lisp
4365
4366 Notice how this structure is more explicit and extensible than the flat
4367 list. For example it makes clear that @code{manual} refers to the
4368 transmission rather than, say, the windows or the locking of the car.
4369 It also allows further properties to use the same symbols among their
4370 possible values without becoming ambiguous:
4371
4372 @lisp
4373 (define car1-properties '((colour . red)
4374 (transmission . manual)
4375 (fuel . unleaded)
4376 (steering . power-assisted)
4377 (seat-colour . red)
4378 (locking . manual)))
4379 @end lisp
4380
4381 With a representation like this, it is easy to use the efficient
4382 @code{assq-XXX} family of procedures (@pxref{Association Lists}) to
4383 extract or change individual pieces of information:
4384
4385 @lisp
4386 (assq-ref car1-properties 'fuel) @result{} unleaded
4387 (assq-ref car1-properties 'transmission) @result{} manual
4388
4389 (assq-set! car1-properties 'seat-colour 'black)
4390 @result{}
4391 ((colour . red)
4392 (transmission . manual)
4393 (fuel . unleaded)
4394 (steering . power-assisted)
4395 (seat-colour . black)
4396 (locking . manual)))
4397 @end lisp
4398
4399 Hash tables also have keys, and exactly the same arguments apply to the
4400 use of symbols in hash tables as in association lists. The hash value
4401 that Guile uses to decide where to add a symbol-keyed entry to a hash
4402 table can be obtained by calling the @code{symbol-hash} procedure:
4403
4404 @deffn {Scheme Procedure} symbol-hash symbol
4405 @deffnx {C Function} scm_symbol_hash (symbol)
4406 Return a hash value for @var{symbol}.
4407 @end deffn
4408
4409 See @ref{Hash Tables} for information about hash tables in general, and
4410 for why you might choose to use a hash table rather than an association
4411 list.
4412
4413
4414 @node Symbol Variables
4415 @subsubsection Symbols as Denoting Variables
4416
4417 When an unquoted symbol in a Scheme program is evaluated, it is
4418 interpreted as a variable reference, and the result of the evaluation is
4419 the appropriate variable's value.
4420
4421 For example, when the expression @code{(string-length "abcd")} is read
4422 and evaluated, the sequence of characters @code{string-length} is read
4423 as the symbol whose name is "string-length". This symbol is associated
4424 with a variable whose value is the procedure that implements string
4425 length calculation. Therefore evaluation of the @code{string-length}
4426 symbol results in that procedure.
4427
4428 The details of the connection between an unquoted symbol and the
4429 variable to which it refers are explained elsewhere. See @ref{Binding
4430 Constructs}, for how associations between symbols and variables are
4431 created, and @ref{Modules}, for how those associations are affected by
4432 Guile's module system.
4433
4434
4435 @node Symbol Primitives
4436 @subsubsection Operations Related to Symbols
4437
4438 Given any Scheme value, you can determine whether it is a symbol using
4439 the @code{symbol?} primitive:
4440
4441 @rnindex symbol?
4442 @deffn {Scheme Procedure} symbol? obj
4443 @deffnx {C Function} scm_symbol_p (obj)
4444 Return @code{#t} if @var{obj} is a symbol, otherwise return
4445 @code{#f}.
4446 @end deffn
4447
4448 @deftypefn {C Function} int scm_is_symbol (SCM val)
4449 Equivalent to @code{scm_is_true (scm_symbol_p (val))}.
4450 @end deftypefn
4451
4452 Once you know that you have a symbol, you can obtain its name as a
4453 string by calling @code{symbol->string}. Note that Guile differs by
4454 default from R5RS on the details of @code{symbol->string} as regards
4455 case-sensitivity:
4456
4457 @rnindex symbol->string
4458 @deffn {Scheme Procedure} symbol->string s
4459 @deffnx {C Function} scm_symbol_to_string (s)
4460 Return the name of symbol @var{s} as a string. By default, Guile reads
4461 symbols case-sensitively, so the string returned will have the same case
4462 variation as the sequence of characters that caused @var{s} to be
4463 created.
4464
4465 If Guile is set to read symbols case-insensitively (as specified by
4466 R5RS), and @var{s} comes into being as part of a literal expression
4467 (@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
4468 by a call to the @code{read} or @code{string-ci->symbol} procedures,
4469 Guile converts any alphabetic characters in the symbol's name to
4470 lower case before creating the symbol object, so the string returned
4471 here will be in lower case.
4472
4473 If @var{s} was created by @code{string->symbol}, the case of characters
4474 in the string returned will be the same as that in the string that was
4475 passed to @code{string->symbol}, regardless of Guile's case-sensitivity
4476 setting at the time @var{s} was created.
4477
4478 It is an error to apply mutation procedures like @code{string-set!} to
4479 strings returned by this procedure.
4480 @end deffn
4481
4482 Most symbols are created by writing them literally in code. However it
4483 is also possible to create symbols programmatically using the following
4484 @code{string->symbol} and @code{string-ci->symbol} procedures:
4485
4486 @rnindex string->symbol
4487 @deffn {Scheme Procedure} string->symbol string
4488 @deffnx {C Function} scm_string_to_symbol (string)
4489 Return the symbol whose name is @var{string}. This procedure can create
4490 symbols with names containing special characters or letters in the
4491 non-standard case, but it is usually a bad idea to create such symbols
4492 because in some implementations of Scheme they cannot be read as
4493 themselves.
4494 @end deffn
4495
4496 @deffn {Scheme Procedure} string-ci->symbol str
4497 @deffnx {C Function} scm_string_ci_to_symbol (str)
4498 Return the symbol whose name is @var{str}. If Guile is currently
4499 reading symbols case-insensitively, @var{str} is converted to lowercase
4500 before the returned symbol is looked up or created.
4501 @end deffn
4502
4503 The following examples illustrate Guile's detailed behaviour as regards
4504 the case-sensitivity of symbols:
4505
4506 @lisp
4507 (read-enable 'case-insensitive) ; R5RS compliant behaviour
4508
4509 (symbol->string 'flying-fish) @result{} "flying-fish"
4510 (symbol->string 'Martin) @result{} "martin"
4511 (symbol->string
4512 (string->symbol "Malvina")) @result{} "Malvina"
4513
4514 (eq? 'mISSISSIppi 'mississippi) @result{} #t
4515 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
4516 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
4517 (eq? 'LolliPop
4518 (string->symbol (symbol->string 'LolliPop))) @result{} #t
4519 (string=? "K. Harper, M.D."
4520 (symbol->string
4521 (string->symbol "K. Harper, M.D."))) @result{} #t
4522
4523 (read-disable 'case-insensitive) ; Guile default behaviour
4524
4525 (symbol->string 'flying-fish) @result{} "flying-fish"
4526 (symbol->string 'Martin) @result{} "Martin"
4527 (symbol->string
4528 (string->symbol "Malvina")) @result{} "Malvina"
4529
4530 (eq? 'mISSISSIppi 'mississippi) @result{} #f
4531 (string->symbol "mISSISSIppi") @result{} mISSISSIppi
4532 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
4533 (eq? 'LolliPop
4534 (string->symbol (symbol->string 'LolliPop))) @result{} #t
4535 (string=? "K. Harper, M.D."
4536 (symbol->string
4537 (string->symbol "K. Harper, M.D."))) @result{} #t
4538 @end lisp
4539
4540 From C, there are lower level functions that construct a Scheme symbol
4541 from a C string in the current locale encoding.
4542
4543 When you want to do more from C, you should convert between symbols
4544 and strings using @code{scm_symbol_to_string} and
4545 @code{scm_string_to_symbol} and work with the strings.
4546
4547 @deffn {C Function} scm_from_locale_symbol (const char *name)
4548 @deffnx {C Function} scm_from_locale_symboln (const char *name, size_t len)
4549 Construct and return a Scheme symbol whose name is specified by
4550 @var{name}. For @code{scm_from_locale_symbol}, @var{name} must be null
4551 terminated; for @code{scm_from_locale_symboln} the length of @var{name} is
4552 specified explicitly by @var{len}.
4553 @end deffn
4554
4555 @deftypefn {C Function} SCM scm_take_locale_symbol (char *str)
4556 @deftypefnx {C Function} SCM scm_take_locale_symboln (char *str, size_t len)
4557 Like @code{scm_from_locale_symbol} and @code{scm_from_locale_symboln},
4558 respectively, but also frees @var{str} with @code{free} eventually.
4559 Thus, you can use this function when you would free @var{str} anyway
4560 immediately after creating the Scheme string. In certain cases, Guile
4561 can then use @var{str} directly as its internal representation.
4562 @end deftypefn
4563
4564
4565 Finally, some applications, especially those that generate new Scheme
4566 code dynamically, need to generate symbols for use in the generated
4567 code. The @code{gensym} primitive meets this need:
4568
4569 @deffn {Scheme Procedure} gensym [prefix]
4570 @deffnx {C Function} scm_gensym (prefix)
4571 Create a new symbol with a name constructed from a prefix and a counter
4572 value. The string @var{prefix} can be specified as an optional
4573 argument. Default prefix is @samp{@w{ g}}. The counter is increased by 1
4574 at each call. There is no provision for resetting the counter.
4575 @end deffn
4576
4577 The symbols generated by @code{gensym} are @emph{likely} to be unique,
4578 since their names begin with a space and it is only otherwise possible
4579 to generate such symbols if a programmer goes out of their way to do
4580 so. Uniqueness can be guaranteed by instead using uninterned symbols
4581 (@pxref{Symbol Uninterned}), though they can't be usefully written out
4582 and read back in.
4583
4584
4585 @node Symbol Props
4586 @subsubsection Function Slots and Property Lists
4587
4588 In traditional Lisp dialects, symbols are often understood as having
4589 three kinds of value at once:
4590
4591 @itemize @bullet
4592 @item
4593 a @dfn{variable} value, which is used when the symbol appears in
4594 code in a variable reference context
4595
4596 @item
4597 a @dfn{function} value, which is used when the symbol appears in
4598 code in a function name position (i.e. as the first element in an
4599 unquoted list)
4600
4601 @item
4602 a @dfn{property list} value, which is used when the symbol is given as
4603 the first argument to Lisp's @code{put} or @code{get} functions.
4604 @end itemize
4605
4606 Although Scheme (as one of its simplifications with respect to Lisp)
4607 does away with the distinction between variable and function namespaces,
4608 Guile currently retains some elements of the traditional structure in
4609 case they turn out to be useful when implementing translators for other
4610 languages, in particular Emacs Lisp.
4611
4612 Specifically, Guile symbols have two extra slots. for a symbol's
4613 property list, and for its ``function value.'' The following procedures
4614 are provided to access these slots.
4615
4616 @deffn {Scheme Procedure} symbol-fref symbol
4617 @deffnx {C Function} scm_symbol_fref (symbol)
4618 Return the contents of @var{symbol}'s @dfn{function slot}.
4619 @end deffn
4620
4621 @deffn {Scheme Procedure} symbol-fset! symbol value
4622 @deffnx {C Function} scm_symbol_fset_x (symbol, value)
4623 Set the contents of @var{symbol}'s function slot to @var{value}.
4624 @end deffn
4625
4626 @deffn {Scheme Procedure} symbol-pref symbol
4627 @deffnx {C Function} scm_symbol_pref (symbol)
4628 Return the @dfn{property list} currently associated with @var{symbol}.
4629 @end deffn
4630
4631 @deffn {Scheme Procedure} symbol-pset! symbol value
4632 @deffnx {C Function} scm_symbol_pset_x (symbol, value)
4633 Set @var{symbol}'s property list to @var{value}.
4634 @end deffn
4635
4636 @deffn {Scheme Procedure} symbol-property sym prop
4637 From @var{sym}'s property list, return the value for property
4638 @var{prop}. The assumption is that @var{sym}'s property list is an
4639 association list whose keys are distinguished from each other using
4640 @code{equal?}; @var{prop} should be one of the keys in that list. If
4641 the property list has no entry for @var{prop}, @code{symbol-property}
4642 returns @code{#f}.
4643 @end deffn
4644
4645 @deffn {Scheme Procedure} set-symbol-property! sym prop val
4646 In @var{sym}'s property list, set the value for property @var{prop} to
4647 @var{val}, or add a new entry for @var{prop}, with value @var{val}, if
4648 none already exists. For the structure of the property list, see
4649 @code{symbol-property}.
4650 @end deffn
4651
4652 @deffn {Scheme Procedure} symbol-property-remove! sym prop
4653 From @var{sym}'s property list, remove the entry for property
4654 @var{prop}, if there is one. For the structure of the property list,
4655 see @code{symbol-property}.
4656 @end deffn
4657
4658 Support for these extra slots may be removed in a future release, and it
4659 is probably better to avoid using them. (In release 1.6, Guile itself
4660 uses the property list slot sparingly, and the function slot not at
4661 all.) For a more modern and Schemely approach to properties, see
4662 @ref{Object Properties}.
4663
4664
4665 @node Symbol Read Syntax
4666 @subsubsection Extended Read Syntax for Symbols
4667
4668 The read syntax for a symbol is a sequence of letters, digits, and
4669 @dfn{extended alphabetic characters}, beginning with a character that
4670 cannot begin a number. In addition, the special cases of @code{+},
4671 @code{-}, and @code{...} are read as symbols even though numbers can
4672 begin with @code{+}, @code{-} or @code{.}.
4673
4674 Extended alphabetic characters may be used within identifiers as if
4675 they were letters. The set of extended alphabetic characters is:
4676
4677 @example
4678 ! $ % & * + - . / : < = > ? @@ ^ _ ~
4679 @end example
4680
4681 In addition to the standard read syntax defined above (which is taken
4682 from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
4683 Scheme})), Guile provides an extended symbol read syntax that allows the
4684 inclusion of unusual characters such as space characters, newlines and
4685 parentheses. If (for whatever reason) you need to write a symbol
4686 containing characters not mentioned above, you can do so as follows.
4687
4688 @itemize @bullet
4689 @item
4690 Begin the symbol with the characters @code{#@{},
4691
4692 @item
4693 write the characters of the symbol and
4694
4695 @item
4696 finish the symbol with the characters @code{@}#}.
4697 @end itemize
4698
4699 Here are a few examples of this form of read syntax. The first symbol
4700 needs to use extended syntax because it contains a space character, the
4701 second because it contains a line break, and the last because it looks
4702 like a number.
4703
4704 @lisp
4705 #@{foo bar@}#
4706
4707 #@{what
4708 ever@}#
4709
4710 #@{4242@}#
4711 @end lisp
4712
4713 Although Guile provides this extended read syntax for symbols,
4714 widespread usage of it is discouraged because it is not portable and not
4715 very readable.
4716
4717
4718 @node Symbol Uninterned
4719 @subsubsection Uninterned Symbols
4720
4721 What makes symbols useful is that they are automatically kept unique.
4722 There are no two symbols that are distinct objects but have the same
4723 name. But of course, there is no rule without exception. In addition
4724 to the normal symbols that have been discussed up to now, you can also
4725 create special @dfn{uninterned} symbols that behave slightly
4726 differently.
4727
4728 To understand what is different about them and why they might be useful,
4729 we look at how normal symbols are actually kept unique.
4730
4731 Whenever Guile wants to find the symbol with a specific name, for
4732 example during @code{read} or when executing @code{string->symbol}, it
4733 first looks into a table of all existing symbols to find out whether a
4734 symbol with the given name already exists. When this is the case, Guile
4735 just returns that symbol. When not, a new symbol with the name is
4736 created and entered into the table so that it can be found later.
4737
4738 Sometimes you might want to create a symbol that is guaranteed `fresh',
4739 i.e. a symbol that did not exist previously. You might also want to
4740 somehow guarantee that no one else will ever unintentionally stumble
4741 across your symbol in the future. These properties of a symbol are
4742 often needed when generating code during macro expansion. When
4743 introducing new temporary variables, you want to guarantee that they
4744 don't conflict with variables in other people's code.
4745
4746 The simplest way to arrange for this is to create a new symbol but
4747 not enter it into the global table of all symbols. That way, no one
4748 will ever get access to your symbol by chance. Symbols that are not in
4749 the table are called @dfn{uninterned}. Of course, symbols that
4750 @emph{are} in the table are called @dfn{interned}.
4751
4752 You create new uninterned symbols with the function @code{make-symbol}.
4753 You can test whether a symbol is interned or not with
4754 @code{symbol-interned?}.
4755
4756 Uninterned symbols break the rule that the name of a symbol uniquely
4757 identifies the symbol object. Because of this, they can not be written
4758 out and read back in like interned symbols. Currently, Guile has no
4759 support for reading uninterned symbols. Note that the function
4760 @code{gensym} does not return uninterned symbols for this reason.
4761
4762 @deffn {Scheme Procedure} make-symbol name
4763 @deffnx {C Function} scm_make_symbol (name)
4764 Return a new uninterned symbol with the name @var{name}. The returned
4765 symbol is guaranteed to be unique and future calls to
4766 @code{string->symbol} will not return it.
4767 @end deffn
4768
4769 @deffn {Scheme Procedure} symbol-interned? symbol
4770 @deffnx {C Function} scm_symbol_interned_p (symbol)
4771 Return @code{#t} if @var{symbol} is interned, otherwise return
4772 @code{#f}.
4773 @end deffn
4774
4775 For example:
4776
4777 @lisp
4778 (define foo-1 (string->symbol "foo"))
4779 (define foo-2 (string->symbol "foo"))
4780 (define foo-3 (make-symbol "foo"))
4781 (define foo-4 (make-symbol "foo"))
4782
4783 (eq? foo-1 foo-2)
4784 @result{} #t
4785 ; Two interned symbols with the same name are the same object,
4786
4787 (eq? foo-1 foo-3)
4788 @result{} #f
4789 ; but a call to make-symbol with the same name returns a
4790 ; distinct object.
4791
4792 (eq? foo-3 foo-4)
4793 @result{} #f
4794 ; A call to make-symbol always returns a new object, even for
4795 ; the same name.
4796
4797 foo-3
4798 @result{} #<uninterned-symbol foo 8085290>
4799 ; Uninterned symbols print differently from interned symbols,
4800
4801 (symbol? foo-3)
4802 @result{} #t
4803 ; but they are still symbols,
4804
4805 (symbol-interned? foo-3)
4806 @result{} #f
4807 ; just not interned.
4808 @end lisp
4809
4810
4811 @node Keywords
4812 @subsection Keywords
4813 @tpindex Keywords
4814
4815 Keywords are self-evaluating objects with a convenient read syntax that
4816 makes them easy to type.
4817
4818 Guile's keyword support conforms to R5RS, and adds a (switchable) read
4819 syntax extension to permit keywords to begin with @code{:} as well as
4820 @code{#:}.
4821
4822 @menu
4823 * Why Use Keywords?:: Motivation for keyword usage.
4824 * Coding With Keywords:: How to use keywords.
4825 * Keyword Read Syntax:: Read syntax for keywords.
4826 * Keyword Procedures:: Procedures for dealing with keywords.
4827 @end menu
4828
4829 @node Why Use Keywords?
4830 @subsubsection Why Use Keywords?
4831
4832 Keywords are useful in contexts where a program or procedure wants to be
4833 able to accept a large number of optional arguments without making its
4834 interface unmanageable.
4835
4836 To illustrate this, consider a hypothetical @code{make-window}
4837 procedure, which creates a new window on the screen for drawing into
4838 using some graphical toolkit. There are many parameters that the caller
4839 might like to specify, but which could also be sensibly defaulted, for
4840 example:
4841
4842 @itemize @bullet
4843 @item
4844 color depth -- Default: the color depth for the screen
4845
4846 @item
4847 background color -- Default: white
4848
4849 @item
4850 width -- Default: 600
4851
4852 @item
4853 height -- Default: 400
4854 @end itemize
4855
4856 If @code{make-window} did not use keywords, the caller would have to
4857 pass in a value for each possible argument, remembering the correct
4858 argument order and using a special value to indicate the default value
4859 for that argument:
4860
4861 @lisp
4862 (make-window 'default ;; Color depth
4863 'default ;; Background color
4864 800 ;; Width
4865 100 ;; Height
4866 @dots{}) ;; More make-window arguments
4867 @end lisp
4868
4869 With keywords, on the other hand, defaulted arguments are omitted, and
4870 non-default arguments are clearly tagged by the appropriate keyword. As
4871 a result, the invocation becomes much clearer:
4872
4873 @lisp
4874 (make-window #:width 800 #:height 100)
4875 @end lisp
4876
4877 On the other hand, for a simpler procedure with few arguments, the use
4878 of keywords would be a hindrance rather than a help. The primitive
4879 procedure @code{cons}, for example, would not be improved if it had to
4880 be invoked as
4881
4882 @lisp
4883 (cons #:car x #:cdr y)
4884 @end lisp
4885
4886 So the decision whether to use keywords or not is purely pragmatic: use
4887 them if they will clarify the procedure invocation at point of call.
4888
4889 @node Coding With Keywords
4890 @subsubsection Coding With Keywords
4891
4892 If a procedure wants to support keywords, it should take a rest argument
4893 and then use whatever means is convenient to extract keywords and their
4894 corresponding arguments from the contents of that rest argument.
4895
4896 The following example illustrates the principle: the code for
4897 @code{make-window} uses a helper procedure called
4898 @code{get-keyword-value} to extract individual keyword arguments from
4899 the rest argument.
4900
4901 @lisp
4902 (define (get-keyword-value args keyword default)
4903 (let ((kv (memq keyword args)))
4904 (if (and kv (>= (length kv) 2))
4905 (cadr kv)
4906 default)))
4907
4908 (define (make-window . args)
4909 (let ((depth (get-keyword-value args #:depth screen-depth))
4910 (bg (get-keyword-value args #:bg "white"))
4911 (width (get-keyword-value args #:width 800))
4912 (height (get-keyword-value args #:height 100))
4913 @dots{})
4914 @dots{}))
4915 @end lisp
4916
4917 But you don't need to write @code{get-keyword-value}. The @code{(ice-9
4918 optargs)} module provides a set of powerful macros that you can use to
4919 implement keyword-supporting procedures like this:
4920
4921 @lisp
4922 (use-modules (ice-9 optargs))
4923
4924 (define (make-window . args)
4925 (let-keywords args #f ((depth screen-depth)
4926 (bg "white")
4927 (width 800)
4928 (height 100))
4929 ...))
4930 @end lisp
4931
4932 @noindent
4933 Or, even more economically, like this:
4934
4935 @lisp
4936 (use-modules (ice-9 optargs))
4937
4938 (define* (make-window #:key (depth screen-depth)
4939 (bg "white")
4940 (width 800)
4941 (height 100))
4942 ...)
4943 @end lisp
4944
4945 For further details on @code{let-keywords}, @code{define*} and other
4946 facilities provided by the @code{(ice-9 optargs)} module, see
4947 @ref{Optional Arguments}.
4948
4949
4950 @node Keyword Read Syntax
4951 @subsubsection Keyword Read Syntax
4952
4953 Guile, by default, only recognizes a keyword syntax that is compatible
4954 with R5RS. A token of the form @code{#:NAME}, where @code{NAME} has the
4955 same syntax as a Scheme symbol (@pxref{Symbol Read Syntax}), is the
4956 external representation of the keyword named @code{NAME}. Keyword
4957 objects print using this syntax as well, so values containing keyword
4958 objects can be read back into Guile. When used in an expression,
4959 keywords are self-quoting objects.
4960
4961 If the @code{keyword} read option is set to @code{'prefix}, Guile also
4962 recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
4963 of the form @code{:NAME} are read as symbols, as required by R5RS.
4964
4965 To enable and disable the alternative non-R5RS keyword syntax, you use
4966 the @code{read-set!} procedure documented in @ref{User level options
4967 interfaces} and @ref{Reader options}.
4968
4969 @smalllisp
4970 (read-set! keywords 'prefix)
4971
4972 #:type
4973 @result{}
4974 #:type
4975
4976 :type
4977 @result{}
4978 #:type
4979
4980 (read-set! keywords #f)
4981
4982 #:type
4983 @result{}
4984 #:type
4985
4986 :type
4987 @print{}
4988 ERROR: In expression :type:
4989 ERROR: Unbound variable: :type
4990 ABORT: (unbound-variable)
4991 @end smalllisp
4992
4993 @node Keyword Procedures
4994 @subsubsection Keyword Procedures
4995
4996 @deffn {Scheme Procedure} keyword? obj
4997 @deffnx {C Function} scm_keyword_p (obj)
4998 Return @code{#t} if the argument @var{obj} is a keyword, else
4999 @code{#f}.
5000 @end deffn
5001
5002 @deffn {Scheme Procedure} keyword->symbol keyword
5003 @deffnx {C Function} scm_keyword_to_symbol (keyword)
5004 Return the symbol with the same name as @var{keyword}.
5005 @end deffn
5006
5007 @deffn {Scheme Procedure} symbol->keyword symbol
5008 @deffnx {C Function} scm_symbol_to_keyword (symbol)
5009 Return the keyword with the same name as @var{symbol}.
5010 @end deffn
5011
5012 @deftypefn {C Function} int scm_is_keyword (SCM obj)
5013 Equivalent to @code{scm_is_true (scm_keyword_p (@var{obj}))}.
5014 @end deftypefn
5015
5016 @deftypefn {C Function} SCM scm_from_locale_keyword (const char *str)
5017 @deftypefnx {C Function} SCM scm_from_locale_keywordn (const char *str, size_t len)
5018 Equivalent to @code{scm_symbol_to_keyword (scm_from_locale_symbol
5019 (@var{str}))} and @code{scm_symbol_to_keyword (scm_from_locale_symboln
5020 (@var{str}, @var{len}))}, respectively.
5021 @end deftypefn
5022
5023 @node Other Types
5024 @subsection ``Functionality-Centric'' Data Types
5025
5026 Procedures and macros are documented in their own chapter: see
5027 @ref{Procedures and Macros}.
5028
5029 Variable objects are documented as part of the description of Guile's
5030 module system: see @ref{Variables}.
5031
5032 Asyncs, dynamic roots and fluids are described in the chapter on
5033 scheduling: see @ref{Scheduling}.
5034
5035 Hooks are documented in the chapter on general utility functions: see
5036 @ref{Hooks}.
5037
5038 Ports are described in the chapter on I/O: see @ref{Input and Output}.
5039
5040
5041 @c Local Variables:
5042 @c TeX-master: "guile.texi"
5043 @c End: