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