Commit | Line | Data |
---|---|---|
a0e07ba4 | 1 | @page |
4c731ece NJ |
2 | @node Simple Data Types |
3 | @chapter Simple Generic Data Types | |
a0e07ba4 | 4 | |
4c731ece NJ |
5 | This chapter describes those of Guile's simple data types which are |
6 | primarily are used for their role as items of generic data. By | |
7 | @dfn{simple} we mean data types that are not primarily used as | |
8 | containers to hold other data --- i.e. pairs, lists, vectors and so on. | |
9 | For the documentation of such @dfn{compound} data types, see | |
10 | @ref{Compound Data Types}. | |
a0e07ba4 NJ |
11 | |
12 | One of the great strengths of Scheme is that there is no straightforward | |
13 | distinction between ``data'' and ``functionality''. For example, | |
14 | Guile's support for dynamic linking could be described | |
15 | ||
16 | @itemize @bullet | |
17 | @item | |
18 | either in a ``data-centric'' way, as the behaviour and properties of the | |
19 | ``dynamically linked object'' data type, and the operations that may be | |
20 | applied to instances of this type | |
21 | ||
22 | @item | |
23 | or in a ``functionality-centric'' way, as the set of procedures that | |
24 | constitute Guile's support for dynamic linking, in the context of the | |
25 | module system. | |
26 | @end itemize | |
27 | ||
85a9b4ed | 28 | The contents of this chapter are, therefore, a matter of judgment. By |
4c731ece | 29 | @dfn{generic}, we mean to select those data types whose typical use as |
a0e07ba4 NJ |
30 | @emph{data} in a wide variety of programming contexts is more important |
31 | than their use in the implementation of a particular piece of | |
4c731ece NJ |
32 | @emph{functionality}. The last section of this chapter provides |
33 | references for all the data types that are documented not here but in a | |
34 | ``functionality-centric'' way elsewhere in the manual. | |
a0e07ba4 NJ |
35 | |
36 | @menu | |
37 | * Booleans:: True/false values. | |
38 | * Numbers:: Numerical data types. | |
39 | * Characters:: New character names. | |
40 | * Strings:: Special things about strings. | |
41 | * Regular Expressions:: Pattern matching and substitution. | |
2a946b44 | 42 | * Symbols:: Symbols. |
a0e07ba4 | 43 | * Keywords:: Self-quoting, customizable display keywords. |
4c731ece | 44 | * Other Types:: "Functionality-centric" data types. |
a0e07ba4 NJ |
45 | @end menu |
46 | ||
47 | ||
48 | @node Booleans | |
49 | @section Booleans | |
50 | @tpindex Booleans | |
51 | ||
52 | The two boolean values are @code{#t} for true and @code{#f} for false. | |
53 | ||
54 | Boolean values are returned by predicate procedures, such as the general | |
55 | equality predicates @code{eq?}, @code{eqv?} and @code{equal?} | |
56 | (@pxref{Equality}) and numerical and string comparison operators like | |
57 | @code{string=?} (@pxref{String Comparison}) and @code{<=} | |
58 | (@pxref{Comparison}). | |
59 | ||
60 | @lisp | |
61 | (<= 3 8) | |
62 | @result{} | |
63 | #t | |
64 | ||
65 | (<= 3 -3) | |
66 | @result{} | |
67 | #f | |
68 | ||
69 | (equal? "house" "houses") | |
70 | @result{} | |
71 | #f | |
72 | ||
73 | (eq? #f #f) | |
74 | @result{} | |
75 | #t | |
76 | @end lisp | |
77 | ||
78 | In test condition contexts like @code{if} and @code{cond} (@pxref{if | |
79 | cond case}), where a group of subexpressions will be evaluated only if a | |
80 | @var{condition} expression evaluates to ``true'', ``true'' means any | |
81 | value at all except @code{#f}. | |
82 | ||
83 | @lisp | |
84 | (if #t "yes" "no") | |
85 | @result{} | |
86 | "yes" | |
87 | ||
88 | (if 0 "yes" "no") | |
89 | @result{} | |
90 | "yes" | |
91 | ||
92 | (if #f "yes" "no") | |
93 | @result{} | |
94 | "no" | |
95 | @end lisp | |
96 | ||
97 | A result of this asymmetry is that typical Scheme source code more often | |
98 | uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to | |
99 | represent an @code{if} or @code{cond} false value, whereas @code{#t} is | |
100 | not necessary to represent an @code{if} or @code{cond} true value. | |
101 | ||
102 | It is important to note that @code{#f} is @strong{not} equivalent to any | |
103 | other Scheme value. In particular, @code{#f} is not the same as the | |
104 | number 0 (like in C and C++), and not the same as the ``empty list'' | |
105 | (like in some Lisp dialects). | |
106 | ||
107 | The @code{not} procedure returns the boolean inverse of its argument: | |
108 | ||
109 | @rnindex not | |
8f85c0c6 NJ |
110 | @deffn {Scheme Procedure} not x |
111 | @deffnx {C Function} scm_not (x) | |
a0e07ba4 NJ |
112 | Return @code{#t} iff @var{x} is @code{#f}, else return @code{#f}. |
113 | @end deffn | |
114 | ||
115 | The @code{boolean?} procedure is a predicate that returns @code{#t} if | |
116 | its argument is one of the boolean values, otherwise @code{#f}. | |
117 | ||
118 | @rnindex boolean? | |
8f85c0c6 NJ |
119 | @deffn {Scheme Procedure} boolean? obj |
120 | @deffnx {C Function} scm_boolean_p (obj) | |
a0e07ba4 NJ |
121 | Return @code{#t} iff @var{obj} is either @code{#t} or @code{#f}. |
122 | @end deffn | |
123 | ||
124 | ||
125 | @node Numbers | |
126 | @section Numerical data types | |
127 | @tpindex Numbers | |
128 | ||
129 | Guile supports a rich ``tower'' of numerical types --- integer, | |
130 | rational, real and complex --- and provides an extensive set of | |
131 | mathematical and scientific functions for operating on numerical | |
132 | data. This section of the manual documents those types and functions. | |
133 | ||
134 | You may also find it illuminating to read R5RS's presentation of numbers | |
135 | in Scheme, which is particularly clear and accessible: see | |
136 | @xref{Numbers,,,r5rs}. | |
137 | ||
138 | @menu | |
139 | * Numerical Tower:: Scheme's numerical "tower". | |
140 | * Integers:: Whole numbers. | |
141 | * Reals and Rationals:: Real and rational numbers. | |
142 | * Complex Numbers:: Complex numbers. | |
143 | * Exactness:: Exactness and inexactness. | |
144 | * Number Syntax:: Read syntax for numerical data. | |
145 | * Integer Operations:: Operations on integer values. | |
146 | * Comparison:: Comparison predicates. | |
147 | * Conversion:: Converting numbers to and from strings. | |
148 | * Complex:: Complex number operations. | |
149 | * Arithmetic:: Arithmetic functions. | |
150 | * Scientific:: Scientific functions. | |
151 | * Primitive Numerics:: Primitive numeric functions. | |
152 | * Bitwise Operations:: Logical AND, OR, NOT, and so on. | |
153 | * Random:: Random number generation. | |
154 | @end menu | |
155 | ||
156 | ||
157 | @node Numerical Tower | |
158 | @subsection Scheme's Numerical ``Tower'' | |
159 | @rnindex number? | |
160 | ||
161 | Scheme's numerical ``tower'' consists of the following categories of | |
162 | numbers: | |
163 | ||
164 | @itemize @bullet | |
165 | @item | |
166 | integers (whole numbers) | |
167 | ||
168 | @item | |
169 | rationals (the set of numbers that can be expressed as P/Q where P and Q | |
170 | are integers) | |
171 | ||
172 | @item | |
173 | real numbers (the set of numbers that describes all possible positions | |
174 | along a one dimensional line) | |
175 | ||
176 | @item | |
177 | complex numbers (the set of numbers that describes all possible | |
178 | positions in a two dimensional space) | |
179 | @end itemize | |
180 | ||
181 | It is called a tower because each category ``sits on'' the one that | |
182 | follows it, in the sense that every integer is also a rational, every | |
183 | rational is also real, and every real number is also a complex number | |
184 | (but with zero imaginary part). | |
185 | ||
186 | Of these, Guile implements integers, reals and complex numbers as | |
187 | distinct types. Rationals are implemented as regards the read syntax | |
188 | for rational numbers that is specified by R5RS, but are immediately | |
189 | converted by Guile to the corresponding real number. | |
190 | ||
191 | The @code{number?} predicate may be applied to any Scheme value to | |
192 | discover whether the value is any of the supported numerical types. | |
193 | ||
8f85c0c6 NJ |
194 | @deffn {Scheme Procedure} number? obj |
195 | @deffnx {C Function} scm_number_p (obj) | |
a0e07ba4 | 196 | Return @code{#t} if @var{obj} is any kind of number, @code{#f} else. |
8f85c0c6 | 197 | @findex number? |
a0e07ba4 NJ |
198 | @end deffn |
199 | ||
200 | For example: | |
201 | ||
202 | @lisp | |
203 | (number? 3) | |
204 | @result{} | |
205 | #t | |
206 | ||
207 | (number? "hello there!") | |
208 | @result{} | |
209 | #f | |
210 | ||
211 | (define pi 3.141592654) | |
212 | (number? pi) | |
213 | @result{} | |
214 | #t | |
215 | @end lisp | |
216 | ||
217 | The next few subsections document each of Guile's numerical data types | |
218 | in detail. | |
219 | ||
220 | @node Integers | |
221 | @subsection Integers | |
222 | ||
223 | @tpindex Integer numbers | |
224 | ||
225 | @rnindex integer? | |
226 | ||
227 | Integers are whole numbers, that is numbers with no fractional part, | |
228 | such as 2, 83 and -3789. | |
229 | ||
230 | Integers in Guile can be arbitrarily big, as shown by the following | |
231 | example. | |
232 | ||
233 | @lisp | |
234 | (define (factorial n) | |
235 | (let loop ((n n) (product 1)) | |
236 | (if (= n 0) | |
237 | product | |
238 | (loop (- n 1) (* product n))))) | |
239 | ||
240 | (factorial 3) | |
241 | @result{} | |
242 | 6 | |
243 | ||
244 | (factorial 20) | |
245 | @result{} | |
246 | 2432902008176640000 | |
247 | ||
248 | (- (factorial 45)) | |
249 | @result{} | |
250 | -119622220865480194561963161495657715064383733760000000000 | |
251 | @end lisp | |
252 | ||
253 | Readers whose background is in programming languages where integers are | |
254 | limited by the need to fit into just 4 or 8 bytes of memory may find | |
255 | this surprising, or suspect that Guile's representation of integers is | |
256 | inefficient. In fact, Guile achieves a near optimal balance of | |
257 | convenience and efficiency by using the host computer's native | |
258 | representation of integers where possible, and a more general | |
259 | representation where the required number does not fit in the native | |
260 | form. Conversion between these two representations is automatic and | |
261 | completely invisible to the Scheme level programmer. | |
262 | ||
263 | @c REFFIXME Maybe point here to discussion of handling immediates/bignums | |
264 | @c on the C level, where the conversion is not so automatic - NJ | |
265 | ||
8f85c0c6 NJ |
266 | @deffn {Scheme Procedure} integer? x |
267 | @deffnx {C Function} scm_integer_p (x) | |
a0e07ba4 NJ |
268 | Return @code{#t} if @var{x} is an integer number, @code{#f} else. |
269 | ||
270 | @lisp | |
271 | (integer? 487) | |
272 | @result{} | |
273 | #t | |
274 | ||
275 | (integer? -3.4) | |
276 | @result{} | |
277 | #f | |
278 | @end lisp | |
279 | @end deffn | |
280 | ||
281 | ||
282 | @node Reals and Rationals | |
283 | @subsection Real and Rational Numbers | |
284 | @tpindex Real numbers | |
285 | @tpindex Rational numbers | |
286 | ||
287 | @rnindex real? | |
288 | @rnindex rational? | |
289 | ||
290 | Mathematically, the real numbers are the set of numbers that describe | |
291 | all possible points along a continuous, infinite, one-dimensional line. | |
292 | The rational numbers are the set of all numbers that can be written as | |
293 | fractions P/Q, where P and Q are integers. All rational numbers are | |
294 | also real, but there are real numbers that are not rational, for example | |
295 | the square root of 2, and pi. | |
296 | ||
297 | Guile represents both real and rational numbers approximately using a | |
298 | floating point encoding with limited precision. Even though the actual | |
299 | encoding is in binary, it may be helpful to think of it as a decimal | |
300 | number with a limited number of significant figures and a decimal point | |
301 | somewhere, since this corresponds to the standard notation for non-whole | |
302 | numbers. For example: | |
303 | ||
304 | @lisp | |
305 | 0.34 | |
306 | -0.00000142857931198 | |
307 | -5648394822220000000000.0 | |
308 | 4.0 | |
309 | @end lisp | |
310 | ||
311 | The limited precision of Guile's encoding means that any ``real'' number | |
312 | in Guile can be written in a rational form, by multiplying and then dividing | |
313 | by sufficient powers of 10 (or in fact, 2). For example, | |
314 | @code{-0.00000142857931198} is the same as @code{142857931198} divided by | |
315 | @code{100000000000000000}. In Guile's current incarnation, therefore, | |
316 | the @code{rational?} and @code{real?} predicates are equivalent. | |
317 | ||
318 | Another aspect of this equivalence is that Guile currently does not | |
319 | preserve the exactness that is possible with rational arithmetic. | |
320 | If such exactness is needed, it is of course possible to implement | |
321 | exact rational arithmetic at the Scheme level using Guile's arbitrary | |
322 | size integers. | |
323 | ||
324 | A planned future revision of Guile's numerical tower will make it | |
325 | possible to implement exact representations and arithmetic for both | |
326 | rational numbers and real irrational numbers such as square roots, | |
327 | and in such a way that the new kinds of number integrate seamlessly | |
328 | with those that are already implemented. | |
329 | ||
8f85c0c6 NJ |
330 | @deffn {Scheme Procedure} real? obj |
331 | @deffnx {C Function} scm_real_p (obj) | |
a0e07ba4 NJ |
332 | Return @code{#t} if @var{obj} is a real number, @code{#f} else. |
333 | Note that the sets of integer and rational values form subsets | |
334 | of the set of real numbers, so the predicate will also be fulfilled | |
335 | if @var{obj} is an integer number or a rational number. | |
8f85c0c6 | 336 | @findex real? |
a0e07ba4 NJ |
337 | @end deffn |
338 | ||
8f85c0c6 NJ |
339 | @deffn {Scheme Procedure} rational? x |
340 | @deffnx {C Function} scm_real_p (x) | |
a0e07ba4 NJ |
341 | Return @code{#t} if @var{x} is a rational number, @code{#f} |
342 | else. Note that the set of integer values forms a subset of | |
343 | the set of rational numbers, i. e. the predicate will also be | |
344 | fulfilled if @var{x} is an integer number. Real numbers | |
345 | will also satisfy this predicate, because of their limited | |
346 | precision. | |
347 | @end deffn | |
348 | ||
349 | ||
350 | @node Complex Numbers | |
351 | @subsection Complex Numbers | |
352 | @tpindex Complex numbers | |
353 | ||
354 | @rnindex complex? | |
355 | ||
356 | Complex numbers are the set of numbers that describe all possible points | |
357 | in a two-dimensional space. The two coordinates of a particular point | |
358 | in this space are known as the @dfn{real} and @dfn{imaginary} parts of | |
359 | the complex number that describes that point. | |
360 | ||
361 | In Guile, complex numbers are written in rectangular form as the sum of | |
362 | their real and imaginary parts, using the symbol @code{i} to indicate | |
363 | the imaginary part. | |
364 | ||
365 | @lisp | |
366 | 3+4i | |
367 | @result{} | |
368 | 3.0+4.0i | |
369 | ||
370 | (* 3-8i 2.3+0.3i) | |
371 | @result{} | |
372 | 9.3-17.5i | |
373 | @end lisp | |
374 | ||
375 | Guile represents a complex number as a pair of numbers both of which are | |
376 | real, so the real and imaginary parts of a complex number have the same | |
377 | properties of inexactness and limited precision as single real numbers. | |
378 | ||
8f85c0c6 NJ |
379 | @deffn {Scheme Procedure} complex? x |
380 | @deffnx {C Function} scm_number_p (x) | |
a0e07ba4 NJ |
381 | Return @code{#t} if @var{x} is a complex number, @code{#f} |
382 | else. Note that the sets of real, rational and integer | |
383 | values form subsets of the set of complex numbers, i. e. the | |
384 | predicate will also be fulfilled if @var{x} is a real, | |
385 | rational or integer number. | |
386 | @end deffn | |
387 | ||
388 | ||
389 | @node Exactness | |
390 | @subsection Exact and Inexact Numbers | |
391 | @tpindex Exact numbers | |
392 | @tpindex Inexact numbers | |
393 | ||
394 | @rnindex exact? | |
395 | @rnindex inexact? | |
396 | @rnindex exact->inexact | |
397 | @rnindex inexact->exact | |
398 | ||
399 | R5RS requires that a calculation involving inexact numbers always | |
400 | produces an inexact result. To meet this requirement, Guile | |
401 | distinguishes between an exact integer value such as @code{5} and the | |
402 | corresponding inexact real value which, to the limited precision | |
403 | available, has no fractional part, and is printed as @code{5.0}. Guile | |
404 | will only convert the latter value to the former when forced to do so by | |
405 | an invocation of the @code{inexact->exact} procedure. | |
406 | ||
8f85c0c6 NJ |
407 | @deffn {Scheme Procedure} exact? x |
408 | @deffnx {C Function} scm_exact_p (x) | |
a0e07ba4 NJ |
409 | Return @code{#t} if @var{x} is an exact number, @code{#f} |
410 | otherwise. | |
411 | @end deffn | |
412 | ||
8f85c0c6 NJ |
413 | @deffn {Scheme Procedure} inexact? x |
414 | @deffnx {C Function} scm_inexact_p (x) | |
a0e07ba4 NJ |
415 | Return @code{#t} if @var{x} is an inexact number, @code{#f} |
416 | else. | |
417 | @end deffn | |
418 | ||
8f85c0c6 NJ |
419 | @deffn {Scheme Procedure} inexact->exact z |
420 | @deffnx {C Function} scm_inexact_to_exact (z) | |
a0e07ba4 NJ |
421 | Return an exact number that is numerically closest to @var{z}. |
422 | @end deffn | |
423 | ||
424 | @c begin (texi-doc-string "guile" "exact->inexact") | |
8f85c0c6 | 425 | @deffn {Scheme Procedure} exact->inexact z |
a0e07ba4 NJ |
426 | Convert the number @var{z} to its inexact representation. |
427 | @end deffn | |
428 | ||
429 | ||
430 | @node Number Syntax | |
431 | @subsection Read Syntax for Numerical Data | |
432 | ||
433 | The read syntax for integers is a string of digits, optionally | |
434 | preceded by a minus or plus character, a code indicating the | |
435 | base in which the integer is encoded, and a code indicating whether | |
436 | the number is exact or inexact. The supported base codes are: | |
437 | ||
438 | @itemize @bullet | |
439 | @item | |
440 | @code{#b}, @code{#B} --- the integer is written in binary (base 2) | |
441 | ||
442 | @item | |
443 | @code{#o}, @code{#O} --- the integer is written in octal (base 8) | |
444 | ||
445 | @item | |
446 | @code{#d}, @code{#D} --- the integer is written in decimal (base 10) | |
447 | ||
448 | @item | |
449 | @code{#x}, @code{#X} --- the integer is written in hexadecimal (base 16). | |
450 | @end itemize | |
451 | ||
452 | If the base code is omitted, the integer is assumed to be decimal. The | |
453 | following examples show how these base codes are used. | |
454 | ||
455 | @lisp | |
456 | -13 | |
457 | @result{} | |
458 | -13 | |
459 | ||
460 | #d-13 | |
461 | @result{} | |
462 | -13 | |
463 | ||
464 | #x-13 | |
465 | @result{} | |
466 | -19 | |
467 | ||
468 | #b+1101 | |
469 | @result{} | |
470 | 13 | |
471 | ||
472 | #o377 | |
473 | @result{} | |
474 | 255 | |
475 | @end lisp | |
476 | ||
477 | The codes for indicating exactness (which can, incidentally, be applied | |
478 | to all numerical values) are: | |
479 | ||
480 | @itemize @bullet | |
481 | @item | |
482 | @code{#e}, @code{#E} --- the number is exact | |
483 | ||
484 | @item | |
485 | @code{#i}, @code{#I} --- the number is inexact. | |
486 | @end itemize | |
487 | ||
488 | If the exactness indicator is omitted, the integer is assumed to be exact, | |
489 | since Guile's internal representation for integers is always exact. | |
490 | Real numbers have limited precision similar to the precision of the | |
491 | @code{double} type in C. A consequence of the limited precision is that | |
492 | all real numbers in Guile are also rational, since any number R with a | |
493 | limited number of decimal places, say N, can be made into an integer by | |
494 | multiplying by 10^N. | |
495 | ||
496 | ||
497 | @node Integer Operations | |
498 | @subsection Operations on Integer Values | |
499 | @rnindex odd? | |
500 | @rnindex even? | |
501 | @rnindex quotient | |
502 | @rnindex remainder | |
503 | @rnindex modulo | |
504 | @rnindex gcd | |
505 | @rnindex lcm | |
506 | ||
8f85c0c6 NJ |
507 | @deffn {Scheme Procedure} odd? n |
508 | @deffnx {C Function} scm_odd_p (n) | |
a0e07ba4 NJ |
509 | Return @code{#t} if @var{n} is an odd number, @code{#f} |
510 | otherwise. | |
511 | @end deffn | |
512 | ||
8f85c0c6 NJ |
513 | @deffn {Scheme Procedure} even? n |
514 | @deffnx {C Function} scm_even_p (n) | |
a0e07ba4 NJ |
515 | Return @code{#t} if @var{n} is an even number, @code{#f} |
516 | otherwise. | |
517 | @end deffn | |
518 | ||
519 | @c begin (texi-doc-string "guile" "quotient") | |
8f85c0c6 | 520 | @deffn {Scheme Procedure} quotient |
a0e07ba4 NJ |
521 | Return the quotient of the numbers @var{x} and @var{y}. |
522 | @end deffn | |
523 | ||
524 | @c begin (texi-doc-string "guile" "remainder") | |
8f85c0c6 | 525 | @deffn {Scheme Procedure} remainder |
a0e07ba4 NJ |
526 | Return the remainder of the numbers @var{x} and @var{y}. |
527 | @lisp | |
528 | (remainder 13 4) @result{} 1 | |
529 | (remainder -13 4) @result{} -1 | |
530 | @end lisp | |
531 | @end deffn | |
532 | ||
533 | @c begin (texi-doc-string "guile" "modulo") | |
8f85c0c6 | 534 | @deffn {Scheme Procedure} modulo |
a0e07ba4 NJ |
535 | Return the modulo of the numbers @var{x} and @var{y}. |
536 | @lisp | |
537 | (modulo 13 4) @result{} 1 | |
538 | (modulo -13 4) @result{} 3 | |
539 | @end lisp | |
540 | @end deffn | |
541 | ||
542 | @c begin (texi-doc-string "guile" "gcd") | |
8f85c0c6 | 543 | @deffn {Scheme Procedure} gcd |
a0e07ba4 NJ |
544 | Return the greatest common divisor of all arguments. |
545 | If called without arguments, 0 is returned. | |
546 | @end deffn | |
547 | ||
548 | @c begin (texi-doc-string "guile" "lcm") | |
8f85c0c6 | 549 | @deffn {Scheme Procedure} lcm |
a0e07ba4 NJ |
550 | Return the least common multiple of the arguments. |
551 | If called without arguments, 1 is returned. | |
552 | @end deffn | |
553 | ||
554 | ||
555 | @node Comparison | |
556 | @subsection Comparison Predicates | |
557 | @rnindex zero? | |
558 | @rnindex positive? | |
559 | @rnindex negative? | |
560 | ||
561 | @c begin (texi-doc-string "guile" "=") | |
8f85c0c6 | 562 | @deffn {Scheme Procedure} = |
a0e07ba4 NJ |
563 | Return @code{#t} if all parameters are numerically equal. |
564 | @end deffn | |
565 | ||
566 | @c begin (texi-doc-string "guile" "<") | |
8f85c0c6 | 567 | @deffn {Scheme Procedure} < |
a0e07ba4 NJ |
568 | Return @code{#t} if the list of parameters is monotonically |
569 | increasing. | |
570 | @end deffn | |
571 | ||
572 | @c begin (texi-doc-string "guile" ">") | |
8f85c0c6 | 573 | @deffn {Scheme Procedure} > |
a0e07ba4 NJ |
574 | Return @code{#t} if the list of parameters is monotonically |
575 | decreasing. | |
576 | @end deffn | |
577 | ||
578 | @c begin (texi-doc-string "guile" "<=") | |
8f85c0c6 | 579 | @deffn {Scheme Procedure} <= |
a0e07ba4 NJ |
580 | Return @code{#t} if the list of parameters is monotonically |
581 | non-decreasing. | |
582 | @end deffn | |
583 | ||
584 | @c begin (texi-doc-string "guile" ">=") | |
8f85c0c6 | 585 | @deffn {Scheme Procedure} >= |
a0e07ba4 NJ |
586 | Return @code{#t} if the list of parameters is monotonically |
587 | non-increasing. | |
588 | @end deffn | |
589 | ||
590 | @c begin (texi-doc-string "guile" "zero?") | |
8f85c0c6 | 591 | @deffn {Scheme Procedure} zero? |
a0e07ba4 NJ |
592 | Return @code{#t} if @var{z} is an exact or inexact number equal to |
593 | zero. | |
594 | @end deffn | |
595 | ||
596 | @c begin (texi-doc-string "guile" "positive?") | |
8f85c0c6 | 597 | @deffn {Scheme Procedure} positive? |
a0e07ba4 NJ |
598 | Return @code{#t} if @var{x} is an exact or inexact number greater than |
599 | zero. | |
600 | @end deffn | |
601 | ||
602 | @c begin (texi-doc-string "guile" "negative?") | |
8f85c0c6 | 603 | @deffn {Scheme Procedure} negative? |
a0e07ba4 NJ |
604 | Return @code{#t} if @var{x} is an exact or inexact number less than |
605 | zero. | |
606 | @end deffn | |
607 | ||
608 | ||
609 | @node Conversion | |
610 | @subsection Converting Numbers To and From Strings | |
611 | @rnindex number->string | |
612 | @rnindex string->number | |
613 | ||
8f85c0c6 NJ |
614 | @deffn {Scheme Procedure} number->string n [radix] |
615 | @deffnx {C Function} scm_number_to_string (n, radix) | |
a0e07ba4 NJ |
616 | Return a string holding the external representation of the |
617 | number @var{n} in the given @var{radix}. If @var{n} is | |
618 | inexact, a radix of 10 will be used. | |
619 | @end deffn | |
620 | ||
8f85c0c6 NJ |
621 | @deffn {Scheme Procedure} string->number string [radix] |
622 | @deffnx {C Function} scm_string_to_number (string, radix) | |
a0e07ba4 NJ |
623 | Return a number of the maximally precise representation |
624 | expressed by the given @var{string}. @var{radix} must be an | |
625 | exact integer, either 2, 8, 10, or 16. If supplied, @var{radix} | |
626 | is a default radix that may be overridden by an explicit radix | |
627 | prefix in @var{string} (e.g. "#o177"). If @var{radix} is not | |
628 | supplied, then the default radix is 10. If string is not a | |
629 | syntactically valid notation for a number, then | |
630 | @code{string->number} returns @code{#f}. | |
631 | @end deffn | |
632 | ||
633 | ||
634 | @node Complex | |
635 | @subsection Complex Number Operations | |
636 | @rnindex make-rectangular | |
637 | @rnindex make-polar | |
638 | @rnindex real-part | |
639 | @rnindex imag-part | |
640 | @rnindex magnitude | |
641 | @rnindex angle | |
642 | ||
8f85c0c6 NJ |
643 | @deffn {Scheme Procedure} make-rectangular real imaginary |
644 | @deffnx {C Function} scm_make_rectangular (real, imaginary) | |
a0e07ba4 NJ |
645 | Return a complex number constructed of the given @var{real} and |
646 | @var{imaginary} parts. | |
647 | @end deffn | |
648 | ||
8f85c0c6 NJ |
649 | @deffn {Scheme Procedure} make-polar x y |
650 | @deffnx {C Function} scm_make_polar (x, y) | |
a0e07ba4 NJ |
651 | Return the complex number @var{x} * e^(i * @var{y}). |
652 | @end deffn | |
653 | ||
654 | @c begin (texi-doc-string "guile" "real-part") | |
8f85c0c6 | 655 | @deffn {Scheme Procedure} real-part |
a0e07ba4 NJ |
656 | Return the real part of the number @var{z}. |
657 | @end deffn | |
658 | ||
659 | @c begin (texi-doc-string "guile" "imag-part") | |
8f85c0c6 | 660 | @deffn {Scheme Procedure} imag-part |
a0e07ba4 NJ |
661 | Return the imaginary part of the number @var{z}. |
662 | @end deffn | |
663 | ||
664 | @c begin (texi-doc-string "guile" "magnitude") | |
8f85c0c6 | 665 | @deffn {Scheme Procedure} magnitude |
a0e07ba4 NJ |
666 | Return the magnitude of the number @var{z}. This is the same as |
667 | @code{abs} for real arguments, but also allows complex numbers. | |
668 | @end deffn | |
669 | ||
670 | @c begin (texi-doc-string "guile" "angle") | |
8f85c0c6 | 671 | @deffn {Scheme Procedure} angle |
a0e07ba4 NJ |
672 | Return the angle of the complex number @var{z}. |
673 | @end deffn | |
674 | ||
675 | ||
676 | @node Arithmetic | |
677 | @subsection Arithmetic Functions | |
678 | @rnindex max | |
679 | @rnindex min | |
680 | @rnindex + | |
681 | @rnindex * | |
682 | @rnindex - | |
683 | @rnindex / | |
684 | @rnindex abs | |
685 | @rnindex floor | |
686 | @rnindex ceiling | |
687 | @rnindex truncate | |
688 | @rnindex round | |
689 | ||
690 | @c begin (texi-doc-string "guile" "+") | |
8f85c0c6 | 691 | @deffn {Scheme Procedure} + z1 @dots{} |
a0e07ba4 NJ |
692 | Return the sum of all parameter values. Return 0 if called without any |
693 | parameters. | |
694 | @end deffn | |
695 | ||
696 | @c begin (texi-doc-string "guile" "-") | |
8f85c0c6 | 697 | @deffn {Scheme Procedure} - z1 z2 @dots{} |
a0e07ba4 NJ |
698 | If called with one argument @var{z1}, -@var{z1} is returned. Otherwise |
699 | the sum of all but the first argument are subtracted from the first | |
700 | argument. | |
701 | @end deffn | |
702 | ||
703 | @c begin (texi-doc-string "guile" "*") | |
8f85c0c6 | 704 | @deffn {Scheme Procedure} * z1 @dots{} |
a0e07ba4 NJ |
705 | Return the product of all arguments. If called without arguments, 1 is |
706 | returned. | |
707 | @end deffn | |
708 | ||
709 | @c begin (texi-doc-string "guile" "/") | |
8f85c0c6 | 710 | @deffn {Scheme Procedure} / z1 z2 @dots{} |
a0e07ba4 NJ |
711 | Divide the first argument by the product of the remaining arguments. If |
712 | called with one argument @var{z1}, 1/@var{z1} is returned. | |
713 | @end deffn | |
714 | ||
715 | @c begin (texi-doc-string "guile" "abs") | |
8f85c0c6 | 716 | @deffn {Scheme Procedure} abs x |
a0e07ba4 NJ |
717 | Return the absolute value of @var{x}. |
718 | @end deffn | |
719 | ||
720 | @c begin (texi-doc-string "guile" "max") | |
8f85c0c6 | 721 | @deffn {Scheme Procedure} max x1 x2 @dots{} |
a0e07ba4 NJ |
722 | Return the maximum of all parameter values. |
723 | @end deffn | |
724 | ||
725 | @c begin (texi-doc-string "guile" "min") | |
8f85c0c6 | 726 | @deffn {Scheme Procedure} min x1 x2 @dots{} |
85a9b4ed | 727 | Return the minimum of all parameter values. |
a0e07ba4 NJ |
728 | @end deffn |
729 | ||
730 | @c begin (texi-doc-string "guile" "truncate") | |
8f85c0c6 | 731 | @deffn {Scheme Procedure} truncate |
a0e07ba4 NJ |
732 | Round the inexact number @var{x} towards zero. |
733 | @end deffn | |
734 | ||
735 | @c begin (texi-doc-string "guile" "round") | |
8f85c0c6 | 736 | @deffn {Scheme Procedure} round x |
a0e07ba4 NJ |
737 | Round the inexact number @var{x} towards zero. |
738 | @end deffn | |
739 | ||
740 | @c begin (texi-doc-string "guile" "floor") | |
8f85c0c6 | 741 | @deffn {Scheme Procedure} floor x |
a0e07ba4 NJ |
742 | Round the number @var{x} towards minus infinity. |
743 | @end deffn | |
744 | ||
745 | @c begin (texi-doc-string "guile" "ceiling") | |
8f85c0c6 | 746 | @deffn {Scheme Procedure} ceiling x |
a0e07ba4 NJ |
747 | Round the number @var{x} towards infinity. |
748 | @end deffn | |
749 | ||
750 | ||
751 | @node Scientific | |
752 | @subsection Scientific Functions | |
753 | ||
754 | The following procedures accept any kind of number as arguments, | |
755 | including complex numbers. | |
756 | ||
757 | @rnindex sqrt | |
758 | @c begin (texi-doc-string "guile" "sqrt") | |
8f85c0c6 | 759 | @deffn {Scheme Procedure} sqrt z |
a0e07ba4 NJ |
760 | Return the square root of @var{z}. |
761 | @end deffn | |
762 | ||
763 | @rnindex expt | |
764 | @c begin (texi-doc-string "guile" "expt") | |
8f85c0c6 | 765 | @deffn {Scheme Procedure} expt z1 z2 |
a0e07ba4 NJ |
766 | Return @var{z1} raised to the power of @var{z2}. |
767 | @end deffn | |
768 | ||
769 | @rnindex sin | |
770 | @c begin (texi-doc-string "guile" "sin") | |
8f85c0c6 | 771 | @deffn {Scheme Procedure} sin z |
a0e07ba4 NJ |
772 | Return the sine of @var{z}. |
773 | @end deffn | |
774 | ||
775 | @rnindex cos | |
776 | @c begin (texi-doc-string "guile" "cos") | |
8f85c0c6 | 777 | @deffn {Scheme Procedure} cos z |
a0e07ba4 NJ |
778 | Return the cosine of @var{z}. |
779 | @end deffn | |
780 | ||
781 | @rnindex tan | |
782 | @c begin (texi-doc-string "guile" "tan") | |
8f85c0c6 | 783 | @deffn {Scheme Procedure} tan z |
a0e07ba4 NJ |
784 | Return the tangent of @var{z}. |
785 | @end deffn | |
786 | ||
787 | @rnindex asin | |
788 | @c begin (texi-doc-string "guile" "asin") | |
8f85c0c6 | 789 | @deffn {Scheme Procedure} asin z |
a0e07ba4 NJ |
790 | Return the arcsine of @var{z}. |
791 | @end deffn | |
792 | ||
793 | @rnindex acos | |
794 | @c begin (texi-doc-string "guile" "acos") | |
8f85c0c6 | 795 | @deffn {Scheme Procedure} acos z |
a0e07ba4 NJ |
796 | Return the arccosine of @var{z}. |
797 | @end deffn | |
798 | ||
799 | @rnindex atan | |
800 | @c begin (texi-doc-string "guile" "atan") | |
8f85c0c6 | 801 | @deffn {Scheme Procedure} atan z |
a0e07ba4 NJ |
802 | Return the arctangent of @var{z}. |
803 | @end deffn | |
804 | ||
805 | @rnindex exp | |
806 | @c begin (texi-doc-string "guile" "exp") | |
8f85c0c6 | 807 | @deffn {Scheme Procedure} exp z |
a0e07ba4 NJ |
808 | Return e to the power of @var{z}, where e is the base of natural |
809 | logarithms (2.71828@dots{}). | |
810 | @end deffn | |
811 | ||
812 | @rnindex log | |
813 | @c begin (texi-doc-string "guile" "log") | |
8f85c0c6 | 814 | @deffn {Scheme Procedure} log z |
a0e07ba4 NJ |
815 | Return the natural logarithm of @var{z}. |
816 | @end deffn | |
817 | ||
818 | @c begin (texi-doc-string "guile" "log10") | |
8f85c0c6 | 819 | @deffn {Scheme Procedure} log10 z |
a0e07ba4 NJ |
820 | Return the base 10 logarithm of @var{z}. |
821 | @end deffn | |
822 | ||
823 | @c begin (texi-doc-string "guile" "sinh") | |
8f85c0c6 | 824 | @deffn {Scheme Procedure} sinh z |
a0e07ba4 NJ |
825 | Return the hyperbolic sine of @var{z}. |
826 | @end deffn | |
827 | ||
828 | @c begin (texi-doc-string "guile" "cosh") | |
8f85c0c6 | 829 | @deffn {Scheme Procedure} cosh z |
a0e07ba4 NJ |
830 | Return the hyperbolic cosine of @var{z}. |
831 | @end deffn | |
832 | ||
833 | @c begin (texi-doc-string "guile" "tanh") | |
8f85c0c6 | 834 | @deffn {Scheme Procedure} tanh z |
a0e07ba4 NJ |
835 | Return the hyperbolic tangent of @var{z}. |
836 | @end deffn | |
837 | ||
838 | @c begin (texi-doc-string "guile" "asinh") | |
8f85c0c6 | 839 | @deffn {Scheme Procedure} asinh z |
a0e07ba4 NJ |
840 | Return the hyperbolic arcsine of @var{z}. |
841 | @end deffn | |
842 | ||
843 | @c begin (texi-doc-string "guile" "acosh") | |
8f85c0c6 | 844 | @deffn {Scheme Procedure} acosh z |
a0e07ba4 NJ |
845 | Return the hyperbolic arccosine of @var{z}. |
846 | @end deffn | |
847 | ||
848 | @c begin (texi-doc-string "guile" "atanh") | |
8f85c0c6 | 849 | @deffn {Scheme Procedure} atanh z |
a0e07ba4 NJ |
850 | Return the hyperbolic arctangent of @var{z}. |
851 | @end deffn | |
852 | ||
853 | ||
854 | @node Primitive Numerics | |
855 | @subsection Primitive Numeric Functions | |
856 | ||
857 | Many of Guile's numeric procedures which accept any kind of numbers as | |
858 | arguments, including complex numbers, are implemented as Scheme | |
859 | procedures that use the following real number-based primitives. These | |
860 | primitives signal an error if they are called with complex arguments. | |
861 | ||
862 | @c begin (texi-doc-string "guile" "$abs") | |
8f85c0c6 | 863 | @deffn {Scheme Procedure} $abs x |
a0e07ba4 NJ |
864 | Return the absolute value of @var{x}. |
865 | @end deffn | |
866 | ||
867 | @c begin (texi-doc-string "guile" "$sqrt") | |
8f85c0c6 | 868 | @deffn {Scheme Procedure} $sqrt x |
a0e07ba4 NJ |
869 | Return the square root of @var{x}. |
870 | @end deffn | |
871 | ||
8f85c0c6 NJ |
872 | @deffn {Scheme Procedure} $expt x y |
873 | @deffnx {C Function} scm_sys_expt (x, y) | |
a0e07ba4 NJ |
874 | Return @var{x} raised to the power of @var{y}. This |
875 | procedure does not accept complex arguments. | |
876 | @end deffn | |
877 | ||
878 | @c begin (texi-doc-string "guile" "$sin") | |
8f85c0c6 | 879 | @deffn {Scheme Procedure} $sin x |
a0e07ba4 NJ |
880 | Return the sine of @var{x}. |
881 | @end deffn | |
882 | ||
883 | @c begin (texi-doc-string "guile" "$cos") | |
8f85c0c6 | 884 | @deffn {Scheme Procedure} $cos x |
a0e07ba4 NJ |
885 | Return the cosine of @var{x}. |
886 | @end deffn | |
887 | ||
888 | @c begin (texi-doc-string "guile" "$tan") | |
8f85c0c6 | 889 | @deffn {Scheme Procedure} $tan x |
a0e07ba4 NJ |
890 | Return the tangent of @var{x}. |
891 | @end deffn | |
892 | ||
893 | @c begin (texi-doc-string "guile" "$asin") | |
8f85c0c6 | 894 | @deffn {Scheme Procedure} $asin x |
a0e07ba4 NJ |
895 | Return the arcsine of @var{x}. |
896 | @end deffn | |
897 | ||
898 | @c begin (texi-doc-string "guile" "$acos") | |
8f85c0c6 | 899 | @deffn {Scheme Procedure} $acos x |
a0e07ba4 NJ |
900 | Return the arccosine of @var{x}. |
901 | @end deffn | |
902 | ||
903 | @c begin (texi-doc-string "guile" "$atan") | |
8f85c0c6 | 904 | @deffn {Scheme Procedure} $atan x |
a0e07ba4 NJ |
905 | Return the arctangent of @var{x} in the range -PI/2 to PI/2. |
906 | @end deffn | |
907 | ||
8f85c0c6 NJ |
908 | @deffn {Scheme Procedure} $atan2 x y |
909 | @deffnx {C Function} scm_sys_atan2 (x, y) | |
a0e07ba4 NJ |
910 | Return the arc tangent of the two arguments @var{x} and |
911 | @var{y}. This is similar to calculating the arc tangent of | |
912 | @var{x} / @var{y}, except that the signs of both arguments | |
913 | are used to determine the quadrant of the result. This | |
914 | procedure does not accept complex arguments. | |
915 | @end deffn | |
916 | ||
917 | @c begin (texi-doc-string "guile" "$exp") | |
8f85c0c6 | 918 | @deffn {Scheme Procedure} $exp x |
a0e07ba4 NJ |
919 | Return e to the power of @var{x}, where e is the base of natural |
920 | logarithms (2.71828@dots{}). | |
921 | @end deffn | |
922 | ||
923 | @c begin (texi-doc-string "guile" "$log") | |
8f85c0c6 | 924 | @deffn {Scheme Procedure} $log x |
a0e07ba4 NJ |
925 | Return the natural logarithm of @var{x}. |
926 | @end deffn | |
927 | ||
928 | @c begin (texi-doc-string "guile" "$sinh") | |
8f85c0c6 | 929 | @deffn {Scheme Procedure} $sinh x |
a0e07ba4 NJ |
930 | Return the hyperbolic sine of @var{x}. |
931 | @end deffn | |
932 | ||
933 | @c begin (texi-doc-string "guile" "$cosh") | |
8f85c0c6 | 934 | @deffn {Scheme Procedure} $cosh x |
a0e07ba4 NJ |
935 | Return the hyperbolic cosine of @var{x}. |
936 | @end deffn | |
937 | ||
938 | @c begin (texi-doc-string "guile" "$tanh") | |
8f85c0c6 | 939 | @deffn {Scheme Procedure} $tanh x |
a0e07ba4 NJ |
940 | Return the hyperbolic tangent of @var{x}. |
941 | @end deffn | |
942 | ||
943 | @c begin (texi-doc-string "guile" "$asinh") | |
8f85c0c6 | 944 | @deffn {Scheme Procedure} $asinh x |
a0e07ba4 NJ |
945 | Return the hyperbolic arcsine of @var{x}. |
946 | @end deffn | |
947 | ||
948 | @c begin (texi-doc-string "guile" "$acosh") | |
8f85c0c6 | 949 | @deffn {Scheme Procedure} $acosh x |
a0e07ba4 NJ |
950 | Return the hyperbolic arccosine of @var{x}. |
951 | @end deffn | |
952 | ||
953 | @c begin (texi-doc-string "guile" "$atanh") | |
8f85c0c6 | 954 | @deffn {Scheme Procedure} $atanh x |
a0e07ba4 NJ |
955 | Return the hyperbolic arctangent of @var{x}. |
956 | @end deffn | |
957 | ||
958 | ||
959 | @node Bitwise Operations | |
960 | @subsection Bitwise Operations | |
961 | ||
8f85c0c6 | 962 | @deffn {Scheme Procedure} logand n1 n2 |
9401323e | 963 | Return the bitwise AND of the integer arguments. |
a0e07ba4 NJ |
964 | |
965 | @lisp | |
9401323e NJ |
966 | (logand) @result{} -1 |
967 | (logand 7) @result{} 7 | |
968 | (logand #b111 #b011 #b001) @result{} 1 | |
a0e07ba4 NJ |
969 | @end lisp |
970 | @end deffn | |
971 | ||
8f85c0c6 | 972 | @deffn {Scheme Procedure} logior n1 n2 |
9401323e | 973 | Return the bitwise OR of the integer arguments. |
a0e07ba4 NJ |
974 | |
975 | @lisp | |
9401323e NJ |
976 | (logior) @result{} 0 |
977 | (logior 7) @result{} 7 | |
978 | (logior #b000 #b001 #b011) @result{} 3 | |
a0e07ba4 NJ |
979 | @end lisp |
980 | @end deffn | |
981 | ||
8f85c0c6 | 982 | @deffn {Scheme Procedure} logxor n1 n2 |
9401323e NJ |
983 | Return the bitwise XOR of the integer arguments. A bit is |
984 | set in the result if it is set in an odd number of arguments. | |
a0e07ba4 | 985 | @lisp |
9401323e NJ |
986 | (logxor) @result{} 0 |
987 | (logxor 7) @result{} 7 | |
988 | (logxor #b000 #b001 #b011) @result{} 2 | |
989 | (logxor #b000 #b001 #b011 #b011) @result{} 1 | |
a0e07ba4 NJ |
990 | @end lisp |
991 | @end deffn | |
992 | ||
8f85c0c6 NJ |
993 | @deffn {Scheme Procedure} lognot n |
994 | @deffnx {C Function} scm_lognot (n) | |
a0e07ba4 NJ |
995 | Return the integer which is the 2s-complement of the integer |
996 | argument. | |
997 | ||
998 | @lisp | |
999 | (number->string (lognot #b10000000) 2) | |
1000 | @result{} "-10000001" | |
1001 | (number->string (lognot #b0) 2) | |
1002 | @result{} "-1" | |
1003 | @end lisp | |
1004 | @end deffn | |
1005 | ||
8f85c0c6 NJ |
1006 | @deffn {Scheme Procedure} logtest j k |
1007 | @deffnx {C Function} scm_logtest (j, k) | |
a0e07ba4 NJ |
1008 | @lisp |
1009 | (logtest j k) @equiv{} (not (zero? (logand j k))) | |
1010 | ||
1011 | (logtest #b0100 #b1011) @result{} #f | |
1012 | (logtest #b0100 #b0111) @result{} #t | |
1013 | @end lisp | |
1014 | @end deffn | |
1015 | ||
8f85c0c6 NJ |
1016 | @deffn {Scheme Procedure} logbit? index j |
1017 | @deffnx {C Function} scm_logbit_p (index, j) | |
a0e07ba4 NJ |
1018 | @lisp |
1019 | (logbit? index j) @equiv{} (logtest (integer-expt 2 index) j) | |
1020 | ||
1021 | (logbit? 0 #b1101) @result{} #t | |
1022 | (logbit? 1 #b1101) @result{} #f | |
1023 | (logbit? 2 #b1101) @result{} #t | |
1024 | (logbit? 3 #b1101) @result{} #t | |
1025 | (logbit? 4 #b1101) @result{} #f | |
1026 | @end lisp | |
1027 | @end deffn | |
1028 | ||
8f85c0c6 NJ |
1029 | @deffn {Scheme Procedure} ash n cnt |
1030 | @deffnx {C Function} scm_ash (n, cnt) | |
a0e07ba4 NJ |
1031 | The function ash performs an arithmetic shift left by @var{cnt} |
1032 | bits (or shift right, if @var{cnt} is negative). 'Arithmetic' | |
1033 | means, that the function does not guarantee to keep the bit | |
1034 | structure of @var{n}, but rather guarantees that the result | |
1035 | will always be rounded towards minus infinity. Therefore, the | |
1036 | results of ash and a corresponding bitwise shift will differ if | |
1037 | @var{n} is negative. | |
1038 | ||
1039 | Formally, the function returns an integer equivalent to | |
1040 | @code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}. | |
1041 | ||
1042 | @lisp | |
1043 | (number->string (ash #b1 3) 2) @result{} "1000" | |
1044 | (number->string (ash #b1010 -1) 2) @result{} "101" | |
1045 | @end lisp | |
1046 | @end deffn | |
1047 | ||
8f85c0c6 NJ |
1048 | @deffn {Scheme Procedure} logcount n |
1049 | @deffnx {C Function} scm_logcount (n) | |
a0e07ba4 NJ |
1050 | Return the number of bits in integer @var{n}. If integer is |
1051 | positive, the 1-bits in its binary representation are counted. | |
1052 | If negative, the 0-bits in its two's-complement binary | |
1053 | representation are counted. If 0, 0 is returned. | |
1054 | ||
1055 | @lisp | |
1056 | (logcount #b10101010) | |
1057 | @result{} 4 | |
1058 | (logcount 0) | |
1059 | @result{} 0 | |
1060 | (logcount -2) | |
1061 | @result{} 1 | |
1062 | @end lisp | |
1063 | @end deffn | |
1064 | ||
8f85c0c6 NJ |
1065 | @deffn {Scheme Procedure} integer-length n |
1066 | @deffnx {C Function} scm_integer_length (n) | |
85a9b4ed | 1067 | Return the number of bits necessary to represent @var{n}. |
a0e07ba4 NJ |
1068 | |
1069 | @lisp | |
1070 | (integer-length #b10101010) | |
1071 | @result{} 8 | |
1072 | (integer-length 0) | |
1073 | @result{} 0 | |
1074 | (integer-length #b1111) | |
1075 | @result{} 4 | |
1076 | @end lisp | |
1077 | @end deffn | |
1078 | ||
8f85c0c6 NJ |
1079 | @deffn {Scheme Procedure} integer-expt n k |
1080 | @deffnx {C Function} scm_integer_expt (n, k) | |
a0e07ba4 NJ |
1081 | Return @var{n} raised to the non-negative integer exponent |
1082 | @var{k}. | |
1083 | ||
1084 | @lisp | |
1085 | (integer-expt 2 5) | |
1086 | @result{} 32 | |
1087 | (integer-expt -3 3) | |
1088 | @result{} -27 | |
1089 | @end lisp | |
1090 | @end deffn | |
1091 | ||
8f85c0c6 NJ |
1092 | @deffn {Scheme Procedure} bit-extract n start end |
1093 | @deffnx {C Function} scm_bit_extract (n, start, end) | |
a0e07ba4 NJ |
1094 | Return the integer composed of the @var{start} (inclusive) |
1095 | through @var{end} (exclusive) bits of @var{n}. The | |
1096 | @var{start}th bit becomes the 0-th bit in the result. | |
1097 | ||
1098 | @lisp | |
1099 | (number->string (bit-extract #b1101101010 0 4) 2) | |
1100 | @result{} "1010" | |
1101 | (number->string (bit-extract #b1101101010 4 9) 2) | |
1102 | @result{} "10110" | |
1103 | @end lisp | |
1104 | @end deffn | |
1105 | ||
1106 | ||
1107 | @node Random | |
1108 | @subsection Random Number Generation | |
1109 | ||
8f85c0c6 NJ |
1110 | @deffn {Scheme Procedure} copy-random-state [state] |
1111 | @deffnx {C Function} scm_copy_random_state (state) | |
a0e07ba4 NJ |
1112 | Return a copy of the random state @var{state}. |
1113 | @end deffn | |
1114 | ||
8f85c0c6 NJ |
1115 | @deffn {Scheme Procedure} random n [state] |
1116 | @deffnx {C Function} scm_random (n, state) | |
a0e07ba4 NJ |
1117 | Return a number in [0,N). |
1118 | ||
1119 | Accepts a positive integer or real n and returns a | |
1120 | number of the same type between zero (inclusive) and | |
1121 | N (exclusive). The values returned have a uniform | |
1122 | distribution. | |
1123 | ||
1124 | The optional argument @var{state} must be of the type produced | |
1125 | by @code{seed->random-state}. It defaults to the value of the | |
1126 | variable @var{*random-state*}. This object is used to maintain | |
1127 | the state of the pseudo-random-number generator and is altered | |
1128 | as a side effect of the random operation. | |
1129 | @end deffn | |
1130 | ||
8f85c0c6 NJ |
1131 | @deffn {Scheme Procedure} random:exp [state] |
1132 | @deffnx {C Function} scm_random_exp (state) | |
a0e07ba4 NJ |
1133 | Return an inexact real in an exponential distribution with mean |
1134 | 1. For an exponential distribution with mean u use (* u | |
1135 | (random:exp)). | |
1136 | @end deffn | |
1137 | ||
8f85c0c6 NJ |
1138 | @deffn {Scheme Procedure} random:hollow-sphere! v [state] |
1139 | @deffnx {C Function} scm_random_hollow_sphere_x (v, state) | |
a0e07ba4 NJ |
1140 | Fills vect with inexact real random numbers |
1141 | the sum of whose squares is equal to 1.0. | |
1142 | Thinking of vect as coordinates in space of | |
1143 | dimension n = (vector-length vect), the coordinates | |
1144 | are uniformly distributed over the surface of the | |
6c997de2 | 1145 | unit n-sphere. |
a0e07ba4 NJ |
1146 | @end deffn |
1147 | ||
8f85c0c6 NJ |
1148 | @deffn {Scheme Procedure} random:normal [state] |
1149 | @deffnx {C Function} scm_random_normal (state) | |
a0e07ba4 NJ |
1150 | Return an inexact real in a normal distribution. The |
1151 | distribution used has mean 0 and standard deviation 1. For a | |
1152 | normal distribution with mean m and standard deviation d use | |
1153 | @code{(+ m (* d (random:normal)))}. | |
1154 | @end deffn | |
1155 | ||
8f85c0c6 NJ |
1156 | @deffn {Scheme Procedure} random:normal-vector! v [state] |
1157 | @deffnx {C Function} scm_random_normal_vector_x (v, state) | |
a0e07ba4 NJ |
1158 | Fills vect with inexact real random numbers that are |
1159 | independent and standard normally distributed | |
1160 | (i.e., with mean 0 and variance 1). | |
1161 | @end deffn | |
1162 | ||
8f85c0c6 NJ |
1163 | @deffn {Scheme Procedure} random:solid-sphere! v [state] |
1164 | @deffnx {C Function} scm_random_solid_sphere_x (v, state) | |
a0e07ba4 NJ |
1165 | Fills vect with inexact real random numbers |
1166 | the sum of whose squares is less than 1.0. | |
1167 | Thinking of vect as coordinates in space of | |
1168 | dimension n = (vector-length vect), the coordinates | |
6c997de2 | 1169 | are uniformly distributed within the unit n-sphere. |
a0e07ba4 NJ |
1170 | The sum of the squares of the numbers is returned. |
1171 | @end deffn | |
1172 | ||
8f85c0c6 NJ |
1173 | @deffn {Scheme Procedure} random:uniform [state] |
1174 | @deffnx {C Function} scm_random_uniform (state) | |
a0e07ba4 NJ |
1175 | Return a uniformly distributed inexact real random number in |
1176 | [0,1). | |
1177 | @end deffn | |
1178 | ||
8f85c0c6 NJ |
1179 | @deffn {Scheme Procedure} seed->random-state seed |
1180 | @deffnx {C Function} scm_seed_to_random_state (seed) | |
a0e07ba4 NJ |
1181 | Return a new random state using @var{seed}. |
1182 | @end deffn | |
1183 | ||
1184 | ||
1185 | @node Characters | |
1186 | @section Characters | |
1187 | @tpindex Characters | |
1188 | ||
1189 | Most of the characters in the ASCII character set may be referred to by | |
1190 | name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and so on. | |
1191 | The following table describes the ASCII names for each character. | |
1192 | ||
1193 | @multitable @columnfractions .25 .25 .25 .25 | |
1194 | @item 0 = @code{#\nul} | |
1195 | @tab 1 = @code{#\soh} | |
1196 | @tab 2 = @code{#\stx} | |
1197 | @tab 3 = @code{#\etx} | |
1198 | @item 4 = @code{#\eot} | |
1199 | @tab 5 = @code{#\enq} | |
1200 | @tab 6 = @code{#\ack} | |
1201 | @tab 7 = @code{#\bel} | |
1202 | @item 8 = @code{#\bs} | |
1203 | @tab 9 = @code{#\ht} | |
1204 | @tab 10 = @code{#\nl} | |
1205 | @tab 11 = @code{#\vt} | |
1206 | @item 12 = @code{#\np} | |
1207 | @tab 13 = @code{#\cr} | |
1208 | @tab 14 = @code{#\so} | |
1209 | @tab 15 = @code{#\si} | |
1210 | @item 16 = @code{#\dle} | |
1211 | @tab 17 = @code{#\dc1} | |
1212 | @tab 18 = @code{#\dc2} | |
1213 | @tab 19 = @code{#\dc3} | |
1214 | @item 20 = @code{#\dc4} | |
1215 | @tab 21 = @code{#\nak} | |
1216 | @tab 22 = @code{#\syn} | |
1217 | @tab 23 = @code{#\etb} | |
1218 | @item 24 = @code{#\can} | |
1219 | @tab 25 = @code{#\em} | |
1220 | @tab 26 = @code{#\sub} | |
1221 | @tab 27 = @code{#\esc} | |
1222 | @item 28 = @code{#\fs} | |
1223 | @tab 29 = @code{#\gs} | |
1224 | @tab 30 = @code{#\rs} | |
1225 | @tab 31 = @code{#\us} | |
1226 | @item 32 = @code{#\sp} | |
1227 | @end multitable | |
1228 | ||
1229 | The @code{delete} character (octal 177) may be referred to with the name | |
1230 | @code{#\del}. | |
1231 | ||
1232 | Several characters have more than one name: | |
1233 | ||
1234 | @itemize @bullet | |
1235 | @item | |
1236 | @code{#\space}, @code{#\sp} | |
1237 | @item | |
1238 | @code{#\newline}, @code{#\nl} | |
1239 | @item | |
1240 | @code{#\tab}, @code{#\ht} | |
1241 | @item | |
1242 | @code{#\backspace}, @code{#\bs} | |
1243 | @item | |
1244 | @code{#\return}, @code{#\cr} | |
1245 | @item | |
1246 | @code{#\page}, @code{#\np} | |
1247 | @item | |
1248 | @code{#\null}, @code{#\nul} | |
1249 | @end itemize | |
1250 | ||
1251 | @rnindex char? | |
8f85c0c6 NJ |
1252 | @deffn {Scheme Procedure} char? x |
1253 | @deffnx {C Function} scm_char_p (x) | |
a0e07ba4 NJ |
1254 | Return @code{#t} iff @var{x} is a character, else @code{#f}. |
1255 | @end deffn | |
1256 | ||
1257 | @rnindex char=? | |
8f85c0c6 | 1258 | @deffn {Scheme Procedure} char=? x y |
a0e07ba4 NJ |
1259 | Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}. |
1260 | @end deffn | |
1261 | ||
1262 | @rnindex char<? | |
8f85c0c6 | 1263 | @deffn {Scheme Procedure} char<? x y |
a0e07ba4 NJ |
1264 | Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence, |
1265 | else @code{#f}. | |
1266 | @end deffn | |
1267 | ||
1268 | @rnindex char<=? | |
8f85c0c6 | 1269 | @deffn {Scheme Procedure} char<=? x y |
a0e07ba4 NJ |
1270 | Return @code{#t} iff @var{x} is less than or equal to @var{y} in the |
1271 | ASCII sequence, else @code{#f}. | |
1272 | @end deffn | |
1273 | ||
1274 | @rnindex char>? | |
8f85c0c6 | 1275 | @deffn {Scheme Procedure} char>? x y |
a0e07ba4 NJ |
1276 | Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII |
1277 | sequence, else @code{#f}. | |
1278 | @end deffn | |
1279 | ||
1280 | @rnindex char>=? | |
8f85c0c6 | 1281 | @deffn {Scheme Procedure} char>=? x y |
a0e07ba4 NJ |
1282 | Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the |
1283 | ASCII sequence, else @code{#f}. | |
1284 | @end deffn | |
1285 | ||
1286 | @rnindex char-ci=? | |
8f85c0c6 | 1287 | @deffn {Scheme Procedure} char-ci=? x y |
a0e07ba4 NJ |
1288 | Return @code{#t} iff @var{x} is the same character as @var{y} ignoring |
1289 | case, else @code{#f}. | |
1290 | @end deffn | |
1291 | ||
1292 | @rnindex char-ci<? | |
8f85c0c6 | 1293 | @deffn {Scheme Procedure} char-ci<? x y |
a0e07ba4 NJ |
1294 | Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence |
1295 | ignoring case, else @code{#f}. | |
1296 | @end deffn | |
1297 | ||
1298 | @rnindex char-ci<=? | |
8f85c0c6 | 1299 | @deffn {Scheme Procedure} char-ci<=? x y |
a0e07ba4 NJ |
1300 | Return @code{#t} iff @var{x} is less than or equal to @var{y} in the |
1301 | ASCII sequence ignoring case, else @code{#f}. | |
1302 | @end deffn | |
1303 | ||
1304 | @rnindex char-ci>? | |
8f85c0c6 | 1305 | @deffn {Scheme Procedure} char-ci>? x y |
a0e07ba4 NJ |
1306 | Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII |
1307 | sequence ignoring case, else @code{#f}. | |
1308 | @end deffn | |
1309 | ||
1310 | @rnindex char-ci>=? | |
8f85c0c6 | 1311 | @deffn {Scheme Procedure} char-ci>=? x y |
a0e07ba4 NJ |
1312 | Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the |
1313 | ASCII sequence ignoring case, else @code{#f}. | |
1314 | @end deffn | |
1315 | ||
1316 | @rnindex char-alphabetic? | |
8f85c0c6 NJ |
1317 | @deffn {Scheme Procedure} char-alphabetic? chr |
1318 | @deffnx {C Function} scm_char_alphabetic_p (chr) | |
a0e07ba4 NJ |
1319 | Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}. |
1320 | Alphabetic means the same thing as the isalpha C library function. | |
1321 | @end deffn | |
1322 | ||
1323 | @rnindex char-numeric? | |
8f85c0c6 NJ |
1324 | @deffn {Scheme Procedure} char-numeric? chr |
1325 | @deffnx {C Function} scm_char_numeric_p (chr) | |
a0e07ba4 NJ |
1326 | Return @code{#t} iff @var{chr} is numeric, else @code{#f}. |
1327 | Numeric means the same thing as the isdigit C library function. | |
1328 | @end deffn | |
1329 | ||
1330 | @rnindex char-whitespace? | |
8f85c0c6 NJ |
1331 | @deffn {Scheme Procedure} char-whitespace? chr |
1332 | @deffnx {C Function} scm_char_whitespace_p (chr) | |
a0e07ba4 NJ |
1333 | Return @code{#t} iff @var{chr} is whitespace, else @code{#f}. |
1334 | Whitespace means the same thing as the isspace C library function. | |
1335 | @end deffn | |
1336 | ||
1337 | @rnindex char-upper-case? | |
8f85c0c6 NJ |
1338 | @deffn {Scheme Procedure} char-upper-case? chr |
1339 | @deffnx {C Function} scm_char_upper_case_p (chr) | |
a0e07ba4 NJ |
1340 | Return @code{#t} iff @var{chr} is uppercase, else @code{#f}. |
1341 | Uppercase means the same thing as the isupper C library function. | |
1342 | @end deffn | |
1343 | ||
1344 | @rnindex char-lower-case? | |
8f85c0c6 NJ |
1345 | @deffn {Scheme Procedure} char-lower-case? chr |
1346 | @deffnx {C Function} scm_char_lower_case_p (chr) | |
a0e07ba4 NJ |
1347 | Return @code{#t} iff @var{chr} is lowercase, else @code{#f}. |
1348 | Lowercase means the same thing as the islower C library function. | |
1349 | @end deffn | |
1350 | ||
8f85c0c6 NJ |
1351 | @deffn {Scheme Procedure} char-is-both? chr |
1352 | @deffnx {C Function} scm_char_is_both_p (chr) | |
a0e07ba4 NJ |
1353 | Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}. |
1354 | Uppercase and lowercase are as defined by the isupper and islower | |
1355 | C library functions. | |
1356 | @end deffn | |
1357 | ||
1358 | @rnindex char->integer | |
8f85c0c6 NJ |
1359 | @deffn {Scheme Procedure} char->integer chr |
1360 | @deffnx {C Function} scm_char_to_integer (chr) | |
a0e07ba4 NJ |
1361 | Return the number corresponding to ordinal position of @var{chr} in the |
1362 | ASCII sequence. | |
1363 | @end deffn | |
1364 | ||
1365 | @rnindex integer->char | |
8f85c0c6 NJ |
1366 | @deffn {Scheme Procedure} integer->char n |
1367 | @deffnx {C Function} scm_integer_to_char (n) | |
a0e07ba4 NJ |
1368 | Return the character at position @var{n} in the ASCII sequence. |
1369 | @end deffn | |
1370 | ||
1371 | @rnindex char-upcase | |
8f85c0c6 NJ |
1372 | @deffn {Scheme Procedure} char-upcase chr |
1373 | @deffnx {C Function} scm_char_upcase (chr) | |
a0e07ba4 NJ |
1374 | Return the uppercase character version of @var{chr}. |
1375 | @end deffn | |
1376 | ||
1377 | @rnindex char-downcase | |
8f85c0c6 NJ |
1378 | @deffn {Scheme Procedure} char-downcase chr |
1379 | @deffnx {C Function} scm_char_downcase (chr) | |
a0e07ba4 NJ |
1380 | Return the lowercase character version of @var{chr}. |
1381 | @end deffn | |
1382 | ||
1383 | ||
1384 | @node Strings | |
1385 | @section Strings | |
1386 | @tpindex Strings | |
1387 | ||
1388 | Strings are fixed-length sequences of characters. They can be created | |
1389 | by calling constructor procedures, but they can also literally get | |
1390 | entered at the REPL or in Scheme source files. | |
1391 | ||
1392 | Guile provides a rich set of string processing procedures, because text | |
1393 | handling is very important when Guile is used as a scripting language. | |
1394 | ||
1395 | Strings always carry the information about how many characters they are | |
1396 | composed of with them, so there is no special end-of-string character, | |
1397 | like in C. That means that Scheme strings can contain any character, | |
1398 | even the NUL character @code{'\0'}. But note: Since most operating | |
1399 | system calls dealing with strings (such as for file operations) expect | |
1400 | strings to be zero-terminated, they might do unexpected things when | |
85a9b4ed | 1401 | called with string containing unusual characters. |
a0e07ba4 NJ |
1402 | |
1403 | @menu | |
1404 | * String Syntax:: Read syntax for strings. | |
1405 | * String Predicates:: Testing strings for certain properties. | |
1406 | * String Constructors:: Creating new string objects. | |
1407 | * List/String Conversion:: Converting from/to lists of characters. | |
1408 | * String Selection:: Select portions from strings. | |
1409 | * String Modification:: Modify parts or whole strings. | |
1410 | * String Comparison:: Lexicographic ordering predicates. | |
1411 | * String Searching:: Searching in strings. | |
1412 | * Alphabetic Case Mapping:: Convert the alphabetic case of strings. | |
1413 | * Appending Strings:: Appending strings to form a new string. | |
a0e07ba4 NJ |
1414 | @end menu |
1415 | ||
1416 | @node String Syntax | |
1417 | @subsection String Read Syntax | |
1418 | ||
1419 | The read syntax for strings is an arbitrarily long sequence of | |
1420 | characters enclosed in double quotes (@code{"}). @footnote{Actually, the | |
1421 | current implementation restricts strings to a length of 2^24 | |
1422 | characters.} If you want to insert a double quote character into a | |
1423 | string literal, it must be prefixed with a backslash @code{\} character | |
6c997de2 | 1424 | (called an @dfn{escape character}). |
a0e07ba4 NJ |
1425 | |
1426 | The following are examples of string literals: | |
1427 | ||
1428 | @lisp | |
1429 | "foo" | |
1430 | "bar plonk" | |
1431 | "Hello World" | |
1432 | "\"Hi\", he said." | |
1433 | @end lisp | |
1434 | ||
1435 | @c FIXME::martin: What about escape sequences like \r, \n etc.? | |
1436 | ||
1437 | @node String Predicates | |
1438 | @subsection String Predicates | |
1439 | ||
1440 | The following procedures can be used to check whether a given string | |
1441 | fulfills some specified property. | |
1442 | ||
1443 | @rnindex string? | |
8f85c0c6 NJ |
1444 | @deffn {Scheme Procedure} string? obj |
1445 | @deffnx {C Function} scm_string_p (obj) | |
6c997de2 | 1446 | Return @code{#t} iff @var{obj} is a string, else @code{#f}. |
a0e07ba4 NJ |
1447 | @end deffn |
1448 | ||
8f85c0c6 NJ |
1449 | @deffn {Scheme Procedure} string-null? str |
1450 | @deffnx {C Function} scm_string_null_p (str) | |
b56b5983 | 1451 | Return @code{#t} if @var{str}'s length is zero, and |
a0e07ba4 NJ |
1452 | @code{#f} otherwise. |
1453 | @lisp | |
1454 | (string-null? "") @result{} #t | |
1455 | y @result{} "foo" | |
1456 | (string-null? y) @result{} #f | |
1457 | @end lisp | |
1458 | @end deffn | |
1459 | ||
1460 | @node String Constructors | |
1461 | @subsection String Constructors | |
1462 | ||
1463 | The string constructor procedures create new string objects, possibly | |
1464 | initializing them with some specified character data. | |
1465 | ||
1466 | @c FIXME::martin: list->string belongs into `List/String Conversion' | |
1467 | ||
1468 | @rnindex string | |
1469 | @rnindex list->string | |
8f85c0c6 NJ |
1470 | @deffn {Scheme Procedure} string . chrs |
1471 | @deffnx {Scheme Procedure} list->string chrs | |
1472 | @deffnx {C Function} scm_string (chrs) | |
a0e07ba4 NJ |
1473 | Return a newly allocated string composed of the arguments, |
1474 | @var{chrs}. | |
1475 | @end deffn | |
1476 | ||
1477 | @rnindex make-string | |
8f85c0c6 NJ |
1478 | @deffn {Scheme Procedure} make-string k [chr] |
1479 | @deffnx {C Function} scm_make_string (k, chr) | |
a0e07ba4 NJ |
1480 | Return a newly allocated string of |
1481 | length @var{k}. If @var{chr} is given, then all elements of | |
1482 | the string are initialized to @var{chr}, otherwise the contents | |
1483 | of the @var{string} are unspecified. | |
1484 | @end deffn | |
1485 | ||
1486 | @node List/String Conversion | |
1487 | @subsection List/String conversion | |
1488 | ||
1489 | When processing strings, it is often convenient to first convert them | |
1490 | into a list representation by using the procedure @code{string->list}, | |
1491 | work with the resulting list, and then convert it back into a string. | |
1492 | These procedures are useful for similar tasks. | |
1493 | ||
1494 | @rnindex string->list | |
8f85c0c6 NJ |
1495 | @deffn {Scheme Procedure} string->list str |
1496 | @deffnx {C Function} scm_string_to_list (str) | |
a0e07ba4 NJ |
1497 | Return a newly allocated list of the characters that make up |
1498 | the given string @var{str}. @code{string->list} and | |
1499 | @code{list->string} are inverses as far as @samp{equal?} is | |
1500 | concerned. | |
1501 | @end deffn | |
1502 | ||
8f85c0c6 NJ |
1503 | @deffn {Scheme Procedure} string-split str chr |
1504 | @deffnx {C Function} scm_string_split (str, chr) | |
a0e07ba4 NJ |
1505 | Split the string @var{str} into the a list of the substrings delimited |
1506 | by appearances of the character @var{chr}. Note that an empty substring | |
1507 | between separator characters will result in an empty string in the | |
1508 | result list. | |
9401323e | 1509 | |
a0e07ba4 | 1510 | @lisp |
72dd0a03 | 1511 | (string-split "root:x:0:0:root:/root:/bin/bash" #\:) |
a0e07ba4 NJ |
1512 | @result{} |
1513 | ("root" "x" "0" "0" "root" "/root" "/bin/bash") | |
1514 | ||
72dd0a03 | 1515 | (string-split "::" #\:) |
a0e07ba4 NJ |
1516 | @result{} |
1517 | ("" "" "") | |
1518 | ||
72dd0a03 | 1519 | (string-split "" #\:) |
a0e07ba4 NJ |
1520 | @result{} |
1521 | ("") | |
1522 | @end lisp | |
1523 | @end deffn | |
1524 | ||
1525 | ||
1526 | @node String Selection | |
1527 | @subsection String Selection | |
1528 | ||
1529 | Portions of strings can be extracted by these procedures. | |
1530 | @code{string-ref} delivers individual characters whereas | |
1531 | @code{substring} can be used to extract substrings from longer strings. | |
1532 | ||
1533 | @rnindex string-length | |
8f85c0c6 NJ |
1534 | @deffn {Scheme Procedure} string-length string |
1535 | @deffnx {C Function} scm_string_length (string) | |
a0e07ba4 NJ |
1536 | Return the number of characters in @var{string}. |
1537 | @end deffn | |
1538 | ||
1539 | @rnindex string-ref | |
8f85c0c6 NJ |
1540 | @deffn {Scheme Procedure} string-ref str k |
1541 | @deffnx {C Function} scm_string_ref (str, k) | |
a0e07ba4 NJ |
1542 | Return character @var{k} of @var{str} using zero-origin |
1543 | indexing. @var{k} must be a valid index of @var{str}. | |
1544 | @end deffn | |
1545 | ||
1546 | @rnindex string-copy | |
8f85c0c6 NJ |
1547 | @deffn {Scheme Procedure} string-copy str |
1548 | @deffnx {C Function} scm_string_copy (str) | |
a0e07ba4 NJ |
1549 | Return a newly allocated copy of the given @var{string}. |
1550 | @end deffn | |
1551 | ||
1552 | @rnindex substring | |
8f85c0c6 NJ |
1553 | @deffn {Scheme Procedure} substring str start [end] |
1554 | @deffnx {C Function} scm_substring (str, start, end) | |
a0e07ba4 NJ |
1555 | Return a newly allocated string formed from the characters |
1556 | of @var{str} beginning with index @var{start} (inclusive) and | |
1557 | ending with index @var{end} (exclusive). | |
1558 | @var{str} must be a string, @var{start} and @var{end} must be | |
1559 | exact integers satisfying: | |
1560 | ||
1561 | 0 <= @var{start} <= @var{end} <= (string-length @var{str}). | |
1562 | @end deffn | |
1563 | ||
1564 | @node String Modification | |
1565 | @subsection String Modification | |
1566 | ||
6c997de2 NJ |
1567 | These procedures are for modifying strings in-place. This means that the |
1568 | result of the operation is not a new string; instead, the original string's | |
1569 | memory representation is modified. | |
a0e07ba4 NJ |
1570 | |
1571 | @rnindex string-set! | |
8f85c0c6 NJ |
1572 | @deffn {Scheme Procedure} string-set! str k chr |
1573 | @deffnx {C Function} scm_string_set_x (str, k, chr) | |
a0e07ba4 NJ |
1574 | Store @var{chr} in element @var{k} of @var{str} and return |
1575 | an unspecified value. @var{k} must be a valid index of | |
1576 | @var{str}. | |
1577 | @end deffn | |
1578 | ||
1579 | @rnindex string-fill! | |
8f85c0c6 NJ |
1580 | @deffn {Scheme Procedure} string-fill! str chr |
1581 | @deffnx {C Function} scm_string_fill_x (str, chr) | |
a0e07ba4 NJ |
1582 | Store @var{char} in every element of the given @var{string} and |
1583 | return an unspecified value. | |
1584 | @end deffn | |
1585 | ||
8f85c0c6 NJ |
1586 | @deffn {Scheme Procedure} substring-fill! str start end fill |
1587 | @deffnx {C Function} scm_substring_fill_x (str, start, end, fill) | |
a0e07ba4 NJ |
1588 | Change every character in @var{str} between @var{start} and |
1589 | @var{end} to @var{fill}. | |
1590 | ||
1591 | @lisp | |
1592 | (define y "abcdefg") | |
1593 | (substring-fill! y 1 3 #\r) | |
1594 | y | |
1595 | @result{} "arrdefg" | |
1596 | @end lisp | |
1597 | @end deffn | |
1598 | ||
8f85c0c6 NJ |
1599 | @deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2 |
1600 | @deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2) | |
a0e07ba4 | 1601 | Copy the substring of @var{str1} bounded by @var{start1} and @var{end1} |
9401323e | 1602 | into @var{str2} beginning at position @var{start2}. |
8f85c0c6 | 1603 | @var{str1} and @var{str2} can be the same string. |
a0e07ba4 NJ |
1604 | @end deffn |
1605 | ||
1606 | ||
1607 | @node String Comparison | |
1608 | @subsection String Comparison | |
1609 | ||
1610 | The procedures in this section are similar to the character ordering | |
1611 | predicates (@pxref{Characters}), but are defined on character sequences. | |
1612 | They all return @code{#t} on success and @code{#f} on failure. The | |
1613 | predicates ending in @code{-ci} ignore the character case when comparing | |
1614 | strings. | |
1615 | ||
1616 | ||
1617 | @rnindex string=? | |
8f85c0c6 | 1618 | @deffn {Scheme Procedure} string=? s1 s2 |
a0e07ba4 NJ |
1619 | Lexicographic equality predicate; return @code{#t} if the two |
1620 | strings are the same length and contain the same characters in | |
1621 | the same positions, otherwise return @code{#f}. | |
1622 | ||
1623 | The procedure @code{string-ci=?} treats upper and lower case | |
1624 | letters as though they were the same character, but | |
1625 | @code{string=?} treats upper and lower case as distinct | |
1626 | characters. | |
1627 | @end deffn | |
1628 | ||
1629 | @rnindex string<? | |
8f85c0c6 | 1630 | @deffn {Scheme Procedure} string<? s1 s2 |
a0e07ba4 NJ |
1631 | Lexicographic ordering predicate; return @code{#t} if @var{s1} |
1632 | is lexicographically less than @var{s2}. | |
1633 | @end deffn | |
1634 | ||
1635 | @rnindex string<=? | |
8f85c0c6 | 1636 | @deffn {Scheme Procedure} string<=? s1 s2 |
a0e07ba4 NJ |
1637 | Lexicographic ordering predicate; return @code{#t} if @var{s1} |
1638 | is lexicographically less than or equal to @var{s2}. | |
1639 | @end deffn | |
1640 | ||
1641 | @rnindex string>? | |
8f85c0c6 | 1642 | @deffn {Scheme Procedure} string>? s1 s2 |
a0e07ba4 NJ |
1643 | Lexicographic ordering predicate; return @code{#t} if @var{s1} |
1644 | is lexicographically greater than @var{s2}. | |
1645 | @end deffn | |
1646 | ||
1647 | @rnindex string>=? | |
8f85c0c6 | 1648 | @deffn {Scheme Procedure} string>=? s1 s2 |
a0e07ba4 NJ |
1649 | Lexicographic ordering predicate; return @code{#t} if @var{s1} |
1650 | is lexicographically greater than or equal to @var{s2}. | |
1651 | @end deffn | |
1652 | ||
1653 | @rnindex string-ci=? | |
8f85c0c6 | 1654 | @deffn {Scheme Procedure} string-ci=? s1 s2 |
a0e07ba4 NJ |
1655 | Case-insensitive string equality predicate; return @code{#t} if |
1656 | the two strings are the same length and their component | |
1657 | characters match (ignoring case) at each position; otherwise | |
1658 | return @code{#f}. | |
1659 | @end deffn | |
1660 | ||
1661 | @rnindex string-ci< | |
8f85c0c6 | 1662 | @deffn {Scheme Procedure} string-ci<? s1 s2 |
a0e07ba4 NJ |
1663 | Case insensitive lexicographic ordering predicate; return |
1664 | @code{#t} if @var{s1} is lexicographically less than @var{s2} | |
1665 | regardless of case. | |
1666 | @end deffn | |
1667 | ||
1668 | @rnindex string<=? | |
8f85c0c6 | 1669 | @deffn {Scheme Procedure} string-ci<=? s1 s2 |
a0e07ba4 NJ |
1670 | Case insensitive lexicographic ordering predicate; return |
1671 | @code{#t} if @var{s1} is lexicographically less than or equal | |
1672 | to @var{s2} regardless of case. | |
1673 | @end deffn | |
1674 | ||
1675 | @rnindex string-ci>? | |
8f85c0c6 | 1676 | @deffn {Scheme Procedure} string-ci>? s1 s2 |
a0e07ba4 NJ |
1677 | Case insensitive lexicographic ordering predicate; return |
1678 | @code{#t} if @var{s1} is lexicographically greater than | |
1679 | @var{s2} regardless of case. | |
1680 | @end deffn | |
1681 | ||
1682 | @rnindex string-ci>=? | |
8f85c0c6 | 1683 | @deffn {Scheme Procedure} string-ci>=? s1 s2 |
a0e07ba4 NJ |
1684 | Case insensitive lexicographic ordering predicate; return |
1685 | @code{#t} if @var{s1} is lexicographically greater than or | |
1686 | equal to @var{s2} regardless of case. | |
1687 | @end deffn | |
1688 | ||
1689 | ||
1690 | @node String Searching | |
1691 | @subsection String Searching | |
1692 | ||
b56b5983 NJ |
1693 | When searching for the index of a character in a string, these |
1694 | procedures can be used. | |
a0e07ba4 | 1695 | |
8f85c0c6 NJ |
1696 | @deffn {Scheme Procedure} string-index str chr [frm [to]] |
1697 | @deffnx {C Function} scm_string_index (str, chr, frm, to) | |
a0e07ba4 NJ |
1698 | Return the index of the first occurrence of @var{chr} in |
1699 | @var{str}. The optional integer arguments @var{frm} and | |
1700 | @var{to} limit the search to a portion of the string. This | |
1701 | procedure essentially implements the @code{index} or | |
1702 | @code{strchr} functions from the C library. | |
1703 | ||
1704 | @lisp | |
1705 | (string-index "weiner" #\e) | |
1706 | @result{} 1 | |
1707 | ||
1708 | (string-index "weiner" #\e 2) | |
1709 | @result{} 4 | |
1710 | ||
1711 | (string-index "weiner" #\e 2 4) | |
1712 | @result{} #f | |
1713 | @end lisp | |
1714 | @end deffn | |
1715 | ||
8f85c0c6 NJ |
1716 | @deffn {Scheme Procedure} string-rindex str chr [frm [to]] |
1717 | @deffnx {C Function} scm_string_rindex (str, chr, frm, to) | |
a0e07ba4 NJ |
1718 | Like @code{string-index}, but search from the right of the |
1719 | string rather than from the left. This procedure essentially | |
1720 | implements the @code{rindex} or @code{strrchr} functions from | |
1721 | the C library. | |
1722 | ||
1723 | @lisp | |
1724 | (string-rindex "weiner" #\e) | |
1725 | @result{} 4 | |
1726 | ||
1727 | (string-rindex "weiner" #\e 2 4) | |
1728 | @result{} #f | |
1729 | ||
1730 | (string-rindex "weiner" #\e 2 5) | |
1731 | @result{} 4 | |
1732 | @end lisp | |
1733 | @end deffn | |
1734 | ||
1735 | @node Alphabetic Case Mapping | |
1736 | @subsection Alphabetic Case Mapping | |
1737 | ||
1738 | These are procedures for mapping strings to their upper- or lower-case | |
1739 | equivalents, respectively, or for capitalizing strings. | |
1740 | ||
8f85c0c6 NJ |
1741 | @deffn {Scheme Procedure} string-upcase str |
1742 | @deffnx {C Function} scm_string_upcase (str) | |
a0e07ba4 NJ |
1743 | Return a freshly allocated string containing the characters of |
1744 | @var{str} in upper case. | |
1745 | @end deffn | |
1746 | ||
8f85c0c6 NJ |
1747 | @deffn {Scheme Procedure} string-upcase! str |
1748 | @deffnx {C Function} scm_string_upcase_x (str) | |
a0e07ba4 NJ |
1749 | Destructively upcase every character in @var{str} and return |
1750 | @var{str}. | |
1751 | @lisp | |
1752 | y @result{} "arrdefg" | |
1753 | (string-upcase! y) @result{} "ARRDEFG" | |
1754 | y @result{} "ARRDEFG" | |
1755 | @end lisp | |
1756 | @end deffn | |
1757 | ||
8f85c0c6 NJ |
1758 | @deffn {Scheme Procedure} string-downcase str |
1759 | @deffnx {C Function} scm_string_downcase (str) | |
a0e07ba4 NJ |
1760 | Return a freshly allocation string containing the characters in |
1761 | @var{str} in lower case. | |
1762 | @end deffn | |
1763 | ||
8f85c0c6 NJ |
1764 | @deffn {Scheme Procedure} string-downcase! str |
1765 | @deffnx {C Function} scm_string_downcase_x (str) | |
a0e07ba4 NJ |
1766 | Destructively downcase every character in @var{str} and return |
1767 | @var{str}. | |
1768 | @lisp | |
1769 | y @result{} "ARRDEFG" | |
1770 | (string-downcase! y) @result{} "arrdefg" | |
1771 | y @result{} "arrdefg" | |
1772 | @end lisp | |
1773 | @end deffn | |
1774 | ||
8f85c0c6 NJ |
1775 | @deffn {Scheme Procedure} string-capitalize str |
1776 | @deffnx {C Function} scm_string_capitalize (str) | |
a0e07ba4 NJ |
1777 | Return a freshly allocated string with the characters in |
1778 | @var{str}, where the first character of every word is | |
1779 | capitalized. | |
1780 | @end deffn | |
1781 | ||
8f85c0c6 NJ |
1782 | @deffn {Scheme Procedure} string-capitalize! str |
1783 | @deffnx {C Function} scm_string_capitalize_x (str) | |
a0e07ba4 NJ |
1784 | Upcase the first character of every word in @var{str} |
1785 | destructively and return @var{str}. | |
1786 | ||
1787 | @lisp | |
1788 | y @result{} "hello world" | |
1789 | (string-capitalize! y) @result{} "Hello World" | |
1790 | y @result{} "Hello World" | |
1791 | @end lisp | |
1792 | @end deffn | |
1793 | ||
1794 | ||
1795 | @node Appending Strings | |
1796 | @subsection Appending Strings | |
1797 | ||
1798 | The procedure @code{string-append} appends several strings together to | |
1799 | form a longer result string. | |
1800 | ||
1801 | @rnindex string-append | |
8f85c0c6 NJ |
1802 | @deffn {Scheme Procedure} string-append . args |
1803 | @deffnx {C Function} scm_string_append (args) | |
a0e07ba4 | 1804 | Return a newly allocated string whose characters form the |
8f85c0c6 | 1805 | concatenation of the given strings, @var{args}. |
a0e07ba4 NJ |
1806 | @end deffn |
1807 | ||
1808 | ||
a0e07ba4 NJ |
1809 | @node Regular Expressions |
1810 | @section Regular Expressions | |
1811 | @tpindex Regular expressions | |
1812 | ||
1813 | @cindex regular expressions | |
1814 | @cindex regex | |
1815 | @cindex emacs regexp | |
1816 | ||
1817 | A @dfn{regular expression} (or @dfn{regexp}) is a pattern that | |
1818 | describes a whole class of strings. A full description of regular | |
1819 | expressions and their syntax is beyond the scope of this manual; | |
1820 | an introduction can be found in the Emacs manual (@pxref{Regexps, | |
6c997de2 | 1821 | , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or |
a0e07ba4 NJ |
1822 | in many general Unix reference books. |
1823 | ||
1824 | If your system does not include a POSIX regular expression library, and | |
1825 | you have not linked Guile with a third-party regexp library such as Rx, | |
1826 | these functions will not be available. You can tell whether your Guile | |
1827 | installation includes regular expression support by checking whether the | |
1828 | @code{*features*} list includes the @code{regex} symbol. | |
1829 | ||
1830 | @menu | |
1831 | * Regexp Functions:: Functions that create and match regexps. | |
1832 | * Match Structures:: Finding what was matched by a regexp. | |
85a9b4ed TTN |
1833 | * Backslash Escapes:: Removing the special meaning of regexp |
1834 | meta-characters. | |
a0e07ba4 NJ |
1835 | @end menu |
1836 | ||
1837 | [FIXME: it may be useful to include an Examples section. Parts of this | |
1838 | interface are bewildering on first glance.] | |
1839 | ||
1840 | @node Regexp Functions | |
1841 | @subsection Regexp Functions | |
1842 | ||
1843 | By default, Guile supports POSIX extended regular expressions. | |
1844 | That means that the characters @samp{(}, @samp{)}, @samp{+} and | |
1845 | @samp{?} are special, and must be escaped if you wish to match the | |
1846 | literal characters. | |
1847 | ||
1848 | This regular expression interface was modeled after that | |
1849 | implemented by SCSH, the Scheme Shell. It is intended to be | |
1850 | upwardly compatible with SCSH regular expressions. | |
1851 | ||
1852 | @c begin (scm-doc-string "regex.scm" "string-match") | |
8f85c0c6 | 1853 | @deffn {Scheme Procedure} string-match pattern str [start] |
a0e07ba4 NJ |
1854 | Compile the string @var{pattern} into a regular expression and compare |
1855 | it with @var{str}. The optional numeric argument @var{start} specifies | |
1856 | the position of @var{str} at which to begin matching. | |
1857 | ||
1858 | @code{string-match} returns a @dfn{match structure} which | |
1859 | describes what, if anything, was matched by the regular | |
1860 | expression. @xref{Match Structures}. If @var{str} does not match | |
1861 | @var{pattern} at all, @code{string-match} returns @code{#f}. | |
1862 | @end deffn | |
1863 | ||
1864 | Each time @code{string-match} is called, it must compile its | |
1865 | @var{pattern} argument into a regular expression structure. This | |
1866 | operation is expensive, which makes @code{string-match} inefficient if | |
1867 | the same regular expression is used several times (for example, in a | |
1868 | loop). For better performance, you can compile a regular expression in | |
1869 | advance and then match strings against the compiled regexp. | |
1870 | ||
8f85c0c6 NJ |
1871 | @deffn {Scheme Procedure} make-regexp pat . flags |
1872 | @deffnx {C Function} scm_make_regexp (pat, flags) | |
a0e07ba4 NJ |
1873 | Compile the regular expression described by @var{pat}, and |
1874 | return the compiled regexp structure. If @var{pat} does not | |
1875 | describe a legal regular expression, @code{make-regexp} throws | |
1876 | a @code{regular-expression-syntax} error. | |
1877 | ||
1878 | The @var{flags} arguments change the behavior of the compiled | |
1879 | regular expression. The following flags may be supplied: | |
1880 | ||
1881 | @table @code | |
1882 | @item regexp/icase | |
1883 | Consider uppercase and lowercase letters to be the same when | |
1884 | matching. | |
1885 | @item regexp/newline | |
1886 | If a newline appears in the target string, then permit the | |
1887 | @samp{^} and @samp{$} operators to match immediately after or | |
1888 | immediately before the newline, respectively. Also, the | |
1889 | @samp{.} and @samp{[^...]} operators will never match a newline | |
1890 | character. The intent of this flag is to treat the target | |
1891 | string as a buffer containing many lines of text, and the | |
1892 | regular expression as a pattern that may match a single one of | |
1893 | those lines. | |
1894 | @item regexp/basic | |
1895 | Compile a basic (``obsolete'') regexp instead of the extended | |
1896 | (``modern'') regexps that are the default. Basic regexps do | |
1897 | not consider @samp{|}, @samp{+} or @samp{?} to be special | |
1898 | characters, and require the @samp{@{...@}} and @samp{(...)} | |
1899 | metacharacters to be backslash-escaped (@pxref{Backslash | |
1900 | Escapes}). There are several other differences between basic | |
1901 | and extended regular expressions, but these are the most | |
1902 | significant. | |
1903 | @item regexp/extended | |
1904 | Compile an extended regular expression rather than a basic | |
1905 | regexp. This is the default behavior; this flag will not | |
1906 | usually be needed. If a call to @code{make-regexp} includes | |
1907 | both @code{regexp/basic} and @code{regexp/extended} flags, the | |
1908 | one which comes last will override the earlier one. | |
1909 | @end table | |
1910 | @end deffn | |
1911 | ||
8f85c0c6 NJ |
1912 | @deffn {Scheme Procedure} regexp-exec rx str [start [flags]] |
1913 | @deffnx {C Function} scm_regexp_exec (rx, str, start, flags) | |
a0e07ba4 NJ |
1914 | Match the compiled regular expression @var{rx} against |
1915 | @code{str}. If the optional integer @var{start} argument is | |
1916 | provided, begin matching from that position in the string. | |
1917 | Return a match structure describing the results of the match, | |
1918 | or @code{#f} if no match could be found. | |
9401323e NJ |
1919 | |
1920 | The @var{flags} arguments change the matching behavior. | |
1921 | The following flags may be supplied: | |
1922 | ||
1923 | @table @code | |
1924 | @item regexp/notbol | |
1925 | Operator @samp{^} always fails (unless @code{regexp/newline} | |
1926 | is used). Use this when the beginning of the string should | |
1927 | not be considered the beginning of a line. | |
1928 | @item regexp/noteol | |
1929 | Operator @samp{$} always fails (unless @code{regexp/newline} | |
1930 | is used). Use this when the end of the string should not be | |
1931 | considered the end of a line. | |
1932 | @end table | |
a0e07ba4 NJ |
1933 | @end deffn |
1934 | ||
8f85c0c6 NJ |
1935 | @deffn {Scheme Procedure} regexp? obj |
1936 | @deffnx {C Function} scm_regexp_p (obj) | |
a0e07ba4 NJ |
1937 | Return @code{#t} if @var{obj} is a compiled regular expression, |
1938 | or @code{#f} otherwise. | |
1939 | @end deffn | |
1940 | ||
1941 | Regular expressions are commonly used to find patterns in one string and | |
1942 | replace them with the contents of another string. | |
1943 | ||
1944 | @c begin (scm-doc-string "regex.scm" "regexp-substitute") | |
8f85c0c6 | 1945 | @deffn {Scheme Procedure} regexp-substitute port match [item@dots{}] |
a0e07ba4 NJ |
1946 | Write to the output port @var{port} selected contents of the match |
1947 | structure @var{match}. Each @var{item} specifies what should be | |
1948 | written, and may be one of the following arguments: | |
1949 | ||
1950 | @itemize @bullet | |
1951 | @item | |
1952 | A string. String arguments are written out verbatim. | |
1953 | ||
1954 | @item | |
1955 | An integer. The submatch with that number is written. | |
1956 | ||
1957 | @item | |
1958 | The symbol @samp{pre}. The portion of the matched string preceding | |
1959 | the regexp match is written. | |
1960 | ||
1961 | @item | |
1962 | The symbol @samp{post}. The portion of the matched string following | |
1963 | the regexp match is written. | |
1964 | @end itemize | |
1965 | ||
1966 | @var{port} may be @code{#f}, in which case nothing is written; instead, | |
1967 | @code{regexp-substitute} constructs a string from the specified | |
1968 | @var{item}s and returns that. | |
1969 | @end deffn | |
1970 | ||
1971 | @c begin (scm-doc-string "regex.scm" "regexp-substitute") | |
8f85c0c6 | 1972 | @deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}] |
a0e07ba4 NJ |
1973 | Similar to @code{regexp-substitute}, but can be used to perform global |
1974 | substitutions on @var{str}. Instead of taking a match structure as an | |
1975 | argument, @code{regexp-substitute/global} takes two string arguments: a | |
1976 | @var{regexp} string describing a regular expression, and a @var{target} | |
1977 | string which should be matched against this regular expression. | |
1978 | ||
1979 | Each @var{item} behaves as in @var{regexp-substitute}, with the | |
1980 | following exceptions: | |
1981 | ||
1982 | @itemize @bullet | |
1983 | @item | |
1984 | A function may be supplied. When this function is called, it will be | |
1985 | passed one argument: a match structure for a given regular expression | |
1986 | match. It should return a string to be written out to @var{port}. | |
1987 | ||
1988 | @item | |
1989 | The @samp{post} symbol causes @code{regexp-substitute/global} to recurse | |
1990 | on the unmatched portion of @var{str}. This @emph{must} be supplied in | |
1991 | order to perform global search-and-replace on @var{str}; if it is not | |
1992 | present among the @var{item}s, then @code{regexp-substitute/global} will | |
1993 | return after processing a single match. | |
1994 | @end itemize | |
1995 | @end deffn | |
1996 | ||
1997 | @node Match Structures | |
1998 | @subsection Match Structures | |
1999 | ||
2000 | @cindex match structures | |
2001 | ||
2002 | A @dfn{match structure} is the object returned by @code{string-match} and | |
2003 | @code{regexp-exec}. It describes which portion of a string, if any, | |
2004 | matched the given regular expression. Match structures include: a | |
2005 | reference to the string that was checked for matches; the starting and | |
2006 | ending positions of the regexp match; and, if the regexp included any | |
2007 | parenthesized subexpressions, the starting and ending positions of each | |
2008 | submatch. | |
2009 | ||
2010 | In each of the regexp match functions described below, the @code{match} | |
2011 | argument must be a match structure returned by a previous call to | |
2012 | @code{string-match} or @code{regexp-exec}. Most of these functions | |
2013 | return some information about the original target string that was | |
2014 | matched against a regular expression; we will call that string | |
2015 | @var{target} for easy reference. | |
2016 | ||
2017 | @c begin (scm-doc-string "regex.scm" "regexp-match?") | |
8f85c0c6 | 2018 | @deffn {Scheme Procedure} regexp-match? obj |
a0e07ba4 NJ |
2019 | Return @code{#t} if @var{obj} is a match structure returned by a |
2020 | previous call to @code{regexp-exec}, or @code{#f} otherwise. | |
2021 | @end deffn | |
2022 | ||
2023 | @c begin (scm-doc-string "regex.scm" "match:substring") | |
8f85c0c6 | 2024 | @deffn {Scheme Procedure} match:substring match [n] |
a0e07ba4 NJ |
2025 | Return the portion of @var{target} matched by subexpression number |
2026 | @var{n}. Submatch 0 (the default) represents the entire regexp match. | |
2027 | If the regular expression as a whole matched, but the subexpression | |
2028 | number @var{n} did not match, return @code{#f}. | |
2029 | @end deffn | |
2030 | ||
2031 | @c begin (scm-doc-string "regex.scm" "match:start") | |
8f85c0c6 | 2032 | @deffn {Scheme Procedure} match:start match [n] |
a0e07ba4 NJ |
2033 | Return the starting position of submatch number @var{n}. |
2034 | @end deffn | |
2035 | ||
2036 | @c begin (scm-doc-string "regex.scm" "match:end") | |
8f85c0c6 | 2037 | @deffn {Scheme Procedure} match:end match [n] |
a0e07ba4 NJ |
2038 | Return the ending position of submatch number @var{n}. |
2039 | @end deffn | |
2040 | ||
2041 | @c begin (scm-doc-string "regex.scm" "match:prefix") | |
8f85c0c6 | 2042 | @deffn {Scheme Procedure} match:prefix match |
a0e07ba4 NJ |
2043 | Return the unmatched portion of @var{target} preceding the regexp match. |
2044 | @end deffn | |
2045 | ||
2046 | @c begin (scm-doc-string "regex.scm" "match:suffix") | |
8f85c0c6 | 2047 | @deffn {Scheme Procedure} match:suffix match |
a0e07ba4 NJ |
2048 | Return the unmatched portion of @var{target} following the regexp match. |
2049 | @end deffn | |
2050 | ||
2051 | @c begin (scm-doc-string "regex.scm" "match:count") | |
8f85c0c6 | 2052 | @deffn {Scheme Procedure} match:count match |
a0e07ba4 NJ |
2053 | Return the number of parenthesized subexpressions from @var{match}. |
2054 | Note that the entire regular expression match itself counts as a | |
2055 | subexpression, and failed submatches are included in the count. | |
2056 | @end deffn | |
2057 | ||
2058 | @c begin (scm-doc-string "regex.scm" "match:string") | |
8f85c0c6 | 2059 | @deffn {Scheme Procedure} match:string match |
a0e07ba4 NJ |
2060 | Return the original @var{target} string. |
2061 | @end deffn | |
2062 | ||
2063 | @node Backslash Escapes | |
2064 | @subsection Backslash Escapes | |
2065 | ||
2066 | Sometimes you will want a regexp to match characters like @samp{*} or | |
2067 | @samp{$} exactly. For example, to check whether a particular string | |
2068 | represents a menu entry from an Info node, it would be useful to match | |
2069 | it against a regexp like @samp{^* [^:]*::}. However, this won't work; | |
2070 | because the asterisk is a metacharacter, it won't match the @samp{*} at | |
2071 | the beginning of the string. In this case, we want to make the first | |
2072 | asterisk un-magic. | |
2073 | ||
2074 | You can do this by preceding the metacharacter with a backslash | |
2075 | character @samp{\}. (This is also called @dfn{quoting} the | |
2076 | metacharacter, and is known as a @dfn{backslash escape}.) When Guile | |
2077 | sees a backslash in a regular expression, it considers the following | |
2078 | glyph to be an ordinary character, no matter what special meaning it | |
2079 | would ordinarily have. Therefore, we can make the above example work by | |
2080 | changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells | |
2081 | the regular expression engine to match only a single asterisk in the | |
2082 | target string. | |
2083 | ||
2084 | Since the backslash is itself a metacharacter, you may force a regexp to | |
2085 | match a backslash in the target string by preceding the backslash with | |
2086 | itself. For example, to find variable references in a @TeX{} program, | |
2087 | you might want to find occurrences of the string @samp{\let\} followed | |
2088 | by any number of alphabetic characters. The regular expression | |
2089 | @samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the | |
2090 | regexp each match a single backslash in the target string. | |
2091 | ||
2092 | @c begin (scm-doc-string "regex.scm" "regexp-quote") | |
8f85c0c6 | 2093 | @deffn {Scheme Procedure} regexp-quote str |
a0e07ba4 NJ |
2094 | Quote each special character found in @var{str} with a backslash, and |
2095 | return the resulting string. | |
2096 | @end deffn | |
2097 | ||
2098 | @strong{Very important:} Using backslash escapes in Guile source code | |
2099 | (as in Emacs Lisp or C) can be tricky, because the backslash character | |
2100 | has special meaning for the Guile reader. For example, if Guile | |
2101 | encounters the character sequence @samp{\n} in the middle of a string | |
2102 | while processing Scheme code, it replaces those characters with a | |
2103 | newline character. Similarly, the character sequence @samp{\t} is | |
2104 | replaced by a horizontal tab. Several of these @dfn{escape sequences} | |
2105 | are processed by the Guile reader before your code is executed. | |
2106 | Unrecognized escape sequences are ignored: if the characters @samp{\*} | |
2107 | appear in a string, they will be translated to the single character | |
2108 | @samp{*}. | |
2109 | ||
2110 | This translation is obviously undesirable for regular expressions, since | |
2111 | we want to be able to include backslashes in a string in order to | |
2112 | escape regexp metacharacters. Therefore, to make sure that a backslash | |
2113 | is preserved in a string in your Guile program, you must use @emph{two} | |
2114 | consecutive backslashes: | |
2115 | ||
2116 | @lisp | |
2117 | (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*")) | |
2118 | @end lisp | |
2119 | ||
2120 | The string in this example is preprocessed by the Guile reader before | |
2121 | any code is executed. The resulting argument to @code{make-regexp} is | |
2122 | the string @samp{^\* [^:]*}, which is what we really want. | |
2123 | ||
2124 | This also means that in order to write a regular expression that matches | |
2125 | a single backslash character, the regular expression string in the | |
2126 | source code must include @emph{four} backslashes. Each consecutive pair | |
2127 | of backslashes gets translated by the Guile reader to a single | |
2128 | backslash, and the resulting double-backslash is interpreted by the | |
2129 | regexp engine as matching a single backslash character. Hence: | |
2130 | ||
2131 | @lisp | |
2132 | (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*")) | |
2133 | @end lisp | |
2134 | ||
2135 | The reason for the unwieldiness of this syntax is historical. Both | |
2136 | regular expression pattern matchers and Unix string processing systems | |
2137 | have traditionally used backslashes with the special meanings | |
2138 | described above. The POSIX regular expression specification and ANSI C | |
2139 | standard both require these semantics. Attempting to abandon either | |
2140 | convention would cause other kinds of compatibility problems, possibly | |
2141 | more severe ones. Therefore, without extending the Scheme reader to | |
2142 | support strings with different quoting conventions (an ungainly and | |
2143 | confusing extension when implemented in other languages), we must adhere | |
2144 | to this cumbersome escape syntax. | |
2145 | ||
a0e07ba4 | 2146 | |
2a946b44 NJ |
2147 | @node Symbols |
2148 | @section Symbols | |
2149 | @tpindex Symbols | |
a0e07ba4 | 2150 | |
2a946b44 NJ |
2151 | Symbols have two main uses. Crucially, they are used for denoting |
2152 | variables in a Scheme program. In addition, they are very useful for | |
2153 | describing discrete literal data. | |
a0e07ba4 | 2154 | |
2a946b44 NJ |
2155 | A symbol is an object with a name that consists of a string of |
2156 | characters. In the usual case (where the name doesn't include any | |
2157 | characters that could be confused with other elements of Scheme syntax) | |
2158 | a symbol can be written in a Scheme program by writing the sequence of | |
2159 | characters that make up the symbol's name. For example, the read syntax | |
2160 | for the symbol named "multiply-by-2" is simply | |
a0e07ba4 | 2161 | |
2a946b44 NJ |
2162 | @lisp |
2163 | multiply-by-2 | |
2164 | @end lisp | |
a0e07ba4 | 2165 | |
2a946b44 NJ |
2166 | Symbols, then, look rather like strings but without any quotation marks. |
2167 | But there are several functional differences between them. The first | |
2168 | big functional difference between symbols and strings concerns | |
2169 | uniqueness. If the same-looking string is read twice from two different | |
2170 | places in a program, the result is two @emph{distinguishable} string | |
2171 | objects whose contents just happen to be the same. If, on the other | |
2172 | hand, the same-looking symbol is read twice from two different places in | |
2173 | a program, the result is the @emph{same} symbol object both times. | |
a0e07ba4 | 2174 | |
2a946b44 NJ |
2175 | @lisp |
2176 | (define str1 "hello") | |
2177 | (define str2 "hello") | |
2178 | (eq? str1 str2) @result{} #f | |
a0e07ba4 | 2179 | |
2a946b44 NJ |
2180 | (define sym1 (quote hello)) |
2181 | (define sym2 (quote hello)) | |
2182 | (eq? sym1 sym2) @result{} #t | |
2183 | @end lisp | |
a0e07ba4 | 2184 | |
2a946b44 NJ |
2185 | The second important difference is that symbols, unlike strings, are not |
2186 | self-evaluating. An unquoted symbol is interpreted as a variable | |
2187 | reference, and the result of evaluating that symbol is the corresponding | |
2188 | variable's value. (By the way, this is why we needed the @code{(quote | |
2189 | @dots{})}s in the example above: @code{(quote hello)} returns the symbol | |
2190 | object named "hello" itself, whereas an unquoted @code{hello} would try | |
2191 | to find and dereference a variable associated with that symbol.) | |
2192 | ||
2193 | For example, when the expression @code{(string-length "abcd")} is read | |
2194 | and evaluated, the sequence of characters @code{string-length} is read | |
2195 | as the symbol whose name is "string-length". This symbol is associated | |
2196 | with a variable whose value is the procedure that implements string | |
2197 | length calculation. Therefore evaluation of the @code{string-length} | |
2198 | symbol results in that procedure. | |
2199 | ||
2200 | Although the use of symbols for variable references is undoubtedly their | |
2201 | most important role in Scheme, it is not documented further here. See | |
2202 | instead @ref{Binding Constructs}, for how associations between symbols | |
2203 | and variables are created, and @ref{Modules}, for how those associations | |
2204 | are affected by Guile's module system. The rest of this section | |
2205 | explains how symbols can also be used to represent discrete values, and | |
2206 | documents the procedures available that relate to symbols as data | |
2207 | objects @i{per se}. | |
a0e07ba4 NJ |
2208 | |
2209 | @menu | |
2a946b44 NJ |
2210 | * Symbol Read Syntax:: Extended read syntax for symbols. |
2211 | * Symbol Primitives:: Operations related to symbols. | |
2212 | * Symbol Discrete:: Using symbols as discrete values. | |
2213 | * Symbol Props:: Function slots and property lists. | |
a0e07ba4 NJ |
2214 | @end menu |
2215 | ||
a0e07ba4 | 2216 | |
2a946b44 NJ |
2217 | @node Symbol Read Syntax |
2218 | @subsection Extended Read Syntax for Symbols | |
a0e07ba4 NJ |
2219 | |
2220 | The read syntax for symbols is a sequence of letters, digits, and | |
2a946b44 NJ |
2221 | @dfn{extended alphabetic characters}, beginning with a character that |
2222 | cannot begin a number. In addition, the special cases of @code{+}, | |
2223 | @code{-}, and @code{...} are read as symbols even though numbers can | |
2224 | begin with @code{+}, @code{-} or @code{.}. | |
a0e07ba4 NJ |
2225 | |
2226 | Extended alphabetic characters may be used within identifiers as if | |
2a946b44 | 2227 | they were letters. The set of extended alphabetic characters is: |
a0e07ba4 NJ |
2228 | |
2229 | @example | |
2230 | ! $ % & * + - . / : < = > ? @@ ^ _ ~ | |
2231 | @end example | |
2232 | ||
2a946b44 NJ |
2233 | In addition to the standard read syntax defined above (which is taken |
2234 | from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on | |
2235 | Scheme})), Guile provides an extended symbol read syntax that allows the | |
2236 | inclusion of unusual characters such as space characters, newlines and | |
2237 | parentheses. If (for whatever reason) you need to write a symbol | |
2238 | containing characters not mentioned above, you can do so as follows. | |
a0e07ba4 NJ |
2239 | |
2240 | @itemize @bullet | |
2241 | @item | |
2a946b44 | 2242 | Begin the symbol with the characters @code{#@{}, |
a0e07ba4 NJ |
2243 | |
2244 | @item | |
2245 | write the characters of the symbol and | |
2246 | ||
2247 | @item | |
2248 | finish the symbol with the characters @code{@}#}. | |
2249 | @end itemize | |
2250 | ||
2a946b44 NJ |
2251 | Here are a few examples of this form of read syntax. The first symbol |
2252 | needs to use extended syntax because it contains a space character, the | |
2253 | second because it contains a line break, and the last because it looks | |
2254 | like a number. | |
a0e07ba4 NJ |
2255 | |
2256 | @lisp | |
2257 | #@{foo bar@}# | |
2a946b44 | 2258 | |
a0e07ba4 NJ |
2259 | #@{what |
2260 | ever@}# | |
2a946b44 | 2261 | |
a0e07ba4 NJ |
2262 | #@{4242@}# |
2263 | @end lisp | |
2264 | ||
2a946b44 NJ |
2265 | Although Guile provides this extended read syntax for symbols, |
2266 | widespread usage of it is discouraged because it is not portable and not | |
2267 | very readable. | |
2268 | ||
2269 | ||
2270 | @node Symbol Primitives | |
2271 | @subsection Operations Related to Symbols | |
a0e07ba4 NJ |
2272 | |
2273 | @rnindex symbol? | |
8f85c0c6 NJ |
2274 | @deffn {Scheme Procedure} symbol? obj |
2275 | @deffnx {C Function} scm_symbol_p (obj) | |
a0e07ba4 NJ |
2276 | Return @code{#t} if @var{obj} is a symbol, otherwise return |
2277 | @code{#f}. | |
2278 | @end deffn | |
2279 | ||
2280 | @rnindex string->symbol | |
8f85c0c6 NJ |
2281 | @deffn {Scheme Procedure} string->symbol string |
2282 | @deffnx {C Function} scm_string_to_symbol (string) | |
a0e07ba4 NJ |
2283 | Return the symbol whose name is @var{string}. This procedure |
2284 | can create symbols with names containing special characters or | |
2285 | letters in the non-standard case, but it is usually a bad idea | |
2286 | to create such symbols because in some implementations of | |
2287 | Scheme they cannot be read as themselves. See | |
2288 | @code{symbol->string}. | |
2289 | ||
2290 | The following examples assume that the implementation's | |
2291 | standard case is lower case: | |
2292 | ||
2293 | @lisp | |
2294 | (eq? 'mISSISSIppi 'mississippi) @result{} #t | |
2295 | (string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"} | |
2296 | (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f | |
2297 | (eq? 'JollyWog | |
2298 | (string->symbol (symbol->string 'JollyWog))) @result{} #t | |
2299 | (string=? "K. Harper, M.D." | |
2300 | (symbol->string | |
2301 | (string->symbol "K. Harper, M.D."))) @result{}#t | |
2302 | @end lisp | |
2303 | @end deffn | |
2304 | ||
2a946b44 NJ |
2305 | @deffn {Scheme Procedure} string-ci->symbol str |
2306 | @deffnx {C Function} scm_string_ci_to_symbol (str) | |
2307 | Return the symbol whose name is @var{str}. @var{str} is | |
2308 | converted to lowercase before the conversion is done, if Guile | |
2309 | is currently reading symbols case-insensitively. | |
2310 | @end deffn | |
2311 | ||
a0e07ba4 | 2312 | @rnindex symbol->string |
8f85c0c6 NJ |
2313 | @deffn {Scheme Procedure} symbol->string s |
2314 | @deffnx {C Function} scm_symbol_to_string (s) | |
a0e07ba4 NJ |
2315 | Return the name of @var{symbol} as a string. If the symbol was |
2316 | part of an object returned as the value of a literal expression | |
2317 | (section @pxref{Literal expressions,,,r5rs, The Revised^5 | |
2318 | Report on Scheme}) or by a call to the @code{read} procedure, | |
2319 | and its name contains alphabetic characters, then the string | |
2320 | returned will contain characters in the implementation's | |
9401323e | 2321 | preferred standard case---some implementations will prefer |
a0e07ba4 NJ |
2322 | upper case, others lower case. If the symbol was returned by |
2323 | @code{string->symbol}, the case of characters in the string | |
2324 | returned will be the same as the case in the string that was | |
2325 | passed to @code{string->symbol}. It is an error to apply | |
2326 | mutation procedures like @code{string-set!} to strings returned | |
2327 | by this procedure. | |
2328 | ||
2329 | The following examples assume that the implementation's | |
2330 | standard case is lower case: | |
2331 | ||
2332 | @lisp | |
2333 | (symbol->string 'flying-fish) @result{} "flying-fish" | |
2334 | (symbol->string 'Martin) @result{} "martin" | |
2335 | (symbol->string | |
2336 | (string->symbol "Malvina")) @result{} "Malvina" | |
2337 | @end lisp | |
2338 | @end deffn | |
2339 | ||
2a946b44 NJ |
2340 | @deffn {Scheme Procedure} symbol-hash symbol |
2341 | @deffnx {C Function} scm_symbol_hash (symbol) | |
2342 | Return a hash value for @var{symbol}. | |
2343 | @end deffn | |
a0e07ba4 | 2344 | |
8f85c0c6 NJ |
2345 | @deffn {Scheme Procedure} gensym [prefix] |
2346 | @deffnx {C Function} scm_gensym (prefix) | |
a0e07ba4 NJ |
2347 | Create a new symbol with a name constructed from a prefix and |
2348 | a counter value. The string @var{prefix} can be specified as | |
2349 | an optional argument. Default prefix is @code{g}. The counter | |
2350 | is increased by 1 at each call. There is no provision for | |
2351 | resetting the counter. | |
2352 | @end deffn | |
2353 | ||
a0e07ba4 | 2354 | |
2a946b44 NJ |
2355 | @node Symbol Discrete |
2356 | @subsection Using Symbols as Discrete Values | |
a0e07ba4 | 2357 | |
2a946b44 NJ |
2358 | Symbols are especially useful because two symbols which are spelled the |
2359 | same way are equivalent in the sense of @code{eq?}. That means that | |
2360 | they are actually the same Scheme object. The advantage is that symbols | |
2361 | can be compared extremely efficiently, although they carry more | |
2362 | information for the human reader than, say, numbers. | |
a0e07ba4 | 2363 | |
2a946b44 NJ |
2364 | It is very common in Scheme programs to use symbols as keys in |
2365 | association lists (@pxref{Association Lists}) or hash tables | |
2366 | (@pxref{Hash Tables}), because this usage improves the readability a | |
2367 | lot, and does not cause any performance loss. | |
a0e07ba4 | 2368 | |
2a946b44 NJ |
2369 | |
2370 | @node Symbol Props | |
2371 | @subsection Function Slots and Property Lists | |
a0e07ba4 | 2372 | |
8f85c0c6 NJ |
2373 | @deffn {Scheme Procedure} symbol-fref symbol |
2374 | @deffnx {C Function} scm_symbol_fref (symbol) | |
a0e07ba4 NJ |
2375 | Return the contents of @var{symbol}'s @dfn{function slot}. |
2376 | @end deffn | |
2377 | ||
8f85c0c6 NJ |
2378 | @deffn {Scheme Procedure} symbol-fset! symbol value |
2379 | @deffnx {C Function} scm_symbol_fset_x (symbol, value) | |
a0e07ba4 NJ |
2380 | Change the binding of @var{symbol}'s function slot. |
2381 | @end deffn | |
2382 | ||
8f85c0c6 NJ |
2383 | @deffn {Scheme Procedure} symbol-pref symbol |
2384 | @deffnx {C Function} scm_symbol_pref (symbol) | |
a0e07ba4 NJ |
2385 | Return the @dfn{property list} currently associated with @var{symbol}. |
2386 | @end deffn | |
2387 | ||
8f85c0c6 NJ |
2388 | @deffn {Scheme Procedure} symbol-pset! symbol value |
2389 | @deffnx {C Function} scm_symbol_pset_x (symbol, value) | |
a0e07ba4 NJ |
2390 | Change the binding of @var{symbol}'s property slot. |
2391 | @end deffn | |
2392 | ||
a0e07ba4 NJ |
2393 | |
2394 | @node Keywords | |
2395 | @section Keywords | |
2396 | @tpindex Keywords | |
2397 | ||
2398 | Keywords are self-evaluating objects with a convenient read syntax that | |
2399 | makes them easy to type. | |
2400 | ||
2401 | Guile's keyword support conforms to R5RS, and adds a (switchable) read | |
2402 | syntax extension to permit keywords to begin with @code{:} as well as | |
2403 | @code{#:}. | |
2404 | ||
2405 | @menu | |
2406 | * Why Use Keywords?:: Motivation for keyword usage. | |
2407 | * Coding With Keywords:: How to use keywords. | |
2408 | * Keyword Read Syntax:: Read syntax for keywords. | |
2409 | * Keyword Procedures:: Procedures for dealing with keywords. | |
2410 | * Keyword Primitives:: The underlying primitive procedures. | |
2411 | @end menu | |
2412 | ||
2413 | @node Why Use Keywords? | |
2414 | @subsection Why Use Keywords? | |
2415 | ||
2416 | Keywords are useful in contexts where a program or procedure wants to be | |
2417 | able to accept a large number of optional arguments without making its | |
2418 | interface unmanageable. | |
2419 | ||
2420 | To illustrate this, consider a hypothetical @code{make-window} | |
2421 | procedure, which creates a new window on the screen for drawing into | |
2422 | using some graphical toolkit. There are many parameters that the caller | |
2423 | might like to specify, but which could also be sensibly defaulted, for | |
2424 | example: | |
2425 | ||
2426 | @itemize @bullet | |
2427 | @item | |
85a9b4ed | 2428 | color depth -- Default: the color depth for the screen |
a0e07ba4 NJ |
2429 | |
2430 | @item | |
85a9b4ed | 2431 | background color -- Default: white |
a0e07ba4 NJ |
2432 | |
2433 | @item | |
2434 | width -- Default: 600 | |
2435 | ||
2436 | @item | |
2437 | height -- Default: 400 | |
2438 | @end itemize | |
2439 | ||
2440 | If @code{make-window} did not use keywords, the caller would have to | |
2441 | pass in a value for each possible argument, remembering the correct | |
2442 | argument order and using a special value to indicate the default value | |
2443 | for that argument: | |
2444 | ||
2445 | @lisp | |
85a9b4ed TTN |
2446 | (make-window 'default ;; Color depth |
2447 | 'default ;; Background color | |
a0e07ba4 NJ |
2448 | 800 ;; Width |
2449 | 100 ;; Height | |
2450 | @dots{}) ;; More make-window arguments | |
2451 | @end lisp | |
2452 | ||
2453 | With keywords, on the other hand, defaulted arguments are omitted, and | |
2454 | non-default arguments are clearly tagged by the appropriate keyword. As | |
2455 | a result, the invocation becomes much clearer: | |
2456 | ||
2457 | @lisp | |
2458 | (make-window #:width 800 #:height 100) | |
2459 | @end lisp | |
2460 | ||
2461 | On the other hand, for a simpler procedure with few arguments, the use | |
2462 | of keywords would be a hindrance rather than a help. The primitive | |
2463 | procedure @code{cons}, for example, would not be improved if it had to | |
2464 | be invoked as | |
2465 | ||
2466 | @lisp | |
2467 | (cons #:car x #:cdr y) | |
2468 | @end lisp | |
2469 | ||
2470 | So the decision whether to use keywords or not is purely pragmatic: use | |
2471 | them if they will clarify the procedure invocation at point of call. | |
2472 | ||
2473 | @node Coding With Keywords | |
2474 | @subsection Coding With Keywords | |
2475 | ||
2476 | If a procedure wants to support keywords, it should take a rest argument | |
2477 | and then use whatever means is convenient to extract keywords and their | |
2478 | corresponding arguments from the contents of that rest argument. | |
2479 | ||
2480 | The following example illustrates the principle: the code for | |
2481 | @code{make-window} uses a helper procedure called | |
2482 | @code{get-keyword-value} to extract individual keyword arguments from | |
2483 | the rest argument. | |
2484 | ||
2485 | @lisp | |
2486 | (define (get-keyword-value args keyword default) | |
2487 | (let ((kv (memq keyword args))) | |
2488 | (if (and kv (>= (length kv) 2)) | |
2489 | (cadr kv) | |
2490 | default))) | |
2491 | ||
2492 | (define (make-window . args) | |
2493 | (let ((depth (get-keyword-value args #:depth screen-depth)) | |
2494 | (bg (get-keyword-value args #:bg "white")) | |
2495 | (width (get-keyword-value args #:width 800)) | |
2496 | (height (get-keyword-value args #:height 100)) | |
2497 | @dots{}) | |
2498 | @dots{})) | |
2499 | @end lisp | |
2500 | ||
2501 | But you don't need to write @code{get-keyword-value}. The @code{(ice-9 | |
2502 | optargs)} module provides a set of powerful macros that you can use to | |
2503 | implement keyword-supporting procedures like this: | |
2504 | ||
2505 | @lisp | |
2506 | (use-modules (ice-9 optargs)) | |
2507 | ||
2508 | (define (make-window . args) | |
2509 | (let-keywords args #f ((depth screen-depth) | |
2510 | (bg "white") | |
2511 | (width 800) | |
2512 | (height 100)) | |
2513 | ...)) | |
2514 | @end lisp | |
2515 | ||
2516 | @noindent | |
2517 | Or, even more economically, like this: | |
2518 | ||
2519 | @lisp | |
2520 | (use-modules (ice-9 optargs)) | |
2521 | ||
2522 | (define* (make-window #:key (depth screen-depth) | |
2523 | (bg "white") | |
2524 | (width 800) | |
2525 | (height 100)) | |
2526 | ...) | |
2527 | @end lisp | |
2528 | ||
2529 | For further details on @code{let-keywords}, @code{define*} and other | |
2a946b44 NJ |
2530 | facilities provided by the @code{(ice-9 optargs)} module, see |
2531 | @ref{Optional Arguments}. | |
a0e07ba4 NJ |
2532 | |
2533 | ||
2534 | @node Keyword Read Syntax | |
2535 | @subsection Keyword Read Syntax | |
2536 | ||
2537 | Guile, by default, only recognizes the keyword syntax specified by R5RS. | |
2538 | A token of the form @code{#:NAME}, where @code{NAME} has the same syntax | |
2a946b44 NJ |
2539 | as a Scheme symbol (@pxref{Symbol Read Syntax}), is the external |
2540 | representation of the keyword named @code{NAME}. Keyword objects print | |
2541 | using this syntax as well, so values containing keyword objects can be | |
2542 | read back into Guile. When used in an expression, keywords are | |
2543 | self-quoting objects. | |
a0e07ba4 NJ |
2544 | |
2545 | If the @code{keyword} read option is set to @code{'prefix}, Guile also | |
2546 | recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens | |
2547 | of the form @code{:NAME} are read as symbols, as required by R5RS. | |
2548 | ||
2549 | To enable and disable the alternative non-R5RS keyword syntax, you use | |
2550 | the @code{read-options} procedure documented in @ref{General option | |
2551 | interface} and @ref{Reader options}. | |
2552 | ||
2553 | @smalllisp | |
2554 | (read-set! keywords 'prefix) | |
2555 | ||
2556 | #:type | |
2557 | @result{} | |
2558 | #:type | |
2559 | ||
2560 | :type | |
2561 | @result{} | |
2562 | #:type | |
2563 | ||
2564 | (read-set! keywords #f) | |
2565 | ||
2566 | #:type | |
2567 | @result{} | |
2568 | #:type | |
2569 | ||
2570 | :type | |
2a946b44 | 2571 | @print{} |
a0e07ba4 NJ |
2572 | ERROR: In expression :type: |
2573 | ERROR: Unbound variable: :type | |
2574 | ABORT: (unbound-variable) | |
2575 | @end smalllisp | |
2576 | ||
2577 | @node Keyword Procedures | |
2578 | @subsection Keyword Procedures | |
2579 | ||
2580 | @c FIXME::martin: Review me! | |
2581 | ||
2582 | The following procedures can be used for converting symbols to keywords | |
2583 | and back. | |
2584 | ||
8f85c0c6 | 2585 | @deffn {Scheme Procedure} symbol->keyword sym |
a0e07ba4 NJ |
2586 | Return a keyword with the same characters as in @var{sym}. |
2587 | @end deffn | |
2588 | ||
8f85c0c6 | 2589 | @deffn {Scheme Procedure} keyword->symbol kw |
a0e07ba4 NJ |
2590 | Return a symbol with the same characters as in @var{kw}. |
2591 | @end deffn | |
2592 | ||
2593 | ||
2594 | @node Keyword Primitives | |
2595 | @subsection Keyword Primitives | |
2596 | ||
2597 | Internally, a keyword is implemented as something like a tagged symbol, | |
2598 | where the tag identifies the keyword as being self-evaluating, and the | |
2599 | symbol, known as the keyword's @dfn{dash symbol} has the same name as | |
2600 | the keyword name but prefixed by a single dash. For example, the | |
2601 | keyword @code{#:name} has the corresponding dash symbol @code{-name}. | |
2602 | ||
2603 | Most keyword objects are constructed automatically by the reader when it | |
2604 | reads a token beginning with @code{#:}. However, if you need to | |
2605 | construct a keyword object programmatically, you can do so by calling | |
2606 | @code{make-keyword-from-dash-symbol} with the corresponding dash symbol | |
2607 | (as the reader does). The dash symbol for a keyword object can be | |
2608 | retrieved using the @code{keyword-dash-symbol} procedure. | |
2609 | ||
8f85c0c6 NJ |
2610 | @deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol |
2611 | @deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol) | |
a0e07ba4 NJ |
2612 | Make a keyword object from a @var{symbol} that starts with a dash. |
2613 | @end deffn | |
2614 | ||
8f85c0c6 NJ |
2615 | @deffn {Scheme Procedure} keyword? obj |
2616 | @deffnx {C Function} scm_keyword_p (obj) | |
a0e07ba4 NJ |
2617 | Return @code{#t} if the argument @var{obj} is a keyword, else |
2618 | @code{#f}. | |
2619 | @end deffn | |
2620 | ||
8f85c0c6 NJ |
2621 | @deffn {Scheme Procedure} keyword-dash-symbol keyword |
2622 | @deffnx {C Function} scm_keyword_dash_symbol (keyword) | |
a0e07ba4 NJ |
2623 | Return the dash symbol for @var{keyword}. |
2624 | This is the inverse of @code{make-keyword-from-dash-symbol}. | |
2625 | @end deffn | |
2626 | ||
a0e07ba4 | 2627 | |
4c731ece NJ |
2628 | @node Other Types |
2629 | @section ``Functionality-Centric'' Data Types | |
a0e07ba4 | 2630 | |
4c731ece NJ |
2631 | Procedures and macros are documented in their own chapter: see |
2632 | @ref{Procedures and Macros}. | |
a0e07ba4 | 2633 | |
4c731ece NJ |
2634 | Variable objects are documented as part of the description of Guile's |
2635 | module system: see @ref{Variables}. | |
a0e07ba4 | 2636 | |
4c731ece NJ |
2637 | Asyncs, dynamic roots and fluids are described in the chapter on |
2638 | scheduling: see @ref{Scheduling}. | |
a0e07ba4 | 2639 | |
4c731ece NJ |
2640 | Hooks are documented in the chapter on general utility functions: see |
2641 | @ref{Hooks}. | |
a0e07ba4 | 2642 | |
4c731ece | 2643 | Ports are described in the chapter on I/O: see @ref{Input and Output}. |
a0e07ba4 | 2644 | |
a0e07ba4 NJ |
2645 | |
2646 | @c Local Variables: | |
2647 | @c TeX-master: "guile.texi" | |
2648 | @c End: |