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