Commit | Line | Data |
---|---|---|
a0e07ba4 NJ |
1 | @page |
2 | @node SRFI Support | |
3 | @chapter SRFI Support Modules | |
4 | ||
5 | SRFI is an acronym for Scheme Request For Implementation. The SRFI | |
6 | documents define a lot of syntactic and procedure extensions to standard | |
7 | Scheme as defined in R5RS. | |
8 | ||
9 | Guile has support for a number of SRFIs. This chapter gives an overview | |
10 | over the available SRFIs and some usage hints. For complete | |
11 | documentation, design rationales and further examples, we advise you to | |
12 | get the relevant SRFI documents from the SRFI home page | |
13 | @url{http://srfi.schemers.org}. | |
14 | ||
15 | @menu | |
16 | * About SRFI Usage:: What to know about Guile's SRFI support. | |
17 | * SRFI-0:: cond-expand | |
18 | * SRFI-1:: List library. | |
19 | * SRFI-2:: and-let*. | |
20 | * SRFI-4:: Homogeneous numeric vector datatypes. | |
21 | * SRFI-6:: Basic String Ports. | |
22 | * SRFI-8:: receive. | |
23 | * SRFI-9:: define-record-type. | |
24 | * SRFI-10:: Hash-Comma Reader Extension. | |
25 | * SRFI-11:: let-values and let-values*. | |
26 | * SRFI-13:: String library. | |
27 | * SRFI-14:: Character-set library. | |
28 | * SRFI-16:: case-lambda | |
29 | * SRFI-17:: Generalized set! | |
30 | @end menu | |
31 | ||
32 | ||
33 | @node About SRFI Usage | |
34 | @section About SRFI Usage | |
35 | ||
36 | @c FIXME::martin: Review me! | |
37 | ||
38 | SRFI support in Guile is currently implemented partly in the core | |
39 | library, and partly as add-on modules. That means that some SRFIs are | |
40 | automatically available when the interpreter is started, whereas the | |
41 | other SRFIs require you to use the appropriate support module | |
42 | explicitly. | |
43 | ||
44 | There are several reasons for this inconsistency. First, the feature | |
45 | checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be | |
46 | available immediately, because it must be there when the user wants to | |
47 | check for the Scheme implementation, that is, before she can know that | |
48 | it is safe to use @code{use-modules} to load SRFI support modules. The | |
49 | second reason is that some features defined in SRFIs had been | |
50 | implemented in Guile before the developers started to add SRFI | |
51 | implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In | |
52 | the future, it is possible that SRFIs in the core library might be | |
53 | factored out into separate modules, requiring explicit module loading | |
54 | when they are needed. So you should be prepared to have to use | |
55 | @code{use-modules} someday in the future to access SRFI-6 bindings. If | |
56 | you want, you can do that already. We have included the module | |
57 | @code{(srfi srfi-6)} in the distribution, which currently does nothing, | |
58 | but ensures that you can write future-safe code. | |
59 | ||
60 | Generally, support for a specific SRFI is made available by using | |
61 | modules named @code{(srfi srfi-@var{number})}, where @var{number} is the | |
62 | number of the SRFI needed. Another possibility is to use the command | |
63 | line option @code{--use-srfi}, which will load the necessary modules | |
64 | automatically (@pxref{Invoking Guile}). | |
65 | ||
66 | ||
67 | @node SRFI-0 | |
68 | @section SRFI-0 - cond-expand | |
69 | ||
70 | @c FIXME::martin: Review me! | |
71 | ||
72 | SRFI-0 defines a means for checking whether a Scheme implementation has | |
73 | support for a specified feature. The syntactic form @code{cond-expand}, | |
74 | which implements this means, has the following syntax. | |
75 | ||
76 | @example | |
77 | @group | |
78 | <cond-expand> | |
79 | --> (cond-expand <cond-expand-clause>+) | |
80 | | (cond-expand <cond-expand-clause>* (else <command-or-definition>)) | |
81 | <cond-expand-clause> | |
82 | --> (<feature-requirement> <command-or-definition>*) | |
83 | <feature-requirement> | |
84 | --> <feature-identifier> | |
85 | | (and <feature-requirement>*) | |
86 | | (or <feature-requirement>*) | |
87 | | (not <feature-requirement>) | |
88 | <feature-identifier> | |
89 | --> <a symbol which is the name or alias of a SRFI> | |
90 | @end group | |
91 | @end example | |
92 | ||
93 | When evaluated, this form checks all clauses in order, until it finds | |
94 | one whose feature requirement is satisfied. Then the form expands into | |
95 | the commands or definitions in the clause. A requirement is tested as | |
96 | follows: | |
97 | ||
98 | @itemize @bullet | |
99 | @item | |
100 | If it is a symbol, it is satisfied if the feature identifier is | |
101 | supported. | |
102 | ||
103 | @item | |
104 | If it is an @code{and} form, all requirements must be satisfied. If no | |
105 | requirements are given, it is satisfied, too. | |
106 | ||
107 | @item | |
108 | If it is an @code{or} form, at least one of the requirements must be | |
109 | satisfied. If no requirements are given, it is not satisfied. | |
110 | ||
111 | @item | |
112 | If it is a @code{not} form, the feature requirement must @emph{not} be | |
113 | satisfied. | |
114 | ||
115 | @item | |
116 | If the feature requirement is the keyword @code{else} and it is the last | |
117 | clause, it is satisfied if no prior clause matched. | |
118 | @end itemize | |
119 | ||
120 | If no clause is satisfied, an error is signalled. | |
121 | ||
122 | Since @code{cond-expand} is needed to tell what a Scheme implementation | |
123 | provides, it must be accessible without using any | |
124 | implementation-dependant operations, such as @code{use-modules} in | |
125 | Guile. Thus, it is not necessary to use any module to get access to | |
126 | this form. | |
127 | ||
128 | Currently, the feature identifiers @code{guile}, @code{r5rs} and | |
129 | @code{srfi-0} are supported. The other SRFIs are not in that list by | |
130 | default, because the SRFI modules must be explicitly used before their | |
131 | exported bindings can be used. | |
132 | ||
133 | So if a Scheme program wishes to use SRFI-8, it has two possibilities: | |
134 | First, it can check whether the running Scheme implementation is Guile, | |
135 | and if it is, it can use the appropriate module: | |
136 | ||
137 | @lisp | |
138 | (cond-expand | |
139 | (guile | |
140 | (use-modules (srfi srfi-8))) | |
141 | (srfi-8 | |
142 | #t)) | |
143 | ;; otherwise fail. | |
144 | @end lisp | |
145 | ||
146 | The other possibility is to use the @code{--use-srfi} command line | |
147 | option when invoking Guile (@pxref{Invoking Guile}). When you do that, | |
148 | the specified SRFI support modules will be loaded and add their feature | |
149 | identifier to the list of symbols checked by @code{cond-expand}. | |
150 | ||
151 | So, if you invoke Guile like this: | |
152 | ||
153 | @example | |
154 | $ guile --use-srfi=8 | |
155 | @end example | |
156 | ||
157 | the following snippet will expand to @code{'hooray}. | |
158 | ||
159 | @lisp | |
160 | (cond-expand (srfi-8 'hooray)) | |
161 | @end lisp | |
162 | ||
163 | ||
164 | @node SRFI-1 | |
165 | @section SRFI-1 - List library | |
166 | ||
167 | @c FIXME::martin: Review me! | |
168 | ||
169 | The list library defined in SRFI-1 contains a lot of useful list | |
170 | processing procedures for construction, examining, destructuring and | |
171 | manipulating lists and pairs. | |
172 | ||
173 | Since SRFI-1 also defines some procedures which are already contained | |
174 | in R5RS and thus are supported by the Guile core library, some list | |
175 | and pair procedures which appear in the SRFI-1 document may not appear | |
176 | in this section. So when looking for a particular list/pair | |
177 | processing procedure, you should also have a look at the sections | |
178 | @ref{Lists} and @ref{Pairs}. | |
179 | ||
180 | @menu | |
181 | * SRFI-1 Constructors:: Constructing new lists. | |
182 | * SRFI-1 Predicates:: Testing list for specific properties. | |
183 | * SRFI-1 Selectors:: Selecting elements from lists. | |
184 | * SRFI-1 Length Append etc:: Length calculation and list appending. | |
185 | * SRFI-1 Fold and Map:: Higher-order list processing. | |
186 | * SRFI-1 Filtering and Partitioning:: Filter lists based on predicates. | |
187 | * SRFI-1 Searching:: Search for elments. | |
188 | * SRFI-1 Deleting:: Delete elements from lists. | |
189 | * SRFI-1 Association Lists:: Handle association lists. | |
190 | * SRFI-1 Set Operations:: Use lists for representing sets. | |
191 | @end menu | |
192 | ||
193 | @node SRFI-1 Constructors | |
194 | @subsection Constructors | |
195 | ||
196 | @c FIXME::martin: Review me! | |
197 | ||
198 | New lists can be constructed by calling one of the following | |
199 | procedures. | |
200 | ||
201 | @deffn procedure xcons d a | |
202 | Like @code{cons}, but with interchanged arguments. Useful mostly when | |
203 | passed to higher-order procedures. | |
204 | @end deffn | |
205 | ||
206 | @deffn procedure list-tabulate n init-proc | |
207 | Return an @var{n}-element list, where each list element is produced by | |
208 | applying the procedure @var{init-proc} to the corresponding list | |
209 | index. The order in which @var{init-proc} is applied to the indices | |
210 | is not specified. | |
211 | @end deffn | |
212 | ||
213 | @deffn procedure circular-list elt1 elt2 @dots{} | |
214 | Return a circular list containing the given arguments @var{elt1} | |
215 | @var{elt2} @dots{}. | |
216 | @end deffn | |
217 | ||
218 | @deffn procedure iota count [start step] | |
219 | Return a list containing @var{count} elements, where each element is | |
220 | calculated as follows: | |
221 | ||
222 | @var{start} + (@var{count} - 1) * @var{step} | |
223 | ||
224 | @var{start} defaults to 0 and @var{step} defaults to 1. | |
225 | @end deffn | |
226 | ||
227 | ||
228 | @node SRFI-1 Predicates | |
229 | @subsection Predicates | |
230 | ||
231 | @c FIXME::martin: Review me! | |
232 | ||
233 | The procedures in this section test specific properties of lists. | |
234 | ||
235 | @deffn procedure proper-list? obj | |
236 | Return @code{#t} if @var{obj} is a proper list, that is a finite list, | |
237 | terminated with the empty list. Otherwise, return @code{#f}. | |
238 | @end deffn | |
239 | ||
240 | @deffn procedure circular-list? obj | |
241 | Return @code{#t} if @var{obj} is a circular list, otherwise return | |
242 | @code{#f}. | |
243 | @end deffn | |
244 | ||
245 | @deffn procedure dotted-list? obj | |
246 | Return @code{#t} if @var{obj} is a dotted list, return @code{#f} | |
247 | otherwise. A dotted list is a finite list which is not terminated by | |
248 | the empty list, but some other value. | |
249 | @end deffn | |
250 | ||
251 | @deffn procedure null-list? lst | |
252 | Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f} | |
253 | otherwise. If something else than a proper or circular list is passed | |
254 | as @var{lst}, an error is signalled. This procedure is recommented | |
255 | for checking for the end of a list in contexts where dotted lists are | |
256 | not allowed. | |
257 | @end deffn | |
258 | ||
259 | @deffn procedure not-pair? obj | |
260 | Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise. | |
261 | This is shorthand notation @code{(not (pair? @var{obj}))} and is | |
262 | supposed to be used for end-of-list checking in contexts where dotted | |
263 | lists are allowed. | |
264 | @end deffn | |
265 | ||
266 | @deffn procedure list= elt= list1 @dots{} | |
267 | Return @code{#t} if all argument lists are equal, @code{#f} otherwise. | |
268 | List equality is determined by testing whether all lists have the same | |
269 | length and the corresponding elements are equal in the sense of the | |
270 | equality predicate @var{elt=}. If no or only one list is given, | |
271 | @code{#t} is returned. | |
272 | @end deffn | |
273 | ||
274 | ||
275 | @node SRFI-1 Selectors | |
276 | @subsection Selectors | |
277 | ||
278 | @c FIXME::martin: Review me! | |
279 | ||
280 | @deffn procedure first pair | |
281 | @deffnx procedure second pair | |
282 | @deffnx procedure third pair | |
283 | @deffnx procedure fourth pair | |
284 | @deffnx procedure fifth pair | |
285 | @deffnx procedure sixth pair | |
286 | @deffnx procedure seventh pair | |
287 | @deffnx procedure eighth pair | |
288 | @deffnx procedure ninth pair | |
289 | @deffnx procedure tenth pair | |
290 | These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}. | |
291 | @end deffn | |
292 | ||
293 | @deffn procedure car+cdr pair | |
294 | Return two values, the @sc{car} and the @sc{cdr} of @var{pair}. | |
295 | @end deffn | |
296 | ||
297 | @deffn procedure take lst i | |
298 | @deffnx procedure take! lst i | |
299 | Return a list containing the first @var{i} elements of @var{lst}. | |
300 | ||
301 | @code{take!} may modify the structure of the argument list @var{lst} | |
302 | in order to produce the result. | |
303 | @end deffn | |
304 | ||
305 | @deffn procedure drop lst i | |
306 | Return a list containing all but the first @var{i} elements of | |
307 | @var{lst}. | |
308 | @end deffn | |
309 | ||
310 | @deffn procedure take-right lst i | |
311 | Return the a list containing the @var{i} last elements of @var{lst}. | |
312 | @end deffn | |
313 | ||
314 | @deffn procedure drop-right lst i | |
315 | @deffnx procedure drop-right! lst i | |
316 | Return the a list containing all but the @var{i} last elements of | |
317 | @var{lst}. | |
318 | ||
319 | @code{drop-right!} may modify the structure of the argument list | |
320 | @var{lst} in order to produce the result. | |
321 | @end deffn | |
322 | ||
323 | @deffn procedure split-at lst i | |
324 | @deffnx procedure split-at! lst i | |
325 | Return two values, a list containing the first @var{i} elements of the | |
326 | list @var{lst} and a list containing the remaining elements. | |
327 | ||
328 | @code{split-at!} may modify the structure of the argument list | |
329 | @var{lst} in order to produce the result. | |
330 | @end deffn | |
331 | ||
332 | @deffn procedure last lst | |
333 | Return the last element of the non-empty, finite list @var{lst}. | |
334 | @end deffn | |
335 | ||
336 | ||
337 | @node SRFI-1 Length Append etc | |
338 | @subsection Length, Append, Concatenate, etc. | |
339 | ||
340 | @c FIXME::martin: Review me! | |
341 | ||
342 | @deffn procedure length+ lst | |
343 | Return the length of the argument list @var{lst}. When @var{lst} is a | |
344 | circular list, @code{#f} is returned. | |
345 | @end deffn | |
346 | ||
347 | @deffn procedure concatenate list-of-lists | |
348 | @deffnx procedure concatenate! list-of-lists | |
349 | Construct a list by appending all lists in @var{list-of-lists}. | |
350 | ||
351 | @code{concatenate!} may modify the structure of the given lists in | |
352 | order to produce the result. | |
353 | @end deffn | |
354 | ||
355 | @deffn procedure append-reverse rev-head tail | |
356 | @deffnx procedure append-reverse! rev-head tail | |
357 | Reverse @var{rev-head}, append @var{tail} and return the result. This | |
358 | is equivalent to @code{(append (reverse @var{rev-head}) @var{tail})}, | |
359 | but more efficient. | |
360 | ||
361 | @code{append-reverse!} may modify @var{rev-head} in order to produce | |
362 | the result. | |
363 | @end deffn | |
364 | ||
365 | @deffn procedure zip lst1 lst2 @dots{} | |
366 | Return a list as long as the shortest of the argument lists, where | |
367 | each element is a list. The first list contains the first elements of | |
368 | the argument lists, the second list contains the second elements, and | |
369 | so on. | |
370 | @end deffn | |
371 | ||
372 | @deffn procedure unzip1 lst | |
373 | @deffnx procedure unzip2 lst | |
374 | @deffnx procedure unzip3 lst | |
375 | @deffnx procedure unzip4 lst | |
376 | @deffnx procedure unzip5 lst | |
377 | @code{unzip1} takes a list of lists, and returns a list containing the | |
378 | first elements of each list, @code{unzip2} returns two lists, the | |
379 | first containing the first elements of each lists and the second | |
380 | containing the second elements of each lists, and so on. | |
381 | @end deffn | |
382 | ||
383 | ||
384 | @node SRFI-1 Fold and Map | |
385 | @subsection Fold, Unfold & Map | |
386 | ||
387 | @c FIXME::martin: Review me! | |
388 | ||
389 | @deffn procedure fold kons knil lst1 lst2 @dots{} | |
390 | Fold the procedure @var{kons} across all elements of @var{lst1}, | |
391 | @var{lst2}, @dots{}. Produce the result of | |
392 | ||
393 | @code{(@var{kons} @var{en1} @var{en2} @dots{} (@var{kons} @var{e21} | |
394 | @var{e22} (@var{kons} @var{e11} @var{e12} @var{knil})))}, | |
395 | ||
396 | if @var{enm} are the elements of the lists @var{lst1}, @var{lst2}, | |
397 | @dots{}. | |
398 | @end deffn | |
399 | ||
400 | @deffn procedure fold-right kons knil lst1 lst2 @dots{} | |
401 | Similar to @code{fold}, but applies @var{kons} in right-to-left order | |
402 | to the list elements, that is: | |
403 | ||
404 | @code{(@var{kons} @var{e11} @var{e12}(@var{kons} @var{e21} | |
405 | @var{e22} @dots{} (@var{kons} @var{en1} @var{en2} @var{knil})))}, | |
406 | @end deffn | |
407 | ||
408 | @deffn procedure pair-fold kons knil lst1 lst2 @dots{} | |
409 | Like @code{fold}, but apply @var{kons} to the pairs of the list | |
410 | instead of the list elements. | |
411 | @end deffn | |
412 | ||
413 | @deffn procedure pair-fold-right kons knil lst1 lst2 @dots{} | |
414 | Like @code{fold-right}, but apply @var{kons} to the pairs of the list | |
415 | instead of the list elements. | |
416 | @end deffn | |
417 | ||
418 | @deffn procedure reduce f ridentity lst | |
419 | @code{reduce} is a variant of @code{reduce}. If @var{lst} is | |
420 | @code{()}, @var{ridentity} is returned. Otherwise, @code{(fold (car | |
421 | @var{lst}) (cdr @var{lst}))} is returned. | |
422 | @end deffn | |
423 | ||
424 | @deffn procedure reduce-right f ridentity lst | |
425 | This is the @code{fold-right} variant of @var{reduce}. | |
426 | @end deffn | |
427 | ||
428 | @deffn procedure unfold p f g seed [tail-gen] | |
429 | @code{unfold} is defined as follows: | |
430 | ||
431 | @lisp | |
432 | (unfold p f g seed) = | |
433 | (if (p seed) (tail-gen seed) | |
434 | (cons (f seed) | |
435 | (unfold p f g (g seed)))) | |
436 | @end lisp | |
437 | ||
438 | @table @var | |
439 | @item p | |
440 | Determines when to stop unfolding. | |
441 | ||
442 | @item f | |
443 | Maps each seed value to the corresponding list element. | |
444 | ||
445 | @item g | |
446 | Maps each seed value to next seed valu. | |
447 | ||
448 | @item seed | |
449 | The state value for the unfold. | |
450 | ||
451 | @item tail-gen | |
452 | Creates the tail of the list; defaults to @code{(lambda (x) '())}. | |
453 | @end table | |
454 | ||
455 | @var{g} produces a series of seed values, which are mapped to list | |
456 | elements by @var{f}. These elements are put into a list in | |
457 | left-to-right order, and @var{p} tells when to stop unfolding. | |
458 | @end deffn | |
459 | ||
460 | @deffn procedure unfold-right p f g seed [tail] | |
461 | Construct a list with the following loop. | |
462 | ||
463 | @lisp | |
464 | (let lp ((seed seed) (lis tail)) | |
465 | (if (p seed) lis | |
466 | (lp (g seed) | |
467 | (cons (f seed) lis)))) | |
468 | @end lisp | |
469 | ||
470 | @table @var | |
471 | @item p | |
472 | Determines when to stop unfolding. | |
473 | ||
474 | @item f | |
475 | Maps each seed value to the corresponding list element. | |
476 | ||
477 | @item g | |
478 | Maps each seed value to next seed valu. | |
479 | ||
480 | @item seed | |
481 | The state value for the unfold. | |
482 | ||
483 | @item tail-gen | |
484 | Creates the tail of the list; defaults to @code{(lambda (x) '())}. | |
485 | @end table | |
486 | ||
487 | @end deffn | |
488 | ||
489 | @deffn procedure map f lst1 lst2 @dots{} | |
490 | Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and | |
491 | return a list containing the results of the procedure applications. | |
492 | This procedure is extended with respect to R5RS, because the argument | |
493 | lists may have different lengths. The result list will have the same | |
494 | length as the shortest argument lists. The order in which @var{f} | |
495 | will be applied to the list element(s) is not specified. | |
496 | @end deffn | |
497 | ||
498 | @deffn procedure for-each f lst1 lst2 @dots{} | |
499 | Apply the procedure @var{f} to each pair of corresponding elements of | |
500 | the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not | |
501 | specified. This procedure is extended with respect to R5RS, because | |
502 | the argument lists may have different lengths. The shortest argument | |
503 | list determines the number of times @var{f} is called. @var{f} will | |
504 | be applied to tge list elements in left-to-right order. | |
505 | ||
506 | @end deffn | |
507 | ||
508 | @deffn procedure append-map f lst1 lst2 @dots{} | |
509 | @deffnx procedure append-map! f lst1 lst2 @dots{} | |
510 | Equivalent to | |
511 | ||
512 | @lisp | |
513 | (apply append (map f clist1 clist2 ...)) | |
514 | @end lisp | |
515 | ||
516 | and | |
517 | ||
518 | @lisp | |
519 | (apply append! (map f clist1 clist2 ...)) | |
520 | @end lisp | |
521 | ||
522 | Map @var{f} over the elements of the lists, just as in the @code{map} | |
523 | function. However, the results of the applications are appended | |
524 | together to make the final result. @code{append-map} uses | |
525 | @code{append} to append the results together; @code{append-map!} uses | |
526 | @code{append!}. | |
527 | ||
528 | The dynamic order in which the various applications of @var{f} are | |
529 | made is not specified. | |
530 | @end deffn | |
531 | ||
532 | @deffn procedure map! f lst1 lst2 @dots{} | |
533 | Linear-update variant of @code{map} -- @code{map!} is allowed, but not | |
534 | required, to alter the cons cells of @var{lst1} to construct the | |
535 | result list. | |
536 | ||
537 | The dynamic order in which the various applications of @var{f} are | |
538 | made is not specified. In the n-ary case, @var{lst2}, @var{lst3}, | |
539 | @dots{} must have at least as many elements as @var{lst1}. | |
540 | @end deffn | |
541 | ||
542 | @deffn procedure pair-for-each f lst1 lst2 @dots{} | |
543 | Like @code{for-each}, but applies the procedure @var{f} to the pairs | |
544 | from which the argument lists are constructed, instead of the list | |
545 | elements. The return value is not specified. | |
546 | @end deffn | |
547 | ||
548 | @deffn procedure filter-map f lst1 lst2 @dots{} | |
549 | Like @code{map}, but only results from the applications of @var{f} | |
550 | which are true are saved in the result list. | |
551 | @end deffn | |
552 | ||
553 | ||
554 | @node SRFI-1 Filtering and Partitioning | |
555 | @subsection Filtering and Partitioning | |
556 | ||
557 | @c FIXME::martin: Review me! | |
558 | ||
559 | Filtering means to collect all elements from a list which satisfy a | |
560 | specific condition. Partitioning a list means to make two groups of | |
561 | list elements, one which contains the elements satisfying a condition, | |
562 | and the other for the elements which don't. | |
563 | ||
564 | @deffn procedure filter pred lst | |
565 | @deffnx procedure filter! pred lst | |
566 | Return a list containing all elements from @var{lst} which satisfy the | |
567 | predicate @var{pred}. The elements in the result list have the same | |
568 | order as in @var{lst}. The order in which @var{pred} is applied to | |
569 | the list elements is not specified. | |
570 | ||
571 | @code{filter!} is allowed, but not required to modify the structure of | |
572 | @end deffn | |
573 | ||
574 | @deffn procedure partition pred lst | |
575 | @deffnx procedure partition! pred lst | |
576 | Return two lists, one containing all elements from @var{lst} which | |
577 | satisfy the predicate @var{pred}, and one list containing the elements | |
578 | which do not satisfy the predicated. The elements in the result lists | |
579 | have the same order as in @var{lst}. The order in which @var{pred} is | |
580 | applied to the list elements is not specified. | |
581 | ||
582 | @code{partition!} is allowed, but not required to modify the structure of | |
583 | the input list. | |
584 | @end deffn | |
585 | ||
586 | @deffn procedure remove pred lst | |
587 | @deffnx procedure remove! pred lst | |
588 | Return a list containing all elements from @var{lst} which do not | |
589 | satisfy the predicate @var{pred}. The elements in the result list | |
590 | have the same order as in @var{lst}. The order in which @var{pred} is | |
591 | applied to the list elements is not specified. | |
592 | ||
593 | @code{remove!} is allowed, but not required to modify the structure of | |
594 | the input list. | |
595 | @end deffn | |
596 | ||
597 | ||
598 | @node SRFI-1 Searching | |
599 | @subsection Searching | |
600 | ||
601 | @c FIXME::martin: Review me! | |
602 | ||
603 | The procedures for searching elements in lists either accept a | |
604 | predicate or a comparison object for determining which elements are to | |
605 | be searched. | |
606 | ||
607 | @deffn procedure find pred lst | |
608 | Return the first element of @var{lst} which satisfies the predicate | |
609 | @var{pred} and @code{#f} if no such element is found. | |
610 | @end deffn | |
611 | ||
612 | @deffn procedure find-tail pred lst | |
613 | Return the first pair of @var{lst} whose @sc{car} satisfies the | |
614 | predicate @var{pred} and @code{#f} if no such element is found. | |
615 | @end deffn | |
616 | ||
617 | @deffn procedure take-while pred lst | |
618 | @deffnx procedure take-while! pred lst | |
619 | Return the longest initial prefix of @var{lst} whose elements all | |
620 | satisfy the predicate @var{pred}. | |
621 | ||
622 | @code{take-while!} is allowed, but not required to modify the input | |
623 | list while producing the result. | |
624 | @end deffn | |
625 | ||
626 | @deffn procedure drop-while pred lst | |
627 | Drop the longest initial prefix of @var{lst} whose elements all | |
628 | satisfy the predicate @var{pred}. | |
629 | @end deffn | |
630 | ||
631 | @deffn procedure span pred lst | |
632 | @deffnx procedure span! pred lst | |
633 | @deffnx procedure break pred lst | |
634 | @deffnx procedure break! pred lst | |
635 | @code{span} splits the list @var{lst} into the longest initial prefix | |
636 | whose elements all satisfy the predicate @var{pred}, and the remaining | |
637 | tail. @code{break} inverts the sense of the predicate. | |
638 | ||
639 | @code{span!} and @code{break!} are allowed, but not required to modify | |
640 | the structure of the input list @var{lst} in order to produce the | |
641 | result. | |
642 | @end deffn | |
643 | ||
644 | @deffn procedure any pred lst1 lst2 @dots{} | |
645 | Apply @var{pred} across the lists and return a true value if the | |
646 | predicate returns true for any of the list elements(s); return | |
647 | @code{#f} otherwise. The true value returned is always the result of | |
648 | the first succesful application of @var{pred}. | |
649 | @end deffn | |
650 | ||
651 | @deffn procedure every pred lst1 lst2 @dots{} | |
652 | Apply @var{pred} across the lists and return a true value if the | |
653 | predicate returns true for every of the list elements(s); return | |
654 | @code{#f} otherwise. The true value returned is always the result of | |
655 | the final succesful application of @var{pred}. | |
656 | @end deffn | |
657 | ||
658 | @deffn procedure list-index pred lst1 lst2 @dots{} | |
659 | Return the index of the leftmost element that satisfies @var{pred}. | |
660 | @end deffn | |
661 | ||
662 | @deffn procedure member x lst [=] | |
663 | Return the first sublist of @var{lst} whose @sc{car} is equal to | |
664 | @var{x}. If @var{x} does no appear in @var{lst}, return @code{#f}. | |
665 | Equality is determined by the equality predicate @var{=}, or | |
666 | @code{equal?} if @var{=} is not given. | |
667 | @end deffn | |
668 | ||
669 | ||
670 | @node SRFI-1 Deleting | |
671 | @subsection Deleting | |
672 | ||
673 | @c FIXME::martin: Review me! | |
674 | ||
675 | The procedures for deleting elements from a list either accept a | |
676 | predicate or a comparison object for determining which elements are to | |
677 | be removed. | |
678 | ||
679 | @deffn procedure delete x lst [=] | |
680 | @deffnx procedure delete! x lst [=] | |
681 | Return a list containing all elements from @var{lst}, but without the | |
682 | elements equal to @var{x}. Equality is determined by the equality | |
683 | predicate @var{=}, which defaults to @code{equal?} if not given. | |
684 | ||
685 | @code{delete!} is allowed, but not required to modify the structure of | |
686 | the argument list in order to produce the result. | |
687 | @end deffn | |
688 | ||
689 | @deffn procedure delete-duplicates lst [=] | |
690 | @deffnx procedure delete-duplicates! lst [=] | |
691 | Return a list containing all elements from @var{lst}, but without | |
692 | duplicate elements. Equality of elements is determined by the | |
693 | equality predicate @var{=}, which defaults to @code{equal?} if not | |
694 | given. | |
695 | ||
696 | @code{delete-duplicates!} is allowed, but not required to modify the | |
697 | structure of the argument list in order to produce the result. | |
698 | @end deffn | |
699 | ||
700 | ||
701 | @node SRFI-1 Association Lists | |
702 | @subsection Association Lists | |
703 | ||
704 | @c FIXME::martin: Review me! | |
705 | ||
706 | Association lists are described in detail in section @ref{Association | |
707 | Lists}. The present section only documents the additional procedures | |
708 | for dealing with association lists defined by SRFI-1. | |
709 | ||
710 | @deffn procedure assoc key alist [=] | |
711 | Return the pair from @var{alist} which matches @var{key}. Equality is | |
712 | determined by @var{=}, which defaults to @code{equal?} if not given. | |
713 | @var{alist} must be an association lists---a list of pairs. | |
714 | @end deffn | |
715 | ||
716 | @deffn procedure alist-cons key datum alist | |
717 | Equivalent to | |
718 | ||
719 | @lisp | |
720 | (cons (cons @var{key} @var{datum}) @var{alist}) | |
721 | @end lisp | |
722 | ||
723 | This procedure is used to coons a new pair onto an existing | |
724 | association list. | |
725 | @end deffn | |
726 | ||
727 | @deffn procedure alist-copy alist | |
728 | Return a newly allocated copy of @var{alist}, that means that the | |
729 | spine of the list as well as the pairs are copied. | |
730 | @end deffn | |
731 | ||
732 | @deffn procedure alist-delete key alist [=] | |
733 | @deffnx procedure alist-delete! key alist [=] | |
734 | Return a list containing the pairs of @var{alist}, but without the | |
735 | pairs whose @sc{cars} are equal to @var{key}. Equality is determined | |
736 | by @var{=}, which defaults to @code{equal?} if not given. | |
737 | ||
738 | @code{alist-delete!} is allowed, but not required to modify the | |
739 | structure of the list @var{alist} in order to produce the result. | |
740 | @end deffn | |
741 | ||
742 | ||
743 | @node SRFI-1 Set Operations | |
744 | @subsection Set Operations on Lists | |
745 | ||
746 | @c FIXME::martin: Review me! | |
747 | ||
748 | Lists can be used for representing sets of objects. The procedures | |
749 | documented in this section can be used for such set representations. | |
750 | Man combinding several sets or adding elements, they make sure that no | |
751 | object is contained more than once in a given list. Please note that | |
752 | lists are not a too efficient implementation method for sets, so if | |
753 | you need high performance, you should think about implementing a | |
754 | custom data structure for representing sets, such as trees, bitsets, | |
755 | hash tables or something similar. | |
756 | ||
757 | All these procedures accept an equality predicate as the first | |
758 | argument. This predicate is used for testing the objects in the list | |
759 | sets for sameness. | |
760 | ||
761 | @deffn procedure lset<= = list1 @dots{} | |
762 | Return @code{#t} if every @var{listi} is a subset of @var{listi+1}, | |
763 | otherwise return @code{#f}. Returns @code{#t} if called with less | |
764 | than two arguments. @var{=} is used for testing element equality. | |
765 | @end deffn | |
766 | ||
767 | @deffn procedure lset= = list1 list2 @dots{} | |
768 | Return @code{#t} if all argument lists are equal. @var{=} is used for | |
769 | testing element equality. | |
770 | @end deffn | |
771 | ||
772 | @deffn procedure lset-adjoin = list elt1 @dots{} | |
773 | @deffnx procedure lset-adjoin! = list elt1 @dots{} | |
774 | Add all @var{elts} to the list @var{list}, suppressing duplicates and | |
775 | return the resulting list. @code{lset-adjoin!} is allowed, but not | |
776 | required to modify its first argument. @var{=} is used for testing | |
777 | element equality. | |
778 | @end deffn | |
779 | ||
780 | @deffn procedure lset-union = list1 @dots{} | |
781 | @deffnx procedure lset-union! = list1 @dots{} | |
782 | Return the union of all argument list sets. The union is the set of | |
783 | all elements which appear in any of the argument sets. | |
784 | @code{lset-union!} is allowed, but not required to modify its first | |
785 | argument. @var{=} is used for testing element equality. | |
786 | @end deffn | |
787 | ||
788 | @deffn procedure lset-intersection = list1 list2 @dots{} | |
789 | @deffnx procedure lset-intersection! = list1 list2 @dots{} | |
790 | Return the intersection of all argument list sets. The intersection | |
791 | is the set containing all elements which appear in all argument sets. | |
792 | @code{lset-intersection!} is allowed, but not required to modify its | |
793 | first argument. @var{=} is used for testing element equality. | |
794 | @end deffn | |
795 | ||
796 | @deffn procedure lset-difference = list1 list2 @dots{} | |
797 | @deffnx procedure lset-difference! = list1 list2 @dots{} | |
798 | Return the difference of all argument list sets. The difference is | |
799 | the the set containing all elements of the first list which do not | |
800 | appear in the other lists. @code{lset-difference!} is allowed, but | |
801 | not required to modify its first argument. @var{=} is used for testing | |
802 | element equality. | |
803 | @end deffn | |
804 | ||
805 | @deffn procedure lset-xor = list1 @dots{} | |
806 | @deffnx procedure lset-xor! = list1 @dots{} | |
807 | Return the set containing all elements which appear in the first | |
808 | argument list set, but not in the second; or, more generally: which | |
809 | appear in an odd number of sets. @code{lset-xor!} is allowed, but | |
810 | not required to modify its first argument. @var{=} is used for testing | |
811 | element equality. | |
812 | @end deffn | |
813 | ||
814 | @deffn procedure lset-diff+intersection = list1 list2 @dots{} | |
815 | @deffnx procedure lset-diff+intersection! = list1 list2 @dots{} | |
816 | Return two values, the difference and the intersection of the argument | |
817 | list sets. This works like a combination of @code{lset-difference} and | |
818 | @code{lset-intersection}, but is more efficient. | |
819 | @code{lset-diff+intersection!} is allowed, but not required to modify | |
820 | its first argument. @var{=} is used for testing element equality. You | |
821 | have to use some means to deal with the multiple values these | |
822 | procedures return (@pxref{Multiple Values}). | |
823 | @end deffn | |
824 | ||
825 | ||
826 | @node SRFI-2 | |
827 | @section SRFI-2 - and-let* | |
828 | ||
829 | @c FIXME::martin: Review me! | |
830 | ||
831 | The syntactic form @code{and-let*} combines the conditional evaluation | |
832 | form @code{and} with the binding form @var{let*}. Each argument | |
833 | expression will be evaluated sequentially, bound to a variable (if a | |
834 | variable name is given), but only as long as no expression returns | |
835 | the false value @code{#f}. | |
836 | ||
837 | Use @code{(use-modules (srfi srfi-2)} to access this syntax form. | |
838 | ||
839 | A short example will demonstrate how it works. In the first expression, | |
840 | @var{x} will get bound to 1, but the next expression (@code{#f}) is | |
841 | false, so evaluation of the form is stopped, and @code{#f} is returned. | |
842 | In the next expression, @var{x} is bound to 1, @var{y} is bound to | |
843 | @code{#t} and since no expression in the binding section was false, the | |
844 | body of the @code{and-let*} expression is evaluated, which in this case | |
845 | returns the value of @var{x}. | |
846 | ||
847 | @lisp | |
848 | (and-let* ((x 1) (y #f)) 42) | |
849 | @result{} | |
850 | #f | |
851 | (and-let* ((x 1) (y #t)) x) | |
852 | @result{} | |
853 | 1 | |
854 | @end lisp | |
855 | ||
856 | ||
857 | @node SRFI-4 | |
858 | @section SRFI-4 - Homogeneous numeric vector datatypes. | |
859 | ||
860 | @c FIXME::martin: Review me! | |
861 | ||
862 | SRFI-4 defines a set of datatypes for vectors whose elements are all | |
863 | of the same numeric type. Vectors for signed and unsigned exact | |
864 | integer or inexact real numbers in several precisions are available. | |
865 | ||
866 | Procedures similar to the vector procedures (@pxref{Vectors}) are | |
867 | provided for handling these homogeneous vectors, but they are distinct | |
868 | datatypes. | |
869 | ||
870 | The reason for providing this set of datatypes is that with the | |
871 | limitation (all elements must have the same type), it is possible to | |
872 | implement them much more memory-efficient than normal, heterogenous | |
873 | vectors. | |
874 | ||
875 | If you want to use these datatypes and the corresponding procedures, | |
876 | you have to use the module @code{(srfi srfi-4)}. | |
877 | ||
878 | Ten vector data types are provided: Unsigned and signed integer values | |
879 | with 8, 16, 32 and 64 bits and floating point values with 32 and 64 | |
880 | bits. In the following descriptions, the tags @code{u8}, @code{s8}, | |
881 | @code{u16}, @code{s16}, @code{u32}, @code{s32}, @code{u64}, | |
882 | @code{s64}, @code{f32}, @code{f64}, respectively, are used for | |
883 | denoting the various types. | |
884 | ||
885 | @menu | |
886 | * SRFI-4 - Read Syntax:: How to write homogeneous vector literals. | |
887 | * SRFI-4 - Procedures:: Available homogeneous vector procedures. | |
888 | @end menu | |
889 | ||
890 | ||
891 | @node SRFI-4 - Read Syntax | |
892 | @subsection SRFI-4 - Read Syntax | |
893 | ||
894 | Homogeneous numeric vectors have an external representation (read | |
895 | syntax) similar to normal Scheme vectors, but with an additional tag | |
896 | telling the vector's type. | |
897 | ||
898 | @lisp | |
899 | #u16(1 2 3) | |
900 | @end lisp | |
901 | ||
902 | denotes a homogeneous numeric vector of three elements, which are the | |
903 | values 1, 2 and 3, represented as 16-bit unsigned integers. | |
904 | Correspondingly, | |
905 | ||
906 | @lisp | |
907 | #f64(3.1415 2.71) | |
908 | @end lisp | |
909 | ||
910 | denotes a vector of two elements, which are the values 3.1415 and | |
911 | 2.71, represented as floating-point values of 64 bit precision. | |
912 | ||
913 | Please note that the read syntax for floating-point vectors conflicts | |
914 | with Standard Scheme, because there @code{#f} is defined to be the | |
915 | literal false value. That means, that with the loaded SRFI-4 module, | |
916 | it is not possible to enter some list like | |
917 | ||
918 | @lisp | |
919 | '(1 #f3) | |
920 | @end lisp | |
921 | ||
922 | and hope that it will be parsed as a three-element list with the | |
923 | elements 1, @code{#f} and 3. In normal use, this should be no | |
924 | problem, because people tend to terminate tokens sensibly when writing | |
925 | Scheme expressions. | |
926 | ||
927 | @node SRFI-4 - Procedures | |
928 | @subsection SRFI-4 Procedures | |
929 | ||
930 | The procedures listed in this section are provided for all homogeneous | |
931 | numeric vector datatypes. For brevity, they are not all documented, | |
932 | but a summary of the procedures is given. In the following | |
933 | descriptions, you can replace @code{TAG} by any of the datatype | |
934 | indicators @code{u8}, @code{s8}, @code{u16}, @code{s16}, @code{u32}, | |
935 | @code{s32}, @code{u64}, @code{s64}, @code{f32} and @code{f64}. | |
936 | ||
937 | For example, you can use the procedures @code{u8vector?}, | |
938 | @code{make-s8vector}, @code{u16vector}, @code{u32vector-length}, | |
939 | @code{s64vector-ref}, @code{f32vector-set!} or @code{f64vector->list}. | |
940 | ||
941 | @deffn primitive TAGvector? obj | |
942 | Return @code{#t} if @var{obj} is a homogeneous numeric vector of type | |
943 | @code{TAG}. | |
944 | @end deffn | |
945 | ||
946 | @deffn primitive make-TAGvector n [value] | |
947 | Create a newly allocated homogeneous numeric vector of type | |
948 | @code{TAG}, which can hold @var{n} elements. If @var{value} is given, | |
949 | the vector is initialized with the value, otherwise, the contents of | |
950 | the returned vector is not specified. | |
951 | @end deffn | |
952 | ||
953 | @deffn primitive TAGvector value1 @dots{} | |
954 | Create a newly allocated homogeneous numeric vector of type | |
955 | @code{TAG}. The returned vector is as long as the number of arguments | |
956 | given, and is initialized with the argument values. | |
957 | @end deffn | |
958 | ||
959 | @deffn primitive TAGvector-length TAGvec | |
960 | Return the number of elements in @var{TAGvec}. | |
961 | @end deffn | |
962 | ||
963 | @deffn primitive TAGvector-ref TAGvec i | |
964 | Return the element at index @var{i} in @var{TAGvec}. | |
965 | @end deffn | |
966 | ||
967 | @deffn primitive TAGvector-ref TAGvec i value | |
968 | Set the element at index @var{i} in @var{TAGvec} to @var{value}. The | |
969 | return value is not specified. | |
970 | @end deffn | |
971 | ||
972 | @deffn primitive TAGvector->list TAGvec | |
973 | Return a newly allocated list holding all elements of @var{TAGvec}. | |
974 | @end deffn | |
975 | ||
976 | @deffn primitive list->TAGvector lst | |
977 | Return a newly allocated homogeneous numeric vector of type @code{TAG}, | |
978 | initialized with the elements of the list @var{lst}. | |
979 | @end deffn | |
980 | ||
981 | ||
982 | @node SRFI-6 | |
983 | @section SRFI-6 - Basic String Ports | |
984 | ||
985 | SRFI-6 defines the procedures @code{open-input-string}, | |
986 | @code{open-output-string} and @code{get-output-string}. These | |
987 | procedures are included in the Guile core, so using this module does not | |
988 | make any difference at the moment. But it is possible that support for | |
989 | SRFI-6 will be factored out of the core library in the future, so using | |
990 | this module does not hurt, after all. | |
991 | ||
992 | @node SRFI-8 | |
993 | @section SRFI-8 - receive | |
994 | ||
995 | @code{receive} is a syntax for making the handling of multiple-value | |
996 | procedures easier. It is documented in @xref{Multiple Values}. | |
997 | ||
998 | ||
999 | @node SRFI-9 | |
1000 | @section SRFI-9 - define-record-type | |
1001 | ||
1002 | This is the SRFI way for defining record types. The Guile | |
1003 | implementation is a layer above Guile's normal record construction | |
1004 | procedures (@pxref{Records}). The nice thing about this kind of record | |
1005 | definition method is that no new names are implicitly created, all | |
1006 | constructor, accessor and predicates are explicitly given. This reduces | |
1007 | the risk of variable capture. | |
1008 | ||
1009 | The syntax of a record type definition is: | |
1010 | ||
1011 | @example | |
1012 | @group | |
1013 | <record type definition> | |
1014 | -> (define-record-type <type name> | |
1015 | (<constructor name> <field tag> ...) | |
1016 | <predicate name> | |
1017 | <field spec> ...) | |
1018 | <field spec> -> (<field tag> <accessor name>) | |
1019 | -> (<field tag> <accessor name> <modifier name>) | |
1020 | <field tag> -> <identifier> | |
1021 | <... name> -> <identifier> | |
1022 | @end group | |
1023 | @end example | |
1024 | ||
1025 | Usage example: | |
1026 | ||
1027 | @example | |
1028 | guile> (use-modules (srfi srfi-9)) | |
1029 | guile> (define-record-type :foo (make-foo x) foo? | |
1030 | (x get-x) (y get-y set-y!)) | |
1031 | guile> (define f (make-foo 1)) | |
1032 | guile> f | |
1033 | #<:foo x: 1 y: #f> | |
1034 | guile> (get-x f) | |
1035 | 1 | |
1036 | guile> (set-y! f 2) | |
1037 | 2 | |
1038 | guile> (get-y f) | |
1039 | 2 | |
1040 | guile> f | |
1041 | #<:foo x: 1 y: 2> | |
1042 | guile> (foo? f) | |
1043 | #t | |
1044 | guile> (foo? 1) | |
1045 | #f | |
1046 | @end example | |
1047 | ||
1048 | ||
1049 | @node SRFI-10 | |
1050 | @section SRFI-10 - Hash-Comma Reader Extension | |
1051 | ||
1052 | @cindex hash-comma | |
1053 | @cindex #,() | |
1054 | The module @code{(srfi srfi-10)} implements the syntax extension | |
1055 | @code{#,()}, also called hash-comma, which is defined in SRFI-10. | |
1056 | ||
1057 | The support for SRFI-10 consists of the procedure | |
1058 | @code{define-reader-ctor} for defining new reader constructors and the | |
1059 | read syntax form | |
1060 | ||
1061 | @example | |
1062 | #,(@var{ctor} @var{datum} ...) | |
1063 | @end example | |
1064 | ||
1065 | where @var{ctor} must be a symbol for which a read constructor was | |
1066 | defined previouly, using @code{define-reader-ctor}. | |
1067 | ||
1068 | Example: | |
1069 | ||
1070 | @lisp | |
1071 | (define-reader-ctor 'file open-input-file) | |
1072 | (define f '#,(file "/etc/passwd")) | |
1073 | (read-line f) | |
1074 | @result{} | |
1075 | "root:x:0:0:root:/root:/bin/bash" | |
1076 | @end lisp | |
1077 | ||
1078 | Please note the quote before the @code{#,(file ...)} expression. This | |
1079 | is necessary because ports are not self-evaluating in Guile. | |
1080 | ||
1081 | @deffn procedure define-reader-ctor symbol proc | |
1082 | Define @var{proc} as the reader constructor for hash-comma forms with a | |
1083 | tag @var{symbol}. @var{proc} will be applied to the datum(s) following | |
1084 | the tag in the hash-comma expression after the complete form has been | |
1085 | read in. The result of @var{proc} is returned by the Scheme reader. | |
1086 | @end deffn | |
1087 | ||
1088 | ||
1089 | @node SRFI-11 | |
1090 | @section SRFI-11 - let-values | |
1091 | ||
1092 | This module implements the binding forms for multiple values | |
1093 | @code{let-values} and @code{let-values*}. These forms are similar to | |
1094 | @code{let} and @code{let*} (@pxref{Local Bindings}), but they support | |
1095 | binding of the values returned by multiple-valued expressions. | |
1096 | ||
1097 | Write @code{(use-modules (srfi srfi-11))} to make the bindings | |
1098 | available. | |
1099 | ||
1100 | @lisp | |
1101 | (let-values (((x y) (values 1 2)) | |
1102 | ((z f) (values 3 4))) | |
1103 | (+ x y z f)) | |
1104 | @result{} | |
1105 | 10 | |
1106 | @end lisp | |
1107 | ||
1108 | @code{let-values} performs all bindings simultaneously, which means that | |
1109 | no expression in the binding clauses may refer to variables bound in the | |
1110 | same clause list. @code{let-values*}, on the other hand, performs the | |
1111 | bindings sequentially, just like @code{let*} does for single-valued | |
1112 | expressions. | |
1113 | ||
1114 | ||
1115 | @node SRFI-13 | |
1116 | @section SRFI-13 - String Library | |
1117 | ||
1118 | In this section, we will describe all procedures defined in SRFI-13 | |
1119 | (string library) and implemented by the module @code{(srfi srfi-13)}. | |
1120 | ||
1121 | Note that only the procedures from SRFI-13 are documented here which are | |
1122 | not already contained in Guile. For procedures not documented here | |
1123 | please refer to the relevant chapters in the Guile Reference Manual, for | |
1124 | example the documentation of strings and string procedures | |
1125 | (@pxref{Strings}). | |
1126 | ||
1127 | All of the procedures defined in SRFI-13, which are not already included | |
1128 | in the Guile core library, are implemented in the module @code{(srfi | |
1129 | srfi-13)}. The procedures which are both in Guile and in SRFI-13, but | |
1130 | which are slightly extended, have been implemented in this module, and | |
1131 | the bindings overwrite those in the Guile core. | |
1132 | ||
1133 | The procedures which are defined in the section @emph{Low-level | |
1134 | procedures} of SRFI-13 for parsing optional string indices, substring | |
1135 | specification checking and Knuth-Morris-Pratt-Searching are not | |
1136 | implemented. | |
1137 | ||
1138 | The procedures @code{string-contains} and @code{string-contains-ci} are | |
1139 | not implemented very efficiently at the moment. This will be changed as | |
1140 | soon as possible. | |
1141 | ||
1142 | @menu | |
1143 | * Loading SRFI-13:: How to load SRFI-13 support. | |
1144 | * SRFI-13 Predicates:: String predicates. | |
1145 | * SRFI-13 Constructors:: String constructing procedures. | |
1146 | * SRFI-13 List/String Conversion:: Conversion from/to lists. | |
1147 | * SRFI-13 Selection:: Selection portions of strings. | |
1148 | * SRFI-13 Modification:: Modfify strings in-place. | |
1149 | * SRFI-13 Comparison:: Compare strings. | |
1150 | * SRFI-13 Prefixes/Suffixes:: Detect common pre-/suffixes. | |
1151 | * SRFI-13 Searching:: Searching for substrings. | |
1152 | * SRFI-13 Case Mapping:: Mapping to lower-/upper-case. | |
1153 | * SRFI-13 Reverse/Append:: Reverse and append strings. | |
1154 | * SRFI-13 Fold/Unfold/Map:: Construct/deconstruct strings. | |
1155 | * SRFI-13 Replicate/Rotate:: Replacate and rotate portions of strings. | |
1156 | * SRFI-13 Miscellaneous:: Left-over string procedures. | |
1157 | * SRFI-13 Filtering/Deleting:: Filter and delete characters from strings. | |
1158 | @end menu | |
1159 | ||
1160 | ||
1161 | @node Loading SRFI-13 | |
1162 | @subsection Loading SRFI-13 | |
1163 | ||
1164 | When Guile is properly installed, SRFI-13 support can be loaded into a | |
1165 | running Guile by using the @code{(srfi srfi-13)} module. | |
1166 | ||
1167 | @example | |
1168 | $ guile | |
1169 | guile> (use-modules (srfi srfi-13)) | |
1170 | guile> | |
1171 | @end example | |
1172 | ||
1173 | When this step causes any errors, Guile is not properly installed. | |
1174 | ||
1175 | One possible reason is that Guile cannot find either the Scheme module | |
1176 | file @file{srfi-13.scm}, or it cannot find the shared object file | |
1177 | @file{libguile-srfi-srfi-13-14.so}. Make sure that the former is in the | |
1178 | Guile load path and that the latter is either installed in some default | |
1179 | location like @file{/usr/local/lib} or that the directory it was | |
1180 | installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to | |
1181 | @file{srfi-14.scm}. | |
1182 | ||
1183 | Now you can test whether the SRFI-13 procedures are working by calling | |
1184 | the @code{string-concatenate} procedure. | |
1185 | ||
1186 | @example | |
1187 | guile> (string-concatenate '("Hello" " " "World!")) | |
1188 | "Hello World!" | |
1189 | @end example | |
1190 | ||
1191 | @node SRFI-13 Predicates | |
1192 | @subsection Predicates | |
1193 | ||
1194 | In addition to the primitives @code{string?} and @code{string-null?}, | |
1195 | which are already in the Guile core, the string predicates | |
1196 | @code{string-any} and @code{string-every} are defined by SRFI-13. | |
1197 | ||
1198 | @deffn primitive string-any pred s [start end] | |
1199 | Check if the predicate @var{pred} is true for any character in | |
1200 | the string @var{s}, proceeding from left (index @var{start}) to | |
1201 | right (index @var{end}). If @code{string-any} returns true, | |
1202 | the returned true value is the one produced by the first | |
1203 | successful application of @var{pred}. | |
1204 | @end deffn | |
1205 | ||
1206 | @deffn primitive string-every pred s [start end] | |
1207 | Check if the predicate @var{pred} is true for every character | |
1208 | in the string @var{s}, proceeding from left (index @var{start}) | |
1209 | to right (index @var{end}). If @code{string-every} returns | |
1210 | true, the returned true value is the one produced by the final | |
1211 | application of @var{pred} to the last character of @var{s}. | |
1212 | @end deffn | |
1213 | ||
1214 | ||
1215 | @c =================================================================== | |
1216 | ||
1217 | @node SRFI-13 Constructors | |
1218 | @subsection Constructors | |
1219 | ||
1220 | SRFI-13 defines several procedures for constructing new strings. In | |
1221 | addition to @code{make-string} and @code{string} (available in the Guile | |
1222 | core library), the procedure @code{string-tabulate} does exist. | |
1223 | ||
1224 | @deffn primitive string-tabulate proc len | |
1225 | @var{proc} is an integer->char procedure. Construct a string | |
1226 | of size @var{len} by applying @var{proc} to each index to | |
1227 | produce the corresponding string element. The order in which | |
1228 | @var{proc} is applied to the indices is not specified. | |
1229 | @end deffn | |
1230 | ||
1231 | ||
1232 | @c =================================================================== | |
1233 | ||
1234 | @node SRFI-13 List/String Conversion | |
1235 | @subsection List/String Conversion | |
1236 | ||
1237 | The procedure @code{string->list} is extended by SRFI-13, that is why it | |
1238 | is included in @code{(srfi srfi-13)}. The other procedures are new. | |
1239 | The Guile core already contains the procedure @code{list->string} for | |
1240 | converting a list of characters into a string (@pxref{List/String | |
1241 | Conversion}). | |
1242 | ||
1243 | @deffn primitive string->list str [start end] | |
1244 | Convert the string @var{str} into a list of characters. | |
1245 | @end deffn | |
1246 | ||
1247 | @deffn primitive reverse-list->string chrs | |
1248 | An efficient implementation of @code{(compose string->list | |
1249 | reverse)}: | |
1250 | ||
1251 | @smalllisp | |
1252 | (reverse-list->string '(#\a #\B #\c)) @result{} "cBa" | |
1253 | @end smalllisp | |
1254 | @end deffn | |
1255 | ||
1256 | @deffn primitive string-join ls [delimiter grammar] | |
1257 | Append the string in the string list @var{ls}, using the string | |
1258 | @var{delim} as a delimiter between the elements of @var{ls}. | |
1259 | @var{grammar} is a symbol which specifies how the delimiter is | |
1260 | placed between the strings, and defaults to the symbol | |
1261 | @code{infix}. | |
1262 | ||
1263 | @table @code | |
1264 | @item infix | |
1265 | Insert the separator between list elements. An empty string | |
1266 | will produce an empty list. | |
1267 | ||
1268 | @item string-infix | |
1269 | Like @code{infix}, but will raise an error if given the empty | |
1270 | list. | |
1271 | ||
1272 | @item suffix | |
1273 | Insert the separator after every list element. | |
1274 | ||
1275 | @item prefix | |
1276 | Insert the separator before each list element. | |
1277 | @end table | |
1278 | @end deffn | |
1279 | ||
1280 | ||
1281 | @c =================================================================== | |
1282 | ||
1283 | @node SRFI-13 Selection | |
1284 | @subsection Selection | |
1285 | ||
1286 | These procedures are called @dfn{selectors}, because they access | |
1287 | information about the string or select pieces of a given string. | |
1288 | ||
1289 | Additional selector procedures are documented in the Strings section | |
1290 | (@pxref{String Selection}), like @code{string-length} or | |
1291 | @code{string-ref}. | |
1292 | ||
1293 | @code{string-copy} is also available in core Guile, but this version | |
1294 | accepts additional start/end indices. | |
1295 | ||
1296 | @deffn primitive string-copy str [start end] | |
1297 | Return a freshly allocated copy of the string @var{str}. If | |
1298 | given, @var{start} and @var{end} delimit the portion of | |
1299 | @var{str} which is copied. | |
1300 | @end deffn | |
1301 | ||
1302 | @deffn primitive substring/shared str start [end] | |
1303 | Like @code{substring}, but the result may share memory with the | |
1304 | argument @var{str}. | |
1305 | @end deffn | |
1306 | ||
1307 | @deffn primitive string-copy! target tstart s [start end] | |
1308 | Copy the sequence of characters from index range [@var{start}, | |
1309 | @var{end}) in string @var{s} to string @var{target}, beginning | |
1310 | at index @var{tstart}. The characters are copied left-to-right | |
1311 | or right-to-left as needed - the copy is guaranteed to work, | |
1312 | even if @var{target} and @var{s} are the same string. It is an | |
1313 | error if the copy operation runs off the end of the target | |
1314 | string. | |
1315 | @end deffn | |
1316 | ||
1317 | @deffn primitive string-take s n | |
1318 | @deffnx primitive string-take-right s n | |
1319 | Return the @var{n} first/last characters of @var{s}. | |
1320 | @end deffn | |
1321 | ||
1322 | @deffn primitive string-drop s n | |
1323 | @deffnx primitive string-drop-right s n | |
1324 | Return all but the first/last @var{n} characters of @var{s}. | |
1325 | @end deffn | |
1326 | ||
1327 | @deffn primitive string-pad s len [chr start end] | |
1328 | @deffnx primitive string-pad-right s len [chr start end] | |
1329 | Take that characters from @var{start} to @var{end} from the | |
1330 | string @var{s} and return a new string, right(left)-padded by the | |
1331 | character @var{chr} to length @var{len}. If the resulting | |
1332 | string is longer than @var{len}, it is truncated on the right (left). | |
1333 | @end deffn | |
1334 | ||
1335 | @deffn primitive string-trim s [char_pred start end] | |
1336 | @deffnx primitive string-trim-right s [char_pred start end] | |
1337 | @deffnx primitive string-trim-both s [char_pred start end] | |
1338 | Trim @var{s} by skipping over all characters on the left/right/both | |
1339 | sides of the string that satisfy the parameter @var{char_pred}: | |
1340 | ||
1341 | @itemize @bullet | |
1342 | @item | |
1343 | if it is the character @var{ch}, characters equal to | |
1344 | @var{ch} are trimmed, | |
1345 | ||
1346 | @item | |
1347 | if it is a procedure @var{pred} characters that | |
1348 | satisfy @var{pred} are trimmed, | |
1349 | ||
1350 | @item | |
1351 | if it is a character set, characters in that set are trimmed. | |
1352 | @end itemize | |
1353 | ||
1354 | If called without a @var{char_pred} argument, all whitespace is | |
1355 | trimmed. | |
1356 | @end deffn | |
1357 | ||
1358 | ||
1359 | @c =================================================================== | |
1360 | ||
1361 | @node SRFI-13 Modification | |
1362 | @subsection Modification | |
1363 | ||
1364 | The procedure @code{string-fill!} is extended from R5RS because it | |
1365 | accepts optional start/end indices. This bindings shadows the procedure | |
1366 | of the same name in the Guile core. The second modification procedure | |
1367 | @code{string-set!} is documented in the Strings section (@pxref{String | |
1368 | Modification}). | |
1369 | ||
1370 | @deffn primitive string-fill! str chr [start end] | |
1371 | Stores @var{chr} in every element of the given @var{str} and | |
1372 | returns an unspecified value. | |
1373 | @end deffn | |
1374 | ||
1375 | ||
1376 | @c =================================================================== | |
1377 | ||
1378 | @node SRFI-13 Comparison | |
1379 | @subsection Comparison | |
1380 | ||
1381 | The procedures in this section are used for comparing strings in | |
1382 | different ways. The comparison predicates differ from those in R5RS in | |
1383 | that they do not only return @code{#t} or @code{#f}, but the mismatch | |
1384 | index in the case of a true return value. | |
1385 | ||
1386 | @code{string-hash} and @code{string-hash-ci} are for calculating hash | |
1387 | values for strings, useful for implementing fast lookup mechanisms. | |
1388 | ||
1389 | @deffn primitive string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2] | |
1390 | @deffnx primitive string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2] | |
1391 | Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the | |
1392 | mismatch index, depending upon whether @var{s1} is less than, | |
1393 | equal to, or greater than @var{s2}. The mismatch index is the | |
1394 | largest index @var{i} such that for every 0 <= @var{j} < | |
1395 | @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] - that is, | |
1396 | @var{i} is the first position that does not match. The | |
1397 | character comparison is done case-insensitively. | |
1398 | @end deffn | |
1399 | ||
1400 | @deffn primitive string= s1 s2 [start1 end1 start2 end2] | |
1401 | @deffnx primitive string<> s1 s2 [start1 end1 start2 end2] | |
1402 | @deffnx primitive string< s1 s2 [start1 end1 start2 end2] | |
1403 | @deffnx primitive string> s1 s2 [start1 end1 start2 end2] | |
1404 | @deffnx primitive string<= s1 s2 [start1 end1 start2 end2] | |
1405 | @deffnx primitive string>= s1 s2 [start1 end1 start2 end2] | |
1406 | Compare @var{s1} and @var{s2} and return @code{#f} if the predicate | |
1407 | fails. Otherwise, the mismatch index is returned (or @var{end1} in the | |
1408 | case of @code{string=}. | |
1409 | @end deffn | |
1410 | ||
1411 | @deffn primitive string-ci= s1 s2 [start1 end1 start2 end2] | |
1412 | @deffnx primitive string-ci<> s1 s2 [start1 end1 start2 end2] | |
1413 | @deffnx primitive string-ci< s1 s2 [start1 end1 start2 end2] | |
1414 | @deffnx primitive string-ci> s1 s2 [start1 end1 start2 end2] | |
1415 | @deffnx primitive string-ci<= s1 s2 [start1 end1 start2 end2] | |
1416 | @deffnx primitive string-ci>= s1 s2 [start1 end1 start2 end2] | |
1417 | Compare @var{s1} and @var{s2} and return @code{#f} if the predicate | |
1418 | fails. Otherwise, the mismatch index is returned (or @var{end1} in the | |
1419 | case of @code{string=}. These are the case-insensitive variants. | |
1420 | @end deffn | |
1421 | ||
1422 | @deffn primitive string-hash s [bound start end] | |
1423 | @deffnx primitive string-hash-ci s [bound start end] | |
1424 | Return a hash value of the string @var{s} in the range 0 @dots{} | |
1425 | @var{bound} - 1. @code{string-hash-ci} is the case-insensitive variant. | |
1426 | @end deffn | |
1427 | ||
1428 | ||
1429 | @c =================================================================== | |
1430 | ||
1431 | @node SRFI-13 Prefixes/Suffixes | |
1432 | @subsection Prefixes/Suffixes | |
1433 | ||
1434 | Using these procedures you can determine whether a given string is a | |
1435 | prefix or suffix of another string or how long a common prefix/suffix | |
1436 | is. | |
1437 | ||
1438 | @deffn primitive string-prefix-length s1 s2 [start1 end1 start2 end2] | |
1439 | @deffnx primitive string-prefix-length-ci s1 s2 [start1 end1 start2 end2] | |
1440 | @deffnx primitive string-suffix-length s1 s2 [start1 end1 start2 end2] | |
1441 | @deffnx primitive string-suffix-length-ci s1 s2 [start1 end1 start2 end2] | |
1442 | Return the length of the longest common prefix/suffix of the two | |
1443 | strings. @code{string-prefix-length-ci} and | |
1444 | @code{string-suffix-length-ci} are the case-insensitive variants. | |
1445 | @end deffn | |
1446 | ||
1447 | @deffn primitive string-prefix? s1 s2 [start1 end1 start2 end2] | |
1448 | @deffnx primitive string-prefix-ci? s1 s2 [start1 end1 start2 end2] | |
1449 | @deffnx primitive string-suffix? s1 s2 [start1 end1 start2 end2] | |
1450 | @deffnx primitive string-suffix-ci? s1 s2 [start1 end1 start2 end2] | |
1451 | Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and | |
1452 | @code{string-suffix-ci?} are the case-insensitive variants. | |
1453 | @end deffn | |
1454 | ||
1455 | ||
1456 | @c =================================================================== | |
1457 | ||
1458 | @node SRFI-13 Searching | |
1459 | @subsection Searching | |
1460 | ||
1461 | Use these procedures to find out whether a string contains a given | |
1462 | character or a given substring, or a character from a set of characters. | |
1463 | ||
1464 | @deffn primitive string-index s char_pred [start end] | |
1465 | @deffnx primitive string-index-right s char_pred [start end] | |
1466 | Search through the string @var{s} from left to right (right to left), | |
1467 | returning the index of the first (last) occurence of a character which | |
1468 | ||
1469 | @itemize @bullet | |
1470 | @item | |
1471 | equals @var{char_pred}, if it is character, | |
1472 | ||
1473 | @item | |
1474 | satisifies the predicate @var{char_pred}, if it is a | |
1475 | procedure, | |
1476 | ||
1477 | @item | |
1478 | is in the set @var{char_pred}, if it is a character set. | |
1479 | @end itemize | |
1480 | @end deffn | |
1481 | ||
1482 | @deffn primitive string-skip s char_pred [start end] | |
1483 | @deffnx primitive string-skip-right s char_pred [start end] | |
1484 | Search through the string @var{s} from left to right (right to left), | |
1485 | returning the index of the first (last) occurence of a character which | |
1486 | ||
1487 | @itemize @bullet | |
1488 | @item | |
1489 | does not equal @var{char_pred}, if it is character, | |
1490 | ||
1491 | @item | |
1492 | does not satisify the predicate @var{char_pred}, if it is | |
1493 | a procedure. | |
1494 | ||
1495 | @item | |
1496 | is not in the set if @var{char_pred} is a character set. | |
1497 | @end itemize | |
1498 | @end deffn | |
1499 | ||
1500 | @deffn primitive string-count s char_pred [start end] | |
1501 | Return the count of the number of characters in the string | |
1502 | @var{s} which | |
1503 | ||
1504 | @itemize @bullet | |
1505 | @item | |
1506 | equals @var{char_pred}, if it is character, | |
1507 | ||
1508 | @item | |
1509 | satisifies the predicate @var{char_pred}, if it is a procedure. | |
1510 | ||
1511 | @item | |
1512 | is in the set @var{char_pred}, if it is a character set. | |
1513 | @end itemize | |
1514 | @end deffn | |
1515 | ||
1516 | @deffn primitive string-contains s1 s2 [start1 end1 start2 end2] | |
1517 | @deffnx primitive string-contains-ci s1 s2 [start1 end1 start2 end2] | |
1518 | Does string @var{s1} contain string @var{s2}? Return the index | |
1519 | in @var{s1} where @var{s2} occurs as a substring, or false. | |
1520 | The optional start/end indices restrict the operation to the | |
1521 | indicated substrings. | |
1522 | ||
1523 | @code{string-contains-ci} is the case-insensitive variant. | |
1524 | @end deffn | |
1525 | ||
1526 | ||
1527 | @c =================================================================== | |
1528 | ||
1529 | @node SRFI-13 Case Mapping | |
1530 | @subsection Alphabetic Case Mapping | |
1531 | ||
1532 | These procedures convert the alphabetic case of strings. They are | |
1533 | similar to the procedures in the Guile core, but are extended to handle | |
1534 | optional start/end indices. | |
1535 | ||
1536 | @deffn primitive string-upcase s [start end] | |
1537 | @deffnx primitive string-upcase! s [start end] | |
1538 | Upcase every character in @var{s}. @code{string-upcase!} is the | |
1539 | side-effecting variant. | |
1540 | @end deffn | |
1541 | ||
1542 | @deffn primitive string-downcase s [start end] | |
1543 | @deffnx primitive string-downcase! s [start end] | |
1544 | Downcase every character in @var{s}. @code{string-downcase!} is the | |
1545 | side-effecting variant. | |
1546 | @end deffn | |
1547 | ||
1548 | @deffn primitive string-titlecase s [start end] | |
1549 | @deffnx primitive string-titlecase! s [start end] | |
1550 | Upcase every first character in every word in @var{s}, downcase the | |
1551 | other characters. @code{string-titlecase!} is the side-effecting | |
1552 | variant. | |
1553 | @end deffn | |
1554 | ||
1555 | ||
1556 | @c =================================================================== | |
1557 | ||
1558 | @node SRFI-13 Reverse/Append | |
1559 | @subsection Reverse/Append | |
1560 | ||
1561 | One appending procedure, @code{string-append} is the same in R5RS and in | |
1562 | SRFI-13, so it is not redefined. | |
1563 | ||
1564 | @deffn primitive string-reverse str [start end] | |
1565 | @deffnx primitive string-reverse! str [start end] | |
1566 | Reverse the string @var{str}. The optional arguments | |
1567 | @var{start} and @var{end} delimit the region of @var{str} to | |
1568 | operate on. | |
1569 | ||
1570 | @code{string-reverse!} modifies the argument string and returns an | |
1571 | unspecified value. | |
1572 | @end deffn | |
1573 | ||
1574 | @deffn primitive string-append/shared ls @dots{} | |
1575 | Like @code{string-append}, but the result may share memory | |
1576 | with the argument strings. | |
1577 | @end deffn | |
1578 | ||
1579 | @deffn primitive string-concatenate ls | |
1580 | Append the elements of @var{ls} (which must be strings) | |
1581 | together into a single string. Guaranteed to return a freshly | |
1582 | allocated string. | |
1583 | @end deffn | |
1584 | ||
1585 | @deffn primitive string-concatenate/shared ls | |
1586 | Like @code{string-concatenate}, but the result may share memory | |
1587 | with the strings in the list @var{ls}. | |
1588 | @end deffn | |
1589 | ||
1590 | @deffn primitive string-concatenate-reverse ls final_string end | |
1591 | Without optional arguments, this procedure is equivalent to | |
1592 | ||
1593 | @smalllisp | |
1594 | (string-concatenate (reverse ls)) | |
1595 | @end smalllisp | |
1596 | ||
1597 | If the optional argument @var{final_string} is specified, it is | |
1598 | consed onto the beginning to @var{ls} before performing the | |
1599 | list-reverse and string-concatenate operations. If @var{end} | |
1600 | is given, only the characters of @var{final_string} up to index | |
1601 | @var{end} are used. | |
1602 | ||
1603 | Guaranteed to return a freshly allocated string. | |
1604 | @end deffn | |
1605 | ||
1606 | @deffn primitive string-concatenate-reverse/shared ls final_string end | |
1607 | Like @code{string-concatenate-reverse}, but the result may | |
1608 | share memory with the the strings in the @var{ls} arguments. | |
1609 | @end deffn | |
1610 | ||
1611 | ||
1612 | @c =================================================================== | |
1613 | ||
1614 | @node SRFI-13 Fold/Unfold/Map | |
1615 | @subsection Fold/Unfold/Map | |
1616 | ||
1617 | @code{string-map}, @code{string-for-each} etc. are for iterating over | |
1618 | the characters a string is composed of. The fold and unfold procedures | |
1619 | are list iterators and constructors. | |
1620 | ||
1621 | @deffn primitive string-map proc s [start end] | |
1622 | @var{proc} is a char->char procedure, it is mapped over | |
1623 | @var{s}. The order in which the procedure is applied to the | |
1624 | string elements is not specified. | |
1625 | @end deffn | |
1626 | ||
1627 | @deffn primitive string-map! proc s [start end] | |
1628 | @var{proc} is a char->char procedure, it is mapped over | |
1629 | @var{s}. The order in which the procedure is applied to the | |
1630 | string elements is not specified. The string @var{s} is | |
1631 | modified in-place, the return value is not specified. | |
1632 | @end deffn | |
1633 | ||
1634 | @deffn primitive string-fold kons knil s [start end] | |
1635 | @deffnx primitive string-fold-right kons knil s [start end] | |
1636 | Fold @var{kons} over the characters of @var{s}, with @var{knil} as the | |
1637 | terminating element, from left to right (or right to left, for | |
1638 | @code{string-fold-right}). @var{kons} must expect two arguments: The | |
1639 | actual character and the last result of @var{kons}' application. | |
1640 | @end deffn | |
1641 | ||
1642 | @deffn primitive string-unfold p f g seed [base make_final] | |
1643 | @deffnx primitive string-unfold-right p f g seed [base make_final] | |
1644 | These are the fundamental string constructors. | |
1645 | @itemize @bullet | |
1646 | @item @var{g} is used to generate a series of @emph{seed} | |
1647 | values from the initial @var{seed}: @var{seed}, (@var{g} | |
1648 | @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), | |
1649 | @dots{} | |
1650 | @item @var{p} tells us when to stop - when it returns true | |
1651 | when applied to one of these seed values. | |
1652 | @item @var{f} maps each seed value to the corresponding | |
1653 | character in the result string. These chars are assembled into the | |
1654 | string in a left-to-right (right-to-left) order. | |
1655 | @item @var{base} is the optional initial/leftmost (rightmost) | |
1656 | portion of the constructed string; it default to the empty string. | |
1657 | @item @var{make_final} is applied to the terminal seed | |
1658 | value (on which @var{p} returns true) to produce the final/rightmost | |
1659 | (leftmost) portion of the constructed string. It defaults to | |
1660 | @code{(lambda (x) "")}. | |
1661 | @end itemize | |
1662 | @end deffn | |
1663 | ||
1664 | @deffn primitive string-for-each proc s [start end] | |
1665 | @var{proc} is mapped over @var{s} in left-to-right order. The | |
1666 | return value is not specified. | |
1667 | @end deffn | |
1668 | ||
1669 | ||
1670 | @c =================================================================== | |
1671 | ||
1672 | @node SRFI-13 Replicate/Rotate | |
1673 | @subsection Replicate/Rotate | |
1674 | ||
1675 | These procedures are special substring procedures, which can also be | |
1676 | used for replicating strings. They are a bit tricky to use, but | |
1677 | consider this code fragment, which replicates the input string | |
1678 | @code{"foo"} so often that the resulting string has a length of six. | |
1679 | ||
1680 | @lisp | |
1681 | (xsubstring "foo" 0 6) | |
1682 | @result{} | |
1683 | "foofoo" | |
1684 | @end lisp | |
1685 | ||
1686 | @deffn primitive xsubstring s from [to start end] | |
1687 | This is the @emph{extended substring} procedure that implements | |
1688 | replicated copying of a substring of some string. | |
1689 | ||
1690 | @var{s} is a string, @var{start} and @var{end} are optional | |
1691 | arguments that demarcate a substring of @var{s}, defaulting to | |
1692 | 0 and the length of @var{s}. Replicate this substring up and | |
1693 | down index space, in both the positive and negative directions. | |
1694 | @code{xsubstring} returns the substring of this string | |
1695 | beginning at index @var{from}, and ending at @var{to}, which | |
1696 | defaults to @var{from} + (@var{end} - @var{start}). | |
1697 | @end deffn | |
1698 | ||
1699 | @deffn primitive string-xcopy! target tstart s sfrom [sto start end] | |
1700 | Exactly the same as @code{xsubstring}, but the extracted text | |
1701 | is written into the string @var{target} starting at index | |
1702 | @var{tstart}. The operation is not defined if @code{(eq? | |
1703 | @var{target} @var{s})} or these arguments share storage - you | |
1704 | cannot copy a string on top of itself. | |
1705 | @end deffn | |
1706 | ||
1707 | ||
1708 | @c =================================================================== | |
1709 | ||
1710 | @node SRFI-13 Miscellaneous | |
1711 | @subsection Miscellaneous | |
1712 | ||
1713 | @code{string-replace} is for replacing a portion of a string with | |
1714 | another string and @code{string-tokenize} splits a string into a list of | |
1715 | strings, breaking it up at a specified character. | |
1716 | ||
1717 | @deffn primitive string-replace s1 s2 [start1 end1 start2 end2] | |
1718 | Return the string @var{s1}, but with the characters | |
1719 | @var{start1} @dots{} @var{end1} replaced by the characters | |
1720 | @var{start2} @dots{} @var{end2} from @var{s2}. | |
1721 | @end deffn | |
1722 | ||
1723 | @deffn primitive string-tokenize s [token_char start end] | |
1724 | Split the string @var{s} into a list of substrings, where each | |
1725 | substring is a maximal non-empty contiguous sequence of | |
1726 | characters equal to the character @var{token_char}, or | |
1727 | whitespace, if @var{token_char} is not given. If | |
1728 | @var{token_char} is a character set, it is used for finding the | |
1729 | token borders. | |
1730 | @end deffn | |
1731 | ||
1732 | ||
1733 | @c =================================================================== | |
1734 | ||
1735 | @node SRFI-13 Filtering/Deleting | |
1736 | @subsection Filtering/Deleting | |
1737 | ||
1738 | @dfn{Filtering} means to remove all characters from a string which do | |
1739 | not match a given criteria, @dfn{deleting} means the opposite. | |
1740 | ||
1741 | @deffn primitive string-filter s char_pred [start end] | |
1742 | Filter the string @var{s}, retaining only those characters that | |
1743 | satisfy the @var{char_pred} argument. If the argument is a | |
1744 | procedure, it is applied to each character as a predicate, if | |
1745 | it is a character, it is tested for equality and if it is a | |
1746 | character set, it is tested for membership. | |
1747 | @end deffn | |
1748 | ||
1749 | @deffn primitive string-delete s char_pred [start end] | |
1750 | Filter the string @var{s}, retaining only those characters that | |
1751 | do not satisfy the @var{char_pred} argument. If the argument | |
1752 | is a procedure, it is applied to each character as a predicate, | |
1753 | if it is a character, it is tested for equality and if it is a | |
1754 | character set, it is tested for membership. | |
1755 | @end deffn | |
1756 | ||
1757 | ||
1758 | @node SRFI-14 | |
1759 | @section SRFI-14 - Character-set Library | |
1760 | ||
1761 | SRFI-14 defines the data type @dfn{character set}, and also defines a | |
1762 | lot of procedures for handling this character type, and a few standard | |
1763 | character sets like whitespace, alphabetic characters and others. | |
1764 | ||
1765 | All procedures from SRFI-14 (character-set library) are implemented in | |
1766 | the module @code{(srfi srfi-14)}, as well as the standard variables | |
1767 | @code{char-set:letter}, @code{char-set:digit} etc. | |
1768 | ||
1769 | @menu | |
1770 | * Loading SRFI-14:: How to make charsets available. | |
1771 | * SRFI-14 Character Set Data Type:: Underlying data type for charsets. | |
1772 | * SRFI-14 Predicates/Comparison:: Charset predicates. | |
1773 | * SRFI-14 Iterating Over Character Sets:: Enumerate charset elements. | |
1774 | * SRFI-14 Creating Character Sets:: Makeing new charsets. | |
1775 | * SRFI-14 Querying Character Sets:: Test charsets for membership etc. | |
1776 | * SRFI-14 Character-Set Algebra:: Calculating new charsets. | |
1777 | * SRFI-14 Standard Character Sets:: Variables containing predefined charsets. | |
1778 | @end menu | |
1779 | ||
1780 | ||
1781 | @node Loading SRFI-14 | |
1782 | @subsection Loading SRFI-14 | |
1783 | ||
1784 | When Guile is properly installed, SRFI-14 support can be loaded into a | |
1785 | running Guile by using the @code{(srfi srfi-14)} module. | |
1786 | ||
1787 | @example | |
1788 | $ guile | |
1789 | guile> (use-modules (srfi srfi-14)) | |
1790 | guile> (char-set-union (char-set #\f #\o #\o) (string->char-set "bar")) | |
1791 | #<charset @{#\a #\b #\f #\o #\r@}> | |
1792 | guile> | |
1793 | @end example | |
1794 | ||
1795 | ||
1796 | @node SRFI-14 Character Set Data Type | |
1797 | @subsection Character Set Data Type | |
1798 | ||
1799 | The data type @dfn{charset} implements sets of characters | |
1800 | (@pxref{Characters}). Because the internal representation of character | |
1801 | sets is not visible to the user, a lot of procedures for handling them | |
1802 | are provided. | |
1803 | ||
1804 | Character sets can be created, extended, tested for the membership of a | |
1805 | characters and be compared to other character sets. | |
1806 | ||
1807 | The Guile implementation of character sets deals with 8-bit characters. | |
1808 | In the standard variables, only the ASCII part of the character range is | |
1809 | really used, so that for example @dfn{Umlaute} and other accented | |
1810 | characters are not considered to be letters. In the future, as Guile | |
1811 | may get support for international character sets, this will change, so | |
1812 | don't rely on these ``features''. | |
1813 | ||
1814 | ||
1815 | @c =================================================================== | |
1816 | ||
1817 | @node SRFI-14 Predicates/Comparison | |
1818 | @subsection Predicates/Comparison | |
1819 | ||
1820 | Use these procedures for testing whether an object is a character set, | |
1821 | or whether several character sets are equal or subsets of each other. | |
1822 | @code{char-set-hash} can be used for calculating a hash value, maybe for | |
1823 | usage in fast lookup procedures. | |
1824 | ||
1825 | @deffn primitive char-set? obj | |
1826 | Return @code{#t} if @var{obj} is a character set, @code{#f} | |
1827 | otherwise. | |
1828 | @end deffn | |
1829 | ||
1830 | @deffn primitive char-set= cs1 @dots{} | |
1831 | Return @code{#t} if all given character sets are equal. | |
1832 | @end deffn | |
1833 | ||
1834 | @deffn primitive char-set<= cs1 @dots{} | |
1835 | Return @code{#t} if every character set @var{cs}i is a subset | |
1836 | of character set @var{cs}i+1. | |
1837 | @end deffn | |
1838 | ||
1839 | @deffn primitive char-set-hash cs [bound] | |
1840 | Compute a hash value for the character set @var{cs}. If | |
1841 | @var{bound} is given and not @code{#f}, it restricts the | |
1842 | returned value to the range 0 @dots{} @var{bound - 1}. | |
1843 | @end deffn | |
1844 | ||
1845 | ||
1846 | @c =================================================================== | |
1847 | ||
1848 | @node SRFI-14 Iterating Over Character Sets | |
1849 | @subsection Iterating Over Character Sets | |
1850 | ||
1851 | Character set cursors are a means for iterating over the members of a | |
1852 | character sets. After creating a character set cursor with | |
1853 | @code{char-set-cursor}, a cursor can be dereferenced with | |
1854 | @code{char-set-ref}, advanced to the next member with | |
1855 | @code{char-set-cursor-next}. Whether a cursor has passed past the last | |
1856 | element of the set can be checked with @code{end-of-char-set?}. | |
1857 | ||
1858 | Additionally, mapping and (un-)folding procedures for character sets are | |
1859 | provided. | |
1860 | ||
1861 | @deffn primitive char-set-cursor cs | |
1862 | Return a cursor into the character set @var{cs}. | |
1863 | @end deffn | |
1864 | ||
1865 | @deffn primitive char-set-ref cs cursor | |
1866 | Return the character at the current cursor position | |
1867 | @var{cursor} in the character set @var{cs}. It is an error to | |
1868 | pass a cursor for which @code{end-of-char-set?} returns true. | |
1869 | @end deffn | |
1870 | ||
1871 | @deffn primitive char-set-cursor-next cs cursor | |
1872 | Advance the character set cursor @var{cursor} to the next | |
1873 | character in the character set @var{cs}. It is an error if the | |
1874 | cursor given satisfies @code{end-of-char-set?}. | |
1875 | @end deffn | |
1876 | ||
1877 | @deffn primitive end-of-char-set? cursor | |
1878 | Return @code{#t} if @var{cursor} has reached the end of a | |
1879 | character set, @code{#f} otherwise. | |
1880 | @end deffn | |
1881 | ||
1882 | @deffn primitive char-set-fold kons knil cs | |
1883 | Fold the procedure @var{kons} over the character set @var{cs}, | |
1884 | initializing it with @var{knil}. | |
1885 | @end deffn | |
1886 | ||
1887 | @deffn primitive char-set-unfold p f g seed [base_cs] | |
1888 | @deffnx primitive char-set-unfold! p f g seed base_cs | |
1889 | This is a fundamental constructor for character sets. | |
1890 | @itemize @bullet | |
1891 | @item @var{g} is used to generate a series of ``seed'' values | |
1892 | from the initial seed: @var{seed}, (@var{g} @var{seed}), | |
1893 | (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{} | |
1894 | @item @var{p} tells us when to stop -- when it returns true | |
1895 | when applied to one of the seed values. | |
1896 | @item @var{f} maps each seed value to a character. These | |
1897 | characters are added to the base character set @var{base_cs} to | |
1898 | form the result; @var{base_cs} defaults to the empty set. | |
1899 | @end itemize | |
1900 | ||
1901 | @code{char-set-unfold!} is the side-effecting variant. | |
1902 | @end deffn | |
1903 | ||
1904 | @deffn primitive char-set-for-each proc cs | |
1905 | Apply @var{proc} to every character in the character set | |
1906 | @var{cs}. The return value is not specified. | |
1907 | @end deffn | |
1908 | ||
1909 | @deffn primitive char-set-map proc cs | |
1910 | Map the procedure @var{proc} over every character in @var{cs}. | |
1911 | @var{proc} must be a character -> character procedure. | |
1912 | @end deffn | |
1913 | ||
1914 | ||
1915 | @c =================================================================== | |
1916 | ||
1917 | @node SRFI-14 Creating Character Sets | |
1918 | @subsection Creating Character Sets | |
1919 | ||
1920 | New character sets are produced with these procedures. | |
1921 | ||
1922 | @deffn primitive char-set-copy cs | |
1923 | Return a newly allocated character set containing all | |
1924 | characters in @var{cs}. | |
1925 | @end deffn | |
1926 | ||
1927 | @deffn primitive char-set char1 @dots{} | |
1928 | Return a character set containing all given characters. | |
1929 | @end deffn | |
1930 | ||
1931 | @deffn primitive list->char-set char_list [base_cs] | |
1932 | @deffnx primitive list->char-set! char_list base_cs | |
1933 | Convert the character list @var{list} to a character set. If | |
1934 | the character set @var{base_cs} is given, the character in this | |
1935 | set are also included in the result. | |
1936 | ||
1937 | @code{list->char-set!} is the side-effecting variant. | |
1938 | @end deffn | |
1939 | ||
1940 | @deffn primitive string->char-set s [base_cs] | |
1941 | @deffnx primitive string->char-set! s base_cs | |
1942 | Convert the string @var{str} to a character set. If the | |
1943 | character set @var{base_cs} is given, the characters in this | |
1944 | set are also included in the result. | |
1945 | ||
1946 | @code{string->char-set!} is the side-effecting variant. | |
1947 | @end deffn | |
1948 | ||
1949 | @deffn primitive char-set-filter pred cs [base_cs] | |
1950 | @deffnx primitive char-set-filter! pred cs base_cs | |
1951 | Return a character set containing every character from @var{cs} | |
1952 | so that it satisfies @var{pred}. If provided, the characters | |
1953 | from @var{base_cs} are added to the result. | |
1954 | ||
1955 | @code{char-set-filter!} is the side-effecting variant. | |
1956 | @end deffn | |
1957 | ||
1958 | @deffn primitive ucs-range->char-set lower upper [error? base_cs] | |
1959 | @deffnx primitive uce-range->char-set! lower upper error? base_cs | |
1960 | Return a character set containing all characters whose | |
1961 | character codes lie in the half-open range | |
1962 | [@var{lower},@var{upper}). | |
1963 | ||
1964 | If @var{error} is a true value, an error is signalled if the | |
1965 | specified range contains characters which are not contained in | |
1966 | the implemented character range. If @var{error} is @code{#f}, | |
1967 | these characters are silently left out of the resultung | |
1968 | character set. | |
1969 | ||
1970 | The characters in @var{base_cs} are added to the result, if | |
1971 | given. | |
1972 | ||
1973 | @code{ucs-range->char-set!} is the side-effecting variant. | |
1974 | @end deffn | |
1975 | ||
1976 | @deffn procedure ->char-set x | |
1977 | Coerce @var{x} into a character set. @var{x} may be a string, a | |
1978 | character or a character set. | |
1979 | @end deffn | |
1980 | ||
1981 | ||
1982 | @c =================================================================== | |
1983 | ||
1984 | @node SRFI-14 Querying Character Sets | |
1985 | @subsection Querying Character Sets | |
1986 | ||
1987 | Access the elements and other information of a character set with these | |
1988 | procedures. | |
1989 | ||
1990 | @deffn primitive char-set-size cs | |
1991 | Return the number of elements in character set @var{cs}. | |
1992 | @end deffn | |
1993 | ||
1994 | @deffn primitive char-set-count pred cs | |
1995 | Return the number of the elements int the character set | |
1996 | @var{cs} which satisfy the predicate @var{pred}. | |
1997 | @end deffn | |
1998 | ||
1999 | @deffn primitive char-set->list cs | |
2000 | Return a list containing the elements of the character set | |
2001 | @var{cs}. | |
2002 | @end deffn | |
2003 | ||
2004 | @deffn primitive char-set->string cs | |
2005 | Return a string containing the elements of the character set | |
2006 | @var{cs}. The order in which the characters are placed in the | |
2007 | string is not defined. | |
2008 | @end deffn | |
2009 | ||
2010 | @deffn primitive char-set-contains? cs char | |
2011 | Return @code{#t} iff the character @var{ch} is contained in the | |
2012 | character set @var{cs}. | |
2013 | @end deffn | |
2014 | ||
2015 | @deffn primitive char-set-every pred cs | |
2016 | Return a true value if every character in the character set | |
2017 | @var{cs} satisfies the predicate @var{pred}. | |
2018 | @end deffn | |
2019 | ||
2020 | @deffn primitive char-set-any pred cs | |
2021 | Return a true value if any character in the character set | |
2022 | @var{cs} satisfies the predicate @var{pred}. | |
2023 | @end deffn | |
2024 | ||
2025 | ||
2026 | @c =================================================================== | |
2027 | ||
2028 | @node SRFI-14 Character-Set Algebra | |
2029 | @subsection Character-Set Algebra | |
2030 | ||
2031 | Character sets can be manipulated with the common set algebra operation, | |
2032 | such as union, complement, intersection etc. All of these procedures | |
2033 | provide side-effecting variants, which modify their character set | |
2034 | argument(s). | |
2035 | ||
2036 | @deffn primitive char-set-adjoin cs char1 @dots{} | |
2037 | @deffnx primitive char-set-adjoin! cs char1 @dots{} | |
2038 | Add all character arguments to the first argument, which must | |
2039 | be a character set. | |
2040 | @end deffn | |
2041 | ||
2042 | @deffn primitive char-set-delete cs char1 @dots{} | |
2043 | @deffnx primitive char-set-delete! cs char1 @dots{} | |
2044 | Delete all character arguments from the first argument, which | |
2045 | must be a character set. | |
2046 | @end deffn | |
2047 | ||
2048 | @deffn primitive char-set-complement cs | |
2049 | @deffnx primitive char-set-complement! cs | |
2050 | Return the complement of the character set @var{cs}. | |
2051 | @end deffn | |
2052 | ||
2053 | @deffn primitive char-set-union cs1 @dots{} | |
2054 | @deffnx primitive char-set-union! cs1 @dots{} | |
2055 | Return the union of all argument character sets. | |
2056 | @end deffn | |
2057 | ||
2058 | @deffn primitive char-set-intersection cs1 @dots{} | |
2059 | @deffnx primitive char-set-intersection! cs1 @dots{} | |
2060 | Return the intersection of all argument character sets. | |
2061 | @end deffn | |
2062 | ||
2063 | @deffn primitive char-set-difference cs1 @dots{} | |
2064 | @deffnx primitive char-set-difference! cs1 @dots{} | |
2065 | Return the difference of all argument character sets. | |
2066 | @end deffn | |
2067 | ||
2068 | @deffn primitive char-set-xor cs1 @dots{} | |
2069 | @deffnx primitive char-set-xor! cs1 @dots{} | |
2070 | Return the exclusive-or of all argument character sets. | |
2071 | @end deffn | |
2072 | ||
2073 | @deffn primitive char-set-diff+intersection cs1 @dots{} | |
2074 | @deffnx primitive char-set-diff+intersection! cs1 @dots{} | |
2075 | Return the difference and the intersection of all argument | |
2076 | character sets. | |
2077 | @end deffn | |
2078 | ||
2079 | ||
2080 | @c =================================================================== | |
2081 | ||
2082 | @node SRFI-14 Standard Character Sets | |
2083 | @subsection Standard Character Sets | |
2084 | ||
2085 | In order to make the use of the character set data type and procedures | |
2086 | useful, several predefined character set variables exist. | |
2087 | ||
2088 | @defvar char-set:lower-case | |
2089 | All lower-case characters. | |
2090 | @end defvar | |
2091 | ||
2092 | @defvar char-set:upper-case | |
2093 | All upper-case characters. | |
2094 | @end defvar | |
2095 | ||
2096 | @defvar char-set:title-case | |
2097 | This is empty, because ASCII has no titlecase characters. | |
2098 | @end defvar | |
2099 | ||
2100 | @defvar char-set:letter | |
2101 | All letters, e.g. the union of @code{char-set:lower-case} and | |
2102 | @code{char-set:upper-case}. | |
2103 | @end defvar | |
2104 | ||
2105 | @defvar char-set:digit | |
2106 | All digits. | |
2107 | @end defvar | |
2108 | ||
2109 | @defvar char-set:letter+digit | |
2110 | The union of @code{char-set:letter} and @code{char-set:digit}. | |
2111 | @end defvar | |
2112 | ||
2113 | @defvar char-set:graphic | |
2114 | All characters which would put ink on the paper. | |
2115 | @end defvar | |
2116 | ||
2117 | @defvar char-set:printing | |
2118 | The union of @code{char-set:graphic} and @code{char-set:whitespace}. | |
2119 | @end defvar | |
2120 | ||
2121 | @defvar char-set:whitespace | |
2122 | All whitespace characters. | |
2123 | @end defvar | |
2124 | ||
2125 | @defvar char-set:blank | |
2126 | All horizontal whitespace characters, that is @code{#\space} and | |
2127 | @code{#\tab}. | |
2128 | @end defvar | |
2129 | ||
2130 | @defvar char-set:iso-control | |
2131 | The ISO control characters with the codes 0--31 and 127. | |
2132 | @end defvar | |
2133 | ||
2134 | @defvar char-set:punctuation | |
2135 | The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}} | |
2136 | @end defvar | |
2137 | ||
2138 | @defvar char-set:symbol | |
2139 | The characters @code{$+<=>^`|~}. | |
2140 | @end defvar | |
2141 | ||
2142 | @defvar char-set:hex-digit | |
2143 | The hexadecimal digits @code{0123456789abcdefABCDEF}. | |
2144 | @end defvar | |
2145 | ||
2146 | @defvar char-set:ascii | |
2147 | All ASCII characters. | |
2148 | @end defvar | |
2149 | ||
2150 | @defvar char-set:empty | |
2151 | The empty character set. | |
2152 | @end defvar | |
2153 | ||
2154 | @defvar char-set:full | |
2155 | This character set contains all possible characters. | |
2156 | @end defvar | |
2157 | ||
2158 | @node SRFI-16 | |
2159 | @section SRFI-16 - case-lambda | |
2160 | ||
2161 | @c FIXME::martin: Review me! | |
2162 | ||
2163 | The syntactic form @code{case-lambda} creates procedures, just like | |
2164 | @code{lambda}, but has syntactic extensions for writing procedures of | |
2165 | varying arity easier. | |
2166 | ||
2167 | The syntax of the @code{case-lambda} form is defined in the following | |
2168 | EBNF grammar. | |
2169 | ||
2170 | @example | |
2171 | @group | |
2172 | <case-lambda> | |
2173 | --> (case-lambda <case-lambda-clause>) | |
2174 | <case-lambda-clause> | |
2175 | --> (<formals> <definition-or-command>*) | |
2176 | <formals> | |
2177 | --> (<identifier>*) | |
2178 | | (<identifier>* . <identifier>) | |
2179 | | <identifier> | |
2180 | @end group | |
2181 | @end example | |
2182 | ||
2183 | The value returned by a @code{case-lambda} form is a procedure which | |
2184 | matches the number of actual arguments against the formals in the | |
2185 | various clauses, in order. @dfn{Formals} means a formal argument list | |
2186 | just like with @code{lambda} (@pxref{Lambda}). The first matching clause | |
2187 | is selected, the corresponding values from the actual parameter list are | |
2188 | bound to the variable names in the clauses and the body of the clause is | |
2189 | evaluated. If no clause matches, an error is signalled. | |
2190 | ||
2191 | The following (silly) definition creates a procedure @var{foo} which | |
2192 | acts differently, depending on the number of actual arguments. If one | |
2193 | argument is given, the constant @code{#t} is returned, two arguments are | |
2194 | added and if more arguments are passed, their product is calculated. | |
2195 | ||
2196 | @lisp | |
2197 | (define foo (case-lambda | |
2198 | ((x) #t) | |
2199 | ((x y) (+ x y)) | |
2200 | (z | |
2201 | (apply * z)))) | |
2202 | (foo 'bar) | |
2203 | @result{} | |
2204 | #t | |
2205 | (foo 2 4) | |
2206 | @result{} | |
2207 | 6 | |
2208 | (foo 3 3 3) | |
2209 | @result{} | |
2210 | 27 | |
2211 | (foo) | |
2212 | @result{} | |
2213 | 1 | |
2214 | @end lisp | |
2215 | ||
2216 | The last expression evaluates to 1 because the last clause is matched, | |
2217 | @var{z} is bound to the empty list and the following multiplication, | |
2218 | applied to zero arguments, yields 1. | |
2219 | ||
2220 | ||
2221 | @node SRFI-17 | |
2222 | @section SRFI-17 - Generalized set! | |
2223 | ||
2224 | This is an implementation of SRFI-17: Generalized set! | |
2225 | ||
2226 | It exports the Guile procedure @code{make-procedure-with-setter} under | |
2227 | the SRFI name @code{getter-with-setter} and exports the standard | |
2228 | procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr}, | |
2229 | @code{string-ref} and @code{vector-ref} as procedures with setters, as | |
2230 | required by the SRFI. | |
2231 | ||
2232 | SRFI-17 was heavily criticized during its discussion period but it was | |
2233 | finalized anyway. One issue was its concept of globally associating | |
2234 | setter @dfn{properties} with (procedure) values, which is non-Schemy. | |
2235 | For this reason, this implementation chooses not to provide a way to set | |
2236 | the setter of a procedure. In fact, @code{(set! (setter @var{proc}) | |
2237 | @var{setter})} signals an error. The only way to attach a setter to a | |
2238 | procedure is to create a new object (a @dfn{procedure with setter}) via | |
2239 | the @code{getter-with-setter} procedure. This procedure is also | |
2240 | specified in the SRFI. Using it avoids the described problems. | |
2241 |