Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
a0e07ba4 NJ |
7 | @page |
8 | @node SRFI Support | |
3229f68b | 9 | @section SRFI Support Modules |
8742c48b | 10 | @cindex SRFI |
a0e07ba4 NJ |
11 | |
12 | SRFI is an acronym for Scheme Request For Implementation. The SRFI | |
13 | documents define a lot of syntactic and procedure extensions to standard | |
14 | Scheme as defined in R5RS. | |
15 | ||
16 | Guile has support for a number of SRFIs. This chapter gives an overview | |
17 | over the available SRFIs and some usage hints. For complete | |
18 | documentation, design rationales and further examples, we advise you to | |
19 | get the relevant SRFI documents from the SRFI home page | |
20 | @url{http://srfi.schemers.org}. | |
21 | ||
22 | @menu | |
23 | * About SRFI Usage:: What to know about Guile's SRFI support. | |
24 | * SRFI-0:: cond-expand | |
25 | * SRFI-1:: List library. | |
26 | * SRFI-2:: and-let*. | |
27 | * SRFI-4:: Homogeneous numeric vector datatypes. | |
28 | * SRFI-6:: Basic String Ports. | |
29 | * SRFI-8:: receive. | |
30 | * SRFI-9:: define-record-type. | |
31 | * SRFI-10:: Hash-Comma Reader Extension. | |
32 | * SRFI-11:: let-values and let-values*. | |
33 | * SRFI-13:: String library. | |
34 | * SRFI-14:: Character-set library. | |
35 | * SRFI-16:: case-lambda | |
36 | * SRFI-17:: Generalized set! | |
bfc9c8e0 | 37 | * SRFI-19:: Time/Date library. |
1de8c1ae | 38 | * SRFI-26:: Specializing parameters |
8638c417 | 39 | * SRFI-31:: A special form `rec' for recursive evaluation |
eeadfda1 | 40 | * SRFI-39:: Parameter objects |
a0e07ba4 NJ |
41 | @end menu |
42 | ||
43 | ||
44 | @node About SRFI Usage | |
3229f68b | 45 | @subsection About SRFI Usage |
a0e07ba4 NJ |
46 | |
47 | @c FIXME::martin: Review me! | |
48 | ||
49 | SRFI support in Guile is currently implemented partly in the core | |
50 | library, and partly as add-on modules. That means that some SRFIs are | |
51 | automatically available when the interpreter is started, whereas the | |
52 | other SRFIs require you to use the appropriate support module | |
12991fed | 53 | explicitly. |
a0e07ba4 NJ |
54 | |
55 | There are several reasons for this inconsistency. First, the feature | |
56 | checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be | |
57 | available immediately, because it must be there when the user wants to | |
58 | check for the Scheme implementation, that is, before she can know that | |
59 | it is safe to use @code{use-modules} to load SRFI support modules. The | |
60 | second reason is that some features defined in SRFIs had been | |
61 | implemented in Guile before the developers started to add SRFI | |
62 | implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In | |
63 | the future, it is possible that SRFIs in the core library might be | |
64 | factored out into separate modules, requiring explicit module loading | |
65 | when they are needed. So you should be prepared to have to use | |
66 | @code{use-modules} someday in the future to access SRFI-6 bindings. If | |
67 | you want, you can do that already. We have included the module | |
68 | @code{(srfi srfi-6)} in the distribution, which currently does nothing, | |
69 | but ensures that you can write future-safe code. | |
70 | ||
71 | Generally, support for a specific SRFI is made available by using | |
72 | modules named @code{(srfi srfi-@var{number})}, where @var{number} is the | |
73 | number of the SRFI needed. Another possibility is to use the command | |
74 | line option @code{--use-srfi}, which will load the necessary modules | |
75 | automatically (@pxref{Invoking Guile}). | |
76 | ||
77 | ||
78 | @node SRFI-0 | |
3229f68b | 79 | @subsection SRFI-0 - cond-expand |
8742c48b | 80 | @cindex SRFI-0 |
a0e07ba4 | 81 | |
5eef0f61 KR |
82 | This SRFI lets a portable Scheme program test for the presence of |
83 | certain features, and adapt itself by using different blocks of code, | |
84 | or fail if the necessary features are not available. There's no | |
85 | module to load, this is in the Guile core. | |
a0e07ba4 | 86 | |
5eef0f61 KR |
87 | A program designed only for Guile will generally not need this |
88 | mechanism, such a program can of course directly use the various | |
89 | documented parts of Guile. | |
a0e07ba4 | 90 | |
5eef0f61 KR |
91 | @deffn syntax cond-expand (feature body@dots{}) @dots{} |
92 | Expand to the @var{body} of the first clause whose @var{feature} | |
93 | specification is satisfied. It is an error if no @var{feature} is | |
a0e07ba4 NJ |
94 | satisfied. |
95 | ||
5eef0f61 KR |
96 | Features are symbols such as @code{srfi-1}, and a feature |
97 | specification can use @code{and}, @code{or} and @code{not} forms to | |
98 | test combinations. The last clause can be an @code{else}, to be used | |
99 | if no other passes. | |
a0e07ba4 | 100 | |
5eef0f61 KR |
101 | For example, define a private version of @code{alist-cons} if SRFI-1 |
102 | is not available. | |
a0e07ba4 | 103 | |
5eef0f61 KR |
104 | @example |
105 | (cond-expand (srfi-1 | |
106 | ) | |
107 | (else | |
108 | (define (alist-cons key val alist) | |
109 | (cons (cons key val) alist)))) | |
110 | @end example | |
a0e07ba4 | 111 | |
5eef0f61 KR |
112 | Or demand a certain set of SRFIs (list operations, string ports, |
113 | @code{receive} and string operations), failing if they're not | |
114 | available. | |
a0e07ba4 | 115 | |
5eef0f61 KR |
116 | @example |
117 | (cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13) | |
118 | )) | |
119 | @end example | |
120 | @end deffn | |
a0e07ba4 | 121 | |
f38d22c5 KR |
122 | @noindent |
123 | The Guile core has the following features, | |
124 | ||
125 | @example | |
126 | guile | |
127 | r5rs | |
128 | srfi-0 | |
129 | srfi-4 | |
130 | srfi-6 | |
131 | srfi-13 | |
132 | srfi-14 | |
133 | @end example | |
134 | ||
135 | Other SRFI feature symbols are defined once their code has been loaded | |
136 | with @code{use-modules}, since only then are their bindings available. | |
a0e07ba4 | 137 | |
5eef0f61 KR |
138 | The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is |
139 | a good way to load SRFIs to satisfy @code{cond-expand} when running a | |
140 | portable program. | |
a0e07ba4 | 141 | |
5eef0f61 KR |
142 | Testing the @code{guile} feature allows a program to adapt itself to |
143 | the Guile module system, but still run on other Scheme systems. For | |
144 | example the following demands SRFI-8 (@code{receive}), but also knows | |
145 | how to load it with the Guile mechanism. | |
a0e07ba4 NJ |
146 | |
147 | @example | |
5eef0f61 KR |
148 | (cond-expand (srfi-8 |
149 | ) | |
150 | (guile | |
151 | (use-modules (srfi srfi-8)))) | |
a0e07ba4 NJ |
152 | @end example |
153 | ||
5eef0f61 KR |
154 | It should be noted that @code{cond-expand} is separate from the |
155 | @code{*features*} mechanism (@pxref{Feature Tracking}), feature | |
156 | symbols in one are unrelated to those in the other. | |
a0e07ba4 NJ |
157 | |
158 | ||
159 | @node SRFI-1 | |
3229f68b | 160 | @subsection SRFI-1 - List library |
8742c48b | 161 | @cindex SRFI-1 |
7c2e18cd | 162 | @cindex list |
a0e07ba4 NJ |
163 | |
164 | @c FIXME::martin: Review me! | |
165 | ||
166 | The list library defined in SRFI-1 contains a lot of useful list | |
167 | processing procedures for construction, examining, destructuring and | |
168 | manipulating lists and pairs. | |
169 | ||
170 | Since SRFI-1 also defines some procedures which are already contained | |
171 | in R5RS and thus are supported by the Guile core library, some list | |
172 | and pair procedures which appear in the SRFI-1 document may not appear | |
173 | in this section. So when looking for a particular list/pair | |
174 | processing procedure, you should also have a look at the sections | |
175 | @ref{Lists} and @ref{Pairs}. | |
176 | ||
177 | @menu | |
178 | * SRFI-1 Constructors:: Constructing new lists. | |
179 | * SRFI-1 Predicates:: Testing list for specific properties. | |
180 | * SRFI-1 Selectors:: Selecting elements from lists. | |
181 | * SRFI-1 Length Append etc:: Length calculation and list appending. | |
182 | * SRFI-1 Fold and Map:: Higher-order list processing. | |
183 | * SRFI-1 Filtering and Partitioning:: Filter lists based on predicates. | |
85a9b4ed | 184 | * SRFI-1 Searching:: Search for elements. |
a0e07ba4 NJ |
185 | * SRFI-1 Deleting:: Delete elements from lists. |
186 | * SRFI-1 Association Lists:: Handle association lists. | |
187 | * SRFI-1 Set Operations:: Use lists for representing sets. | |
188 | @end menu | |
189 | ||
190 | @node SRFI-1 Constructors | |
3229f68b | 191 | @subsubsection Constructors |
7c2e18cd | 192 | @cindex list constructor |
a0e07ba4 NJ |
193 | |
194 | @c FIXME::martin: Review me! | |
195 | ||
196 | New lists can be constructed by calling one of the following | |
197 | procedures. | |
198 | ||
8f85c0c6 | 199 | @deffn {Scheme Procedure} xcons d a |
a0e07ba4 NJ |
200 | Like @code{cons}, but with interchanged arguments. Useful mostly when |
201 | passed to higher-order procedures. | |
202 | @end deffn | |
203 | ||
8f85c0c6 | 204 | @deffn {Scheme Procedure} list-tabulate n init-proc |
a0e07ba4 NJ |
205 | Return an @var{n}-element list, where each list element is produced by |
206 | applying the procedure @var{init-proc} to the corresponding list | |
207 | index. The order in which @var{init-proc} is applied to the indices | |
208 | is not specified. | |
209 | @end deffn | |
210 | ||
57066448 KR |
211 | @deffn {Scheme Procedure} list-copy lst |
212 | Return a new list containing the elements of the list @var{lst}. | |
213 | ||
214 | This function differs from the core @code{list-copy} (@pxref{List | |
215 | Constructors}) in accepting improper lists too. And if @var{lst} is | |
216 | not a pair at all then it's treated as the final tail of an improper | |
217 | list and simply returned. | |
218 | @end deffn | |
219 | ||
8f85c0c6 | 220 | @deffn {Scheme Procedure} circular-list elt1 elt2 @dots{} |
a0e07ba4 NJ |
221 | Return a circular list containing the given arguments @var{elt1} |
222 | @var{elt2} @dots{}. | |
223 | @end deffn | |
224 | ||
8f85c0c6 | 225 | @deffn {Scheme Procedure} iota count [start step] |
256853db KR |
226 | Return a list containing @var{count} numbers, starting from |
227 | @var{start} and adding @var{step} each time. The default @var{start} | |
228 | is 0, the default @var{step} is 1. For example, | |
a0e07ba4 | 229 | |
256853db KR |
230 | @example |
231 | (iota 6) @result{} (0 1 2 3 4 5) | |
232 | (iota 4 2.5 -2) @result{} (2.5 0.5 -1.5 -3.5) | |
233 | @end example | |
a0e07ba4 | 234 | |
256853db KR |
235 | This function takes its name from the corresponding primitive in the |
236 | APL language. | |
a0e07ba4 NJ |
237 | @end deffn |
238 | ||
239 | ||
240 | @node SRFI-1 Predicates | |
3229f68b | 241 | @subsubsection Predicates |
7c2e18cd | 242 | @cindex list predicate |
a0e07ba4 NJ |
243 | |
244 | @c FIXME::martin: Review me! | |
245 | ||
246 | The procedures in this section test specific properties of lists. | |
247 | ||
8f85c0c6 | 248 | @deffn {Scheme Procedure} proper-list? obj |
f18f87aa KR |
249 | Return @code{#t} if @var{obj} is a proper list, or @code{#f} |
250 | otherwise. This is the same as the core @code{list?} (@pxref{List | |
251 | Predicates}). | |
252 | ||
253 | A proper list is a list which ends with the empty list @code{()} in | |
254 | the usual way. The empty list @code{()} itself is a proper list too. | |
255 | ||
256 | @example | |
257 | (proper-list? '(1 2 3)) @result{} #t | |
258 | (proper-list? '()) @result{} #t | |
259 | @end example | |
a0e07ba4 NJ |
260 | @end deffn |
261 | ||
8f85c0c6 | 262 | @deffn {Scheme Procedure} circular-list? obj |
f18f87aa KR |
263 | Return @code{#t} if @var{obj} is a circular list, or @code{#f} |
264 | otherwise. | |
265 | ||
266 | A circular list is a list where at some point the @code{cdr} refers | |
267 | back to a previous pair in the list (either the start or some later | |
268 | point), so that following the @code{cdr}s takes you around in a | |
269 | circle, with no end. | |
270 | ||
271 | @example | |
272 | (define x (list 1 2 3 4)) | |
273 | (set-cdr! (last-pair x) (cddr x)) | |
274 | x @result{} (1 2 3 4 3 4 3 4 ...) | |
275 | (circular-list? x) @result{} #t | |
276 | @end example | |
a0e07ba4 NJ |
277 | @end deffn |
278 | ||
8f85c0c6 | 279 | @deffn {Scheme Procedure} dotted-list? obj |
f18f87aa KR |
280 | Return @code{#t} if @var{obj} is a dotted list, or @code{#f} |
281 | otherwise. | |
282 | ||
283 | A dotted list is a list where the @code{cdr} of the last pair is not | |
284 | the empty list @code{()}. Any non-pair @var{obj} is also considered a | |
285 | dotted list, with length zero. | |
286 | ||
287 | @example | |
288 | (dotted-list? '(1 2 . 3)) @result{} #t | |
289 | (dotted-list? 99) @result{} #t | |
290 | @end example | |
a0e07ba4 NJ |
291 | @end deffn |
292 | ||
f18f87aa KR |
293 | It will be noted that any Scheme object passes exactly one of the |
294 | above three tests @code{proper-list?}, @code{circular-list?} and | |
295 | @code{dotted-list?}. Non-lists are @code{dotted-list?}, finite lists | |
296 | are either @code{proper-list?} or @code{dotted-list?}, and infinite | |
297 | lists are @code{circular-list?}. | |
298 | ||
299 | @sp 1 | |
8f85c0c6 | 300 | @deffn {Scheme Procedure} null-list? lst |
a0e07ba4 NJ |
301 | Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f} |
302 | otherwise. If something else than a proper or circular list is passed | |
85a9b4ed | 303 | as @var{lst}, an error is signalled. This procedure is recommended |
a0e07ba4 NJ |
304 | for checking for the end of a list in contexts where dotted lists are |
305 | not allowed. | |
306 | @end deffn | |
307 | ||
8f85c0c6 | 308 | @deffn {Scheme Procedure} not-pair? obj |
a0e07ba4 NJ |
309 | Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise. |
310 | This is shorthand notation @code{(not (pair? @var{obj}))} and is | |
311 | supposed to be used for end-of-list checking in contexts where dotted | |
312 | lists are allowed. | |
313 | @end deffn | |
314 | ||
8f85c0c6 | 315 | @deffn {Scheme Procedure} list= elt= list1 @dots{} |
a0e07ba4 NJ |
316 | Return @code{#t} if all argument lists are equal, @code{#f} otherwise. |
317 | List equality is determined by testing whether all lists have the same | |
318 | length and the corresponding elements are equal in the sense of the | |
319 | equality predicate @var{elt=}. If no or only one list is given, | |
320 | @code{#t} is returned. | |
321 | @end deffn | |
322 | ||
323 | ||
324 | @node SRFI-1 Selectors | |
3229f68b | 325 | @subsubsection Selectors |
7c2e18cd | 326 | @cindex list selector |
a0e07ba4 NJ |
327 | |
328 | @c FIXME::martin: Review me! | |
329 | ||
8f85c0c6 NJ |
330 | @deffn {Scheme Procedure} first pair |
331 | @deffnx {Scheme Procedure} second pair | |
332 | @deffnx {Scheme Procedure} third pair | |
333 | @deffnx {Scheme Procedure} fourth pair | |
334 | @deffnx {Scheme Procedure} fifth pair | |
335 | @deffnx {Scheme Procedure} sixth pair | |
336 | @deffnx {Scheme Procedure} seventh pair | |
337 | @deffnx {Scheme Procedure} eighth pair | |
338 | @deffnx {Scheme Procedure} ninth pair | |
339 | @deffnx {Scheme Procedure} tenth pair | |
a0e07ba4 NJ |
340 | These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}. |
341 | @end deffn | |
342 | ||
8f85c0c6 | 343 | @deffn {Scheme Procedure} car+cdr pair |
a0e07ba4 NJ |
344 | Return two values, the @sc{car} and the @sc{cdr} of @var{pair}. |
345 | @end deffn | |
346 | ||
8f85c0c6 NJ |
347 | @deffn {Scheme Procedure} take lst i |
348 | @deffnx {Scheme Procedure} take! lst i | |
a0e07ba4 NJ |
349 | Return a list containing the first @var{i} elements of @var{lst}. |
350 | ||
351 | @code{take!} may modify the structure of the argument list @var{lst} | |
352 | in order to produce the result. | |
353 | @end deffn | |
354 | ||
8f85c0c6 | 355 | @deffn {Scheme Procedure} drop lst i |
a0e07ba4 NJ |
356 | Return a list containing all but the first @var{i} elements of |
357 | @var{lst}. | |
358 | @end deffn | |
359 | ||
8f85c0c6 | 360 | @deffn {Scheme Procedure} take-right lst i |
a0e07ba4 NJ |
361 | Return the a list containing the @var{i} last elements of @var{lst}. |
362 | @end deffn | |
363 | ||
8f85c0c6 NJ |
364 | @deffn {Scheme Procedure} drop-right lst i |
365 | @deffnx {Scheme Procedure} drop-right! lst i | |
a0e07ba4 NJ |
366 | Return the a list containing all but the @var{i} last elements of |
367 | @var{lst}. | |
368 | ||
369 | @code{drop-right!} may modify the structure of the argument list | |
370 | @var{lst} in order to produce the result. | |
371 | @end deffn | |
372 | ||
8f85c0c6 NJ |
373 | @deffn {Scheme Procedure} split-at lst i |
374 | @deffnx {Scheme Procedure} split-at! lst i | |
a0e07ba4 NJ |
375 | Return two values, a list containing the first @var{i} elements of the |
376 | list @var{lst} and a list containing the remaining elements. | |
377 | ||
378 | @code{split-at!} may modify the structure of the argument list | |
379 | @var{lst} in order to produce the result. | |
380 | @end deffn | |
381 | ||
8f85c0c6 | 382 | @deffn {Scheme Procedure} last lst |
a0e07ba4 NJ |
383 | Return the last element of the non-empty, finite list @var{lst}. |
384 | @end deffn | |
385 | ||
386 | ||
387 | @node SRFI-1 Length Append etc | |
3229f68b | 388 | @subsubsection Length, Append, Concatenate, etc. |
a0e07ba4 NJ |
389 | |
390 | @c FIXME::martin: Review me! | |
391 | ||
8f85c0c6 | 392 | @deffn {Scheme Procedure} length+ lst |
a0e07ba4 NJ |
393 | Return the length of the argument list @var{lst}. When @var{lst} is a |
394 | circular list, @code{#f} is returned. | |
395 | @end deffn | |
396 | ||
8f85c0c6 NJ |
397 | @deffn {Scheme Procedure} concatenate list-of-lists |
398 | @deffnx {Scheme Procedure} concatenate! list-of-lists | |
a0e07ba4 NJ |
399 | Construct a list by appending all lists in @var{list-of-lists}. |
400 | ||
401 | @code{concatenate!} may modify the structure of the given lists in | |
402 | order to produce the result. | |
a3e856f2 KR |
403 | |
404 | @code{concatenate} is the same as @code{(apply append | |
405 | @var{list-of-lists})}. It exists because some Scheme implementations | |
406 | have a limit on the number of arguments a function takes, which the | |
407 | @code{apply} might exceed. In Guile there is no such limit. | |
a0e07ba4 NJ |
408 | @end deffn |
409 | ||
8f85c0c6 NJ |
410 | @deffn {Scheme Procedure} append-reverse rev-head tail |
411 | @deffnx {Scheme Procedure} append-reverse! rev-head tail | |
a0e07ba4 NJ |
412 | Reverse @var{rev-head}, append @var{tail} and return the result. This |
413 | is equivalent to @code{(append (reverse @var{rev-head}) @var{tail})}, | |
414 | but more efficient. | |
415 | ||
416 | @code{append-reverse!} may modify @var{rev-head} in order to produce | |
417 | the result. | |
418 | @end deffn | |
419 | ||
8f85c0c6 | 420 | @deffn {Scheme Procedure} zip lst1 lst2 @dots{} |
a0e07ba4 NJ |
421 | Return a list as long as the shortest of the argument lists, where |
422 | each element is a list. The first list contains the first elements of | |
423 | the argument lists, the second list contains the second elements, and | |
424 | so on. | |
425 | @end deffn | |
426 | ||
8f85c0c6 NJ |
427 | @deffn {Scheme Procedure} unzip1 lst |
428 | @deffnx {Scheme Procedure} unzip2 lst | |
429 | @deffnx {Scheme Procedure} unzip3 lst | |
430 | @deffnx {Scheme Procedure} unzip4 lst | |
431 | @deffnx {Scheme Procedure} unzip5 lst | |
a0e07ba4 NJ |
432 | @code{unzip1} takes a list of lists, and returns a list containing the |
433 | first elements of each list, @code{unzip2} returns two lists, the | |
434 | first containing the first elements of each lists and the second | |
435 | containing the second elements of each lists, and so on. | |
436 | @end deffn | |
437 | ||
e508c863 KR |
438 | @deffn {Scheme Procedure} count pred lst1 @dots{} lstN |
439 | Return a count of the number of times @var{pred} returns true when | |
440 | called on elements from the given lists. | |
441 | ||
442 | @var{pred} is called with @var{N} parameters @code{(@var{pred} | |
443 | @var{elem1} @dots{} @var{elemN})}, each element being from the | |
444 | corresponding @var{lst1} @dots{} @var{lstN}. The first call is with | |
445 | the first element of each list, the second with the second element | |
446 | from each, and so on. | |
447 | ||
448 | Counting stops when the end of the shortest list is reached. At least | |
449 | one list must be non-circular. | |
450 | @end deffn | |
451 | ||
a0e07ba4 NJ |
452 | |
453 | @node SRFI-1 Fold and Map | |
3229f68b | 454 | @subsubsection Fold, Unfold & Map |
7c2e18cd KR |
455 | @cindex list fold |
456 | @cindex list map | |
a0e07ba4 NJ |
457 | |
458 | @c FIXME::martin: Review me! | |
459 | ||
1e181a08 KR |
460 | @deffn {Scheme Procedure} fold proc init lst1 @dots{} lstN |
461 | @deffnx {Scheme Procedure} fold-right proc init lst1 @dots{} lstN | |
462 | Apply @var{proc} to the elements of @var{lst1} @dots{} @var{lstN} to | |
463 | build a result, and return that result. | |
a0e07ba4 | 464 | |
1e181a08 KR |
465 | Each @var{proc} call is @code{(@var{proc} @var{elem1} @dots{} |
466 | @var{elemN} @var{previous})}, where @var{elem1} is from @var{lst1}, | |
467 | through @var{elemN} from @var{lstN}. @var{previous} is the return | |
468 | from the previous call to @var{proc}, or the given @var{init} for the | |
469 | first call. If any list is empty, just @var{init} is returned. | |
a0e07ba4 | 470 | |
1e181a08 KR |
471 | @code{fold} works through the list elements from first to last. The |
472 | following shows a list reversal and the calls it makes, | |
a0e07ba4 | 473 | |
1e181a08 KR |
474 | @example |
475 | (fold cons '() '(1 2 3)) | |
a0e07ba4 | 476 | |
1e181a08 KR |
477 | (cons 1 '()) |
478 | (cons 2 '(1)) | |
479 | (cons 3 '(2 1) | |
480 | @result{} (3 2 1) | |
481 | @end example | |
a0e07ba4 | 482 | |
1e181a08 KR |
483 | @code{fold-right} works through the list elements from last to first, |
484 | ie.@: from the right. So for example the following finds the longest | |
485 | string, and the last among equal longest, | |
486 | ||
487 | @example | |
488 | (fold-right (lambda (str prev) | |
489 | (if (> (string-length str) (string-length prev)) | |
490 | str | |
491 | prev)) | |
492 | "" | |
493 | '("x" "abc" "xyz" "jk")) | |
494 | @result{} "xyz" | |
495 | @end example | |
a0e07ba4 | 496 | |
1e181a08 KR |
497 | If @var{lst1} through @var{lstN} have different lengths, @code{fold} |
498 | stops when the end of the shortest is reached; @code{fold-right} | |
499 | commences at the last element of the shortest. Ie.@: elements past | |
500 | the length of the shortest are ignored in the other @var{lst}s. At | |
501 | least one @var{lst} must be non-circular. | |
502 | ||
503 | @code{fold} should be preferred over @code{fold-right} if the order of | |
504 | processing doesn't matter, or can be arranged either way, since | |
505 | @code{fold} is a little more efficient. | |
506 | ||
507 | The way @code{fold} builds a result from iterating is quite general, | |
508 | it can do more than other iterations like say @code{map} or | |
509 | @code{filter}. The following for example removes adjacent duplicate | |
510 | elements from a list, | |
511 | ||
512 | @example | |
513 | (define (delete-adjacent-duplicates lst) | |
514 | (fold-right (lambda (elem ret) | |
515 | (if (equal? elem (first ret)) | |
516 | ret | |
517 | (cons elem ret))) | |
518 | (list (last lst)) | |
519 | lst)) | |
520 | (delete-adjacent-duplicates '(1 2 3 3 4 4 4 5)) | |
521 | @result{} (1 2 3 4 5) | |
522 | @end example | |
523 | ||
524 | Clearly the same sort of thing can be done with a @code{for-each} and | |
525 | a variable in which build the result, but a self-contained @var{proc} | |
526 | can be re-used in multiple contexts, where a @code{for-each} would | |
527 | have to be written out each time. | |
a0e07ba4 NJ |
528 | @end deffn |
529 | ||
1e181a08 KR |
530 | @deffn {Scheme Procedure} pair-fold proc init lst1 @dots{} lstN |
531 | @deffnx {Scheme Procedure} pair-fold-right proc init lst1 @dots{} lstN | |
532 | The same as @code{fold} and @code{fold-right}, but apply @var{proc} to | |
533 | the pairs of the lists instead of the list elements. | |
a0e07ba4 NJ |
534 | @end deffn |
535 | ||
1e181a08 KR |
536 | @deffn {Scheme Procedure} reduce proc identity lst |
537 | @deffnx {Scheme Procedure} reduce-right proc identity lst | |
538 | @code{reduce} is a variant of @code{fold} (see above), designed for | |
539 | cases where the initial value is an ``identity'', so that @var{proc} | |
540 | can start directly from the first element of @var{lst}. | |
541 | ||
542 | Consider folding with @code{+} and initial value 0, calls would be for | |
543 | instance | |
544 | ||
545 | @example | |
546 | (fold + 0 '(4 5 6)) | |
547 | @result{} | |
548 | (+ 4 0) | |
549 | (+ 5 4) | |
550 | (+ 6 9) | |
551 | @end example | |
552 | ||
553 | The first call @code{(+ 4 0)} is unnecessary, adding 0 to 4 doesn't | |
554 | change that value. The first element @code{4} may as well be the | |
555 | initial ``previous'' value argument to @var{proc}. This is what | |
556 | @code{reduce} does. | |
557 | ||
558 | @example | |
559 | (reduce + 0 '(4 5 6)) | |
560 | @result{} | |
561 | (+ 5 4) | |
562 | (+ 6 9) | |
563 | @end example | |
564 | ||
565 | The @var{identity} parameter is the return when @var{lst} is empty, | |
566 | that's the only time @var{identity} is used. If @var{lst} has just | |
567 | one element, that's the return with no calls to @var{proc}. | |
568 | ||
569 | @code{reduce-right} is a similar variation on @code{fold-right}, | |
570 | working from the end (ie.@: the right) of @var{lst}. Calls in this | |
571 | case become | |
572 | ||
573 | @example | |
574 | (reduce-right + 0 '(4 5 6)) | |
575 | @result{} | |
576 | (+ 5 6) | |
577 | (+ 4 11) | |
578 | @end example | |
579 | ||
580 | @code{reduce} should be preferred over @code{reduce-right} if the | |
581 | order of processing doesn't matter, or can be arranged either way, | |
582 | since @code{reduce} is a little more efficient. | |
583 | ||
584 | In the above examples of course @code{+} takes any number of | |
585 | arguments, so it can be used on a list just with @code{apply}. An | |
586 | example where that's not the case would be SRFI-19 @code{add-duration} | |
587 | (@pxref{SRFI-19 Time}) on a list of durations, | |
588 | ||
589 | @example | |
590 | (use-modules (srfi srfi-19)) | |
591 | (reduce add-duration | |
592 | (make-time time-duration 0 0) | |
593 | (list (make-time time-duration 0 4) | |
594 | (make-time time-duration 0 5) | |
595 | (make-time time-duration 0 6))) | |
596 | @result{} #<time duration 15 seconds> | |
597 | @end example | |
a0e07ba4 NJ |
598 | @end deffn |
599 | ||
8f85c0c6 | 600 | @deffn {Scheme Procedure} unfold p f g seed [tail-gen] |
a0e07ba4 NJ |
601 | @code{unfold} is defined as follows: |
602 | ||
603 | @lisp | |
604 | (unfold p f g seed) = | |
605 | (if (p seed) (tail-gen seed) | |
606 | (cons (f seed) | |
607 | (unfold p f g (g seed)))) | |
608 | @end lisp | |
609 | ||
610 | @table @var | |
611 | @item p | |
612 | Determines when to stop unfolding. | |
613 | ||
614 | @item f | |
615 | Maps each seed value to the corresponding list element. | |
616 | ||
617 | @item g | |
618 | Maps each seed value to next seed valu. | |
619 | ||
620 | @item seed | |
621 | The state value for the unfold. | |
622 | ||
623 | @item tail-gen | |
624 | Creates the tail of the list; defaults to @code{(lambda (x) '())}. | |
625 | @end table | |
626 | ||
627 | @var{g} produces a series of seed values, which are mapped to list | |
628 | elements by @var{f}. These elements are put into a list in | |
629 | left-to-right order, and @var{p} tells when to stop unfolding. | |
630 | @end deffn | |
631 | ||
8f85c0c6 | 632 | @deffn {Scheme Procedure} unfold-right p f g seed [tail] |
a0e07ba4 NJ |
633 | Construct a list with the following loop. |
634 | ||
635 | @lisp | |
636 | (let lp ((seed seed) (lis tail)) | |
637 | (if (p seed) lis | |
638 | (lp (g seed) | |
639 | (cons (f seed) lis)))) | |
640 | @end lisp | |
641 | ||
642 | @table @var | |
643 | @item p | |
644 | Determines when to stop unfolding. | |
645 | ||
646 | @item f | |
647 | Maps each seed value to the corresponding list element. | |
648 | ||
649 | @item g | |
650 | Maps each seed value to next seed valu. | |
651 | ||
652 | @item seed | |
653 | The state value for the unfold. | |
654 | ||
655 | @item tail-gen | |
656 | Creates the tail of the list; defaults to @code{(lambda (x) '())}. | |
657 | @end table | |
658 | ||
659 | @end deffn | |
660 | ||
8f85c0c6 | 661 | @deffn {Scheme Procedure} map f lst1 lst2 @dots{} |
a0e07ba4 NJ |
662 | Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and |
663 | return a list containing the results of the procedure applications. | |
664 | This procedure is extended with respect to R5RS, because the argument | |
665 | lists may have different lengths. The result list will have the same | |
666 | length as the shortest argument lists. The order in which @var{f} | |
667 | will be applied to the list element(s) is not specified. | |
668 | @end deffn | |
669 | ||
8f85c0c6 | 670 | @deffn {Scheme Procedure} for-each f lst1 lst2 @dots{} |
a0e07ba4 NJ |
671 | Apply the procedure @var{f} to each pair of corresponding elements of |
672 | the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not | |
673 | specified. This procedure is extended with respect to R5RS, because | |
674 | the argument lists may have different lengths. The shortest argument | |
675 | list determines the number of times @var{f} is called. @var{f} will | |
85a9b4ed | 676 | be applied to the list elements in left-to-right order. |
a0e07ba4 NJ |
677 | |
678 | @end deffn | |
679 | ||
8f85c0c6 NJ |
680 | @deffn {Scheme Procedure} append-map f lst1 lst2 @dots{} |
681 | @deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{} | |
12991fed | 682 | Equivalent to |
a0e07ba4 NJ |
683 | |
684 | @lisp | |
12991fed | 685 | (apply append (map f clist1 clist2 ...)) |
a0e07ba4 NJ |
686 | @end lisp |
687 | ||
12991fed | 688 | and |
a0e07ba4 NJ |
689 | |
690 | @lisp | |
12991fed | 691 | (apply append! (map f clist1 clist2 ...)) |
a0e07ba4 NJ |
692 | @end lisp |
693 | ||
694 | Map @var{f} over the elements of the lists, just as in the @code{map} | |
695 | function. However, the results of the applications are appended | |
696 | together to make the final result. @code{append-map} uses | |
697 | @code{append} to append the results together; @code{append-map!} uses | |
698 | @code{append!}. | |
699 | ||
700 | The dynamic order in which the various applications of @var{f} are | |
701 | made is not specified. | |
702 | @end deffn | |
703 | ||
8f85c0c6 | 704 | @deffn {Scheme Procedure} map! f lst1 lst2 @dots{} |
a0e07ba4 NJ |
705 | Linear-update variant of @code{map} -- @code{map!} is allowed, but not |
706 | required, to alter the cons cells of @var{lst1} to construct the | |
707 | result list. | |
708 | ||
709 | The dynamic order in which the various applications of @var{f} are | |
710 | made is not specified. In the n-ary case, @var{lst2}, @var{lst3}, | |
711 | @dots{} must have at least as many elements as @var{lst1}. | |
712 | @end deffn | |
713 | ||
8f85c0c6 | 714 | @deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{} |
a0e07ba4 NJ |
715 | Like @code{for-each}, but applies the procedure @var{f} to the pairs |
716 | from which the argument lists are constructed, instead of the list | |
717 | elements. The return value is not specified. | |
718 | @end deffn | |
719 | ||
8f85c0c6 | 720 | @deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{} |
a0e07ba4 NJ |
721 | Like @code{map}, but only results from the applications of @var{f} |
722 | which are true are saved in the result list. | |
723 | @end deffn | |
724 | ||
725 | ||
726 | @node SRFI-1 Filtering and Partitioning | |
3229f68b | 727 | @subsubsection Filtering and Partitioning |
7c2e18cd KR |
728 | @cindex list filter |
729 | @cindex list partition | |
a0e07ba4 NJ |
730 | |
731 | @c FIXME::martin: Review me! | |
732 | ||
733 | Filtering means to collect all elements from a list which satisfy a | |
734 | specific condition. Partitioning a list means to make two groups of | |
735 | list elements, one which contains the elements satisfying a condition, | |
736 | and the other for the elements which don't. | |
737 | ||
60e25dc4 KR |
738 | The @code{filter} and @code{filter!} functions are implemented in the |
739 | Guile core, @xref{List Modification}. | |
a0e07ba4 | 740 | |
8f85c0c6 NJ |
741 | @deffn {Scheme Procedure} partition pred lst |
742 | @deffnx {Scheme Procedure} partition! pred lst | |
193239f1 KR |
743 | Split @var{lst} into those elements which do and don't satisfy the |
744 | predicate @var{pred}. | |
a0e07ba4 | 745 | |
193239f1 KR |
746 | The return is two values (@pxref{Multiple Values}), the first being a |
747 | list of all elements from @var{lst} which satisfy @var{pred}, the | |
748 | second a list of those which do not. | |
749 | ||
750 | The elements in the result lists are in the same order as in @var{lst} | |
751 | but the order in which the calls @code{(@var{pred} elem)} are made on | |
752 | the list elements is unspecified. | |
753 | ||
754 | @code{partition} does not change @var{lst}, but one of the returned | |
755 | lists may share a tail with it. @code{partition!} may modify | |
756 | @var{lst} to construct its return. | |
a0e07ba4 NJ |
757 | @end deffn |
758 | ||
8f85c0c6 NJ |
759 | @deffn {Scheme Procedure} remove pred lst |
760 | @deffnx {Scheme Procedure} remove! pred lst | |
a0e07ba4 NJ |
761 | Return a list containing all elements from @var{lst} which do not |
762 | satisfy the predicate @var{pred}. The elements in the result list | |
763 | have the same order as in @var{lst}. The order in which @var{pred} is | |
764 | applied to the list elements is not specified. | |
765 | ||
766 | @code{remove!} is allowed, but not required to modify the structure of | |
767 | the input list. | |
768 | @end deffn | |
769 | ||
770 | ||
771 | @node SRFI-1 Searching | |
3229f68b | 772 | @subsubsection Searching |
7c2e18cd | 773 | @cindex list search |
a0e07ba4 NJ |
774 | |
775 | @c FIXME::martin: Review me! | |
776 | ||
777 | The procedures for searching elements in lists either accept a | |
778 | predicate or a comparison object for determining which elements are to | |
779 | be searched. | |
780 | ||
8f85c0c6 | 781 | @deffn {Scheme Procedure} find pred lst |
a0e07ba4 NJ |
782 | Return the first element of @var{lst} which satisfies the predicate |
783 | @var{pred} and @code{#f} if no such element is found. | |
784 | @end deffn | |
785 | ||
8f85c0c6 | 786 | @deffn {Scheme Procedure} find-tail pred lst |
a0e07ba4 NJ |
787 | Return the first pair of @var{lst} whose @sc{car} satisfies the |
788 | predicate @var{pred} and @code{#f} if no such element is found. | |
789 | @end deffn | |
790 | ||
8f85c0c6 NJ |
791 | @deffn {Scheme Procedure} take-while pred lst |
792 | @deffnx {Scheme Procedure} take-while! pred lst | |
a0e07ba4 NJ |
793 | Return the longest initial prefix of @var{lst} whose elements all |
794 | satisfy the predicate @var{pred}. | |
795 | ||
796 | @code{take-while!} is allowed, but not required to modify the input | |
797 | list while producing the result. | |
798 | @end deffn | |
799 | ||
8f85c0c6 | 800 | @deffn {Scheme Procedure} drop-while pred lst |
a0e07ba4 NJ |
801 | Drop the longest initial prefix of @var{lst} whose elements all |
802 | satisfy the predicate @var{pred}. | |
803 | @end deffn | |
804 | ||
8f85c0c6 NJ |
805 | @deffn {Scheme Procedure} span pred lst |
806 | @deffnx {Scheme Procedure} span! pred lst | |
807 | @deffnx {Scheme Procedure} break pred lst | |
808 | @deffnx {Scheme Procedure} break! pred lst | |
a0e07ba4 NJ |
809 | @code{span} splits the list @var{lst} into the longest initial prefix |
810 | whose elements all satisfy the predicate @var{pred}, and the remaining | |
811 | tail. @code{break} inverts the sense of the predicate. | |
812 | ||
813 | @code{span!} and @code{break!} are allowed, but not required to modify | |
814 | the structure of the input list @var{lst} in order to produce the | |
815 | result. | |
3e73b6f9 KR |
816 | |
817 | Note that the name @code{break} conflicts with the @code{break} | |
818 | binding established by @code{while} (@pxref{while do}). Applications | |
819 | wanting to use @code{break} from within a @code{while} loop will need | |
820 | to make a new define under a different name. | |
a0e07ba4 NJ |
821 | @end deffn |
822 | ||
62705beb KR |
823 | @deffn {Scheme Procedure} any pred lst1 lst2 @dots{} lstN |
824 | Test whether any set of elements from @var{lst1} @dots{} lstN | |
825 | satisfies @var{pred}. If so the return value is the return from the | |
826 | successful @var{pred} call, or if not the return is @code{#f}. | |
827 | ||
828 | Each @var{pred} call is @code{(@var{pred} @var{elem1} @dots{} | |
829 | @var{elemN})} taking an element from each @var{lst}. The calls are | |
830 | made successively for the first, second, etc elements of the lists, | |
831 | stopping when @var{pred} returns non-@code{#f}, or when the end of the | |
832 | shortest list is reached. | |
833 | ||
834 | The @var{pred} call on the last set of elements (ie.@: when the end of | |
835 | the shortest list has been reached), if that point is reached, is a | |
836 | tail call. | |
837 | @end deffn | |
838 | ||
839 | @deffn {Scheme Procedure} every pred lst1 lst2 @dots{} lstN | |
840 | Test whether every set of elements from @var{lst1} @dots{} lstN | |
841 | satisfies @var{pred}. If so the return value is the return from the | |
842 | final @var{pred} call, or if not the return is @code{#f}. | |
843 | ||
844 | Each @var{pred} call is @code{(@var{pred} @var{elem1} @dots{} | |
845 | @var{elemN})} taking an element from each @var{lst}. The calls are | |
846 | made successively for the first, second, etc elements of the lists, | |
847 | stopping if @var{pred} returns @code{#f}, or when the end of any of | |
848 | the lists is reached. | |
849 | ||
850 | The @var{pred} call on the last set of elements (ie.@: when the end of | |
851 | the shortest list has been reached) is a tail call. | |
852 | ||
853 | If one of @var{lst1} @dots{} @var{lstN} is empty then no calls to | |
854 | @var{pred} are made, and the return is @code{#t}. | |
a0e07ba4 NJ |
855 | @end deffn |
856 | ||
0166e7f2 | 857 | @deffn {Scheme Procedure} list-index pred lst1 @dots{} lstN |
d1736abf KR |
858 | Return the index of the first set of elements, one from each of |
859 | @var{lst1}@dots{}@var{lstN}, which satisfies @var{pred}. | |
860 | ||
861 | @var{pred} is called as @code{(@var{pred} elem1 @dots{} elemN)}. | |
862 | Searching stops when the end of the shortest @var{lst} is reached. | |
863 | The return index starts from 0 for the first set of elements. If no | |
864 | set of elements pass then the return is @code{#f}. | |
0166e7f2 KR |
865 | |
866 | @example | |
867 | (list-index odd? '(2 4 6 9)) @result{} 3 | |
868 | (list-index = '(1 2 3) '(3 1 2)) @result{} #f | |
869 | @end example | |
a0e07ba4 NJ |
870 | @end deffn |
871 | ||
8f85c0c6 | 872 | @deffn {Scheme Procedure} member x lst [=] |
a0e07ba4 | 873 | Return the first sublist of @var{lst} whose @sc{car} is equal to |
ca04a5ae | 874 | @var{x}. If @var{x} does not appear in @var{lst}, return @code{#f}. |
ea6ea01b | 875 | |
ca04a5ae KR |
876 | Equality is determined by @code{equal?}, or by the equality predicate |
877 | @var{=} if given. @var{=} is called @code{(= @var{x} elem)}, | |
878 | ie.@: with the given @var{x} first, so for example to find the first | |
879 | element greater than 5, | |
880 | ||
881 | @example | |
882 | (member 5 '(3 5 1 7 2 9) <) @result{} (7 2 9) | |
883 | @end example | |
884 | ||
885 | This version of @code{member} extends the core @code{member} | |
886 | (@pxref{List Searching}) by accepting an equality predicate. | |
a0e07ba4 NJ |
887 | @end deffn |
888 | ||
889 | ||
890 | @node SRFI-1 Deleting | |
3229f68b | 891 | @subsubsection Deleting |
7c2e18cd | 892 | @cindex list delete |
a0e07ba4 NJ |
893 | |
894 | @c FIXME::martin: Review me! | |
895 | ||
8f85c0c6 NJ |
896 | @deffn {Scheme Procedure} delete x lst [=] |
897 | @deffnx {Scheme Procedure} delete! x lst [=] | |
b6b9376a KR |
898 | Return a list containing the elements of @var{lst} but with those |
899 | equal to @var{x} deleted. The returned elements will be in the same | |
900 | order as they were in @var{lst}. | |
901 | ||
902 | Equality is determined by the @var{=} predicate, or @code{equal?} if | |
903 | not given. An equality call is made just once for each element, but | |
904 | the order in which the calls are made on the elements is unspecified. | |
a0e07ba4 | 905 | |
243bdb63 | 906 | The equality calls are always @code{(= x elem)}, ie.@: the given @var{x} |
b6b9376a KR |
907 | is first. This means for instance elements greater than 5 can be |
908 | deleted with @code{(delete 5 lst <)}. | |
909 | ||
910 | @code{delete} does not modify @var{lst}, but the return might share a | |
911 | common tail with @var{lst}. @code{delete!} may modify the structure | |
912 | of @var{lst} to construct its return. | |
ea6ea01b KR |
913 | |
914 | These functions extend the core @code{delete} and @code{delete!} in | |
915 | accepting an equality predicate. (@pxref{List Modification}) | |
a0e07ba4 NJ |
916 | @end deffn |
917 | ||
8f85c0c6 NJ |
918 | @deffn {Scheme Procedure} delete-duplicates lst [=] |
919 | @deffnx {Scheme Procedure} delete-duplicates! lst [=] | |
b6b9376a KR |
920 | Return a list containing the elements of @var{lst} but without |
921 | duplicates. | |
922 | ||
923 | When elements are equal, only the first in @var{lst} is retained. | |
924 | Equal elements can be anywhere in @var{lst}, they don't have to be | |
925 | adjacent. The returned list will have the retained elements in the | |
926 | same order as they were in @var{lst}. | |
927 | ||
928 | Equality is determined by the @var{=} predicate, or @code{equal?} if | |
929 | not given. Calls @code{(= x y)} are made with element @var{x} being | |
930 | before @var{y} in @var{lst}. A call is made at most once for each | |
931 | combination, but the sequence of the calls across the elements is | |
932 | unspecified. | |
933 | ||
934 | @code{delete-duplicates} does not modify @var{lst}, but the return | |
935 | might share a common tail with @var{lst}. @code{delete-duplicates!} | |
936 | may modify the structure of @var{lst} to construct its return. | |
937 | ||
938 | In the worst case, this is an @math{O(N^2)} algorithm because it must | |
939 | check each element against all those preceding it. For long lists it | |
940 | is more efficient to sort and then compare only adjacent elements. | |
a0e07ba4 NJ |
941 | @end deffn |
942 | ||
943 | ||
944 | @node SRFI-1 Association Lists | |
3229f68b | 945 | @subsubsection Association Lists |
7c2e18cd KR |
946 | @cindex association list |
947 | @cindex alist | |
a0e07ba4 NJ |
948 | |
949 | @c FIXME::martin: Review me! | |
950 | ||
951 | Association lists are described in detail in section @ref{Association | |
952 | Lists}. The present section only documents the additional procedures | |
953 | for dealing with association lists defined by SRFI-1. | |
954 | ||
8f85c0c6 | 955 | @deffn {Scheme Procedure} assoc key alist [=] |
a0e07ba4 NJ |
956 | Return the pair from @var{alist} which matches @var{key}. Equality is |
957 | determined by @var{=}, which defaults to @code{equal?} if not given. | |
958 | @var{alist} must be an association lists---a list of pairs. | |
ea6ea01b KR |
959 | |
960 | This function extends the core @code{assoc} by accepting an equality | |
961 | predicate. (@pxref{Association Lists}) | |
a0e07ba4 NJ |
962 | @end deffn |
963 | ||
8f85c0c6 | 964 | @deffn {Scheme Procedure} alist-cons key datum alist |
a0e07ba4 NJ |
965 | Equivalent to |
966 | ||
967 | @lisp | |
968 | (cons (cons @var{key} @var{datum}) @var{alist}) | |
969 | @end lisp | |
970 | ||
971 | This procedure is used to coons a new pair onto an existing | |
972 | association list. | |
973 | @end deffn | |
974 | ||
8f85c0c6 | 975 | @deffn {Scheme Procedure} alist-copy alist |
a0e07ba4 NJ |
976 | Return a newly allocated copy of @var{alist}, that means that the |
977 | spine of the list as well as the pairs are copied. | |
978 | @end deffn | |
979 | ||
8f85c0c6 NJ |
980 | @deffn {Scheme Procedure} alist-delete key alist [=] |
981 | @deffnx {Scheme Procedure} alist-delete! key alist [=] | |
bd35f1f0 KR |
982 | Return a list containing the elements of @var{alist} but with those |
983 | elements whose keys are equal to @var{key} deleted. The returned | |
984 | elements will be in the same order as they were in @var{alist}. | |
a0e07ba4 | 985 | |
bd35f1f0 KR |
986 | Equality is determined by the @var{=} predicate, or @code{equal?} if |
987 | not given. The order in which elements are tested is unspecified, but | |
988 | each equality call is made @code{(= key alistkey)}, ie. the given | |
989 | @var{key} parameter is first and the key from @var{alist} second. | |
990 | This means for instance all associations with a key greater than 5 can | |
991 | be removed with @code{(alist-delete 5 alist <)}. | |
992 | ||
993 | @code{alist-delete} does not modify @var{alist}, but the return might | |
994 | share a common tail with @var{alist}. @code{alist-delete!} may modify | |
995 | the list structure of @var{alist} to construct its return. | |
a0e07ba4 NJ |
996 | @end deffn |
997 | ||
998 | ||
999 | @node SRFI-1 Set Operations | |
3229f68b | 1000 | @subsubsection Set Operations on Lists |
7c2e18cd | 1001 | @cindex list set operation |
a0e07ba4 NJ |
1002 | |
1003 | @c FIXME::martin: Review me! | |
1004 | ||
1005 | Lists can be used for representing sets of objects. The procedures | |
1006 | documented in this section can be used for such set representations. | |
85a9b4ed | 1007 | Man combining several sets or adding elements, they make sure that no |
a0e07ba4 NJ |
1008 | object is contained more than once in a given list. Please note that |
1009 | lists are not a too efficient implementation method for sets, so if | |
1010 | you need high performance, you should think about implementing a | |
1011 | custom data structure for representing sets, such as trees, bitsets, | |
1012 | hash tables or something similar. | |
1013 | ||
1014 | All these procedures accept an equality predicate as the first | |
1015 | argument. This predicate is used for testing the objects in the list | |
1016 | sets for sameness. | |
1017 | ||
8f85c0c6 | 1018 | @deffn {Scheme Procedure} lset<= = list1 @dots{} |
a0e07ba4 NJ |
1019 | Return @code{#t} if every @var{listi} is a subset of @var{listi+1}, |
1020 | otherwise return @code{#f}. Returns @code{#t} if called with less | |
1021 | than two arguments. @var{=} is used for testing element equality. | |
1022 | @end deffn | |
1023 | ||
8f85c0c6 | 1024 | @deffn {Scheme Procedure} lset= = list1 list2 @dots{} |
a0e07ba4 NJ |
1025 | Return @code{#t} if all argument lists are equal. @var{=} is used for |
1026 | testing element equality. | |
1027 | @end deffn | |
1028 | ||
8f85c0c6 | 1029 | @deffn {Scheme Procedure} lset-adjoin = list elt1 @dots{} |
a0e07ba4 | 1030 | Add all @var{elts} to the list @var{list}, suppressing duplicates and |
ac70289c | 1031 | return the resulting list. @var{=} is used for testing |
a0e07ba4 NJ |
1032 | element equality. |
1033 | @end deffn | |
1034 | ||
8f85c0c6 NJ |
1035 | @deffn {Scheme Procedure} lset-union = list1 @dots{} |
1036 | @deffnx {Scheme Procedure} lset-union! = list1 @dots{} | |
a0e07ba4 NJ |
1037 | Return the union of all argument list sets. The union is the set of |
1038 | all elements which appear in any of the argument sets. | |
1039 | @code{lset-union!} is allowed, but not required to modify its first | |
1040 | argument. @var{=} is used for testing element equality. | |
1041 | @end deffn | |
1042 | ||
8f85c0c6 NJ |
1043 | @deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{} |
1044 | @deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{} | |
a0e07ba4 NJ |
1045 | Return the intersection of all argument list sets. The intersection |
1046 | is the set containing all elements which appear in all argument sets. | |
1047 | @code{lset-intersection!} is allowed, but not required to modify its | |
1048 | first argument. @var{=} is used for testing element equality. | |
1049 | @end deffn | |
1050 | ||
8f85c0c6 NJ |
1051 | @deffn {Scheme Procedure} lset-difference = list1 list2 @dots{} |
1052 | @deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{} | |
a0e07ba4 NJ |
1053 | Return the difference of all argument list sets. The difference is |
1054 | the the set containing all elements of the first list which do not | |
1055 | appear in the other lists. @code{lset-difference!} is allowed, but | |
1056 | not required to modify its first argument. @var{=} is used for testing | |
1057 | element equality. | |
1058 | @end deffn | |
1059 | ||
8f85c0c6 NJ |
1060 | @deffn {Scheme Procedure} lset-xor = list1 @dots{} |
1061 | @deffnx {Scheme Procedure} lset-xor! = list1 @dots{} | |
a0e07ba4 NJ |
1062 | Return the set containing all elements which appear in the first |
1063 | argument list set, but not in the second; or, more generally: which | |
1064 | appear in an odd number of sets. @code{lset-xor!} is allowed, but | |
1065 | not required to modify its first argument. @var{=} is used for testing | |
1066 | element equality. | |
1067 | @end deffn | |
1068 | ||
8f85c0c6 NJ |
1069 | @deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{} |
1070 | @deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{} | |
a0e07ba4 NJ |
1071 | Return two values, the difference and the intersection of the argument |
1072 | list sets. This works like a combination of @code{lset-difference} and | |
1073 | @code{lset-intersection}, but is more efficient. | |
1074 | @code{lset-diff+intersection!} is allowed, but not required to modify | |
1075 | its first argument. @var{=} is used for testing element equality. You | |
1076 | have to use some means to deal with the multiple values these | |
1077 | procedures return (@pxref{Multiple Values}). | |
1078 | @end deffn | |
1079 | ||
1080 | ||
1081 | @node SRFI-2 | |
3229f68b | 1082 | @subsection SRFI-2 - and-let* |
8742c48b | 1083 | @cindex SRFI-2 |
a0e07ba4 | 1084 | |
4fd0db14 KR |
1085 | @noindent |
1086 | The following syntax can be obtained with | |
a0e07ba4 | 1087 | |
4fd0db14 KR |
1088 | @lisp |
1089 | (use-modules (srfi srfi-2)) | |
1090 | @end lisp | |
a0e07ba4 | 1091 | |
4fd0db14 KR |
1092 | @deffn {library syntax} and-let* (clause @dots{}) body @dots{} |
1093 | A combination of @code{and} and @code{let*}. | |
1094 | ||
1095 | Each @var{clause} is evaluated in turn, and if @code{#f} is obtained | |
1096 | then evaluation stops and @code{#f} is returned. If all are | |
1097 | non-@code{#f} then @var{body} is evaluated and the last form gives the | |
6b1a6e4c KR |
1098 | return value, or if @var{body} is empty then the result is @code{#t}. |
1099 | Each @var{clause} should be one of the following, | |
4fd0db14 KR |
1100 | |
1101 | @table @code | |
1102 | @item (symbol expr) | |
1103 | Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}. | |
1104 | Like @code{let*}, that binding is available to subsequent clauses. | |
1105 | @item (expr) | |
1106 | Evaluate @var{expr} and check for @code{#f}. | |
1107 | @item symbol | |
1108 | Get the value bound to @var{symbol} and check for @code{#f}. | |
1109 | @end table | |
a0e07ba4 | 1110 | |
4fd0db14 KR |
1111 | Notice that @code{(expr)} has an ``extra'' pair of parentheses, for |
1112 | instance @code{((eq? x y))}. One way to remember this is to imagine | |
1113 | the @code{symbol} in @code{(symbol expr)} is omitted. | |
a0e07ba4 | 1114 | |
4fd0db14 KR |
1115 | @code{and-let*} is good for calculations where a @code{#f} value means |
1116 | termination, but where a non-@code{#f} value is going to be needed in | |
1117 | subsequent expressions. | |
1118 | ||
1119 | The following illustrates this, it returns text between brackets | |
1120 | @samp{[...]} in a string, or @code{#f} if there are no such brackets | |
1121 | (ie.@: either @code{string-index} gives @code{#f}). | |
1122 | ||
1123 | @example | |
1124 | (define (extract-brackets str) | |
1125 | (and-let* ((start (string-index str #\[)) | |
1126 | (end (string-index str #\] start))) | |
1127 | (substring str (1+ start) end))) | |
1128 | @end example | |
1129 | ||
1130 | The following shows plain variables and expressions tested too. | |
1131 | @code{diagnostic-levels} is taken to be an alist associating a | |
1132 | diagnostic type with a level. @code{str} is printed only if the type | |
1133 | is known and its level is high enough. | |
1134 | ||
1135 | @example | |
1136 | (define (show-diagnostic type str) | |
1137 | (and-let* (want-diagnostics | |
1138 | (level (assq-ref diagnostic-levels type)) | |
1139 | ((>= level current-diagnostic-level))) | |
1140 | (display str))) | |
1141 | @end example | |
1142 | ||
1143 | The advantage of @code{and-let*} is that an extended sequence of | |
1144 | expressions and tests doesn't require lots of nesting as would arise | |
1145 | from separate @code{and} and @code{let*}, or from @code{cond} with | |
1146 | @code{=>}. | |
1147 | ||
1148 | @end deffn | |
a0e07ba4 NJ |
1149 | |
1150 | ||
1151 | @node SRFI-4 | |
3229f68b | 1152 | @subsection SRFI-4 - Homogeneous numeric vector datatypes |
8742c48b | 1153 | @cindex SRFI-4 |
a0e07ba4 | 1154 | |
e6b226b9 | 1155 | The SRFI-4 procedures and data types are always available, @xref{Uniform |
3dd6e0cf | 1156 | Numeric Vectors}. |
a0e07ba4 NJ |
1157 | |
1158 | @node SRFI-6 | |
3229f68b | 1159 | @subsection SRFI-6 - Basic String Ports |
8742c48b | 1160 | @cindex SRFI-6 |
a0e07ba4 NJ |
1161 | |
1162 | SRFI-6 defines the procedures @code{open-input-string}, | |
1163 | @code{open-output-string} and @code{get-output-string}. These | |
1164 | procedures are included in the Guile core, so using this module does not | |
1165 | make any difference at the moment. But it is possible that support for | |
1166 | SRFI-6 will be factored out of the core library in the future, so using | |
1167 | this module does not hurt, after all. | |
1168 | ||
1169 | @node SRFI-8 | |
3229f68b | 1170 | @subsection SRFI-8 - receive |
8742c48b | 1171 | @cindex SRFI-8 |
a0e07ba4 NJ |
1172 | |
1173 | @code{receive} is a syntax for making the handling of multiple-value | |
1174 | procedures easier. It is documented in @xref{Multiple Values}. | |
1175 | ||
1176 | ||
1177 | @node SRFI-9 | |
3229f68b | 1178 | @subsection SRFI-9 - define-record-type |
8742c48b | 1179 | @cindex SRFI-9 |
7c2e18cd | 1180 | @cindex record |
a0e07ba4 | 1181 | |
6afe385d KR |
1182 | This SRFI is a syntax for defining new record types and creating |
1183 | predicate, constructor, and field getter and setter functions. In | |
1184 | Guile this is simply an alternate interface to the core record | |
1185 | functionality (@pxref{Records}). It can be used with, | |
a0e07ba4 | 1186 | |
6afe385d KR |
1187 | @example |
1188 | (use-modules (srfi srfi-9)) | |
1189 | @end example | |
1190 | ||
1191 | @deffn {library syntax} define-record-type type @* (constructor fieldname @dots{}) @* predicate @* (fieldname accessor [modifier]) @dots{} | |
1192 | @sp 1 | |
1193 | Create a new record type, and make various @code{define}s for using | |
1194 | it. This syntax can only occur at the top-level, not nested within | |
1195 | some other form. | |
1196 | ||
1197 | @var{type} is bound to the record type, which is as per the return | |
1198 | from the core @code{make-record-type}. @var{type} also provides the | |
1199 | name for the record, as per @code{record-type-name}. | |
1200 | ||
1201 | @var{constructor} is bound to a function to be called as | |
1202 | @code{(@var{constructor} fieldval @dots{})} to create a new record of | |
1203 | this type. The arguments are initial values for the fields, one | |
1204 | argument for each field, in the order they appear in the | |
1205 | @code{define-record-type} form. | |
1206 | ||
1207 | The @var{fieldname}s provide the names for the record fields, as per | |
1208 | the core @code{record-type-fields} etc, and are referred to in the | |
1209 | subsequent accessor/modifier forms. | |
1210 | ||
1211 | @var{predictate} is bound to a function to be called as | |
1212 | @code{(@var{predicate} obj)}. It returns @code{#t} or @code{#f} | |
1213 | according to whether @var{obj} is a record of this type. | |
1214 | ||
1215 | Each @var{accessor} is bound to a function to be called | |
1216 | @code{(@var{accessor} record)} to retrieve the respective field from a | |
1217 | @var{record}. Similarly each @var{modifier} is bound to a function to | |
1218 | be called @code{(@var{modifier} record val)} to set the respective | |
1219 | field in a @var{record}. | |
1220 | @end deffn | |
1221 | ||
1222 | @noindent | |
1223 | An example will illustrate typical usage, | |
a0e07ba4 NJ |
1224 | |
1225 | @example | |
6afe385d KR |
1226 | (define-record-type employee-type |
1227 | (make-employee name age salary) | |
1228 | employee? | |
1229 | (name get-employee-name) | |
1230 | (age get-employee-age set-employee-age) | |
1231 | (salary get-employee-salary set-employee-salary)) | |
a0e07ba4 NJ |
1232 | @end example |
1233 | ||
6afe385d KR |
1234 | This creates a new employee data type, with name, age and salary |
1235 | fields. Accessor functions are created for each field, but no | |
1236 | modifier function for the name (the intention in this example being | |
1237 | that it's established only when an employee object is created). These | |
1238 | can all then be used as for example, | |
a0e07ba4 NJ |
1239 | |
1240 | @example | |
6afe385d KR |
1241 | employee-type @result{} #<record-type employee-type> |
1242 | ||
1243 | (define fred (make-employee "Fred" 45 20000.00)) | |
1244 | ||
1245 | (employee? fred) @result{} #t | |
1246 | (get-employee-age fred) @result{} 45 | |
1247 | (set-employee-salary fred 25000.00) ;; pay rise | |
a0e07ba4 NJ |
1248 | @end example |
1249 | ||
6afe385d KR |
1250 | The functions created by @code{define-record-type} are ordinary |
1251 | top-level @code{define}s. They can be redefined or @code{set!} as | |
1252 | desired, exported from a module, etc. | |
1253 | ||
a0e07ba4 NJ |
1254 | |
1255 | @node SRFI-10 | |
3229f68b | 1256 | @subsection SRFI-10 - Hash-Comma Reader Extension |
8742c48b | 1257 | @cindex SRFI-10 |
a0e07ba4 NJ |
1258 | |
1259 | @cindex hash-comma | |
1260 | @cindex #,() | |
633acbe2 KR |
1261 | This SRFI implements a reader extension @code{#,()} called hash-comma. |
1262 | It allows the reader to give new kinds of objects, for use both in | |
1263 | data and as constants or literals in source code. This feature is | |
1264 | available with | |
a0e07ba4 | 1265 | |
633acbe2 KR |
1266 | @example |
1267 | (use-modules (srfi srfi-10)) | |
1268 | @end example | |
1269 | ||
1270 | @noindent | |
1271 | The new read syntax is of the form | |
a0e07ba4 NJ |
1272 | |
1273 | @example | |
633acbe2 | 1274 | #,(@var{tag} @var{arg}@dots{}) |
a0e07ba4 NJ |
1275 | @end example |
1276 | ||
633acbe2 KR |
1277 | @noindent |
1278 | where @var{tag} is a symbol and the @var{arg}s are objects taken as | |
1279 | parameters. @var{tag}s are registered with the following procedure. | |
a0e07ba4 | 1280 | |
633acbe2 KR |
1281 | @deffn {Scheme Procedure} define-reader-ctor tag proc |
1282 | Register @var{proc} as the constructor for a hash-comma read syntax | |
1283 | starting with symbol @var{tag}, ie. @nicode{#,(@var{tag} arg@dots{})}. | |
1284 | @var{proc} is called with the given arguments @code{(@var{proc} | |
1285 | arg@dots{})} and the object it returns is the result of the read. | |
1286 | @end deffn | |
a0e07ba4 | 1287 | |
633acbe2 KR |
1288 | @noindent |
1289 | For example, a syntax giving a list of @var{N} copies of an object. | |
1290 | ||
1291 | @example | |
1292 | (define-reader-ctor 'repeat | |
1293 | (lambda (obj reps) | |
1294 | (make-list reps obj))) | |
1295 | ||
1296 | (display '#,(repeat 99 3)) | |
1297 | @print{} (99 99 99) | |
1298 | @end example | |
1299 | ||
1300 | Notice the quote @nicode{'} when the @nicode{#,( )} is used. The | |
1301 | @code{repeat} handler returns a list and the program must quote to use | |
1302 | it literally, the same as any other list. Ie. | |
1303 | ||
1304 | @example | |
1305 | (display '#,(repeat 99 3)) | |
a0e07ba4 | 1306 | @result{} |
633acbe2 KR |
1307 | (display '(99 99 99)) |
1308 | @end example | |
a0e07ba4 | 1309 | |
633acbe2 KR |
1310 | When a handler returns an object which is self-evaluating, like a |
1311 | number or a string, then there's no need for quoting, just as there's | |
1312 | no need when giving those directly as literals. For example an | |
1313 | addition, | |
a0e07ba4 | 1314 | |
633acbe2 KR |
1315 | @example |
1316 | (define-reader-ctor 'sum | |
1317 | (lambda (x y) | |
1318 | (+ x y))) | |
1319 | (display #,(sum 123 456)) @print{} 579 | |
1320 | @end example | |
1321 | ||
1322 | A typical use for @nicode{#,()} is to get a read syntax for objects | |
1323 | which don't otherwise have one. For example, the following allows a | |
1324 | hash table to be given literally, with tags and values, ready for fast | |
1325 | lookup. | |
1326 | ||
1327 | @example | |
1328 | (define-reader-ctor 'hash | |
1329 | (lambda elems | |
1330 | (let ((table (make-hash-table))) | |
1331 | (for-each (lambda (elem) | |
1332 | (apply hash-set! table elem)) | |
1333 | elems) | |
1334 | table))) | |
1335 | ||
1336 | (define (animal->family animal) | |
1337 | (hash-ref '#,(hash ("tiger" "cat") | |
1338 | ("lion" "cat") | |
1339 | ("wolf" "dog")) | |
1340 | animal)) | |
1341 | ||
1342 | (animal->family "lion") @result{} "cat" | |
1343 | @end example | |
1344 | ||
1345 | Or for example the following is a syntax for a compiled regular | |
1346 | expression (@pxref{Regular Expressions}). | |
1347 | ||
1348 | @example | |
1349 | (use-modules (ice-9 regex)) | |
1350 | ||
1351 | (define-reader-ctor 'regexp make-regexp) | |
1352 | ||
1353 | (define (extract-angs str) | |
1354 | (let ((match (regexp-exec '#,(regexp "<([A-Z0-9]+)>") str))) | |
1355 | (and match | |
1356 | (match:substring match 1)))) | |
1357 | ||
1358 | (extract-angs "foo <BAR> quux") @result{} "BAR" | |
1359 | @end example | |
1360 | ||
1361 | @sp 1 | |
1362 | @nicode{#,()} is somewhat similar to @code{define-macro} | |
1363 | (@pxref{Macros}) in that handler code is run to produce a result, but | |
1364 | @nicode{#,()} operates at the read stage, so it can appear in data for | |
1365 | @code{read} (@pxref{Scheme Read}), not just in code to be executed. | |
1366 | ||
1367 | Because @nicode{#,()} is handled at read-time it has no direct access | |
1368 | to variables etc. A symbol in the arguments is just a symbol, not a | |
1369 | variable reference. The arguments are essentially constants, though | |
1370 | the handler procedure can use them in any complicated way it might | |
1371 | want. | |
1372 | ||
1373 | Once @code{(srfi srfi-10)} has loaded, @nicode{#,()} is available | |
1374 | globally, there's no need to use @code{(srfi srfi-10)} in later | |
1375 | modules. Similarly the tags registered are global and can be used | |
1376 | anywhere once registered. | |
1377 | ||
1378 | There's no attempt to record what previous @nicode{#,()} forms have | |
1379 | been seen, if two identical forms occur then two calls are made to the | |
1380 | handler procedure. The handler might like to maintain a cache or | |
1381 | similar to avoid making copies of large objects, depending on expected | |
1382 | usage. | |
1383 | ||
1384 | In code the best uses of @nicode{#,()} are generally when there's a | |
1385 | lot of objects of a particular kind as literals or constants. If | |
1386 | there's just a few then some local variables and initializers are | |
1387 | fine, but that becomes tedious and error prone when there's a lot, and | |
1388 | the anonymous and compact syntax of @nicode{#,()} is much better. | |
a0e07ba4 NJ |
1389 | |
1390 | ||
1391 | @node SRFI-11 | |
3229f68b | 1392 | @subsection SRFI-11 - let-values |
8742c48b | 1393 | @cindex SRFI-11 |
a0e07ba4 | 1394 | |
8742c48b KR |
1395 | @findex let-values |
1396 | @findex let-values* | |
a0e07ba4 NJ |
1397 | This module implements the binding forms for multiple values |
1398 | @code{let-values} and @code{let-values*}. These forms are similar to | |
1399 | @code{let} and @code{let*} (@pxref{Local Bindings}), but they support | |
1400 | binding of the values returned by multiple-valued expressions. | |
1401 | ||
1402 | Write @code{(use-modules (srfi srfi-11))} to make the bindings | |
1403 | available. | |
1404 | ||
1405 | @lisp | |
1406 | (let-values (((x y) (values 1 2)) | |
1407 | ((z f) (values 3 4))) | |
1408 | (+ x y z f)) | |
1409 | @result{} | |
1410 | 10 | |
1411 | @end lisp | |
1412 | ||
1413 | @code{let-values} performs all bindings simultaneously, which means that | |
1414 | no expression in the binding clauses may refer to variables bound in the | |
1415 | same clause list. @code{let-values*}, on the other hand, performs the | |
1416 | bindings sequentially, just like @code{let*} does for single-valued | |
1417 | expressions. | |
1418 | ||
1419 | ||
1420 | @node SRFI-13 | |
3229f68b | 1421 | @subsection SRFI-13 - String Library |
8742c48b | 1422 | @cindex SRFI-13 |
a0e07ba4 | 1423 | |
5676b4fa | 1424 | The SRFI-13 procedures are always available, @xref{Strings}. |
a0e07ba4 NJ |
1425 | |
1426 | @node SRFI-14 | |
3229f68b | 1427 | @subsection SRFI-14 - Character-set Library |
8742c48b | 1428 | @cindex SRFI-14 |
a0e07ba4 | 1429 | |
050ab45f MV |
1430 | The SRFI-14 data type and procedures are always available, |
1431 | @xref{Character Sets}. | |
a0e07ba4 NJ |
1432 | |
1433 | @node SRFI-16 | |
3229f68b | 1434 | @subsection SRFI-16 - case-lambda |
8742c48b | 1435 | @cindex SRFI-16 |
7c2e18cd KR |
1436 | @cindex variable arity |
1437 | @cindex arity, variable | |
a0e07ba4 NJ |
1438 | |
1439 | @c FIXME::martin: Review me! | |
1440 | ||
8742c48b | 1441 | @findex case-lambda |
a0e07ba4 NJ |
1442 | The syntactic form @code{case-lambda} creates procedures, just like |
1443 | @code{lambda}, but has syntactic extensions for writing procedures of | |
1444 | varying arity easier. | |
1445 | ||
1446 | The syntax of the @code{case-lambda} form is defined in the following | |
1447 | EBNF grammar. | |
1448 | ||
1449 | @example | |
1450 | @group | |
1451 | <case-lambda> | |
1452 | --> (case-lambda <case-lambda-clause>) | |
1453 | <case-lambda-clause> | |
1454 | --> (<formals> <definition-or-command>*) | |
1455 | <formals> | |
1456 | --> (<identifier>*) | |
1457 | | (<identifier>* . <identifier>) | |
1458 | | <identifier> | |
1459 | @end group | |
1460 | @end example | |
1461 | ||
1462 | The value returned by a @code{case-lambda} form is a procedure which | |
1463 | matches the number of actual arguments against the formals in the | |
1464 | various clauses, in order. @dfn{Formals} means a formal argument list | |
1465 | just like with @code{lambda} (@pxref{Lambda}). The first matching clause | |
1466 | is selected, the corresponding values from the actual parameter list are | |
1467 | bound to the variable names in the clauses and the body of the clause is | |
1468 | evaluated. If no clause matches, an error is signalled. | |
1469 | ||
1470 | The following (silly) definition creates a procedure @var{foo} which | |
1471 | acts differently, depending on the number of actual arguments. If one | |
1472 | argument is given, the constant @code{#t} is returned, two arguments are | |
1473 | added and if more arguments are passed, their product is calculated. | |
1474 | ||
1475 | @lisp | |
1476 | (define foo (case-lambda | |
1477 | ((x) #t) | |
1478 | ((x y) (+ x y)) | |
1479 | (z | |
1480 | (apply * z)))) | |
1481 | (foo 'bar) | |
1482 | @result{} | |
1483 | #t | |
1484 | (foo 2 4) | |
1485 | @result{} | |
1486 | 6 | |
1487 | (foo 3 3 3) | |
1488 | @result{} | |
1489 | 27 | |
1490 | (foo) | |
1491 | @result{} | |
1492 | 1 | |
1493 | @end lisp | |
1494 | ||
1495 | The last expression evaluates to 1 because the last clause is matched, | |
1496 | @var{z} is bound to the empty list and the following multiplication, | |
1497 | applied to zero arguments, yields 1. | |
1498 | ||
1499 | ||
1500 | @node SRFI-17 | |
3229f68b | 1501 | @subsection SRFI-17 - Generalized set! |
8742c48b | 1502 | @cindex SRFI-17 |
a0e07ba4 NJ |
1503 | |
1504 | This is an implementation of SRFI-17: Generalized set! | |
1505 | ||
8742c48b | 1506 | @findex getter-with-setter |
a0e07ba4 NJ |
1507 | It exports the Guile procedure @code{make-procedure-with-setter} under |
1508 | the SRFI name @code{getter-with-setter} and exports the standard | |
1509 | procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr}, | |
1510 | @code{string-ref} and @code{vector-ref} as procedures with setters, as | |
1511 | required by the SRFI. | |
1512 | ||
1513 | SRFI-17 was heavily criticized during its discussion period but it was | |
1514 | finalized anyway. One issue was its concept of globally associating | |
1515 | setter @dfn{properties} with (procedure) values, which is non-Schemy. | |
1516 | For this reason, this implementation chooses not to provide a way to set | |
1517 | the setter of a procedure. In fact, @code{(set! (setter @var{proc}) | |
1518 | @var{setter})} signals an error. The only way to attach a setter to a | |
1519 | procedure is to create a new object (a @dfn{procedure with setter}) via | |
1520 | the @code{getter-with-setter} procedure. This procedure is also | |
1521 | specified in the SRFI. Using it avoids the described problems. | |
1522 | ||
12991fed TTN |
1523 | |
1524 | @node SRFI-19 | |
3229f68b | 1525 | @subsection SRFI-19 - Time/Date Library |
8742c48b | 1526 | @cindex SRFI-19 |
7c2e18cd KR |
1527 | @cindex time |
1528 | @cindex date | |
12991fed | 1529 | |
85600a0f KR |
1530 | This is an implementation of the SRFI-19 time/date library. The |
1531 | functions and variables described here are provided by | |
12991fed TTN |
1532 | |
1533 | @example | |
85600a0f | 1534 | (use-modules (srfi srfi-19)) |
12991fed TTN |
1535 | @end example |
1536 | ||
85600a0f KR |
1537 | @menu |
1538 | * SRFI-19 Introduction:: | |
1539 | * SRFI-19 Time:: | |
1540 | * SRFI-19 Date:: | |
1541 | * SRFI-19 Time/Date conversions:: | |
1542 | * SRFI-19 Date to string:: | |
1543 | * SRFI-19 String to date:: | |
1544 | @end menu | |
12991fed | 1545 | |
85600a0f | 1546 | @node SRFI-19 Introduction |
3229f68b | 1547 | @subsubsection SRFI-19 Introduction |
85600a0f KR |
1548 | |
1549 | @cindex universal time | |
1550 | @cindex atomic time | |
1551 | @cindex UTC | |
1552 | @cindex TAI | |
1553 | This module implements time and date representations and calculations, | |
1554 | in various time systems, including universal time (UTC) and atomic | |
1555 | time (TAI). | |
1556 | ||
1557 | For those not familiar with these time systems, TAI is based on a | |
1558 | fixed length second derived from oscillations of certain atoms. UTC | |
1559 | differs from TAI by an integral number of seconds, which is increased | |
1560 | or decreased at announced times to keep UTC aligned to a mean solar | |
1561 | day (the orbit and rotation of the earth are not quite constant). | |
1562 | ||
1563 | @cindex leap second | |
1564 | So far, only increases in the TAI | |
1565 | @tex | |
1566 | $\leftrightarrow$ | |
1567 | @end tex | |
1568 | @ifnottex | |
1569 | <-> | |
1570 | @end ifnottex | |
1571 | UTC difference have been needed. Such an increase is a ``leap | |
1572 | second'', an extra second of TAI introduced at the end of a UTC day. | |
1573 | When working entirely within UTC this is never seen, every day simply | |
1574 | has 86400 seconds. But when converting from TAI to a UTC date, an | |
1575 | extra 23:59:60 is present, where normally a day would end at 23:59:59. | |
1576 | Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI | |
1577 | seconds. | |
1578 | ||
1579 | @cindex system clock | |
1580 | In the current implementation, the system clock is assumed to be UTC, | |
1581 | and a table of leap seconds in the code converts to TAI. See comments | |
1582 | in @file{srfi-19.scm} for how to update this table. | |
1583 | ||
1584 | @cindex julian day | |
1585 | @cindex modified julian day | |
1586 | Also, for those not familiar with the terminology, a @dfn{Julian Day} | |
1587 | is a real number which is a count of days and fraction of a day, in | |
1588 | UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan | |
7c2e18cd KR |
1589 | 4713 B.C. A @dfn{Modified Julian Day} is the same, but starting from |
1590 | 1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC. That time | |
1591 | is julian day 2400000.5. | |
85600a0f KR |
1592 | |
1593 | @c The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at | |
1594 | @c noon, UTC), but this is incorrect. It looks like it might have | |
1595 | @c arisen from the code incorrectly treating years a multiple of 100 | |
7c2e18cd | 1596 | @c but not 400 prior to 1582 as non-leap years, where instead the Julian |
85600a0f KR |
1597 | @c calendar should be used so all multiples of 4 before 1582 are leap |
1598 | @c years. | |
1599 | ||
1600 | ||
1601 | @node SRFI-19 Time | |
3229f68b | 1602 | @subsubsection SRFI-19 Time |
85600a0f KR |
1603 | @cindex time |
1604 | ||
1605 | A @dfn{time} object has type, seconds and nanoseconds fields | |
1606 | representing a point in time starting from some epoch. This is an | |
1607 | arbitrary point in time, not just a time of day. Although times are | |
1608 | represented in nanoseconds, the actual resolution may be lower. | |
1609 | ||
1610 | The following variables hold the possible time types. For instance | |
1611 | @code{(current-time time-process)} would give the current CPU process | |
1612 | time. | |
1613 | ||
1614 | @defvar time-utc | |
1615 | Universal Coordinated Time (UTC). | |
1616 | @cindex UTC | |
1617 | @end defvar | |
12991fed | 1618 | |
85600a0f KR |
1619 | @defvar time-tai |
1620 | International Atomic Time (TAI). | |
1621 | @cindex TAI | |
1622 | @end defvar | |
12991fed | 1623 | |
85600a0f KR |
1624 | @defvar time-monotonic |
1625 | Monotonic time, meaning a monotonically increasing time starting from | |
1626 | an unspecified epoch. | |
12991fed | 1627 | |
85600a0f KR |
1628 | Note that in the current implementation @code{time-monotonic} is the |
1629 | same as @code{time-tai}, and unfortunately is therefore affected by | |
1630 | adjustments to the system clock. Perhaps this will change in the | |
1631 | future. | |
1632 | @end defvar | |
12991fed | 1633 | |
85600a0f KR |
1634 | @defvar time-duration |
1635 | A duration, meaning simply a difference between two times. | |
1636 | @end defvar | |
12991fed | 1637 | |
85600a0f KR |
1638 | @defvar time-process |
1639 | CPU time spent in the current process, starting from when the process | |
1640 | began. | |
1641 | @cindex process time | |
1642 | @end defvar | |
12991fed | 1643 | |
85600a0f KR |
1644 | @defvar time-thread |
1645 | CPU time spent in the current thread. Not currently implemented. | |
1646 | @cindex thread time | |
1647 | @end defvar | |
12991fed | 1648 | |
85600a0f KR |
1649 | @sp 1 |
1650 | @defun time? obj | |
1651 | Return @code{#t} if @var{obj} is a time object, or @code{#f} if not. | |
1652 | @end defun | |
1653 | ||
1654 | @defun make-time type nanoseconds seconds | |
1655 | Create a time object with the given @var{type}, @var{seconds} and | |
1656 | @var{nanoseconds}. | |
1657 | @end defun | |
1658 | ||
1659 | @defun time-type time | |
1660 | @defunx time-nanosecond time | |
1661 | @defunx time-second time | |
1662 | @defunx set-time-type! time type | |
1663 | @defunx set-time-nanosecond! time nsec | |
1664 | @defunx set-time-second! time sec | |
1665 | Get or set the type, seconds or nanoseconds fields of a time object. | |
1666 | ||
1667 | @code{set-time-type!} merely changes the field, it doesn't convert the | |
1668 | time value. For conversions, see @ref{SRFI-19 Time/Date conversions}. | |
1669 | @end defun | |
1670 | ||
1671 | @defun copy-time time | |
1672 | Return a new time object, which is a copy of the given @var{time}. | |
1673 | @end defun | |
1674 | ||
1675 | @defun current-time [type] | |
1676 | Return the current time of the given @var{type}. The default | |
1677 | @var{type} is @code{time-utc}. | |
1678 | ||
1679 | Note that the name @code{current-time} conflicts with the Guile core | |
1680 | @code{current-time} function (@pxref{Time}). Applications wanting to | |
1681 | use both will need to use a different name for one of them. | |
1682 | @end defun | |
1683 | ||
1684 | @defun time-resolution [type] | |
1685 | Return the resolution, in nanoseconds, of the given time @var{type}. | |
1686 | The default @var{type} is @code{time-utc}. | |
1687 | @end defun | |
1688 | ||
1689 | @defun time<=? t1 t2 | |
1690 | @defunx time<? t1 t2 | |
1691 | @defunx time=? t1 t2 | |
1692 | @defunx time>=? t1 t2 | |
1693 | @defunx time>? t1 t2 | |
1694 | Return @code{#t} or @code{#f} according to the respective relation | |
1695 | between time objects @var{t1} and @var{t2}. @var{t1} and @var{t2} | |
1696 | must be the same time type. | |
1697 | @end defun | |
1698 | ||
1699 | @defun time-difference t1 t2 | |
1700 | @defunx time-difference! t1 t2 | |
1701 | Return a time object of type @code{time-duration} representing the | |
1702 | period between @var{t1} and @var{t2}. @var{t1} and @var{t2} must be | |
1703 | the same time type. | |
1704 | ||
1705 | @code{time-difference} returns a new time object, | |
1706 | @code{time-difference!} may modify @var{t1} to form its return. | |
1707 | @end defun | |
1708 | ||
1709 | @defun add-duration time duration | |
1710 | @defunx add-duration! time duration | |
1711 | @defunx subtract-duration time duration | |
1712 | @defunx subtract-duration! time duration | |
1713 | Return a time object which is @var{time} with the given @var{duration} | |
1714 | added or subtracted. @var{duration} must be a time object of type | |
1715 | @code{time-duration}. | |
1716 | ||
1717 | @code{add-duration} and @code{subtract-duration} return a new time | |
1718 | object. @code{add-duration!} and @code{subtract-duration!} may modify | |
1719 | the given @var{time} to form their return. | |
1720 | @end defun | |
1721 | ||
1722 | ||
1723 | @node SRFI-19 Date | |
3229f68b | 1724 | @subsubsection SRFI-19 Date |
85600a0f KR |
1725 | @cindex date |
1726 | ||
1727 | A @dfn{date} object represents a date in the Gregorian calendar and a | |
1728 | time of day on that date in some timezone. | |
1729 | ||
1730 | The fields are year, month, day, hour, minute, second, nanoseconds and | |
1731 | timezone. A date object is immutable, its fields can be read but they | |
1732 | cannot be modified once the object is created. | |
1733 | ||
1734 | @defun date? obj | |
1735 | Return @code{#t} if @var{obj} is a date object, or @code{#f} if not. | |
1736 | @end defun | |
1737 | ||
1738 | @defun make-date nsecs seconds minutes hours date month year zone-offset | |
1739 | Create a new date object. | |
1740 | @c | |
1741 | @c FIXME: What can we say about the ranges of the values. The | |
1742 | @c current code looks it doesn't normalize, but expects then in their | |
1743 | @c usual range already. | |
1744 | @c | |
1745 | @end defun | |
1746 | ||
1747 | @defun date-nanosecond date | |
1748 | Nanoseconds, 0 to 999999999. | |
1749 | @end defun | |
1750 | ||
1751 | @defun date-second date | |
7c2e18cd KR |
1752 | Seconds, 0 to 59, or 60 for a leap second. 60 is never seen when working |
1753 | entirely within UTC, it's only when converting to or from TAI. | |
85600a0f KR |
1754 | @end defun |
1755 | ||
1756 | @defun date-minute date | |
1757 | Minutes, 0 to 59. | |
1758 | @end defun | |
1759 | ||
1760 | @defun date-hour date | |
1761 | Hour, 0 to 23. | |
1762 | @end defun | |
1763 | ||
1764 | @defun date-day date | |
1765 | Day of the month, 1 to 31 (or less, according to the month). | |
1766 | @end defun | |
1767 | ||
1768 | @defun date-month date | |
1769 | Month, 1 to 12. | |
1770 | @end defun | |
1771 | ||
1772 | @defun date-year date | |
7c2e18cd KR |
1773 | Year, eg.@: 2003. Dates B.C.@: are negative, eg.@: @math{-46} is 46 |
1774 | B.C. There is no year 0, year @math{-1} is followed by year 1. | |
85600a0f KR |
1775 | @end defun |
1776 | ||
1777 | @defun date-zone-offset date | |
1778 | Time zone, an integer number of seconds east of Greenwich. | |
1779 | @end defun | |
1780 | ||
1781 | @defun date-year-day date | |
1782 | Day of the year, starting from 1 for 1st January. | |
1783 | @end defun | |
1784 | ||
1785 | @defun date-week-day date | |
1786 | Day of the week, starting from 0 for Sunday. | |
1787 | @end defun | |
1788 | ||
1789 | @defun date-week-number date dstartw | |
1790 | Week of the year, ignoring a first partial week. @var{dstartw} is the | |
1791 | day of the week which is taken to start a week, 0 for Sunday, 1 for | |
1792 | Monday, etc. | |
1793 | @c | |
1794 | @c FIXME: The spec doesn't say whether numbering starts at 0 or 1. | |
1795 | @c The code looks like it's 0, if that's the correct intention. | |
1796 | @c | |
1797 | @end defun | |
1798 | ||
1799 | @c The SRFI text doesn't actually give the default for tz-offset, but | |
1800 | @c the reference implementation has the local timezone and the | |
1801 | @c conversions functions all specify that, so it should be ok to | |
1802 | @c document it here. | |
1803 | @c | |
1804 | @defun current-date [tz-offset] | |
7c2e18cd KR |
1805 | Return a date object representing the current date/time, in UTC offset |
1806 | by @var{tz-offset}. @var{tz-offset} is seconds east of Greenwich and | |
1807 | defaults to the local timezone. | |
85600a0f KR |
1808 | @end defun |
1809 | ||
1810 | @defun current-julian-day | |
1811 | @cindex julian day | |
1812 | Return the current Julian Day. | |
1813 | @end defun | |
1814 | ||
1815 | @defun current-modified-julian-day | |
1816 | @cindex modified julian day | |
1817 | Return the current Modified Julian Day. | |
1818 | @end defun | |
1819 | ||
1820 | ||
1821 | @node SRFI-19 Time/Date conversions | |
3229f68b | 1822 | @subsubsection SRFI-19 Time/Date conversions |
7c2e18cd KR |
1823 | @cindex time conversion |
1824 | @cindex date conversion | |
85600a0f KR |
1825 | |
1826 | @defun date->julian-day date | |
1827 | @defunx date->modified-julian-day date | |
1828 | @defunx date->time-monotonic date | |
1829 | @defunx date->time-tai date | |
1830 | @defunx date->time-utc date | |
1831 | @end defun | |
1832 | @defun julian-day->date jdn [tz-offset] | |
1833 | @defunx julian-day->time-monotonic jdn | |
1834 | @defunx julian-day->time-tai jdn | |
1835 | @defunx julian-day->time-utc jdn | |
1836 | @end defun | |
1837 | @defun modified-julian-day->date jdn [tz-offset] | |
1838 | @defunx modified-julian-day->time-monotonic jdn | |
1839 | @defunx modified-julian-day->time-tai jdn | |
1840 | @defunx modified-julian-day->time-utc jdn | |
1841 | @end defun | |
1842 | @defun time-monotonic->date time [tz-offset] | |
1843 | @defunx time-monotonic->time-tai time | |
1844 | @defunx time-monotonic->time-tai! time | |
1845 | @defunx time-monotonic->time-utc time | |
1846 | @defunx time-monotonic->time-utc! time | |
1847 | @end defun | |
1848 | @defun time-tai->date time [tz-offset] | |
1849 | @defunx time-tai->julian-day time | |
1850 | @defunx time-tai->modified-julian-day time | |
1851 | @defunx time-tai->time-monotonic time | |
1852 | @defunx time-tai->time-monotonic! time | |
1853 | @defunx time-tai->time-utc time | |
1854 | @defunx time-tai->time-utc! time | |
1855 | @end defun | |
1856 | @defun time-utc->date time [tz-offset] | |
1857 | @defunx time-utc->julian-day time | |
1858 | @defunx time-utc->modified-julian-day time | |
1859 | @defunx time-utc->time-monotonic time | |
1860 | @defunx time-utc->time-monotonic! time | |
1861 | @defunx time-utc->time-tai time | |
1862 | @defunx time-utc->time-tai! time | |
1863 | @sp 1 | |
1864 | Convert between dates, times and days of the respective types. For | |
1865 | instance @code{time-tai->time-utc} accepts a @var{time} object of type | |
1866 | @code{time-tai} and returns an object of type @code{time-utc}. | |
1867 | ||
85600a0f KR |
1868 | The @code{!} variants may modify their @var{time} argument to form |
1869 | their return. The plain functions create a new object. | |
702e6e09 KR |
1870 | |
1871 | For conversions to dates, @var{tz-offset} is seconds east of | |
1872 | Greenwich. The default is the local timezone, at the given time, as | |
1873 | provided by the system, using @code{localtime} (@pxref{Time}). | |
1874 | ||
1875 | On 32-bit systems, @code{localtime} is limited to a 32-bit | |
1876 | @code{time_t}, so a default @var{tz-offset} is only available for | |
1877 | times between Dec 1901 and Jan 2038. For prior dates an application | |
1878 | might like to use the value in 1902, though some locations have zone | |
1879 | changes prior to that. For future dates an application might like to | |
1880 | assume today's rules extend indefinitely. But for correct daylight | |
1881 | savings transitions it will be necessary to take an offset for the | |
1882 | same day and time but a year in range and which has the same starting | |
1883 | weekday and same leap/non-leap (to support rules like last Sunday in | |
1884 | October). | |
85600a0f KR |
1885 | @end defun |
1886 | ||
1887 | @node SRFI-19 Date to string | |
3229f68b | 1888 | @subsubsection SRFI-19 Date to string |
85600a0f | 1889 | @cindex date to string |
7c2e18cd | 1890 | @cindex string, from date |
85600a0f KR |
1891 | |
1892 | @defun date->string date [format] | |
1893 | Convert a date to a string under the control of a format. | |
1894 | @var{format} should be a string containing @samp{~} escapes, which | |
1895 | will be expanded as per the following conversion table. The default | |
1896 | @var{format} is @samp{~c}, a locale-dependent date and time. | |
1897 | ||
1898 | Many of these conversion characters are the same as POSIX | |
1899 | @code{strftime} (@pxref{Time}), but there are some extras and some | |
1900 | variations. | |
1901 | ||
1902 | @multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} | |
1903 | @item @nicode{~~} @tab literal ~ | |
1904 | @item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun} | |
1905 | @item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday} | |
1906 | @item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan} | |
1907 | @item @nicode{~B} @tab locale full month, eg.@: @samp{January} | |
1908 | @item @nicode{~c} @tab locale date and time, eg.@: @* | |
1909 | @samp{Fri Jul 14 20:28:42-0400 2000} | |
1910 | @item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31} | |
1911 | ||
1912 | @c Spec says d/m/y, reference implementation says m/d/y. | |
1913 | @c Apparently the reference code was the intention, but would like to | |
1914 | @c see an errata published for the spec before contradicting it here. | |
1915 | @c | |
1916 | @c @item @nicode{~D} @tab date @nicode{~d/~m/~y} | |
1917 | ||
1918 | @item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31} | |
1919 | @item @nicode{~f} @tab seconds and fractional seconds, | |
1920 | with locale decimal point, eg.@: @samp{5.2} | |
1921 | @item @nicode{~h} @tab same as @nicode{~b} | |
1922 | @item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23} | |
1923 | @item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12} | |
1924 | @item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366} | |
1925 | @item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23} | |
1926 | @item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12} | |
1927 | @item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12} | |
1928 | @item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59} | |
1929 | @item @nicode{~n} @tab newline | |
1930 | @item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999} | |
1931 | @item @nicode{~p} @tab locale AM or PM | |
1932 | @item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p} | |
1933 | @item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC | |
1934 | @item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @* | |
1935 | (usual limit is 59, 60 is a leap second) | |
1936 | @item @nicode{~t} @tab horizontal tab character | |
1937 | @item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S} | |
1938 | @item @nicode{~U} @tab week of year, Sunday first day of week, | |
1939 | @samp{00} to @samp{52} | |
1940 | @item @nicode{~V} @tab week of year, Monday first day of week, | |
1941 | @samp{01} to @samp{53} | |
1942 | @item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6} | |
1943 | @item @nicode{~W} @tab week of year, Monday first day of week, | |
1944 | @samp{00} to @samp{52} | |
1945 | ||
1946 | @c The spec has ~x as an apparent duplicate of ~W, and ~X as a locale | |
1947 | @c date. The reference code has ~x as the locale date and ~X as a | |
1948 | @c locale time. The rule is apparently that the code should be | |
1949 | @c believed, but would like to see an errata for the spec before | |
1950 | @c contradicting it here. | |
1951 | @c | |
1952 | @c @item @nicode{~x} @tab week of year, Monday as first day of week, | |
1953 | @c @samp{00} to @samp{53} | |
1954 | @c @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00} | |
1955 | ||
1956 | @item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99} | |
1957 | @item @nicode{~Y} @tab year, full, eg.@: @samp{2003} | |
1958 | @item @nicode{~z} @tab time zone, RFC-822 style | |
1959 | @item @nicode{~Z} @tab time zone symbol (not currently implemented) | |
1960 | @item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d} | |
1961 | @item @nicode{~2} @tab ISO-8601 time+zone, @samp{~k:~M:~S~z} | |
1962 | @item @nicode{~3} @tab ISO-8601 time, @samp{~k:~M:~S} | |
1963 | @item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~k:~M:~S~z} | |
1964 | @item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~k:~M:~S} | |
1965 | @end multitable | |
1966 | @end defun | |
1967 | ||
1968 | Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently | |
1969 | described here, since the specification and reference implementation | |
1970 | differ. | |
1971 | ||
1972 | Currently Guile doesn't implement any localizations for the above, all | |
1973 | outputs are in English, and the @samp{~c} conversion is POSIX | |
1974 | @code{ctime} style @samp{~a ~b ~d ~H:~M:~S~z ~Y}. This may change in | |
1975 | the future. | |
1976 | ||
1977 | ||
1978 | @node SRFI-19 String to date | |
3229f68b | 1979 | @subsubsection SRFI-19 String to date |
85600a0f | 1980 | @cindex string to date |
7c2e18cd | 1981 | @cindex date, from string |
85600a0f KR |
1982 | |
1983 | @c FIXME: Can we say what happens when an incomplete date is | |
1984 | @c converted? Ie. fields left as 0, or what? The spec seems to be | |
1985 | @c silent on this. | |
1986 | ||
1987 | @defun string->date input template | |
1988 | Convert an @var{input} string to a date under the control of a | |
1989 | @var{template} string. Return a newly created date object. | |
1990 | ||
1991 | Literal characters in @var{template} must match characters in | |
1992 | @var{input} and @samp{~} escapes must match the input forms described | |
1993 | in the table below. ``Skip to'' means characters up to one of the | |
1994 | given type are ignored, or ``no skip'' for no skipping. ``Read'' is | |
1995 | what's then read, and ``Set'' is the field affected in the date | |
1996 | object. | |
1997 | ||
1998 | For example @samp{~Y} skips input characters until a digit is reached, | |
1999 | at which point it expects a year and stores that to the year field of | |
2000 | the date. | |
2001 | ||
2002 | @multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}} | |
2003 | @item | |
2004 | @tab Skip to | |
2005 | @tab Read | |
2006 | @tab Set | |
2007 | ||
2008 | @item @nicode{~~} | |
2009 | @tab no skip | |
2010 | @tab literal ~ | |
2011 | @tab nothing | |
2012 | ||
2013 | @item @nicode{~a} | |
2014 | @tab @nicode{char-alphabetic?} | |
2015 | @tab locale abbreviated weekday name | |
2016 | @tab nothing | |
2017 | ||
2018 | @item @nicode{~A} | |
2019 | @tab @nicode{char-alphabetic?} | |
2020 | @tab locale full weekday name | |
2021 | @tab nothing | |
2022 | ||
2023 | @c Note that the SRFI spec says that ~b and ~B don't set anything, | |
2024 | @c but that looks like a mistake. The reference implementation sets | |
2025 | @c the month field, which seems sensible and is what we describe | |
2026 | @c here. | |
2027 | ||
2028 | @item @nicode{~b} | |
2029 | @tab @nicode{char-alphabetic?} | |
2030 | @tab locale abbreviated month name | |
2031 | @tab @nicode{date-month} | |
2032 | ||
2033 | @item @nicode{~B} | |
2034 | @tab @nicode{char-alphabetic?} | |
2035 | @tab locale full month name | |
2036 | @tab @nicode{date-month} | |
2037 | ||
2038 | @item @nicode{~d} | |
2039 | @tab @nicode{char-numeric?} | |
2040 | @tab day of month | |
2041 | @tab @nicode{date-day} | |
2042 | ||
2043 | @item @nicode{~e} | |
2044 | @tab no skip | |
2045 | @tab day of month, blank padded | |
2046 | @tab @nicode{date-day} | |
2047 | ||
2048 | @item @nicode{~h} | |
2049 | @tab same as @samp{~b} | |
2050 | ||
2051 | @item @nicode{~H} | |
2052 | @tab @nicode{char-numeric?} | |
2053 | @tab hour | |
2054 | @tab @nicode{date-hour} | |
2055 | ||
2056 | @item @nicode{~k} | |
2057 | @tab no skip | |
2058 | @tab hour, blank padded | |
2059 | @tab @nicode{date-hour} | |
2060 | ||
2061 | @item @nicode{~m} | |
2062 | @tab @nicode{char-numeric?} | |
2063 | @tab month | |
2064 | @tab @nicode{date-month} | |
2065 | ||
2066 | @item @nicode{~M} | |
2067 | @tab @nicode{char-numeric?} | |
2068 | @tab minute | |
2069 | @tab @nicode{date-minute} | |
2070 | ||
2071 | @item @nicode{~S} | |
2072 | @tab @nicode{char-numeric?} | |
2073 | @tab second | |
2074 | @tab @nicode{date-second} | |
2075 | ||
2076 | @item @nicode{~y} | |
2077 | @tab no skip | |
2078 | @tab 2-digit year | |
2079 | @tab @nicode{date-year} within 50 years | |
2080 | ||
2081 | @item @nicode{~Y} | |
2082 | @tab @nicode{char-numeric?} | |
2083 | @tab year | |
2084 | @tab @nicode{date-year} | |
2085 | ||
2086 | @item @nicode{~z} | |
2087 | @tab no skip | |
2088 | @tab time zone | |
2089 | @tab date-zone-offset | |
2090 | @end multitable | |
2091 | ||
2092 | Notice that the weekday matching forms don't affect the date object | |
2093 | returned, instead the weekday will be derived from the day, month and | |
2094 | year. | |
2095 | ||
2096 | Currently Guile doesn't implement any localizations for the above, | |
2097 | month and weekday names are always expected in English. This may | |
2098 | change in the future. | |
2099 | @end defun | |
12991fed | 2100 | |
1de8c1ae | 2101 | |
b0b55bd6 | 2102 | @node SRFI-26 |
3229f68b | 2103 | @subsection SRFI-26 - specializing parameters |
1de8c1ae | 2104 | @cindex SRFI-26 |
7c2e18cd KR |
2105 | @cindex parameter specialize |
2106 | @cindex argument specialize | |
2107 | @cindex specialize parameter | |
1de8c1ae KR |
2108 | |
2109 | This SRFI provides a syntax for conveniently specializing selected | |
2110 | parameters of a function. It can be used with, | |
2111 | ||
2112 | @example | |
2113 | (use-modules (srfi srfi-26)) | |
2114 | @end example | |
2115 | ||
2116 | @deffn {library syntax} cut slot @dots{} | |
2117 | @deffnx {library syntax} cute slot @dots{} | |
2118 | Return a new procedure which will make a call (@var{slot} @dots{}) but | |
2119 | with selected parameters specialized to given expressions. | |
2120 | ||
2121 | An example will illustrate the idea. The following is a | |
2122 | specialization of @code{write}, sending output to | |
2123 | @code{my-output-port}, | |
2124 | ||
2125 | @example | |
2126 | (cut write <> my-output-port) | |
2127 | @result{} | |
2128 | (lambda (obj) (write obj my-output-port)) | |
2129 | @end example | |
2130 | ||
2131 | The special symbol @code{<>} indicates a slot to be filled by an | |
2132 | argument to the new procedure. @code{my-output-port} on the other | |
2133 | hand is an expression to be evaluated and passed, ie.@: it specializes | |
2134 | the behaviour of @code{write}. | |
2135 | ||
2136 | @table @nicode | |
2137 | @item <> | |
2138 | A slot to be filled by an argument from the created procedure. | |
2139 | Arguments are assigned to @code{<>} slots in the order they appear in | |
2140 | the @code{cut} form, there's no way to re-arrange arguments. | |
2141 | ||
2142 | The first argument to @code{cut} is usually a procedure (or expression | |
2143 | giving a procedure), but @code{<>} is allowed there too. For example, | |
2144 | ||
2145 | @example | |
2146 | (cut <> 1 2 3) | |
2147 | @result{} | |
2148 | (lambda (proc) (proc 1 2 3)) | |
2149 | @end example | |
2150 | ||
2151 | @item <...> | |
2152 | A slot to be filled by all remaining arguments from the new procedure. | |
2153 | This can only occur at the end of a @code{cut} form. | |
2154 | ||
2155 | For example, a procedure taking a variable number of arguments like | |
2156 | @code{max} but in addition enforcing a lower bound, | |
2157 | ||
2158 | @example | |
2159 | (define my-lower-bound 123) | |
2160 | ||
2161 | (cut max my-lower-bound <...>) | |
2162 | @result{} | |
2163 | (lambda arglist (apply max my-lower-bound arglist)) | |
2164 | @end example | |
2165 | @end table | |
2166 | ||
2167 | For @code{cut} the specializing expressions are evaluated each time | |
2168 | the new procedure is called. For @code{cute} they're evaluated just | |
2169 | once, when the new procedure is created. The name @code{cute} stands | |
2170 | for ``@code{cut} with evaluated arguments''. In all cases the | |
2171 | evaluations take place in an unspecified order. | |
2172 | ||
2173 | The following illustrates the difference between @code{cut} and | |
2174 | @code{cute}, | |
2175 | ||
2176 | @example | |
2177 | (cut format <> "the time is ~s" (current-time)) | |
2178 | @result{} | |
2179 | (lambda (port) (format port "the time is ~s" (current-time))) | |
2180 | ||
2181 | (cute format <> "the time is ~s" (current-time)) | |
2182 | @result{} | |
2183 | (let ((val (current-time))) | |
2184 | (lambda (port) (format port "the time is ~s" val)) | |
2185 | @end example | |
2186 | ||
2187 | (There's no provision for a mixture of @code{cut} and @code{cute} | |
2188 | where some expressions would be evaluated every time but others | |
2189 | evaluated only once.) | |
2190 | ||
2191 | @code{cut} is really just a shorthand for the sort of @code{lambda} | |
2192 | forms shown in the above examples. But notice @code{cut} avoids the | |
2193 | need to name unspecialized parameters, and is more compact. Use in | |
2194 | functional programming style or just with @code{map}, @code{for-each} | |
2195 | or similar is typical. | |
2196 | ||
2197 | @example | |
2198 | (map (cut * 2 <>) '(1 2 3 4)) | |
2199 | ||
2200 | (for-each (cut write <> my-port) my-list) | |
2201 | @end example | |
2202 | @end deffn | |
b0b55bd6 | 2203 | |
8638c417 RB |
2204 | @node SRFI-31 |
2205 | @subsection SRFI-31 - A special form `rec' for recursive evaluation | |
2206 | @cindex SRFI-31 | |
7c2e18cd | 2207 | @cindex recursive expression |
8638c417 RB |
2208 | @findex rec |
2209 | ||
2210 | SRFI-31 defines a special form that can be used to create | |
2211 | self-referential expressions more conveniently. The syntax is as | |
2212 | follows: | |
2213 | ||
2214 | @example | |
2215 | @group | |
2216 | <rec expression> --> (rec <variable> <expression>) | |
2217 | <rec expression> --> (rec (<variable>+) <body>) | |
2218 | @end group | |
2219 | @end example | |
2220 | ||
2221 | The first syntax can be used to create self-referential expressions, | |
2222 | for example: | |
2223 | ||
2224 | @lisp | |
2225 | guile> (define tmp (rec ones (cons 1 (delay ones)))) | |
2226 | @end lisp | |
2227 | ||
2228 | The second syntax can be used to create anonymous recursive functions: | |
2229 | ||
2230 | @lisp | |
2231 | guile> (define tmp (rec (display-n item n) | |
2232 | (if (positive? n) | |
2233 | (begin (display n) (display-n (- n 1)))))) | |
2234 | guile> (tmp 42 3) | |
2235 | 424242 | |
2236 | guile> | |
2237 | @end lisp | |
12991fed | 2238 | |
eeadfda1 KR |
2239 | |
2240 | @node SRFI-39 | |
2241 | @subsection SRFI-39 - Parameters | |
2242 | @cindex SRFI-39 | |
2243 | @cindex parameter object | |
2244 | @tindex Parameter | |
2245 | ||
2246 | This SRFI provides parameter objects, which implement dynamically | |
2247 | bound locations for values. The functions below are available from | |
2248 | ||
2249 | @example | |
2250 | (use-modules (srfi srfi-39)) | |
2251 | @end example | |
2252 | ||
2253 | A parameter object is a procedure. Called with no arguments it | |
2254 | returns its value, called with one argument it sets the value. | |
2255 | ||
2256 | @example | |
2257 | (define my-param (make-parameter 123)) | |
2258 | (my-param) @result{} 123 | |
2259 | (my-param 456) | |
2260 | (my-param) @result{} 456 | |
2261 | @end example | |
2262 | ||
2263 | The @code{parameterize} special form establishes new locations for | |
2264 | parameters, those new locations having effect within the dynamic scope | |
2265 | of the @code{parameterize} body. Leaving restores the previous | |
2266 | locations, or re-entering through a saved continuation will again use | |
2267 | the new locations. | |
2268 | ||
2269 | @example | |
2270 | (parameterize ((my-param 789)) | |
2271 | (my-param) @result{} 789 | |
2272 | ) | |
2273 | (my-param) @result{} 456 | |
2274 | @end example | |
2275 | ||
2276 | Parameters are like dynamically bound variables in other Lisp dialets. | |
2277 | They allow an application to establish parameter settings (as the name | |
2278 | suggests) just for the execution of a particular bit of code, | |
2279 | restoring when done. Examples of such parameters might be | |
2280 | case-sensitivity for a search, or a prompt for user input. | |
2281 | ||
2282 | Global variables are not as good as parameter objects for this sort of | |
2283 | thing. Changes to them are visible to all threads, but in Guile | |
2284 | parameter object locations are per-thread, thereby truely limiting the | |
2285 | effect of @code{parameterize} to just its dynamic execution. | |
2286 | ||
2287 | Passing arguments to functions is thread-safe, but that soon becomes | |
2288 | tedious when there's more than a few or when they need to pass down | |
2289 | through several layers of calls before reaching the point they should | |
2290 | affect. And introducing a new setting to existing code is often | |
2291 | easier with a parameter object than adding arguments. | |
2292 | ||
2293 | ||
2294 | @sp 1 | |
2295 | @defun make-parameter init [converter] | |
2296 | Return a new parameter object, with initial value @var{init}. | |
2297 | ||
2298 | A parameter object is a procedure. When called @code{(param)} it | |
2299 | returns its value, or a call @code{(param val)} sets its value. For | |
2300 | example, | |
2301 | ||
2302 | @example | |
2303 | (define my-param (make-parameter 123)) | |
2304 | (my-param) @result{} 123 | |
2305 | ||
2306 | (my-param 456) | |
2307 | (my-param) @result{} 456 | |
2308 | @end example | |
2309 | ||
2310 | If a @var{converter} is given, then a call @code{(@var{converter} | |
2311 | val)} is made for each value set, its return is the value stored. | |
2312 | Such a call is made for the @var{init} initial value too. | |
2313 | ||
2314 | A @var{converter} allows values to be validated, or put into a | |
2315 | canonical form. For example, | |
2316 | ||
2317 | @example | |
2318 | (define my-param (make-parameter 123 | |
2319 | (lambda (val) | |
2320 | (if (not (number? val)) | |
2321 | (error "must be a number")) | |
2322 | (inexact->exact val)))) | |
2323 | (my-param 0.75) | |
2324 | (my-param) @result{} 3/4 | |
2325 | @end example | |
2326 | @end defun | |
2327 | ||
2328 | @deffn {library syntax} parameterize ((param value) @dots{}) body @dots{} | |
2329 | Establish a new dynamic scope with the given @var{param}s bound to new | |
2330 | locations and set to the given @var{value}s. @var{body} is evaluated | |
2331 | in that environment, the result is the return from the last form in | |
2332 | @var{body}. | |
2333 | ||
2334 | Each @var{param} is an expression which is evaluated to get the | |
2335 | parameter object. Often this will just be the name of a variable | |
2336 | holding the object, but it can be anything that evaluates to a | |
2337 | parameter. | |
2338 | ||
2339 | The @var{param} expressions and @var{value} expressions are all | |
2340 | evaluated before establishing the new dynamic bindings, and they're | |
2341 | evaluated in an unspecified order. | |
2342 | ||
2343 | For example, | |
2344 | ||
2345 | @example | |
2346 | (define prompt (make-parameter "Type something: ")) | |
2347 | (define (get-input) | |
2348 | (display (prompt)) | |
2349 | ...) | |
2350 | ||
2351 | (parameterize ((prompt "Type a number: ")) | |
2352 | (get-input) | |
2353 | ...) | |
2354 | @end example | |
2355 | @end deffn | |
2356 | ||
2357 | @deffn {Parameter object} current-input-port [new-port] | |
2358 | @deffnx {Parameter object} current-output-port [new-port] | |
2359 | @deffnx {Parameter object} current-error-port [new-port] | |
2360 | This SRFI extends the core @code{current-input-port} and | |
2361 | @code{current-output-port}, making them parameter objects. The | |
2362 | Guile-specific @code{current-error-port} is extended too, for | |
2363 | consistency. (@pxref{Default Ports}.) | |
2364 | ||
2365 | This is an upwardly compatible extension, a plain call like | |
2366 | @code{(current-input-port)} still returns the current input port, and | |
2367 | @code{set-current-input-port} can still be used. But the port can now | |
2368 | also be set with @code{(current-input-port my-port)} and bound | |
2369 | dynamically with @code{parameterize}. | |
2370 | @end deffn | |
2371 | ||
2372 | @defun with-parameters* param-list value-list thunk | |
2373 | Establish a new dynamic scope, as per @code{parameterize} above, | |
2374 | taking parameters from @var{param-list} and corresponding values from | |
2375 | @var{values-list}. A call @code{(@var{thunk})} is made in the new | |
2376 | scope and the result from that @var{thunk} is the return from | |
2377 | @code{with-parameters*}. | |
2378 | ||
2379 | This function is a Guile-specific addition to the SRFI, it's similar | |
2380 | to the core @code{with-fluids*} (@pxref{Fluids}). | |
2381 | @end defun | |
2382 | ||
2383 | ||
2384 | @sp 1 | |
2385 | Parameter objects are implemented using fluids (@pxref{Fluids}), so | |
2386 | each dynamic root has it's own parameter locations. That includes the | |
2387 | separate locations when outside any @code{parameterize} form. When a | |
2388 | parameter is created it gets a separate initial location in each | |
2389 | dynamic root, all initialized to the given @var{init} value. | |
2390 | ||
2391 | As alluded to above, because each thread is a separate dynamic root, | |
2392 | each thread has it's own locations behind parameter objects, and | |
2393 | changes in one thread are not visible to any other. When a new | |
2394 | dynamic root or thread is created, the values of parameters in the | |
2395 | originating context are copied, into new locations. | |
2396 | ||
2397 | SRFI-39 doesn't specify the interaction between parameter objects and | |
2398 | threads, so the threading behaviour described here should be regarded | |
2399 | as Guile-specific. | |
2400 | ||
2401 | ||
12991fed | 2402 | @c srfi-modules.texi ends here |
193239f1 KR |
2403 | |
2404 | @c Local Variables: | |
2405 | @c TeX-master: "guile.texi" | |
2406 | @c End: |