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 |
a0e07ba4 NJ |
40 | @end menu |
41 | ||
42 | ||
43 | @node About SRFI Usage | |
3229f68b | 44 | @subsection About SRFI Usage |
a0e07ba4 NJ |
45 | |
46 | @c FIXME::martin: Review me! | |
47 | ||
48 | SRFI support in Guile is currently implemented partly in the core | |
49 | library, and partly as add-on modules. That means that some SRFIs are | |
50 | automatically available when the interpreter is started, whereas the | |
51 | other SRFIs require you to use the appropriate support module | |
12991fed | 52 | explicitly. |
a0e07ba4 NJ |
53 | |
54 | There are several reasons for this inconsistency. First, the feature | |
55 | checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be | |
56 | available immediately, because it must be there when the user wants to | |
57 | check for the Scheme implementation, that is, before she can know that | |
58 | it is safe to use @code{use-modules} to load SRFI support modules. The | |
59 | second reason is that some features defined in SRFIs had been | |
60 | implemented in Guile before the developers started to add SRFI | |
61 | implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In | |
62 | the future, it is possible that SRFIs in the core library might be | |
63 | factored out into separate modules, requiring explicit module loading | |
64 | when they are needed. So you should be prepared to have to use | |
65 | @code{use-modules} someday in the future to access SRFI-6 bindings. If | |
66 | you want, you can do that already. We have included the module | |
67 | @code{(srfi srfi-6)} in the distribution, which currently does nothing, | |
68 | but ensures that you can write future-safe code. | |
69 | ||
70 | Generally, support for a specific SRFI is made available by using | |
71 | modules named @code{(srfi srfi-@var{number})}, where @var{number} is the | |
72 | number of the SRFI needed. Another possibility is to use the command | |
73 | line option @code{--use-srfi}, which will load the necessary modules | |
74 | automatically (@pxref{Invoking Guile}). | |
75 | ||
76 | ||
77 | @node SRFI-0 | |
3229f68b | 78 | @subsection SRFI-0 - cond-expand |
8742c48b | 79 | @cindex SRFI-0 |
a0e07ba4 | 80 | |
5eef0f61 KR |
81 | This SRFI lets a portable Scheme program test for the presence of |
82 | certain features, and adapt itself by using different blocks of code, | |
83 | or fail if the necessary features are not available. There's no | |
84 | module to load, this is in the Guile core. | |
a0e07ba4 | 85 | |
5eef0f61 KR |
86 | A program designed only for Guile will generally not need this |
87 | mechanism, such a program can of course directly use the various | |
88 | documented parts of Guile. | |
a0e07ba4 | 89 | |
5eef0f61 KR |
90 | @deffn syntax cond-expand (feature body@dots{}) @dots{} |
91 | Expand to the @var{body} of the first clause whose @var{feature} | |
92 | specification is satisfied. It is an error if no @var{feature} is | |
a0e07ba4 NJ |
93 | satisfied. |
94 | ||
5eef0f61 KR |
95 | Features are symbols such as @code{srfi-1}, and a feature |
96 | specification can use @code{and}, @code{or} and @code{not} forms to | |
97 | test combinations. The last clause can be an @code{else}, to be used | |
98 | if no other passes. | |
a0e07ba4 | 99 | |
5eef0f61 KR |
100 | For example, define a private version of @code{alist-cons} if SRFI-1 |
101 | is not available. | |
a0e07ba4 | 102 | |
5eef0f61 KR |
103 | @example |
104 | (cond-expand (srfi-1 | |
105 | ) | |
106 | (else | |
107 | (define (alist-cons key val alist) | |
108 | (cons (cons key val) alist)))) | |
109 | @end example | |
a0e07ba4 | 110 | |
5eef0f61 KR |
111 | Or demand a certain set of SRFIs (list operations, string ports, |
112 | @code{receive} and string operations), failing if they're not | |
113 | available. | |
a0e07ba4 | 114 | |
5eef0f61 KR |
115 | @example |
116 | (cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13) | |
117 | )) | |
118 | @end example | |
119 | @end deffn | |
a0e07ba4 | 120 | |
5eef0f61 KR |
121 | The Guile core provides features @code{guile}, @code{r5rs}, |
122 | @code{srfi-0} and @code{srfi-6} initially. Other SRFI feature symbols | |
123 | are defined once their code has been loaded with @code{use-modules}, | |
124 | since only then are their bindings available. | |
a0e07ba4 | 125 | |
5eef0f61 KR |
126 | The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is |
127 | a good way to load SRFIs to satisfy @code{cond-expand} when running a | |
128 | portable program. | |
a0e07ba4 | 129 | |
5eef0f61 KR |
130 | Testing the @code{guile} feature allows a program to adapt itself to |
131 | the Guile module system, but still run on other Scheme systems. For | |
132 | example the following demands SRFI-8 (@code{receive}), but also knows | |
133 | how to load it with the Guile mechanism. | |
a0e07ba4 NJ |
134 | |
135 | @example | |
5eef0f61 KR |
136 | (cond-expand (srfi-8 |
137 | ) | |
138 | (guile | |
139 | (use-modules (srfi srfi-8)))) | |
a0e07ba4 NJ |
140 | @end example |
141 | ||
5eef0f61 KR |
142 | It should be noted that @code{cond-expand} is separate from the |
143 | @code{*features*} mechanism (@pxref{Feature Tracking}), feature | |
144 | symbols in one are unrelated to those in the other. | |
a0e07ba4 NJ |
145 | |
146 | ||
147 | @node SRFI-1 | |
3229f68b | 148 | @subsection SRFI-1 - List library |
8742c48b | 149 | @cindex SRFI-1 |
a0e07ba4 NJ |
150 | |
151 | @c FIXME::martin: Review me! | |
152 | ||
153 | The list library defined in SRFI-1 contains a lot of useful list | |
154 | processing procedures for construction, examining, destructuring and | |
155 | manipulating lists and pairs. | |
156 | ||
157 | Since SRFI-1 also defines some procedures which are already contained | |
158 | in R5RS and thus are supported by the Guile core library, some list | |
159 | and pair procedures which appear in the SRFI-1 document may not appear | |
160 | in this section. So when looking for a particular list/pair | |
161 | processing procedure, you should also have a look at the sections | |
162 | @ref{Lists} and @ref{Pairs}. | |
163 | ||
164 | @menu | |
165 | * SRFI-1 Constructors:: Constructing new lists. | |
166 | * SRFI-1 Predicates:: Testing list for specific properties. | |
167 | * SRFI-1 Selectors:: Selecting elements from lists. | |
168 | * SRFI-1 Length Append etc:: Length calculation and list appending. | |
169 | * SRFI-1 Fold and Map:: Higher-order list processing. | |
170 | * SRFI-1 Filtering and Partitioning:: Filter lists based on predicates. | |
85a9b4ed | 171 | * SRFI-1 Searching:: Search for elements. |
a0e07ba4 NJ |
172 | * SRFI-1 Deleting:: Delete elements from lists. |
173 | * SRFI-1 Association Lists:: Handle association lists. | |
174 | * SRFI-1 Set Operations:: Use lists for representing sets. | |
175 | @end menu | |
176 | ||
177 | @node SRFI-1 Constructors | |
3229f68b | 178 | @subsubsection Constructors |
a0e07ba4 NJ |
179 | |
180 | @c FIXME::martin: Review me! | |
181 | ||
182 | New lists can be constructed by calling one of the following | |
183 | procedures. | |
184 | ||
8f85c0c6 | 185 | @deffn {Scheme Procedure} xcons d a |
a0e07ba4 NJ |
186 | Like @code{cons}, but with interchanged arguments. Useful mostly when |
187 | passed to higher-order procedures. | |
188 | @end deffn | |
189 | ||
8f85c0c6 | 190 | @deffn {Scheme Procedure} list-tabulate n init-proc |
a0e07ba4 NJ |
191 | Return an @var{n}-element list, where each list element is produced by |
192 | applying the procedure @var{init-proc} to the corresponding list | |
193 | index. The order in which @var{init-proc} is applied to the indices | |
194 | is not specified. | |
195 | @end deffn | |
196 | ||
57066448 KR |
197 | @deffn {Scheme Procedure} list-copy lst |
198 | Return a new list containing the elements of the list @var{lst}. | |
199 | ||
200 | This function differs from the core @code{list-copy} (@pxref{List | |
201 | Constructors}) in accepting improper lists too. And if @var{lst} is | |
202 | not a pair at all then it's treated as the final tail of an improper | |
203 | list and simply returned. | |
204 | @end deffn | |
205 | ||
8f85c0c6 | 206 | @deffn {Scheme Procedure} circular-list elt1 elt2 @dots{} |
a0e07ba4 NJ |
207 | Return a circular list containing the given arguments @var{elt1} |
208 | @var{elt2} @dots{}. | |
209 | @end deffn | |
210 | ||
8f85c0c6 | 211 | @deffn {Scheme Procedure} iota count [start step] |
256853db KR |
212 | Return a list containing @var{count} numbers, starting from |
213 | @var{start} and adding @var{step} each time. The default @var{start} | |
214 | is 0, the default @var{step} is 1. For example, | |
a0e07ba4 | 215 | |
256853db KR |
216 | @example |
217 | (iota 6) @result{} (0 1 2 3 4 5) | |
218 | (iota 4 2.5 -2) @result{} (2.5 0.5 -1.5 -3.5) | |
219 | @end example | |
a0e07ba4 | 220 | |
256853db KR |
221 | This function takes its name from the corresponding primitive in the |
222 | APL language. | |
a0e07ba4 NJ |
223 | @end deffn |
224 | ||
225 | ||
226 | @node SRFI-1 Predicates | |
3229f68b | 227 | @subsubsection Predicates |
a0e07ba4 NJ |
228 | |
229 | @c FIXME::martin: Review me! | |
230 | ||
231 | The procedures in this section test specific properties of lists. | |
232 | ||
8f85c0c6 | 233 | @deffn {Scheme Procedure} proper-list? obj |
a0e07ba4 NJ |
234 | Return @code{#t} if @var{obj} is a proper list, that is a finite list, |
235 | terminated with the empty list. Otherwise, return @code{#f}. | |
236 | @end deffn | |
237 | ||
8f85c0c6 | 238 | @deffn {Scheme Procedure} circular-list? obj |
a0e07ba4 NJ |
239 | Return @code{#t} if @var{obj} is a circular list, otherwise return |
240 | @code{#f}. | |
241 | @end deffn | |
242 | ||
8f85c0c6 | 243 | @deffn {Scheme Procedure} dotted-list? obj |
a0e07ba4 NJ |
244 | Return @code{#t} if @var{obj} is a dotted list, return @code{#f} |
245 | otherwise. A dotted list is a finite list which is not terminated by | |
246 | the empty list, but some other value. | |
247 | @end deffn | |
248 | ||
8f85c0c6 | 249 | @deffn {Scheme Procedure} null-list? lst |
a0e07ba4 NJ |
250 | Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f} |
251 | otherwise. If something else than a proper or circular list is passed | |
85a9b4ed | 252 | as @var{lst}, an error is signalled. This procedure is recommended |
a0e07ba4 NJ |
253 | for checking for the end of a list in contexts where dotted lists are |
254 | not allowed. | |
255 | @end deffn | |
256 | ||
8f85c0c6 | 257 | @deffn {Scheme Procedure} not-pair? obj |
a0e07ba4 NJ |
258 | Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise. |
259 | This is shorthand notation @code{(not (pair? @var{obj}))} and is | |
260 | supposed to be used for end-of-list checking in contexts where dotted | |
261 | lists are allowed. | |
262 | @end deffn | |
263 | ||
8f85c0c6 | 264 | @deffn {Scheme Procedure} list= elt= list1 @dots{} |
a0e07ba4 NJ |
265 | Return @code{#t} if all argument lists are equal, @code{#f} otherwise. |
266 | List equality is determined by testing whether all lists have the same | |
267 | length and the corresponding elements are equal in the sense of the | |
268 | equality predicate @var{elt=}. If no or only one list is given, | |
269 | @code{#t} is returned. | |
270 | @end deffn | |
271 | ||
272 | ||
273 | @node SRFI-1 Selectors | |
3229f68b | 274 | @subsubsection Selectors |
a0e07ba4 NJ |
275 | |
276 | @c FIXME::martin: Review me! | |
277 | ||
8f85c0c6 NJ |
278 | @deffn {Scheme Procedure} first pair |
279 | @deffnx {Scheme Procedure} second pair | |
280 | @deffnx {Scheme Procedure} third pair | |
281 | @deffnx {Scheme Procedure} fourth pair | |
282 | @deffnx {Scheme Procedure} fifth pair | |
283 | @deffnx {Scheme Procedure} sixth pair | |
284 | @deffnx {Scheme Procedure} seventh pair | |
285 | @deffnx {Scheme Procedure} eighth pair | |
286 | @deffnx {Scheme Procedure} ninth pair | |
287 | @deffnx {Scheme Procedure} tenth pair | |
a0e07ba4 NJ |
288 | These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}. |
289 | @end deffn | |
290 | ||
8f85c0c6 | 291 | @deffn {Scheme Procedure} car+cdr pair |
a0e07ba4 NJ |
292 | Return two values, the @sc{car} and the @sc{cdr} of @var{pair}. |
293 | @end deffn | |
294 | ||
8f85c0c6 NJ |
295 | @deffn {Scheme Procedure} take lst i |
296 | @deffnx {Scheme Procedure} take! lst i | |
a0e07ba4 NJ |
297 | Return a list containing the first @var{i} elements of @var{lst}. |
298 | ||
299 | @code{take!} may modify the structure of the argument list @var{lst} | |
300 | in order to produce the result. | |
301 | @end deffn | |
302 | ||
8f85c0c6 | 303 | @deffn {Scheme Procedure} drop lst i |
a0e07ba4 NJ |
304 | Return a list containing all but the first @var{i} elements of |
305 | @var{lst}. | |
306 | @end deffn | |
307 | ||
8f85c0c6 | 308 | @deffn {Scheme Procedure} take-right lst i |
a0e07ba4 NJ |
309 | Return the a list containing the @var{i} last elements of @var{lst}. |
310 | @end deffn | |
311 | ||
8f85c0c6 NJ |
312 | @deffn {Scheme Procedure} drop-right lst i |
313 | @deffnx {Scheme Procedure} drop-right! lst i | |
a0e07ba4 NJ |
314 | Return the a list containing all but the @var{i} last elements of |
315 | @var{lst}. | |
316 | ||
317 | @code{drop-right!} may modify the structure of the argument list | |
318 | @var{lst} in order to produce the result. | |
319 | @end deffn | |
320 | ||
8f85c0c6 NJ |
321 | @deffn {Scheme Procedure} split-at lst i |
322 | @deffnx {Scheme Procedure} split-at! lst i | |
a0e07ba4 NJ |
323 | Return two values, a list containing the first @var{i} elements of the |
324 | list @var{lst} and a list containing the remaining elements. | |
325 | ||
326 | @code{split-at!} may modify the structure of the argument list | |
327 | @var{lst} in order to produce the result. | |
328 | @end deffn | |
329 | ||
8f85c0c6 | 330 | @deffn {Scheme Procedure} last lst |
a0e07ba4 NJ |
331 | Return the last element of the non-empty, finite list @var{lst}. |
332 | @end deffn | |
333 | ||
334 | ||
335 | @node SRFI-1 Length Append etc | |
3229f68b | 336 | @subsubsection Length, Append, Concatenate, etc. |
a0e07ba4 NJ |
337 | |
338 | @c FIXME::martin: Review me! | |
339 | ||
8f85c0c6 | 340 | @deffn {Scheme Procedure} length+ lst |
a0e07ba4 NJ |
341 | Return the length of the argument list @var{lst}. When @var{lst} is a |
342 | circular list, @code{#f} is returned. | |
343 | @end deffn | |
344 | ||
8f85c0c6 NJ |
345 | @deffn {Scheme Procedure} concatenate list-of-lists |
346 | @deffnx {Scheme Procedure} concatenate! list-of-lists | |
a0e07ba4 NJ |
347 | Construct a list by appending all lists in @var{list-of-lists}. |
348 | ||
349 | @code{concatenate!} may modify the structure of the given lists in | |
350 | order to produce the result. | |
351 | @end deffn | |
352 | ||
8f85c0c6 NJ |
353 | @deffn {Scheme Procedure} append-reverse rev-head tail |
354 | @deffnx {Scheme Procedure} append-reverse! rev-head tail | |
a0e07ba4 NJ |
355 | Reverse @var{rev-head}, append @var{tail} and return the result. This |
356 | is equivalent to @code{(append (reverse @var{rev-head}) @var{tail})}, | |
357 | but more efficient. | |
358 | ||
359 | @code{append-reverse!} may modify @var{rev-head} in order to produce | |
360 | the result. | |
361 | @end deffn | |
362 | ||
8f85c0c6 | 363 | @deffn {Scheme Procedure} zip lst1 lst2 @dots{} |
a0e07ba4 NJ |
364 | Return a list as long as the shortest of the argument lists, where |
365 | each element is a list. The first list contains the first elements of | |
366 | the argument lists, the second list contains the second elements, and | |
367 | so on. | |
368 | @end deffn | |
369 | ||
8f85c0c6 NJ |
370 | @deffn {Scheme Procedure} unzip1 lst |
371 | @deffnx {Scheme Procedure} unzip2 lst | |
372 | @deffnx {Scheme Procedure} unzip3 lst | |
373 | @deffnx {Scheme Procedure} unzip4 lst | |
374 | @deffnx {Scheme Procedure} unzip5 lst | |
a0e07ba4 NJ |
375 | @code{unzip1} takes a list of lists, and returns a list containing the |
376 | first elements of each list, @code{unzip2} returns two lists, the | |
377 | first containing the first elements of each lists and the second | |
378 | containing the second elements of each lists, and so on. | |
379 | @end deffn | |
380 | ||
e508c863 KR |
381 | @deffn {Scheme Procedure} count pred lst1 @dots{} lstN |
382 | Return a count of the number of times @var{pred} returns true when | |
383 | called on elements from the given lists. | |
384 | ||
385 | @var{pred} is called with @var{N} parameters @code{(@var{pred} | |
386 | @var{elem1} @dots{} @var{elemN})}, each element being from the | |
387 | corresponding @var{lst1} @dots{} @var{lstN}. The first call is with | |
388 | the first element of each list, the second with the second element | |
389 | from each, and so on. | |
390 | ||
391 | Counting stops when the end of the shortest list is reached. At least | |
392 | one list must be non-circular. | |
393 | @end deffn | |
394 | ||
a0e07ba4 NJ |
395 | |
396 | @node SRFI-1 Fold and Map | |
3229f68b | 397 | @subsubsection Fold, Unfold & Map |
a0e07ba4 NJ |
398 | |
399 | @c FIXME::martin: Review me! | |
400 | ||
8f85c0c6 | 401 | @deffn {Scheme Procedure} fold kons knil lst1 lst2 @dots{} |
a0e07ba4 NJ |
402 | Fold the procedure @var{kons} across all elements of @var{lst1}, |
403 | @var{lst2}, @dots{}. Produce the result of | |
404 | ||
405 | @code{(@var{kons} @var{en1} @var{en2} @dots{} (@var{kons} @var{e21} | |
406 | @var{e22} (@var{kons} @var{e11} @var{e12} @var{knil})))}, | |
407 | ||
408 | if @var{enm} are the elements of the lists @var{lst1}, @var{lst2}, | |
409 | @dots{}. | |
410 | @end deffn | |
411 | ||
8f85c0c6 | 412 | @deffn {Scheme Procedure} fold-right kons knil lst1 lst2 @dots{} |
a0e07ba4 NJ |
413 | Similar to @code{fold}, but applies @var{kons} in right-to-left order |
414 | to the list elements, that is: | |
415 | ||
416 | @code{(@var{kons} @var{e11} @var{e12}(@var{kons} @var{e21} | |
417 | @var{e22} @dots{} (@var{kons} @var{en1} @var{en2} @var{knil})))}, | |
418 | @end deffn | |
419 | ||
8f85c0c6 | 420 | @deffn {Scheme Procedure} pair-fold kons knil lst1 lst2 @dots{} |
a0e07ba4 NJ |
421 | Like @code{fold}, but apply @var{kons} to the pairs of the list |
422 | instead of the list elements. | |
423 | @end deffn | |
424 | ||
8f85c0c6 | 425 | @deffn {Scheme Procedure} pair-fold-right kons knil lst1 lst2 @dots{} |
a0e07ba4 NJ |
426 | Like @code{fold-right}, but apply @var{kons} to the pairs of the list |
427 | instead of the list elements. | |
428 | @end deffn | |
429 | ||
8f85c0c6 | 430 | @deffn {Scheme Procedure} reduce f ridentity lst |
1ae7b878 KR |
431 | @code{reduce} is a variant of @code{fold}. If @var{lst} is |
432 | @code{()}, @var{ridentity} is returned. Otherwise, @code{(fold f (car | |
a0e07ba4 NJ |
433 | @var{lst}) (cdr @var{lst}))} is returned. |
434 | @end deffn | |
435 | ||
8f85c0c6 | 436 | @deffn {Scheme Procedure} reduce-right f ridentity lst |
b5aa0215 | 437 | This is the @code{fold-right} variant of @code{reduce}. |
a0e07ba4 NJ |
438 | @end deffn |
439 | ||
8f85c0c6 | 440 | @deffn {Scheme Procedure} unfold p f g seed [tail-gen] |
a0e07ba4 NJ |
441 | @code{unfold} is defined as follows: |
442 | ||
443 | @lisp | |
444 | (unfold p f g seed) = | |
445 | (if (p seed) (tail-gen seed) | |
446 | (cons (f seed) | |
447 | (unfold p f g (g seed)))) | |
448 | @end lisp | |
449 | ||
450 | @table @var | |
451 | @item p | |
452 | Determines when to stop unfolding. | |
453 | ||
454 | @item f | |
455 | Maps each seed value to the corresponding list element. | |
456 | ||
457 | @item g | |
458 | Maps each seed value to next seed valu. | |
459 | ||
460 | @item seed | |
461 | The state value for the unfold. | |
462 | ||
463 | @item tail-gen | |
464 | Creates the tail of the list; defaults to @code{(lambda (x) '())}. | |
465 | @end table | |
466 | ||
467 | @var{g} produces a series of seed values, which are mapped to list | |
468 | elements by @var{f}. These elements are put into a list in | |
469 | left-to-right order, and @var{p} tells when to stop unfolding. | |
470 | @end deffn | |
471 | ||
8f85c0c6 | 472 | @deffn {Scheme Procedure} unfold-right p f g seed [tail] |
a0e07ba4 NJ |
473 | Construct a list with the following loop. |
474 | ||
475 | @lisp | |
476 | (let lp ((seed seed) (lis tail)) | |
477 | (if (p seed) lis | |
478 | (lp (g seed) | |
479 | (cons (f seed) lis)))) | |
480 | @end lisp | |
481 | ||
482 | @table @var | |
483 | @item p | |
484 | Determines when to stop unfolding. | |
485 | ||
486 | @item f | |
487 | Maps each seed value to the corresponding list element. | |
488 | ||
489 | @item g | |
490 | Maps each seed value to next seed valu. | |
491 | ||
492 | @item seed | |
493 | The state value for the unfold. | |
494 | ||
495 | @item tail-gen | |
496 | Creates the tail of the list; defaults to @code{(lambda (x) '())}. | |
497 | @end table | |
498 | ||
499 | @end deffn | |
500 | ||
8f85c0c6 | 501 | @deffn {Scheme Procedure} map f lst1 lst2 @dots{} |
a0e07ba4 NJ |
502 | Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and |
503 | return a list containing the results of the procedure applications. | |
504 | This procedure is extended with respect to R5RS, because the argument | |
505 | lists may have different lengths. The result list will have the same | |
506 | length as the shortest argument lists. The order in which @var{f} | |
507 | will be applied to the list element(s) is not specified. | |
508 | @end deffn | |
509 | ||
8f85c0c6 | 510 | @deffn {Scheme Procedure} for-each f lst1 lst2 @dots{} |
a0e07ba4 NJ |
511 | Apply the procedure @var{f} to each pair of corresponding elements of |
512 | the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not | |
513 | specified. This procedure is extended with respect to R5RS, because | |
514 | the argument lists may have different lengths. The shortest argument | |
515 | list determines the number of times @var{f} is called. @var{f} will | |
85a9b4ed | 516 | be applied to the list elements in left-to-right order. |
a0e07ba4 NJ |
517 | |
518 | @end deffn | |
519 | ||
8f85c0c6 NJ |
520 | @deffn {Scheme Procedure} append-map f lst1 lst2 @dots{} |
521 | @deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{} | |
12991fed | 522 | Equivalent to |
a0e07ba4 NJ |
523 | |
524 | @lisp | |
12991fed | 525 | (apply append (map f clist1 clist2 ...)) |
a0e07ba4 NJ |
526 | @end lisp |
527 | ||
12991fed | 528 | and |
a0e07ba4 NJ |
529 | |
530 | @lisp | |
12991fed | 531 | (apply append! (map f clist1 clist2 ...)) |
a0e07ba4 NJ |
532 | @end lisp |
533 | ||
534 | Map @var{f} over the elements of the lists, just as in the @code{map} | |
535 | function. However, the results of the applications are appended | |
536 | together to make the final result. @code{append-map} uses | |
537 | @code{append} to append the results together; @code{append-map!} uses | |
538 | @code{append!}. | |
539 | ||
540 | The dynamic order in which the various applications of @var{f} are | |
541 | made is not specified. | |
542 | @end deffn | |
543 | ||
8f85c0c6 | 544 | @deffn {Scheme Procedure} map! f lst1 lst2 @dots{} |
a0e07ba4 NJ |
545 | Linear-update variant of @code{map} -- @code{map!} is allowed, but not |
546 | required, to alter the cons cells of @var{lst1} to construct the | |
547 | result list. | |
548 | ||
549 | The dynamic order in which the various applications of @var{f} are | |
550 | made is not specified. In the n-ary case, @var{lst2}, @var{lst3}, | |
551 | @dots{} must have at least as many elements as @var{lst1}. | |
552 | @end deffn | |
553 | ||
8f85c0c6 | 554 | @deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{} |
a0e07ba4 NJ |
555 | Like @code{for-each}, but applies the procedure @var{f} to the pairs |
556 | from which the argument lists are constructed, instead of the list | |
557 | elements. The return value is not specified. | |
558 | @end deffn | |
559 | ||
8f85c0c6 | 560 | @deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{} |
a0e07ba4 NJ |
561 | Like @code{map}, but only results from the applications of @var{f} |
562 | which are true are saved in the result list. | |
563 | @end deffn | |
564 | ||
565 | ||
566 | @node SRFI-1 Filtering and Partitioning | |
3229f68b | 567 | @subsubsection Filtering and Partitioning |
a0e07ba4 NJ |
568 | |
569 | @c FIXME::martin: Review me! | |
570 | ||
571 | Filtering means to collect all elements from a list which satisfy a | |
572 | specific condition. Partitioning a list means to make two groups of | |
573 | list elements, one which contains the elements satisfying a condition, | |
574 | and the other for the elements which don't. | |
575 | ||
60e25dc4 KR |
576 | The @code{filter} and @code{filter!} functions are implemented in the |
577 | Guile core, @xref{List Modification}. | |
a0e07ba4 | 578 | |
8f85c0c6 NJ |
579 | @deffn {Scheme Procedure} partition pred lst |
580 | @deffnx {Scheme Procedure} partition! pred lst | |
193239f1 KR |
581 | Split @var{lst} into those elements which do and don't satisfy the |
582 | predicate @var{pred}. | |
a0e07ba4 | 583 | |
193239f1 KR |
584 | The return is two values (@pxref{Multiple Values}), the first being a |
585 | list of all elements from @var{lst} which satisfy @var{pred}, the | |
586 | second a list of those which do not. | |
587 | ||
588 | The elements in the result lists are in the same order as in @var{lst} | |
589 | but the order in which the calls @code{(@var{pred} elem)} are made on | |
590 | the list elements is unspecified. | |
591 | ||
592 | @code{partition} does not change @var{lst}, but one of the returned | |
593 | lists may share a tail with it. @code{partition!} may modify | |
594 | @var{lst} to construct its return. | |
a0e07ba4 NJ |
595 | @end deffn |
596 | ||
8f85c0c6 NJ |
597 | @deffn {Scheme Procedure} remove pred lst |
598 | @deffnx {Scheme Procedure} remove! pred lst | |
a0e07ba4 NJ |
599 | Return a list containing all elements from @var{lst} which do not |
600 | satisfy the predicate @var{pred}. The elements in the result list | |
601 | have the same order as in @var{lst}. The order in which @var{pred} is | |
602 | applied to the list elements is not specified. | |
603 | ||
604 | @code{remove!} is allowed, but not required to modify the structure of | |
605 | the input list. | |
606 | @end deffn | |
607 | ||
608 | ||
609 | @node SRFI-1 Searching | |
3229f68b | 610 | @subsubsection Searching |
a0e07ba4 NJ |
611 | |
612 | @c FIXME::martin: Review me! | |
613 | ||
614 | The procedures for searching elements in lists either accept a | |
615 | predicate or a comparison object for determining which elements are to | |
616 | be searched. | |
617 | ||
8f85c0c6 | 618 | @deffn {Scheme Procedure} find pred lst |
a0e07ba4 NJ |
619 | Return the first element of @var{lst} which satisfies the predicate |
620 | @var{pred} and @code{#f} if no such element is found. | |
621 | @end deffn | |
622 | ||
8f85c0c6 | 623 | @deffn {Scheme Procedure} find-tail pred lst |
a0e07ba4 NJ |
624 | Return the first pair of @var{lst} whose @sc{car} satisfies the |
625 | predicate @var{pred} and @code{#f} if no such element is found. | |
626 | @end deffn | |
627 | ||
8f85c0c6 NJ |
628 | @deffn {Scheme Procedure} take-while pred lst |
629 | @deffnx {Scheme Procedure} take-while! pred lst | |
a0e07ba4 NJ |
630 | Return the longest initial prefix of @var{lst} whose elements all |
631 | satisfy the predicate @var{pred}. | |
632 | ||
633 | @code{take-while!} is allowed, but not required to modify the input | |
634 | list while producing the result. | |
635 | @end deffn | |
636 | ||
8f85c0c6 | 637 | @deffn {Scheme Procedure} drop-while pred lst |
a0e07ba4 NJ |
638 | Drop the longest initial prefix of @var{lst} whose elements all |
639 | satisfy the predicate @var{pred}. | |
640 | @end deffn | |
641 | ||
8f85c0c6 NJ |
642 | @deffn {Scheme Procedure} span pred lst |
643 | @deffnx {Scheme Procedure} span! pred lst | |
644 | @deffnx {Scheme Procedure} break pred lst | |
645 | @deffnx {Scheme Procedure} break! pred lst | |
a0e07ba4 NJ |
646 | @code{span} splits the list @var{lst} into the longest initial prefix |
647 | whose elements all satisfy the predicate @var{pred}, and the remaining | |
648 | tail. @code{break} inverts the sense of the predicate. | |
649 | ||
650 | @code{span!} and @code{break!} are allowed, but not required to modify | |
651 | the structure of the input list @var{lst} in order to produce the | |
652 | result. | |
3e73b6f9 KR |
653 | |
654 | Note that the name @code{break} conflicts with the @code{break} | |
655 | binding established by @code{while} (@pxref{while do}). Applications | |
656 | wanting to use @code{break} from within a @code{while} loop will need | |
657 | to make a new define under a different name. | |
a0e07ba4 NJ |
658 | @end deffn |
659 | ||
8f85c0c6 | 660 | @deffn {Scheme Procedure} any pred lst1 lst2 @dots{} |
a0e07ba4 NJ |
661 | Apply @var{pred} across the lists and return a true value if the |
662 | predicate returns true for any of the list elements(s); return | |
663 | @code{#f} otherwise. The true value returned is always the result of | |
85a9b4ed | 664 | the first successful application of @var{pred}. |
a0e07ba4 NJ |
665 | @end deffn |
666 | ||
8f85c0c6 | 667 | @deffn {Scheme Procedure} every pred lst1 lst2 @dots{} |
a0e07ba4 NJ |
668 | Apply @var{pred} across the lists and return a true value if the |
669 | predicate returns true for every of the list elements(s); return | |
670 | @code{#f} otherwise. The true value returned is always the result of | |
85a9b4ed | 671 | the final successful application of @var{pred}. |
a0e07ba4 NJ |
672 | @end deffn |
673 | ||
8f85c0c6 | 674 | @deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{} |
a0e07ba4 NJ |
675 | Return the index of the leftmost element that satisfies @var{pred}. |
676 | @end deffn | |
677 | ||
8f85c0c6 | 678 | @deffn {Scheme Procedure} member x lst [=] |
a0e07ba4 NJ |
679 | Return the first sublist of @var{lst} whose @sc{car} is equal to |
680 | @var{x}. If @var{x} does no appear in @var{lst}, return @code{#f}. | |
681 | Equality is determined by the equality predicate @var{=}, or | |
682 | @code{equal?} if @var{=} is not given. | |
ea6ea01b KR |
683 | |
684 | This function extends the core @code{member} by accepting an equality | |
685 | predicate. (@pxref{List Searching}) | |
a0e07ba4 NJ |
686 | @end deffn |
687 | ||
688 | ||
689 | @node SRFI-1 Deleting | |
3229f68b | 690 | @subsubsection Deleting |
a0e07ba4 NJ |
691 | |
692 | @c FIXME::martin: Review me! | |
693 | ||
8f85c0c6 NJ |
694 | @deffn {Scheme Procedure} delete x lst [=] |
695 | @deffnx {Scheme Procedure} delete! x lst [=] | |
b6b9376a KR |
696 | Return a list containing the elements of @var{lst} but with those |
697 | equal to @var{x} deleted. The returned elements will be in the same | |
698 | order as they were in @var{lst}. | |
699 | ||
700 | Equality is determined by the @var{=} predicate, or @code{equal?} if | |
701 | not given. An equality call is made just once for each element, but | |
702 | the order in which the calls are made on the elements is unspecified. | |
a0e07ba4 | 703 | |
243bdb63 | 704 | The equality calls are always @code{(= x elem)}, ie.@: the given @var{x} |
b6b9376a KR |
705 | is first. This means for instance elements greater than 5 can be |
706 | deleted with @code{(delete 5 lst <)}. | |
707 | ||
708 | @code{delete} does not modify @var{lst}, but the return might share a | |
709 | common tail with @var{lst}. @code{delete!} may modify the structure | |
710 | of @var{lst} to construct its return. | |
ea6ea01b KR |
711 | |
712 | These functions extend the core @code{delete} and @code{delete!} in | |
713 | accepting an equality predicate. (@pxref{List Modification}) | |
a0e07ba4 NJ |
714 | @end deffn |
715 | ||
8f85c0c6 NJ |
716 | @deffn {Scheme Procedure} delete-duplicates lst [=] |
717 | @deffnx {Scheme Procedure} delete-duplicates! lst [=] | |
b6b9376a KR |
718 | Return a list containing the elements of @var{lst} but without |
719 | duplicates. | |
720 | ||
721 | When elements are equal, only the first in @var{lst} is retained. | |
722 | Equal elements can be anywhere in @var{lst}, they don't have to be | |
723 | adjacent. The returned list will have the retained elements in the | |
724 | same order as they were in @var{lst}. | |
725 | ||
726 | Equality is determined by the @var{=} predicate, or @code{equal?} if | |
727 | not given. Calls @code{(= x y)} are made with element @var{x} being | |
728 | before @var{y} in @var{lst}. A call is made at most once for each | |
729 | combination, but the sequence of the calls across the elements is | |
730 | unspecified. | |
731 | ||
732 | @code{delete-duplicates} does not modify @var{lst}, but the return | |
733 | might share a common tail with @var{lst}. @code{delete-duplicates!} | |
734 | may modify the structure of @var{lst} to construct its return. | |
735 | ||
736 | In the worst case, this is an @math{O(N^2)} algorithm because it must | |
737 | check each element against all those preceding it. For long lists it | |
738 | is more efficient to sort and then compare only adjacent elements. | |
a0e07ba4 NJ |
739 | @end deffn |
740 | ||
741 | ||
742 | @node SRFI-1 Association Lists | |
3229f68b | 743 | @subsubsection Association Lists |
a0e07ba4 NJ |
744 | |
745 | @c FIXME::martin: Review me! | |
746 | ||
747 | Association lists are described in detail in section @ref{Association | |
748 | Lists}. The present section only documents the additional procedures | |
749 | for dealing with association lists defined by SRFI-1. | |
750 | ||
8f85c0c6 | 751 | @deffn {Scheme Procedure} assoc key alist [=] |
a0e07ba4 NJ |
752 | Return the pair from @var{alist} which matches @var{key}. Equality is |
753 | determined by @var{=}, which defaults to @code{equal?} if not given. | |
754 | @var{alist} must be an association lists---a list of pairs. | |
ea6ea01b KR |
755 | |
756 | This function extends the core @code{assoc} by accepting an equality | |
757 | predicate. (@pxref{Association Lists}) | |
a0e07ba4 NJ |
758 | @end deffn |
759 | ||
8f85c0c6 | 760 | @deffn {Scheme Procedure} alist-cons key datum alist |
a0e07ba4 NJ |
761 | Equivalent to |
762 | ||
763 | @lisp | |
764 | (cons (cons @var{key} @var{datum}) @var{alist}) | |
765 | @end lisp | |
766 | ||
767 | This procedure is used to coons a new pair onto an existing | |
768 | association list. | |
769 | @end deffn | |
770 | ||
8f85c0c6 | 771 | @deffn {Scheme Procedure} alist-copy alist |
a0e07ba4 NJ |
772 | Return a newly allocated copy of @var{alist}, that means that the |
773 | spine of the list as well as the pairs are copied. | |
774 | @end deffn | |
775 | ||
8f85c0c6 NJ |
776 | @deffn {Scheme Procedure} alist-delete key alist [=] |
777 | @deffnx {Scheme Procedure} alist-delete! key alist [=] | |
bd35f1f0 KR |
778 | Return a list containing the elements of @var{alist} but with those |
779 | elements whose keys are equal to @var{key} deleted. The returned | |
780 | elements will be in the same order as they were in @var{alist}. | |
a0e07ba4 | 781 | |
bd35f1f0 KR |
782 | Equality is determined by the @var{=} predicate, or @code{equal?} if |
783 | not given. The order in which elements are tested is unspecified, but | |
784 | each equality call is made @code{(= key alistkey)}, ie. the given | |
785 | @var{key} parameter is first and the key from @var{alist} second. | |
786 | This means for instance all associations with a key greater than 5 can | |
787 | be removed with @code{(alist-delete 5 alist <)}. | |
788 | ||
789 | @code{alist-delete} does not modify @var{alist}, but the return might | |
790 | share a common tail with @var{alist}. @code{alist-delete!} may modify | |
791 | the list structure of @var{alist} to construct its return. | |
a0e07ba4 NJ |
792 | @end deffn |
793 | ||
794 | ||
795 | @node SRFI-1 Set Operations | |
3229f68b | 796 | @subsubsection Set Operations on Lists |
a0e07ba4 NJ |
797 | |
798 | @c FIXME::martin: Review me! | |
799 | ||
800 | Lists can be used for representing sets of objects. The procedures | |
801 | documented in this section can be used for such set representations. | |
85a9b4ed | 802 | Man combining several sets or adding elements, they make sure that no |
a0e07ba4 NJ |
803 | object is contained more than once in a given list. Please note that |
804 | lists are not a too efficient implementation method for sets, so if | |
805 | you need high performance, you should think about implementing a | |
806 | custom data structure for representing sets, such as trees, bitsets, | |
807 | hash tables or something similar. | |
808 | ||
809 | All these procedures accept an equality predicate as the first | |
810 | argument. This predicate is used for testing the objects in the list | |
811 | sets for sameness. | |
812 | ||
8f85c0c6 | 813 | @deffn {Scheme Procedure} lset<= = list1 @dots{} |
a0e07ba4 NJ |
814 | Return @code{#t} if every @var{listi} is a subset of @var{listi+1}, |
815 | otherwise return @code{#f}. Returns @code{#t} if called with less | |
816 | than two arguments. @var{=} is used for testing element equality. | |
817 | @end deffn | |
818 | ||
8f85c0c6 | 819 | @deffn {Scheme Procedure} lset= = list1 list2 @dots{} |
a0e07ba4 NJ |
820 | Return @code{#t} if all argument lists are equal. @var{=} is used for |
821 | testing element equality. | |
822 | @end deffn | |
823 | ||
8f85c0c6 NJ |
824 | @deffn {Scheme Procedure} lset-adjoin = list elt1 @dots{} |
825 | @deffnx {Scheme Procedure} lset-adjoin! = list elt1 @dots{} | |
a0e07ba4 NJ |
826 | Add all @var{elts} to the list @var{list}, suppressing duplicates and |
827 | return the resulting list. @code{lset-adjoin!} is allowed, but not | |
828 | required to modify its first argument. @var{=} is used for testing | |
829 | element equality. | |
830 | @end deffn | |
831 | ||
8f85c0c6 NJ |
832 | @deffn {Scheme Procedure} lset-union = list1 @dots{} |
833 | @deffnx {Scheme Procedure} lset-union! = list1 @dots{} | |
a0e07ba4 NJ |
834 | Return the union of all argument list sets. The union is the set of |
835 | all elements which appear in any of the argument sets. | |
836 | @code{lset-union!} is allowed, but not required to modify its first | |
837 | argument. @var{=} is used for testing element equality. | |
838 | @end deffn | |
839 | ||
8f85c0c6 NJ |
840 | @deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{} |
841 | @deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{} | |
a0e07ba4 NJ |
842 | Return the intersection of all argument list sets. The intersection |
843 | is the set containing all elements which appear in all argument sets. | |
844 | @code{lset-intersection!} is allowed, but not required to modify its | |
845 | first argument. @var{=} is used for testing element equality. | |
846 | @end deffn | |
847 | ||
8f85c0c6 NJ |
848 | @deffn {Scheme Procedure} lset-difference = list1 list2 @dots{} |
849 | @deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{} | |
a0e07ba4 NJ |
850 | Return the difference of all argument list sets. The difference is |
851 | the the set containing all elements of the first list which do not | |
852 | appear in the other lists. @code{lset-difference!} is allowed, but | |
853 | not required to modify its first argument. @var{=} is used for testing | |
854 | element equality. | |
855 | @end deffn | |
856 | ||
8f85c0c6 NJ |
857 | @deffn {Scheme Procedure} lset-xor = list1 @dots{} |
858 | @deffnx {Scheme Procedure} lset-xor! = list1 @dots{} | |
a0e07ba4 NJ |
859 | Return the set containing all elements which appear in the first |
860 | argument list set, but not in the second; or, more generally: which | |
861 | appear in an odd number of sets. @code{lset-xor!} is allowed, but | |
862 | not required to modify its first argument. @var{=} is used for testing | |
863 | element equality. | |
864 | @end deffn | |
865 | ||
8f85c0c6 NJ |
866 | @deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{} |
867 | @deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{} | |
a0e07ba4 NJ |
868 | Return two values, the difference and the intersection of the argument |
869 | list sets. This works like a combination of @code{lset-difference} and | |
870 | @code{lset-intersection}, but is more efficient. | |
871 | @code{lset-diff+intersection!} is allowed, but not required to modify | |
872 | its first argument. @var{=} is used for testing element equality. You | |
873 | have to use some means to deal with the multiple values these | |
874 | procedures return (@pxref{Multiple Values}). | |
875 | @end deffn | |
876 | ||
877 | ||
878 | @node SRFI-2 | |
3229f68b | 879 | @subsection SRFI-2 - and-let* |
8742c48b | 880 | @cindex SRFI-2 |
a0e07ba4 | 881 | |
4fd0db14 KR |
882 | @noindent |
883 | The following syntax can be obtained with | |
a0e07ba4 | 884 | |
4fd0db14 KR |
885 | @lisp |
886 | (use-modules (srfi srfi-2)) | |
887 | @end lisp | |
a0e07ba4 | 888 | |
4fd0db14 KR |
889 | @deffn {library syntax} and-let* (clause @dots{}) body @dots{} |
890 | A combination of @code{and} and @code{let*}. | |
891 | ||
892 | Each @var{clause} is evaluated in turn, and if @code{#f} is obtained | |
893 | then evaluation stops and @code{#f} is returned. If all are | |
894 | non-@code{#f} then @var{body} is evaluated and the last form gives the | |
895 | return value. Each @var{clause} should be one of the following, | |
896 | ||
897 | @table @code | |
898 | @item (symbol expr) | |
899 | Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}. | |
900 | Like @code{let*}, that binding is available to subsequent clauses. | |
901 | @item (expr) | |
902 | Evaluate @var{expr} and check for @code{#f}. | |
903 | @item symbol | |
904 | Get the value bound to @var{symbol} and check for @code{#f}. | |
905 | @end table | |
a0e07ba4 | 906 | |
4fd0db14 KR |
907 | Notice that @code{(expr)} has an ``extra'' pair of parentheses, for |
908 | instance @code{((eq? x y))}. One way to remember this is to imagine | |
909 | the @code{symbol} in @code{(symbol expr)} is omitted. | |
a0e07ba4 | 910 | |
4fd0db14 KR |
911 | @code{and-let*} is good for calculations where a @code{#f} value means |
912 | termination, but where a non-@code{#f} value is going to be needed in | |
913 | subsequent expressions. | |
914 | ||
915 | The following illustrates this, it returns text between brackets | |
916 | @samp{[...]} in a string, or @code{#f} if there are no such brackets | |
917 | (ie.@: either @code{string-index} gives @code{#f}). | |
918 | ||
919 | @example | |
920 | (define (extract-brackets str) | |
921 | (and-let* ((start (string-index str #\[)) | |
922 | (end (string-index str #\] start))) | |
923 | (substring str (1+ start) end))) | |
924 | @end example | |
925 | ||
926 | The following shows plain variables and expressions tested too. | |
927 | @code{diagnostic-levels} is taken to be an alist associating a | |
928 | diagnostic type with a level. @code{str} is printed only if the type | |
929 | is known and its level is high enough. | |
930 | ||
931 | @example | |
932 | (define (show-diagnostic type str) | |
933 | (and-let* (want-diagnostics | |
934 | (level (assq-ref diagnostic-levels type)) | |
935 | ((>= level current-diagnostic-level))) | |
936 | (display str))) | |
937 | @end example | |
938 | ||
939 | The advantage of @code{and-let*} is that an extended sequence of | |
940 | expressions and tests doesn't require lots of nesting as would arise | |
941 | from separate @code{and} and @code{let*}, or from @code{cond} with | |
942 | @code{=>}. | |
943 | ||
944 | @end deffn | |
a0e07ba4 NJ |
945 | |
946 | ||
947 | @node SRFI-4 | |
3229f68b | 948 | @subsection SRFI-4 - Homogeneous numeric vector datatypes |
8742c48b | 949 | @cindex SRFI-4 |
a0e07ba4 NJ |
950 | |
951 | @c FIXME::martin: Review me! | |
952 | ||
f85f9591 KR |
953 | SRFI-4 defines a set of datatypes and functions for vectors whose |
954 | elements are numbers, all of the same numeric type. Vectors for | |
955 | signed and unsigned exact integers and inexact reals in several | |
956 | precisions are available. Being homogeneous means they require less | |
957 | memory than normal vectors. | |
a0e07ba4 | 958 | |
f85f9591 KR |
959 | The functions and the read syntax in this section are made available |
960 | with | |
a0e07ba4 | 961 | |
f85f9591 KR |
962 | @lisp |
963 | (use-modules (srfi srfi-4)) | |
964 | @end lisp | |
a0e07ba4 | 965 | |
f85f9591 KR |
966 | Procedures similar to the vector procedures (@pxref{Vectors}) are |
967 | provided for handling these homogeneous vectors, but they are distinct | |
968 | datatypes and the two cannot be inter-mixed. | |
a0e07ba4 NJ |
969 | |
970 | Ten vector data types are provided: Unsigned and signed integer values | |
971 | with 8, 16, 32 and 64 bits and floating point values with 32 and 64 | |
f85f9591 KR |
972 | bits. The type is indicated by a tag in the function names, |
973 | @code{u8}, @code{s8}, @code{u16}, @code{s16}, @code{u32}, @code{s32}, | |
974 | @code{u64}, @code{s64}, @code{f32}, @code{f64}. | |
a0e07ba4 | 975 | |
f85f9591 KR |
976 | The external representation (ie.@: read syntax) for these vectors is |
977 | similar to normal Scheme vectors, but with an additional tag | |
978 | indiciating the vector's type. For example, | |
a0e07ba4 NJ |
979 | |
980 | @lisp | |
981 | #u16(1 2 3) | |
a0e07ba4 NJ |
982 | #f64(3.1415 2.71) |
983 | @end lisp | |
984 | ||
f85f9591 KR |
985 | Note that the read syntax for floating-point here conflicts with |
986 | @code{#f} for false. In Standard Scheme one can write @code{(1 | |
987 | #f3)} for a three element list @code{(1 #f 3)}, but with the SRFI-4 | |
988 | module @code{(1 #f3)} is invalid. @code{(1 #f 3)} is almost certainly | |
989 | what one should write anyway to make the intention clear, so this is | |
990 | rarely a problem. | |
991 | ||
992 | @deffn {Scheme Procedure} u8vector? obj | |
993 | @deffnx {Scheme Procedure} s8vector? obj | |
994 | @deffnx {Scheme Procedure} u16vector? obj | |
995 | @deffnx {Scheme Procedure} s16vector? obj | |
996 | @deffnx {Scheme Procedure} u32vector? obj | |
997 | @deffnx {Scheme Procedure} s32vector? obj | |
998 | @deffnx {Scheme Procedure} u64vector? obj | |
999 | @deffnx {Scheme Procedure} s64vector? obj | |
1000 | @deffnx {Scheme Procedure} f32vector? obj | |
1001 | @deffnx {Scheme Procedure} f64vector? obj | |
1002 | Return @code{#t} if @var{obj} is a homogeneous numeric vector of the | |
1003 | indicated type. | |
1004 | @end deffn | |
1005 | ||
1006 | @deffn {Scheme Procedure} make-u8vector n [value] | |
1007 | @deffnx {Scheme Procedure} make-s8vector n [value] | |
1008 | @deffnx {Scheme Procedure} make-u16vector n [value] | |
1009 | @deffnx {Scheme Procedure} make-s16vector n [value] | |
1010 | @deffnx {Scheme Procedure} make-u32vector n [value] | |
1011 | @deffnx {Scheme Procedure} make-s32vector n [value] | |
1012 | @deffnx {Scheme Procedure} make-u64vector n [value] | |
1013 | @deffnx {Scheme Procedure} make-s64vector n [value] | |
1014 | @deffnx {Scheme Procedure} make-f32vector n [value] | |
1015 | @deffnx {Scheme Procedure} make-f64vector n [value] | |
1016 | Return a newly allocated homogeneous numeric vector holding @var{n} | |
1017 | elements of the indicated type. If @var{value} is given, the vector | |
1018 | is initialized with that value, otherwise the contents are | |
1019 | unspecified. | |
a0e07ba4 NJ |
1020 | @end deffn |
1021 | ||
f85f9591 KR |
1022 | @deffn {Scheme Procedure} u8vector value @dots{} |
1023 | @deffnx {Scheme Procedure} s8vector value @dots{} | |
1024 | @deffnx {Scheme Procedure} u16vector value @dots{} | |
1025 | @deffnx {Scheme Procedure} s16vector value @dots{} | |
1026 | @deffnx {Scheme Procedure} u32vector value @dots{} | |
1027 | @deffnx {Scheme Procedure} s32vector value @dots{} | |
1028 | @deffnx {Scheme Procedure} u64vector value @dots{} | |
1029 | @deffnx {Scheme Procedure} s64vector value @dots{} | |
1030 | @deffnx {Scheme Procedure} f32vector value @dots{} | |
1031 | @deffnx {Scheme Procedure} f64vector value @dots{} | |
1032 | Return a newly allocated homogeneous numeric vector of the indicated | |
1033 | type, holding the given parameter @var{value}s. The vector length is | |
1034 | the number of parameters given. | |
1035 | @end deffn | |
1036 | ||
1037 | @deffn {Scheme Procedure} u8vector-length vec | |
1038 | @deffnx {Scheme Procedure} s8vector-length vec | |
1039 | @deffnx {Scheme Procedure} u16vector-length vec | |
1040 | @deffnx {Scheme Procedure} s16vector-length vec | |
1041 | @deffnx {Scheme Procedure} u32vector-length vec | |
1042 | @deffnx {Scheme Procedure} s32vector-length vec | |
1043 | @deffnx {Scheme Procedure} u64vector-length vec | |
1044 | @deffnx {Scheme Procedure} s64vector-length vec | |
1045 | @deffnx {Scheme Procedure} f32vector-length vec | |
1046 | @deffnx {Scheme Procedure} f64vector-length vec | |
1047 | Return the number of elements in @var{vec}. | |
1048 | @end deffn | |
1049 | ||
1050 | @deffn {Scheme Procedure} u8vector-ref vec i | |
1051 | @deffnx {Scheme Procedure} s8vector-ref vec i | |
1052 | @deffnx {Scheme Procedure} u16vector-ref vec i | |
1053 | @deffnx {Scheme Procedure} s16vector-ref vec i | |
1054 | @deffnx {Scheme Procedure} u32vector-ref vec i | |
1055 | @deffnx {Scheme Procedure} s32vector-ref vec i | |
1056 | @deffnx {Scheme Procedure} u64vector-ref vec i | |
1057 | @deffnx {Scheme Procedure} s64vector-ref vec i | |
1058 | @deffnx {Scheme Procedure} f32vector-ref vec i | |
1059 | @deffnx {Scheme Procedure} f64vector-ref vec i | |
1060 | Return the element at index @var{i} in @var{vec}. The first element | |
1061 | in @var{vec} is index 0. | |
1062 | @end deffn | |
1063 | ||
1064 | @deffn {Scheme Procedure} u8vector-ref vec i value | |
1065 | @deffnx {Scheme Procedure} s8vector-ref vec i value | |
1066 | @deffnx {Scheme Procedure} u16vector-ref vec i value | |
1067 | @deffnx {Scheme Procedure} s16vector-ref vec i value | |
1068 | @deffnx {Scheme Procedure} u32vector-ref vec i value | |
1069 | @deffnx {Scheme Procedure} s32vector-ref vec i value | |
1070 | @deffnx {Scheme Procedure} u64vector-ref vec i value | |
1071 | @deffnx {Scheme Procedure} s64vector-ref vec i value | |
1072 | @deffnx {Scheme Procedure} f32vector-ref vec i value | |
1073 | @deffnx {Scheme Procedure} f64vector-ref vec i value | |
1074 | Set the element at index @var{i} in @var{vec} to @var{value}. The | |
1075 | first element in @var{vec} is index 0. The return value is | |
1076 | unspecified. | |
a0e07ba4 NJ |
1077 | @end deffn |
1078 | ||
f85f9591 KR |
1079 | @deffn {Scheme Procedure} u8vector->list vec |
1080 | @deffnx {Scheme Procedure} s8vector->list vec | |
1081 | @deffnx {Scheme Procedure} u16vector->list vec | |
1082 | @deffnx {Scheme Procedure} s16vector->list vec | |
1083 | @deffnx {Scheme Procedure} u32vector->list vec | |
1084 | @deffnx {Scheme Procedure} s32vector->list vec | |
1085 | @deffnx {Scheme Procedure} u64vector->list vec | |
1086 | @deffnx {Scheme Procedure} s64vector->list vec | |
1087 | @deffnx {Scheme Procedure} f32vector->list vec | |
1088 | @deffnx {Scheme Procedure} f64vector->list vec | |
1089 | Return a newly allocated list holding all elements of @var{vec}. | |
1090 | @end deffn | |
1091 | ||
1092 | @deffn {Scheme Procedure} list->u8vector lst | |
1093 | @deffnx {Scheme Procedure} list->s8vector lst | |
1094 | @deffnx {Scheme Procedure} list->u16vector lst | |
1095 | @deffnx {Scheme Procedure} list->s16vector lst | |
1096 | @deffnx {Scheme Procedure} list->u32vector lst | |
1097 | @deffnx {Scheme Procedure} list->s32vector lst | |
1098 | @deffnx {Scheme Procedure} list->u64vector lst | |
1099 | @deffnx {Scheme Procedure} list->s64vector lst | |
1100 | @deffnx {Scheme Procedure} list->f32vector lst | |
1101 | @deffnx {Scheme Procedure} list->f64vector lst | |
1102 | Return a newly allocated homogeneous numeric vector of the indicated type, | |
a0e07ba4 NJ |
1103 | initialized with the elements of the list @var{lst}. |
1104 | @end deffn | |
1105 | ||
1106 | ||
1107 | @node SRFI-6 | |
3229f68b | 1108 | @subsection SRFI-6 - Basic String Ports |
8742c48b | 1109 | @cindex SRFI-6 |
a0e07ba4 NJ |
1110 | |
1111 | SRFI-6 defines the procedures @code{open-input-string}, | |
1112 | @code{open-output-string} and @code{get-output-string}. These | |
1113 | procedures are included in the Guile core, so using this module does not | |
1114 | make any difference at the moment. But it is possible that support for | |
1115 | SRFI-6 will be factored out of the core library in the future, so using | |
1116 | this module does not hurt, after all. | |
1117 | ||
1118 | @node SRFI-8 | |
3229f68b | 1119 | @subsection SRFI-8 - receive |
8742c48b | 1120 | @cindex SRFI-8 |
a0e07ba4 NJ |
1121 | |
1122 | @code{receive} is a syntax for making the handling of multiple-value | |
1123 | procedures easier. It is documented in @xref{Multiple Values}. | |
1124 | ||
1125 | ||
1126 | @node SRFI-9 | |
3229f68b | 1127 | @subsection SRFI-9 - define-record-type |
8742c48b | 1128 | @cindex SRFI-9 |
a0e07ba4 | 1129 | |
6afe385d KR |
1130 | This SRFI is a syntax for defining new record types and creating |
1131 | predicate, constructor, and field getter and setter functions. In | |
1132 | Guile this is simply an alternate interface to the core record | |
1133 | functionality (@pxref{Records}). It can be used with, | |
a0e07ba4 | 1134 | |
6afe385d KR |
1135 | @example |
1136 | (use-modules (srfi srfi-9)) | |
1137 | @end example | |
1138 | ||
1139 | @deffn {library syntax} define-record-type type @* (constructor fieldname @dots{}) @* predicate @* (fieldname accessor [modifier]) @dots{} | |
1140 | @sp 1 | |
1141 | Create a new record type, and make various @code{define}s for using | |
1142 | it. This syntax can only occur at the top-level, not nested within | |
1143 | some other form. | |
1144 | ||
1145 | @var{type} is bound to the record type, which is as per the return | |
1146 | from the core @code{make-record-type}. @var{type} also provides the | |
1147 | name for the record, as per @code{record-type-name}. | |
1148 | ||
1149 | @var{constructor} is bound to a function to be called as | |
1150 | @code{(@var{constructor} fieldval @dots{})} to create a new record of | |
1151 | this type. The arguments are initial values for the fields, one | |
1152 | argument for each field, in the order they appear in the | |
1153 | @code{define-record-type} form. | |
1154 | ||
1155 | The @var{fieldname}s provide the names for the record fields, as per | |
1156 | the core @code{record-type-fields} etc, and are referred to in the | |
1157 | subsequent accessor/modifier forms. | |
1158 | ||
1159 | @var{predictate} is bound to a function to be called as | |
1160 | @code{(@var{predicate} obj)}. It returns @code{#t} or @code{#f} | |
1161 | according to whether @var{obj} is a record of this type. | |
1162 | ||
1163 | Each @var{accessor} is bound to a function to be called | |
1164 | @code{(@var{accessor} record)} to retrieve the respective field from a | |
1165 | @var{record}. Similarly each @var{modifier} is bound to a function to | |
1166 | be called @code{(@var{modifier} record val)} to set the respective | |
1167 | field in a @var{record}. | |
1168 | @end deffn | |
1169 | ||
1170 | @noindent | |
1171 | An example will illustrate typical usage, | |
a0e07ba4 NJ |
1172 | |
1173 | @example | |
6afe385d KR |
1174 | (define-record-type employee-type |
1175 | (make-employee name age salary) | |
1176 | employee? | |
1177 | (name get-employee-name) | |
1178 | (age get-employee-age set-employee-age) | |
1179 | (salary get-employee-salary set-employee-salary)) | |
a0e07ba4 NJ |
1180 | @end example |
1181 | ||
6afe385d KR |
1182 | This creates a new employee data type, with name, age and salary |
1183 | fields. Accessor functions are created for each field, but no | |
1184 | modifier function for the name (the intention in this example being | |
1185 | that it's established only when an employee object is created). These | |
1186 | can all then be used as for example, | |
a0e07ba4 NJ |
1187 | |
1188 | @example | |
6afe385d KR |
1189 | employee-type @result{} #<record-type employee-type> |
1190 | ||
1191 | (define fred (make-employee "Fred" 45 20000.00)) | |
1192 | ||
1193 | (employee? fred) @result{} #t | |
1194 | (get-employee-age fred) @result{} 45 | |
1195 | (set-employee-salary fred 25000.00) ;; pay rise | |
a0e07ba4 NJ |
1196 | @end example |
1197 | ||
6afe385d KR |
1198 | The functions created by @code{define-record-type} are ordinary |
1199 | top-level @code{define}s. They can be redefined or @code{set!} as | |
1200 | desired, exported from a module, etc. | |
1201 | ||
a0e07ba4 NJ |
1202 | |
1203 | @node SRFI-10 | |
3229f68b | 1204 | @subsection SRFI-10 - Hash-Comma Reader Extension |
8742c48b | 1205 | @cindex SRFI-10 |
a0e07ba4 NJ |
1206 | |
1207 | @cindex hash-comma | |
1208 | @cindex #,() | |
1209 | The module @code{(srfi srfi-10)} implements the syntax extension | |
1210 | @code{#,()}, also called hash-comma, which is defined in SRFI-10. | |
1211 | ||
1212 | The support for SRFI-10 consists of the procedure | |
1213 | @code{define-reader-ctor} for defining new reader constructors and the | |
1214 | read syntax form | |
1215 | ||
1216 | @example | |
1217 | #,(@var{ctor} @var{datum} ...) | |
1218 | @end example | |
1219 | ||
1220 | where @var{ctor} must be a symbol for which a read constructor was | |
85a9b4ed | 1221 | defined previously, using @code{define-reader-ctor}. |
a0e07ba4 NJ |
1222 | |
1223 | Example: | |
1224 | ||
1225 | @lisp | |
4310df36 | 1226 | (use-modules (ice-9 rdelim)) ; for read-line |
a0e07ba4 NJ |
1227 | (define-reader-ctor 'file open-input-file) |
1228 | (define f '#,(file "/etc/passwd")) | |
1229 | (read-line f) | |
1230 | @result{} | |
1231 | "root:x:0:0:root:/root:/bin/bash" | |
1232 | @end lisp | |
1233 | ||
1234 | Please note the quote before the @code{#,(file ...)} expression. This | |
1235 | is necessary because ports are not self-evaluating in Guile. | |
1236 | ||
8f85c0c6 | 1237 | @deffn {Scheme Procedure} define-reader-ctor symbol proc |
a0e07ba4 NJ |
1238 | Define @var{proc} as the reader constructor for hash-comma forms with a |
1239 | tag @var{symbol}. @var{proc} will be applied to the datum(s) following | |
1240 | the tag in the hash-comma expression after the complete form has been | |
1241 | read in. The result of @var{proc} is returned by the Scheme reader. | |
1242 | @end deffn | |
1243 | ||
1244 | ||
1245 | @node SRFI-11 | |
3229f68b | 1246 | @subsection SRFI-11 - let-values |
8742c48b | 1247 | @cindex SRFI-11 |
a0e07ba4 | 1248 | |
8742c48b KR |
1249 | @findex let-values |
1250 | @findex let-values* | |
a0e07ba4 NJ |
1251 | This module implements the binding forms for multiple values |
1252 | @code{let-values} and @code{let-values*}. These forms are similar to | |
1253 | @code{let} and @code{let*} (@pxref{Local Bindings}), but they support | |
1254 | binding of the values returned by multiple-valued expressions. | |
1255 | ||
1256 | Write @code{(use-modules (srfi srfi-11))} to make the bindings | |
1257 | available. | |
1258 | ||
1259 | @lisp | |
1260 | (let-values (((x y) (values 1 2)) | |
1261 | ((z f) (values 3 4))) | |
1262 | (+ x y z f)) | |
1263 | @result{} | |
1264 | 10 | |
1265 | @end lisp | |
1266 | ||
1267 | @code{let-values} performs all bindings simultaneously, which means that | |
1268 | no expression in the binding clauses may refer to variables bound in the | |
1269 | same clause list. @code{let-values*}, on the other hand, performs the | |
1270 | bindings sequentially, just like @code{let*} does for single-valued | |
1271 | expressions. | |
1272 | ||
1273 | ||
1274 | @node SRFI-13 | |
3229f68b | 1275 | @subsection SRFI-13 - String Library |
8742c48b | 1276 | @cindex SRFI-13 |
a0e07ba4 NJ |
1277 | |
1278 | In this section, we will describe all procedures defined in SRFI-13 | |
1279 | (string library) and implemented by the module @code{(srfi srfi-13)}. | |
1280 | ||
1281 | Note that only the procedures from SRFI-13 are documented here which are | |
1282 | not already contained in Guile. For procedures not documented here | |
1283 | please refer to the relevant chapters in the Guile Reference Manual, for | |
1284 | example the documentation of strings and string procedures | |
1285 | (@pxref{Strings}). | |
1286 | ||
40f316d0 MG |
1287 | All of the procedures defined in SRFI-13, which are not already |
1288 | included in the Guile core library, are implemented in the module | |
1289 | @code{(srfi srfi-13)}. The procedures which are both in Guile and in | |
1290 | SRFI-13 are slightly extended in this module. Their bindings | |
1291 | overwrite those in the Guile core. | |
a0e07ba4 NJ |
1292 | |
1293 | The procedures which are defined in the section @emph{Low-level | |
1294 | procedures} of SRFI-13 for parsing optional string indices, substring | |
1295 | specification checking and Knuth-Morris-Pratt-Searching are not | |
1296 | implemented. | |
1297 | ||
1298 | The procedures @code{string-contains} and @code{string-contains-ci} are | |
1299 | not implemented very efficiently at the moment. This will be changed as | |
1300 | soon as possible. | |
1301 | ||
1302 | @menu | |
1303 | * Loading SRFI-13:: How to load SRFI-13 support. | |
1304 | * SRFI-13 Predicates:: String predicates. | |
1305 | * SRFI-13 Constructors:: String constructing procedures. | |
1306 | * SRFI-13 List/String Conversion:: Conversion from/to lists. | |
1307 | * SRFI-13 Selection:: Selection portions of strings. | |
85a9b4ed | 1308 | * SRFI-13 Modification:: Modify strings in-place. |
a0e07ba4 NJ |
1309 | * SRFI-13 Comparison:: Compare strings. |
1310 | * SRFI-13 Prefixes/Suffixes:: Detect common pre-/suffixes. | |
1311 | * SRFI-13 Searching:: Searching for substrings. | |
1312 | * SRFI-13 Case Mapping:: Mapping to lower-/upper-case. | |
1313 | * SRFI-13 Reverse/Append:: Reverse and append strings. | |
1314 | * SRFI-13 Fold/Unfold/Map:: Construct/deconstruct strings. | |
40f316d0 | 1315 | * SRFI-13 Replicate/Rotate:: Replicate and rotate portions of strings. |
a0e07ba4 NJ |
1316 | * SRFI-13 Miscellaneous:: Left-over string procedures. |
1317 | * SRFI-13 Filtering/Deleting:: Filter and delete characters from strings. | |
1318 | @end menu | |
1319 | ||
1320 | ||
1321 | @node Loading SRFI-13 | |
3229f68b | 1322 | @subsubsection Loading SRFI-13 |
a0e07ba4 NJ |
1323 | |
1324 | When Guile is properly installed, SRFI-13 support can be loaded into a | |
1325 | running Guile by using the @code{(srfi srfi-13)} module. | |
1326 | ||
1327 | @example | |
1328 | $ guile | |
1329 | guile> (use-modules (srfi srfi-13)) | |
1330 | guile> | |
1331 | @end example | |
1332 | ||
1333 | When this step causes any errors, Guile is not properly installed. | |
1334 | ||
1335 | One possible reason is that Guile cannot find either the Scheme module | |
1336 | file @file{srfi-13.scm}, or it cannot find the shared object file | |
1337 | @file{libguile-srfi-srfi-13-14.so}. Make sure that the former is in the | |
1338 | Guile load path and that the latter is either installed in some default | |
1339 | location like @file{/usr/local/lib} or that the directory it was | |
1340 | installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to | |
1341 | @file{srfi-14.scm}. | |
1342 | ||
1343 | Now you can test whether the SRFI-13 procedures are working by calling | |
1344 | the @code{string-concatenate} procedure. | |
1345 | ||
1346 | @example | |
1347 | guile> (string-concatenate '("Hello" " " "World!")) | |
1348 | "Hello World!" | |
1349 | @end example | |
1350 | ||
1351 | @node SRFI-13 Predicates | |
3229f68b | 1352 | @subsubsection Predicates |
a0e07ba4 NJ |
1353 | |
1354 | In addition to the primitives @code{string?} and @code{string-null?}, | |
1355 | which are already in the Guile core, the string predicates | |
1356 | @code{string-any} and @code{string-every} are defined by SRFI-13. | |
1357 | ||
6ae50c71 KR |
1358 | @deffn {Scheme Procedure} string-any char_pred s [start end] |
1359 | Return true if @code{char_pred} is satisfied for any character in the | |
1360 | string @var{s}. @var{char_pred} can be | |
1361 | ||
1362 | @itemize @bullet | |
1363 | @item | |
1364 | A character, to to test for any in @var{s} equal to that. | |
1365 | @item | |
1366 | A character set (@pxref{SRFI-14}), to test for any character in | |
1367 | @var{s} in that character set. | |
1368 | @item | |
1369 | A predicate function, called as @code{(@var{char_pred} c)} for each | |
1370 | character in @var{s}, from left to right, to test for any on which | |
1371 | @var{char_pred} returns true. | |
1372 | ||
1373 | When @var{char_pred} does return true (ie.@: non-@code{#f}), that | |
1374 | value is the value returned by @code{string-any}. | |
1375 | @end itemize | |
c1ab7397 | 1376 | |
6ae50c71 KR |
1377 | If there are no characters in @var{s} (ie.@: @var{start} equals |
1378 | @var{end}) then the return is @code{#f}. | |
1379 | ||
1380 | SRFI-13 specifies that when @var{char_pred} is a predicate function, | |
1381 | the call on the last character of @var{s} (assuming that point is | |
1382 | reached) is a tail call, but currently in Guile this is not the case. | |
a0e07ba4 NJ |
1383 | @end deffn |
1384 | ||
6ae50c71 KR |
1385 | @deffn {Scheme Procedure} string-every char_pred s [start end] |
1386 | Return true if @var{char_pred} is satisifed for every character in the | |
1387 | string @var{s}. @var{char_pred} can be | |
1388 | ||
1389 | @itemize @bullet | |
1390 | @item | |
1391 | A character, to to test for every character in @var{s} equal to that. | |
1392 | @item | |
1393 | A character set (@pxref{SRFI-14}), to test for every character in | |
1394 | @var{s} being in that character set. | |
1395 | @item | |
1396 | A predicate function, called as @code{(@var{char_pred} c)} for each | |
1397 | character in @var{s}, from left to right, to test that it returns true | |
1398 | for every character in @var{s}. | |
c1ab7397 | 1399 | |
6ae50c71 KR |
1400 | When @var{char_pred} does return true (ie.@: non-@code{#f}) for every |
1401 | character, the return from the last call is the value returned by | |
5b4dba24 | 1402 | @code{string-every}. |
6ae50c71 | 1403 | @end itemize |
c1ab7397 KR |
1404 | |
1405 | If there are no characters in @var{s} (ie.@: @var{start} equals | |
1406 | @var{end}) then the return is @code{#t}. | |
a0e07ba4 | 1407 | |
6ae50c71 KR |
1408 | SRFI-13 specifies that when @var{char_pred} is a predicate function, |
1409 | the call on the last character of @var{s} (assuming that point is | |
1410 | reached) is a tail call, but currently in Guile this is not the case. | |
1411 | @end deffn | |
a0e07ba4 NJ |
1412 | |
1413 | @c =================================================================== | |
1414 | ||
1415 | @node SRFI-13 Constructors | |
3229f68b | 1416 | @subsubsection Constructors |
a0e07ba4 NJ |
1417 | |
1418 | SRFI-13 defines several procedures for constructing new strings. In | |
1419 | addition to @code{make-string} and @code{string} (available in the Guile | |
1420 | core library), the procedure @code{string-tabulate} does exist. | |
1421 | ||
8f85c0c6 | 1422 | @deffn {Scheme Procedure} string-tabulate proc len |
a0e07ba4 NJ |
1423 | @var{proc} is an integer->char procedure. Construct a string |
1424 | of size @var{len} by applying @var{proc} to each index to | |
1425 | produce the corresponding string element. The order in which | |
1426 | @var{proc} is applied to the indices is not specified. | |
1427 | @end deffn | |
1428 | ||
1429 | ||
1430 | @c =================================================================== | |
1431 | ||
1432 | @node SRFI-13 List/String Conversion | |
3229f68b | 1433 | @subsubsection List/String Conversion |
a0e07ba4 NJ |
1434 | |
1435 | The procedure @code{string->list} is extended by SRFI-13, that is why it | |
1436 | is included in @code{(srfi srfi-13)}. The other procedures are new. | |
1437 | The Guile core already contains the procedure @code{list->string} for | |
1438 | converting a list of characters into a string (@pxref{List/String | |
1439 | Conversion}). | |
1440 | ||
8f85c0c6 | 1441 | @deffn {Scheme Procedure} string->list str [start end] |
a0e07ba4 NJ |
1442 | Convert the string @var{str} into a list of characters. |
1443 | @end deffn | |
1444 | ||
8f85c0c6 | 1445 | @deffn {Scheme Procedure} reverse-list->string chrs |
a0e07ba4 NJ |
1446 | An efficient implementation of @code{(compose string->list |
1447 | reverse)}: | |
1448 | ||
1449 | @smalllisp | |
1450 | (reverse-list->string '(#\a #\B #\c)) @result{} "cBa" | |
1451 | @end smalllisp | |
1452 | @end deffn | |
1453 | ||
8f85c0c6 | 1454 | @deffn {Scheme Procedure} string-join ls [delimiter grammar] |
a0e07ba4 NJ |
1455 | Append the string in the string list @var{ls}, using the string |
1456 | @var{delim} as a delimiter between the elements of @var{ls}. | |
1457 | @var{grammar} is a symbol which specifies how the delimiter is | |
1458 | placed between the strings, and defaults to the symbol | |
1459 | @code{infix}. | |
1460 | ||
1461 | @table @code | |
1462 | @item infix | |
1463 | Insert the separator between list elements. An empty string | |
1464 | will produce an empty list. | |
1465 | ||
1466 | @item string-infix | |
1467 | Like @code{infix}, but will raise an error if given the empty | |
1468 | list. | |
1469 | ||
1470 | @item suffix | |
1471 | Insert the separator after every list element. | |
1472 | ||
1473 | @item prefix | |
1474 | Insert the separator before each list element. | |
1475 | @end table | |
1476 | @end deffn | |
1477 | ||
1478 | ||
1479 | @c =================================================================== | |
1480 | ||
1481 | @node SRFI-13 Selection | |
3229f68b | 1482 | @subsubsection Selection |
a0e07ba4 NJ |
1483 | |
1484 | These procedures are called @dfn{selectors}, because they access | |
1485 | information about the string or select pieces of a given string. | |
1486 | ||
1487 | Additional selector procedures are documented in the Strings section | |
1488 | (@pxref{String Selection}), like @code{string-length} or | |
1489 | @code{string-ref}. | |
1490 | ||
1491 | @code{string-copy} is also available in core Guile, but this version | |
1492 | accepts additional start/end indices. | |
1493 | ||
8f85c0c6 | 1494 | @deffn {Scheme Procedure} string-copy str [start end] |
a0e07ba4 NJ |
1495 | Return a freshly allocated copy of the string @var{str}. If |
1496 | given, @var{start} and @var{end} delimit the portion of | |
1497 | @var{str} which is copied. | |
1498 | @end deffn | |
1499 | ||
8f85c0c6 | 1500 | @deffn {Scheme Procedure} substring/shared str start [end] |
a0e07ba4 NJ |
1501 | Like @code{substring}, but the result may share memory with the |
1502 | argument @var{str}. | |
1503 | @end deffn | |
1504 | ||
8f85c0c6 | 1505 | @deffn {Scheme Procedure} string-copy! target tstart s [start end] |
a0e07ba4 NJ |
1506 | Copy the sequence of characters from index range [@var{start}, |
1507 | @var{end}) in string @var{s} to string @var{target}, beginning | |
1508 | at index @var{tstart}. The characters are copied left-to-right | |
1509 | or right-to-left as needed - the copy is guaranteed to work, | |
1510 | even if @var{target} and @var{s} are the same string. It is an | |
1511 | error if the copy operation runs off the end of the target | |
1512 | string. | |
1513 | @end deffn | |
1514 | ||
8f85c0c6 NJ |
1515 | @deffn {Scheme Procedure} string-take s n |
1516 | @deffnx {Scheme Procedure} string-take-right s n | |
a0e07ba4 NJ |
1517 | Return the @var{n} first/last characters of @var{s}. |
1518 | @end deffn | |
1519 | ||
8f85c0c6 NJ |
1520 | @deffn {Scheme Procedure} string-drop s n |
1521 | @deffnx {Scheme Procedure} string-drop-right s n | |
a0e07ba4 NJ |
1522 | Return all but the first/last @var{n} characters of @var{s}. |
1523 | @end deffn | |
1524 | ||
8f85c0c6 NJ |
1525 | @deffn {Scheme Procedure} string-pad s len [chr start end] |
1526 | @deffnx {Scheme Procedure} string-pad-right s len [chr start end] | |
a0e07ba4 NJ |
1527 | Take that characters from @var{start} to @var{end} from the |
1528 | string @var{s} and return a new string, right(left)-padded by the | |
1529 | character @var{chr} to length @var{len}. If the resulting | |
1530 | string is longer than @var{len}, it is truncated on the right (left). | |
1531 | @end deffn | |
1532 | ||
8f85c0c6 NJ |
1533 | @deffn {Scheme Procedure} string-trim s [char_pred start end] |
1534 | @deffnx {Scheme Procedure} string-trim-right s [char_pred start end] | |
1535 | @deffnx {Scheme Procedure} string-trim-both s [char_pred start end] | |
a0e07ba4 NJ |
1536 | Trim @var{s} by skipping over all characters on the left/right/both |
1537 | sides of the string that satisfy the parameter @var{char_pred}: | |
1538 | ||
1539 | @itemize @bullet | |
1540 | @item | |
1541 | if it is the character @var{ch}, characters equal to | |
1542 | @var{ch} are trimmed, | |
1543 | ||
1544 | @item | |
1545 | if it is a procedure @var{pred} characters that | |
1546 | satisfy @var{pred} are trimmed, | |
1547 | ||
1548 | @item | |
1549 | if it is a character set, characters in that set are trimmed. | |
1550 | @end itemize | |
1551 | ||
1552 | If called without a @var{char_pred} argument, all whitespace is | |
1553 | trimmed. | |
1554 | @end deffn | |
1555 | ||
1556 | ||
1557 | @c =================================================================== | |
1558 | ||
1559 | @node SRFI-13 Modification | |
3229f68b | 1560 | @subsubsection Modification |
a0e07ba4 NJ |
1561 | |
1562 | The procedure @code{string-fill!} is extended from R5RS because it | |
1563 | accepts optional start/end indices. This bindings shadows the procedure | |
1564 | of the same name in the Guile core. The second modification procedure | |
1565 | @code{string-set!} is documented in the Strings section (@pxref{String | |
1566 | Modification}). | |
1567 | ||
8f85c0c6 | 1568 | @deffn {Scheme Procedure} string-fill! str chr [start end] |
a0e07ba4 NJ |
1569 | Stores @var{chr} in every element of the given @var{str} and |
1570 | returns an unspecified value. | |
1571 | @end deffn | |
1572 | ||
1573 | ||
1574 | @c =================================================================== | |
1575 | ||
1576 | @node SRFI-13 Comparison | |
3229f68b | 1577 | @subsubsection Comparison |
a0e07ba4 NJ |
1578 | |
1579 | The procedures in this section are used for comparing strings in | |
1580 | different ways. The comparison predicates differ from those in R5RS in | |
1581 | that they do not only return @code{#t} or @code{#f}, but the mismatch | |
1582 | index in the case of a true return value. | |
1583 | ||
1584 | @code{string-hash} and @code{string-hash-ci} are for calculating hash | |
1585 | values for strings, useful for implementing fast lookup mechanisms. | |
1586 | ||
8f85c0c6 NJ |
1587 | @deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2] |
1588 | @deffnx {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2] | |
a0e07ba4 NJ |
1589 | Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the |
1590 | mismatch index, depending upon whether @var{s1} is less than, | |
1591 | equal to, or greater than @var{s2}. The mismatch index is the | |
1592 | largest index @var{i} such that for every 0 <= @var{j} < | |
1593 | @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] - that is, | |
1594 | @var{i} is the first position that does not match. The | |
1595 | character comparison is done case-insensitively. | |
1596 | @end deffn | |
1597 | ||
8f85c0c6 NJ |
1598 | @deffn {Scheme Procedure} string= s1 s2 [start1 end1 start2 end2] |
1599 | @deffnx {Scheme Procedure} string<> s1 s2 [start1 end1 start2 end2] | |
1600 | @deffnx {Scheme Procedure} string< s1 s2 [start1 end1 start2 end2] | |
1601 | @deffnx {Scheme Procedure} string> s1 s2 [start1 end1 start2 end2] | |
1602 | @deffnx {Scheme Procedure} string<= s1 s2 [start1 end1 start2 end2] | |
1603 | @deffnx {Scheme Procedure} string>= s1 s2 [start1 end1 start2 end2] | |
a0e07ba4 NJ |
1604 | Compare @var{s1} and @var{s2} and return @code{#f} if the predicate |
1605 | fails. Otherwise, the mismatch index is returned (or @var{end1} in the | |
1606 | case of @code{string=}. | |
1607 | @end deffn | |
1608 | ||
8f85c0c6 NJ |
1609 | @deffn {Scheme Procedure} string-ci= s1 s2 [start1 end1 start2 end2] |
1610 | @deffnx {Scheme Procedure} string-ci<> s1 s2 [start1 end1 start2 end2] | |
1611 | @deffnx {Scheme Procedure} string-ci< s1 s2 [start1 end1 start2 end2] | |
1612 | @deffnx {Scheme Procedure} string-ci> s1 s2 [start1 end1 start2 end2] | |
1613 | @deffnx {Scheme Procedure} string-ci<= s1 s2 [start1 end1 start2 end2] | |
1614 | @deffnx {Scheme Procedure} string-ci>= s1 s2 [start1 end1 start2 end2] | |
a0e07ba4 NJ |
1615 | Compare @var{s1} and @var{s2} and return @code{#f} if the predicate |
1616 | fails. Otherwise, the mismatch index is returned (or @var{end1} in the | |
1617 | case of @code{string=}. These are the case-insensitive variants. | |
1618 | @end deffn | |
1619 | ||
8f85c0c6 NJ |
1620 | @deffn {Scheme Procedure} string-hash s [bound start end] |
1621 | @deffnx {Scheme Procedure} string-hash-ci s [bound start end] | |
a0e07ba4 NJ |
1622 | Return a hash value of the string @var{s} in the range 0 @dots{} |
1623 | @var{bound} - 1. @code{string-hash-ci} is the case-insensitive variant. | |
1624 | @end deffn | |
1625 | ||
1626 | ||
1627 | @c =================================================================== | |
1628 | ||
1629 | @node SRFI-13 Prefixes/Suffixes | |
3229f68b | 1630 | @subsubsection Prefixes/Suffixes |
a0e07ba4 NJ |
1631 | |
1632 | Using these procedures you can determine whether a given string is a | |
1633 | prefix or suffix of another string or how long a common prefix/suffix | |
1634 | is. | |
1635 | ||
8f85c0c6 NJ |
1636 | @deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 end1 start2 end2] |
1637 | @deffnx {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 end1 start2 end2] | |
1638 | @deffnx {Scheme Procedure} string-suffix-length s1 s2 [start1 end1 start2 end2] | |
1639 | @deffnx {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 end1 start2 end2] | |
a0e07ba4 NJ |
1640 | Return the length of the longest common prefix/suffix of the two |
1641 | strings. @code{string-prefix-length-ci} and | |
1642 | @code{string-suffix-length-ci} are the case-insensitive variants. | |
1643 | @end deffn | |
1644 | ||
8f85c0c6 NJ |
1645 | @deffn {Scheme Procedure} string-prefix? s1 s2 [start1 end1 start2 end2] |
1646 | @deffnx {Scheme Procedure} string-prefix-ci? s1 s2 [start1 end1 start2 end2] | |
1647 | @deffnx {Scheme Procedure} string-suffix? s1 s2 [start1 end1 start2 end2] | |
1648 | @deffnx {Scheme Procedure} string-suffix-ci? s1 s2 [start1 end1 start2 end2] | |
a0e07ba4 NJ |
1649 | Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and |
1650 | @code{string-suffix-ci?} are the case-insensitive variants. | |
1651 | @end deffn | |
1652 | ||
1653 | ||
1654 | @c =================================================================== | |
1655 | ||
1656 | @node SRFI-13 Searching | |
3229f68b | 1657 | @subsubsection Searching |
a0e07ba4 NJ |
1658 | |
1659 | Use these procedures to find out whether a string contains a given | |
1660 | character or a given substring, or a character from a set of characters. | |
1661 | ||
8f85c0c6 NJ |
1662 | @deffn {Scheme Procedure} string-index s char_pred [start end] |
1663 | @deffnx {Scheme Procedure} string-index-right s char_pred [start end] | |
a0e07ba4 | 1664 | Search through the string @var{s} from left to right (right to left), |
85a9b4ed | 1665 | returning the index of the first (last) occurrence of a character which |
a0e07ba4 NJ |
1666 | |
1667 | @itemize @bullet | |
1668 | @item | |
1669 | equals @var{char_pred}, if it is character, | |
1670 | ||
1671 | @item | |
85a9b4ed | 1672 | satisfies the predicate @var{char_pred}, if it is a |
a0e07ba4 NJ |
1673 | procedure, |
1674 | ||
1675 | @item | |
1676 | is in the set @var{char_pred}, if it is a character set. | |
1677 | @end itemize | |
1678 | @end deffn | |
1679 | ||
8f85c0c6 NJ |
1680 | @deffn {Scheme Procedure} string-skip s char_pred [start end] |
1681 | @deffnx {Scheme Procedure} string-skip-right s char_pred [start end] | |
a0e07ba4 | 1682 | Search through the string @var{s} from left to right (right to left), |
85a9b4ed | 1683 | returning the index of the first (last) occurrence of a character which |
a0e07ba4 NJ |
1684 | |
1685 | @itemize @bullet | |
1686 | @item | |
1687 | does not equal @var{char_pred}, if it is character, | |
1688 | ||
1689 | @item | |
85a9b4ed | 1690 | does not satisfy the predicate @var{char_pred}, if it is |
a0e07ba4 NJ |
1691 | a procedure. |
1692 | ||
1693 | @item | |
1694 | is not in the set if @var{char_pred} is a character set. | |
1695 | @end itemize | |
1696 | @end deffn | |
1697 | ||
8f85c0c6 | 1698 | @deffn {Scheme Procedure} string-count s char_pred [start end] |
a0e07ba4 NJ |
1699 | Return the count of the number of characters in the string |
1700 | @var{s} which | |
1701 | ||
1702 | @itemize @bullet | |
1703 | @item | |
1704 | equals @var{char_pred}, if it is character, | |
1705 | ||
1706 | @item | |
85a9b4ed | 1707 | satisfies the predicate @var{char_pred}, if it is a procedure. |
a0e07ba4 NJ |
1708 | |
1709 | @item | |
1710 | is in the set @var{char_pred}, if it is a character set. | |
1711 | @end itemize | |
1712 | @end deffn | |
1713 | ||
8f85c0c6 NJ |
1714 | @deffn {Scheme Procedure} string-contains s1 s2 [start1 end1 start2 end2] |
1715 | @deffnx {Scheme Procedure} string-contains-ci s1 s2 [start1 end1 start2 end2] | |
a0e07ba4 NJ |
1716 | Does string @var{s1} contain string @var{s2}? Return the index |
1717 | in @var{s1} where @var{s2} occurs as a substring, or false. | |
1718 | The optional start/end indices restrict the operation to the | |
1719 | indicated substrings. | |
1720 | ||
1721 | @code{string-contains-ci} is the case-insensitive variant. | |
1722 | @end deffn | |
1723 | ||
1724 | ||
1725 | @c =================================================================== | |
1726 | ||
1727 | @node SRFI-13 Case Mapping | |
3229f68b | 1728 | @subsubsection Alphabetic Case Mapping |
a0e07ba4 NJ |
1729 | |
1730 | These procedures convert the alphabetic case of strings. They are | |
1731 | similar to the procedures in the Guile core, but are extended to handle | |
1732 | optional start/end indices. | |
1733 | ||
8f85c0c6 NJ |
1734 | @deffn {Scheme Procedure} string-upcase s [start end] |
1735 | @deffnx {Scheme Procedure} string-upcase! s [start end] | |
a0e07ba4 NJ |
1736 | Upcase every character in @var{s}. @code{string-upcase!} is the |
1737 | side-effecting variant. | |
1738 | @end deffn | |
1739 | ||
8f85c0c6 NJ |
1740 | @deffn {Scheme Procedure} string-downcase s [start end] |
1741 | @deffnx {Scheme Procedure} string-downcase! s [start end] | |
a0e07ba4 NJ |
1742 | Downcase every character in @var{s}. @code{string-downcase!} is the |
1743 | side-effecting variant. | |
1744 | @end deffn | |
1745 | ||
8f85c0c6 NJ |
1746 | @deffn {Scheme Procedure} string-titlecase s [start end] |
1747 | @deffnx {Scheme Procedure} string-titlecase! s [start end] | |
a0e07ba4 NJ |
1748 | Upcase every first character in every word in @var{s}, downcase the |
1749 | other characters. @code{string-titlecase!} is the side-effecting | |
1750 | variant. | |
1751 | @end deffn | |
1752 | ||
1753 | ||
1754 | @c =================================================================== | |
1755 | ||
1756 | @node SRFI-13 Reverse/Append | |
3229f68b | 1757 | @subsubsection Reverse/Append |
a0e07ba4 NJ |
1758 | |
1759 | One appending procedure, @code{string-append} is the same in R5RS and in | |
1760 | SRFI-13, so it is not redefined. | |
1761 | ||
8f85c0c6 NJ |
1762 | @deffn {Scheme Procedure} string-reverse str [start end] |
1763 | @deffnx {Scheme Procedure} string-reverse! str [start end] | |
a0e07ba4 NJ |
1764 | Reverse the string @var{str}. The optional arguments |
1765 | @var{start} and @var{end} delimit the region of @var{str} to | |
1766 | operate on. | |
1767 | ||
1768 | @code{string-reverse!} modifies the argument string and returns an | |
1769 | unspecified value. | |
1770 | @end deffn | |
1771 | ||
8f85c0c6 | 1772 | @deffn {Scheme Procedure} string-append/shared ls @dots{} |
a0e07ba4 NJ |
1773 | Like @code{string-append}, but the result may share memory |
1774 | with the argument strings. | |
1775 | @end deffn | |
1776 | ||
8f85c0c6 | 1777 | @deffn {Scheme Procedure} string-concatenate ls |
a0e07ba4 NJ |
1778 | Append the elements of @var{ls} (which must be strings) |
1779 | together into a single string. Guaranteed to return a freshly | |
1780 | allocated string. | |
1781 | @end deffn | |
1782 | ||
8f85c0c6 | 1783 | @deffn {Scheme Procedure} string-concatenate/shared ls |
a0e07ba4 NJ |
1784 | Like @code{string-concatenate}, but the result may share memory |
1785 | with the strings in the list @var{ls}. | |
1786 | @end deffn | |
1787 | ||
8f85c0c6 | 1788 | @deffn {Scheme Procedure} string-concatenate-reverse ls final_string end |
a0e07ba4 NJ |
1789 | Without optional arguments, this procedure is equivalent to |
1790 | ||
1791 | @smalllisp | |
1792 | (string-concatenate (reverse ls)) | |
1793 | @end smalllisp | |
1794 | ||
1795 | If the optional argument @var{final_string} is specified, it is | |
1796 | consed onto the beginning to @var{ls} before performing the | |
1797 | list-reverse and string-concatenate operations. If @var{end} | |
1798 | is given, only the characters of @var{final_string} up to index | |
1799 | @var{end} are used. | |
1800 | ||
1801 | Guaranteed to return a freshly allocated string. | |
1802 | @end deffn | |
1803 | ||
8f85c0c6 | 1804 | @deffn {Scheme Procedure} string-concatenate-reverse/shared ls final_string end |
a0e07ba4 NJ |
1805 | Like @code{string-concatenate-reverse}, but the result may |
1806 | share memory with the the strings in the @var{ls} arguments. | |
1807 | @end deffn | |
1808 | ||
1809 | ||
1810 | @c =================================================================== | |
1811 | ||
1812 | @node SRFI-13 Fold/Unfold/Map | |
3229f68b | 1813 | @subsubsection Fold/Unfold/Map |
a0e07ba4 NJ |
1814 | |
1815 | @code{string-map}, @code{string-for-each} etc. are for iterating over | |
1816 | the characters a string is composed of. The fold and unfold procedures | |
1817 | are list iterators and constructors. | |
1818 | ||
8f85c0c6 | 1819 | @deffn {Scheme Procedure} string-map proc s [start end] |
a0e07ba4 NJ |
1820 | @var{proc} is a char->char procedure, it is mapped over |
1821 | @var{s}. The order in which the procedure is applied to the | |
1822 | string elements is not specified. | |
1823 | @end deffn | |
1824 | ||
8f85c0c6 | 1825 | @deffn {Scheme Procedure} string-map! proc s [start end] |
a0e07ba4 NJ |
1826 | @var{proc} is a char->char procedure, it is mapped over |
1827 | @var{s}. The order in which the procedure is applied to the | |
1828 | string elements is not specified. The string @var{s} is | |
1829 | modified in-place, the return value is not specified. | |
1830 | @end deffn | |
1831 | ||
8f85c0c6 NJ |
1832 | @deffn {Scheme Procedure} string-fold kons knil s [start end] |
1833 | @deffnx {Scheme Procedure} string-fold-right kons knil s [start end] | |
a0e07ba4 NJ |
1834 | Fold @var{kons} over the characters of @var{s}, with @var{knil} as the |
1835 | terminating element, from left to right (or right to left, for | |
1836 | @code{string-fold-right}). @var{kons} must expect two arguments: The | |
1837 | actual character and the last result of @var{kons}' application. | |
1838 | @end deffn | |
1839 | ||
8f85c0c6 NJ |
1840 | @deffn {Scheme Procedure} string-unfold p f g seed [base make_final] |
1841 | @deffnx {Scheme Procedure} string-unfold-right p f g seed [base make_final] | |
a0e07ba4 NJ |
1842 | These are the fundamental string constructors. |
1843 | @itemize @bullet | |
1844 | @item @var{g} is used to generate a series of @emph{seed} | |
1845 | values from the initial @var{seed}: @var{seed}, (@var{g} | |
1846 | @var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), | |
1847 | @dots{} | |
1848 | @item @var{p} tells us when to stop - when it returns true | |
1849 | when applied to one of these seed values. | |
12991fed | 1850 | @item @var{f} maps each seed value to the corresponding |
a0e07ba4 NJ |
1851 | character in the result string. These chars are assembled into the |
1852 | string in a left-to-right (right-to-left) order. | |
1853 | @item @var{base} is the optional initial/leftmost (rightmost) | |
1854 | portion of the constructed string; it default to the empty string. | |
1855 | @item @var{make_final} is applied to the terminal seed | |
1856 | value (on which @var{p} returns true) to produce the final/rightmost | |
1857 | (leftmost) portion of the constructed string. It defaults to | |
1858 | @code{(lambda (x) "")}. | |
1859 | @end itemize | |
1860 | @end deffn | |
1861 | ||
8f85c0c6 | 1862 | @deffn {Scheme Procedure} string-for-each proc s [start end] |
a0e07ba4 NJ |
1863 | @var{proc} is mapped over @var{s} in left-to-right order. The |
1864 | return value is not specified. | |
1865 | @end deffn | |
1866 | ||
1867 | ||
1868 | @c =================================================================== | |
1869 | ||
1870 | @node SRFI-13 Replicate/Rotate | |
3229f68b | 1871 | @subsubsection Replicate/Rotate |
a0e07ba4 NJ |
1872 | |
1873 | These procedures are special substring procedures, which can also be | |
1874 | used for replicating strings. They are a bit tricky to use, but | |
1875 | consider this code fragment, which replicates the input string | |
1876 | @code{"foo"} so often that the resulting string has a length of six. | |
1877 | ||
1878 | @lisp | |
1879 | (xsubstring "foo" 0 6) | |
1880 | @result{} | |
1881 | "foofoo" | |
1882 | @end lisp | |
1883 | ||
8f85c0c6 | 1884 | @deffn {Scheme Procedure} xsubstring s from [to start end] |
a0e07ba4 NJ |
1885 | This is the @emph{extended substring} procedure that implements |
1886 | replicated copying of a substring of some string. | |
1887 | ||
1888 | @var{s} is a string, @var{start} and @var{end} are optional | |
1889 | arguments that demarcate a substring of @var{s}, defaulting to | |
1890 | 0 and the length of @var{s}. Replicate this substring up and | |
1891 | down index space, in both the positive and negative directions. | |
1892 | @code{xsubstring} returns the substring of this string | |
1893 | beginning at index @var{from}, and ending at @var{to}, which | |
1894 | defaults to @var{from} + (@var{end} - @var{start}). | |
1895 | @end deffn | |
1896 | ||
8f85c0c6 | 1897 | @deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto start end] |
a0e07ba4 NJ |
1898 | Exactly the same as @code{xsubstring}, but the extracted text |
1899 | is written into the string @var{target} starting at index | |
1900 | @var{tstart}. The operation is not defined if @code{(eq? | |
1901 | @var{target} @var{s})} or these arguments share storage - you | |
1902 | cannot copy a string on top of itself. | |
1903 | @end deffn | |
1904 | ||
1905 | ||
1906 | @c =================================================================== | |
1907 | ||
1908 | @node SRFI-13 Miscellaneous | |
3229f68b | 1909 | @subsubsection Miscellaneous |
a0e07ba4 NJ |
1910 | |
1911 | @code{string-replace} is for replacing a portion of a string with | |
1912 | another string and @code{string-tokenize} splits a string into a list of | |
1913 | strings, breaking it up at a specified character. | |
1914 | ||
8c24f46e | 1915 | @deffn {Scheme Procedure} string-replace s1 s2 [start1 end1 start2 end2] |
a0e07ba4 NJ |
1916 | Return the string @var{s1}, but with the characters |
1917 | @var{start1} @dots{} @var{end1} replaced by the characters | |
1918 | @var{start2} @dots{} @var{end2} from @var{s2}. | |
5519096e KR |
1919 | |
1920 | For reference, note that SRFI-13 specifies @var{start1} and @var{end1} | |
1921 | as mandatory, but in Guile they are optional. | |
a0e07ba4 NJ |
1922 | @end deffn |
1923 | ||
c0ab7f13 | 1924 | @deffn {Scheme Procedure} string-tokenize s [token-set start end] |
a0e07ba4 | 1925 | Split the string @var{s} into a list of substrings, where each |
c0ab7f13 MV |
1926 | substring is a maximal non-empty contiguous sequence of characters |
1927 | from the character set @var{token_set}, which defaults to an | |
1928 | equivalent of @code{char-set:graphic}. If @var{start} or @var{end} | |
1929 | indices are provided, they restrict @code{string-tokenize} to | |
1930 | operating on the indicated substring of @var{s}. | |
a0e07ba4 NJ |
1931 | @end deffn |
1932 | ||
1933 | ||
1934 | @c =================================================================== | |
1935 | ||
1936 | @node SRFI-13 Filtering/Deleting | |
3229f68b | 1937 | @subsubsection Filtering/Deleting |
a0e07ba4 NJ |
1938 | |
1939 | @dfn{Filtering} means to remove all characters from a string which do | |
1940 | not match a given criteria, @dfn{deleting} means the opposite. | |
1941 | ||
8f85c0c6 | 1942 | @deffn {Scheme Procedure} string-filter s char_pred [start end] |
a0e07ba4 NJ |
1943 | Filter the string @var{s}, retaining only those characters that |
1944 | satisfy the @var{char_pred} argument. If the argument is a | |
1945 | procedure, it is applied to each character as a predicate, if | |
1946 | it is a character, it is tested for equality and if it is a | |
1947 | character set, it is tested for membership. | |
1948 | @end deffn | |
1949 | ||
8f85c0c6 | 1950 | @deffn {Scheme Procedure} string-delete s char_pred [start end] |
a0e07ba4 NJ |
1951 | Filter the string @var{s}, retaining only those characters that |
1952 | do not satisfy the @var{char_pred} argument. If the argument | |
1953 | is a procedure, it is applied to each character as a predicate, | |
1954 | if it is a character, it is tested for equality and if it is a | |
1955 | character set, it is tested for membership. | |
1956 | @end deffn | |
1957 | ||
1958 | ||
1959 | @node SRFI-14 | |
3229f68b | 1960 | @subsection SRFI-14 - Character-set Library |
8742c48b | 1961 | @cindex SRFI-14 |
a0e07ba4 NJ |
1962 | |
1963 | SRFI-14 defines the data type @dfn{character set}, and also defines a | |
1964 | lot of procedures for handling this character type, and a few standard | |
1965 | character sets like whitespace, alphabetic characters and others. | |
1966 | ||
1967 | All procedures from SRFI-14 (character-set library) are implemented in | |
1968 | the module @code{(srfi srfi-14)}, as well as the standard variables | |
1969 | @code{char-set:letter}, @code{char-set:digit} etc. | |
1970 | ||
1971 | @menu | |
1972 | * Loading SRFI-14:: How to make charsets available. | |
1973 | * SRFI-14 Character Set Data Type:: Underlying data type for charsets. | |
1974 | * SRFI-14 Predicates/Comparison:: Charset predicates. | |
1975 | * SRFI-14 Iterating Over Character Sets:: Enumerate charset elements. | |
85a9b4ed | 1976 | * SRFI-14 Creating Character Sets:: Making new charsets. |
a0e07ba4 NJ |
1977 | * SRFI-14 Querying Character Sets:: Test charsets for membership etc. |
1978 | * SRFI-14 Character-Set Algebra:: Calculating new charsets. | |
1979 | * SRFI-14 Standard Character Sets:: Variables containing predefined charsets. | |
1980 | @end menu | |
1981 | ||
1982 | ||
1983 | @node Loading SRFI-14 | |
3229f68b | 1984 | @subsubsection Loading SRFI-14 |
a0e07ba4 NJ |
1985 | |
1986 | When Guile is properly installed, SRFI-14 support can be loaded into a | |
1987 | running Guile by using the @code{(srfi srfi-14)} module. | |
1988 | ||
1989 | @example | |
1990 | $ guile | |
1991 | guile> (use-modules (srfi srfi-14)) | |
1992 | guile> (char-set-union (char-set #\f #\o #\o) (string->char-set "bar")) | |
1993 | #<charset @{#\a #\b #\f #\o #\r@}> | |
1994 | guile> | |
1995 | @end example | |
1996 | ||
1997 | ||
1998 | @node SRFI-14 Character Set Data Type | |
3229f68b | 1999 | @subsubsection Character Set Data Type |
a0e07ba4 NJ |
2000 | |
2001 | The data type @dfn{charset} implements sets of characters | |
2002 | (@pxref{Characters}). Because the internal representation of character | |
2003 | sets is not visible to the user, a lot of procedures for handling them | |
2004 | are provided. | |
2005 | ||
2006 | Character sets can be created, extended, tested for the membership of a | |
2007 | characters and be compared to other character sets. | |
2008 | ||
2009 | The Guile implementation of character sets deals with 8-bit characters. | |
2010 | In the standard variables, only the ASCII part of the character range is | |
2011 | really used, so that for example @dfn{Umlaute} and other accented | |
2012 | characters are not considered to be letters. In the future, as Guile | |
2013 | may get support for international character sets, this will change, so | |
2014 | don't rely on these ``features''. | |
2015 | ||
2016 | ||
2017 | @c =================================================================== | |
2018 | ||
2019 | @node SRFI-14 Predicates/Comparison | |
3229f68b | 2020 | @subsubsection Predicates/Comparison |
a0e07ba4 NJ |
2021 | |
2022 | Use these procedures for testing whether an object is a character set, | |
2023 | or whether several character sets are equal or subsets of each other. | |
2024 | @code{char-set-hash} can be used for calculating a hash value, maybe for | |
2025 | usage in fast lookup procedures. | |
2026 | ||
8f85c0c6 | 2027 | @deffn {Scheme Procedure} char-set? obj |
a0e07ba4 NJ |
2028 | Return @code{#t} if @var{obj} is a character set, @code{#f} |
2029 | otherwise. | |
2030 | @end deffn | |
2031 | ||
8f85c0c6 | 2032 | @deffn {Scheme Procedure} char-set= cs1 @dots{} |
a0e07ba4 NJ |
2033 | Return @code{#t} if all given character sets are equal. |
2034 | @end deffn | |
2035 | ||
8f85c0c6 | 2036 | @deffn {Scheme Procedure} char-set<= cs1 @dots{} |
a0e07ba4 NJ |
2037 | Return @code{#t} if every character set @var{cs}i is a subset |
2038 | of character set @var{cs}i+1. | |
2039 | @end deffn | |
2040 | ||
8f85c0c6 | 2041 | @deffn {Scheme Procedure} char-set-hash cs [bound] |
a0e07ba4 NJ |
2042 | Compute a hash value for the character set @var{cs}. If |
2043 | @var{bound} is given and not @code{#f}, it restricts the | |
2044 | returned value to the range 0 @dots{} @var{bound - 1}. | |
2045 | @end deffn | |
2046 | ||
2047 | ||
2048 | @c =================================================================== | |
2049 | ||
2050 | @node SRFI-14 Iterating Over Character Sets | |
3229f68b | 2051 | @subsubsection Iterating Over Character Sets |
a0e07ba4 NJ |
2052 | |
2053 | Character set cursors are a means for iterating over the members of a | |
2054 | character sets. After creating a character set cursor with | |
2055 | @code{char-set-cursor}, a cursor can be dereferenced with | |
2056 | @code{char-set-ref}, advanced to the next member with | |
2057 | @code{char-set-cursor-next}. Whether a cursor has passed past the last | |
2058 | element of the set can be checked with @code{end-of-char-set?}. | |
2059 | ||
2060 | Additionally, mapping and (un-)folding procedures for character sets are | |
2061 | provided. | |
2062 | ||
8f85c0c6 | 2063 | @deffn {Scheme Procedure} char-set-cursor cs |
a0e07ba4 NJ |
2064 | Return a cursor into the character set @var{cs}. |
2065 | @end deffn | |
2066 | ||
8f85c0c6 | 2067 | @deffn {Scheme Procedure} char-set-ref cs cursor |
a0e07ba4 NJ |
2068 | Return the character at the current cursor position |
2069 | @var{cursor} in the character set @var{cs}. It is an error to | |
2070 | pass a cursor for which @code{end-of-char-set?} returns true. | |
2071 | @end deffn | |
2072 | ||
8f85c0c6 | 2073 | @deffn {Scheme Procedure} char-set-cursor-next cs cursor |
a0e07ba4 NJ |
2074 | Advance the character set cursor @var{cursor} to the next |
2075 | character in the character set @var{cs}. It is an error if the | |
2076 | cursor given satisfies @code{end-of-char-set?}. | |
2077 | @end deffn | |
2078 | ||
8f85c0c6 | 2079 | @deffn {Scheme Procedure} end-of-char-set? cursor |
a0e07ba4 NJ |
2080 | Return @code{#t} if @var{cursor} has reached the end of a |
2081 | character set, @code{#f} otherwise. | |
2082 | @end deffn | |
2083 | ||
8f85c0c6 | 2084 | @deffn {Scheme Procedure} char-set-fold kons knil cs |
a0e07ba4 NJ |
2085 | Fold the procedure @var{kons} over the character set @var{cs}, |
2086 | initializing it with @var{knil}. | |
2087 | @end deffn | |
2088 | ||
8f85c0c6 NJ |
2089 | @deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs] |
2090 | @deffnx {Scheme Procedure} char-set-unfold! p f g seed base_cs | |
a0e07ba4 NJ |
2091 | This is a fundamental constructor for character sets. |
2092 | @itemize @bullet | |
12991fed | 2093 | @item @var{g} is used to generate a series of ``seed'' values |
a0e07ba4 NJ |
2094 | from the initial seed: @var{seed}, (@var{g} @var{seed}), |
2095 | (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{} | |
2096 | @item @var{p} tells us when to stop -- when it returns true | |
12991fed | 2097 | when applied to one of the seed values. |
a0e07ba4 NJ |
2098 | @item @var{f} maps each seed value to a character. These |
2099 | characters are added to the base character set @var{base_cs} to | |
2100 | form the result; @var{base_cs} defaults to the empty set. | |
2101 | @end itemize | |
2102 | ||
2103 | @code{char-set-unfold!} is the side-effecting variant. | |
2104 | @end deffn | |
2105 | ||
8f85c0c6 | 2106 | @deffn {Scheme Procedure} char-set-for-each proc cs |
a0e07ba4 NJ |
2107 | Apply @var{proc} to every character in the character set |
2108 | @var{cs}. The return value is not specified. | |
2109 | @end deffn | |
2110 | ||
8f85c0c6 | 2111 | @deffn {Scheme Procedure} char-set-map proc cs |
a0e07ba4 NJ |
2112 | Map the procedure @var{proc} over every character in @var{cs}. |
2113 | @var{proc} must be a character -> character procedure. | |
2114 | @end deffn | |
2115 | ||
2116 | ||
2117 | @c =================================================================== | |
2118 | ||
2119 | @node SRFI-14 Creating Character Sets | |
3229f68b | 2120 | @subsubsection Creating Character Sets |
a0e07ba4 NJ |
2121 | |
2122 | New character sets are produced with these procedures. | |
2123 | ||
8f85c0c6 | 2124 | @deffn {Scheme Procedure} char-set-copy cs |
a0e07ba4 NJ |
2125 | Return a newly allocated character set containing all |
2126 | characters in @var{cs}. | |
2127 | @end deffn | |
2128 | ||
8f85c0c6 | 2129 | @deffn {Scheme Procedure} char-set char1 @dots{} |
a0e07ba4 NJ |
2130 | Return a character set containing all given characters. |
2131 | @end deffn | |
2132 | ||
8f85c0c6 NJ |
2133 | @deffn {Scheme Procedure} list->char-set char_list [base_cs] |
2134 | @deffnx {Scheme Procedure} list->char-set! char_list base_cs | |
a0e07ba4 NJ |
2135 | Convert the character list @var{list} to a character set. If |
2136 | the character set @var{base_cs} is given, the character in this | |
2137 | set are also included in the result. | |
2138 | ||
2139 | @code{list->char-set!} is the side-effecting variant. | |
2140 | @end deffn | |
2141 | ||
8f85c0c6 NJ |
2142 | @deffn {Scheme Procedure} string->char-set s [base_cs] |
2143 | @deffnx {Scheme Procedure} string->char-set! s base_cs | |
a0e07ba4 NJ |
2144 | Convert the string @var{str} to a character set. If the |
2145 | character set @var{base_cs} is given, the characters in this | |
2146 | set are also included in the result. | |
2147 | ||
2148 | @code{string->char-set!} is the side-effecting variant. | |
2149 | @end deffn | |
2150 | ||
8f85c0c6 NJ |
2151 | @deffn {Scheme Procedure} char-set-filter pred cs [base_cs] |
2152 | @deffnx {Scheme Procedure} char-set-filter! pred cs base_cs | |
a0e07ba4 NJ |
2153 | Return a character set containing every character from @var{cs} |
2154 | so that it satisfies @var{pred}. If provided, the characters | |
2155 | from @var{base_cs} are added to the result. | |
2156 | ||
2157 | @code{char-set-filter!} is the side-effecting variant. | |
2158 | @end deffn | |
2159 | ||
8f85c0c6 NJ |
2160 | @deffn {Scheme Procedure} ucs-range->char-set lower upper [error? base_cs] |
2161 | @deffnx {Scheme Procedure} uce-range->char-set! lower upper error? base_cs | |
a0e07ba4 NJ |
2162 | Return a character set containing all characters whose |
2163 | character codes lie in the half-open range | |
2164 | [@var{lower},@var{upper}). | |
2165 | ||
2166 | If @var{error} is a true value, an error is signalled if the | |
2167 | specified range contains characters which are not contained in | |
2168 | the implemented character range. If @var{error} is @code{#f}, | |
85a9b4ed | 2169 | these characters are silently left out of the resulting |
a0e07ba4 NJ |
2170 | character set. |
2171 | ||
2172 | The characters in @var{base_cs} are added to the result, if | |
2173 | given. | |
2174 | ||
2175 | @code{ucs-range->char-set!} is the side-effecting variant. | |
2176 | @end deffn | |
2177 | ||
8f85c0c6 | 2178 | @deffn {Scheme Procedure} ->char-set x |
a0e07ba4 NJ |
2179 | Coerce @var{x} into a character set. @var{x} may be a string, a |
2180 | character or a character set. | |
2181 | @end deffn | |
2182 | ||
2183 | ||
2184 | @c =================================================================== | |
2185 | ||
2186 | @node SRFI-14 Querying Character Sets | |
3229f68b | 2187 | @subsubsection Querying Character Sets |
a0e07ba4 NJ |
2188 | |
2189 | Access the elements and other information of a character set with these | |
2190 | procedures. | |
2191 | ||
8f85c0c6 | 2192 | @deffn {Scheme Procedure} char-set-size cs |
a0e07ba4 NJ |
2193 | Return the number of elements in character set @var{cs}. |
2194 | @end deffn | |
2195 | ||
8f85c0c6 | 2196 | @deffn {Scheme Procedure} char-set-count pred cs |
a0e07ba4 NJ |
2197 | Return the number of the elements int the character set |
2198 | @var{cs} which satisfy the predicate @var{pred}. | |
2199 | @end deffn | |
2200 | ||
8f85c0c6 | 2201 | @deffn {Scheme Procedure} char-set->list cs |
a0e07ba4 NJ |
2202 | Return a list containing the elements of the character set |
2203 | @var{cs}. | |
2204 | @end deffn | |
2205 | ||
8f85c0c6 | 2206 | @deffn {Scheme Procedure} char-set->string cs |
a0e07ba4 NJ |
2207 | Return a string containing the elements of the character set |
2208 | @var{cs}. The order in which the characters are placed in the | |
2209 | string is not defined. | |
2210 | @end deffn | |
2211 | ||
8f85c0c6 | 2212 | @deffn {Scheme Procedure} char-set-contains? cs char |
a0e07ba4 NJ |
2213 | Return @code{#t} iff the character @var{ch} is contained in the |
2214 | character set @var{cs}. | |
2215 | @end deffn | |
2216 | ||
8f85c0c6 | 2217 | @deffn {Scheme Procedure} char-set-every pred cs |
a0e07ba4 NJ |
2218 | Return a true value if every character in the character set |
2219 | @var{cs} satisfies the predicate @var{pred}. | |
2220 | @end deffn | |
2221 | ||
8f85c0c6 | 2222 | @deffn {Scheme Procedure} char-set-any pred cs |
a0e07ba4 NJ |
2223 | Return a true value if any character in the character set |
2224 | @var{cs} satisfies the predicate @var{pred}. | |
2225 | @end deffn | |
2226 | ||
2227 | ||
2228 | @c =================================================================== | |
2229 | ||
2230 | @node SRFI-14 Character-Set Algebra | |
3229f68b | 2231 | @subsubsection Character-Set Algebra |
a0e07ba4 NJ |
2232 | |
2233 | Character sets can be manipulated with the common set algebra operation, | |
2234 | such as union, complement, intersection etc. All of these procedures | |
2235 | provide side-effecting variants, which modify their character set | |
2236 | argument(s). | |
2237 | ||
8f85c0c6 NJ |
2238 | @deffn {Scheme Procedure} char-set-adjoin cs char1 @dots{} |
2239 | @deffnx {Scheme Procedure} char-set-adjoin! cs char1 @dots{} | |
a0e07ba4 NJ |
2240 | Add all character arguments to the first argument, which must |
2241 | be a character set. | |
2242 | @end deffn | |
2243 | ||
8f85c0c6 NJ |
2244 | @deffn {Scheme Procedure} char-set-delete cs char1 @dots{} |
2245 | @deffnx {Scheme Procedure} char-set-delete! cs char1 @dots{} | |
a0e07ba4 NJ |
2246 | Delete all character arguments from the first argument, which |
2247 | must be a character set. | |
2248 | @end deffn | |
2249 | ||
8f85c0c6 NJ |
2250 | @deffn {Scheme Procedure} char-set-complement cs |
2251 | @deffnx {Scheme Procedure} char-set-complement! cs | |
a0e07ba4 NJ |
2252 | Return the complement of the character set @var{cs}. |
2253 | @end deffn | |
2254 | ||
8f85c0c6 NJ |
2255 | @deffn {Scheme Procedure} char-set-union cs1 @dots{} |
2256 | @deffnx {Scheme Procedure} char-set-union! cs1 @dots{} | |
a0e07ba4 NJ |
2257 | Return the union of all argument character sets. |
2258 | @end deffn | |
2259 | ||
8f85c0c6 NJ |
2260 | @deffn {Scheme Procedure} char-set-intersection cs1 @dots{} |
2261 | @deffnx {Scheme Procedure} char-set-intersection! cs1 @dots{} | |
a0e07ba4 NJ |
2262 | Return the intersection of all argument character sets. |
2263 | @end deffn | |
2264 | ||
8f85c0c6 NJ |
2265 | @deffn {Scheme Procedure} char-set-difference cs1 @dots{} |
2266 | @deffnx {Scheme Procedure} char-set-difference! cs1 @dots{} | |
a0e07ba4 NJ |
2267 | Return the difference of all argument character sets. |
2268 | @end deffn | |
2269 | ||
8f85c0c6 NJ |
2270 | @deffn {Scheme Procedure} char-set-xor cs1 @dots{} |
2271 | @deffnx {Scheme Procedure} char-set-xor! cs1 @dots{} | |
a0e07ba4 NJ |
2272 | Return the exclusive-or of all argument character sets. |
2273 | @end deffn | |
2274 | ||
8f85c0c6 NJ |
2275 | @deffn {Scheme Procedure} char-set-diff+intersection cs1 @dots{} |
2276 | @deffnx {Scheme Procedure} char-set-diff+intersection! cs1 @dots{} | |
a0e07ba4 NJ |
2277 | Return the difference and the intersection of all argument |
2278 | character sets. | |
2279 | @end deffn | |
2280 | ||
2281 | ||
2282 | @c =================================================================== | |
2283 | ||
2284 | @node SRFI-14 Standard Character Sets | |
3229f68b | 2285 | @subsubsection Standard Character Sets |
a0e07ba4 NJ |
2286 | |
2287 | In order to make the use of the character set data type and procedures | |
2288 | useful, several predefined character set variables exist. | |
2289 | ||
2290 | @defvar char-set:lower-case | |
2291 | All lower-case characters. | |
2292 | @end defvar | |
2293 | ||
2294 | @defvar char-set:upper-case | |
2295 | All upper-case characters. | |
2296 | @end defvar | |
2297 | ||
2298 | @defvar char-set:title-case | |
2299 | This is empty, because ASCII has no titlecase characters. | |
2300 | @end defvar | |
2301 | ||
2302 | @defvar char-set:letter | |
2303 | All letters, e.g. the union of @code{char-set:lower-case} and | |
2304 | @code{char-set:upper-case}. | |
2305 | @end defvar | |
2306 | ||
2307 | @defvar char-set:digit | |
2308 | All digits. | |
2309 | @end defvar | |
2310 | ||
2311 | @defvar char-set:letter+digit | |
2312 | The union of @code{char-set:letter} and @code{char-set:digit}. | |
2313 | @end defvar | |
2314 | ||
2315 | @defvar char-set:graphic | |
2316 | All characters which would put ink on the paper. | |
2317 | @end defvar | |
2318 | ||
2319 | @defvar char-set:printing | |
2320 | The union of @code{char-set:graphic} and @code{char-set:whitespace}. | |
2321 | @end defvar | |
2322 | ||
2323 | @defvar char-set:whitespace | |
2324 | All whitespace characters. | |
2325 | @end defvar | |
2326 | ||
2327 | @defvar char-set:blank | |
2328 | All horizontal whitespace characters, that is @code{#\space} and | |
2329 | @code{#\tab}. | |
2330 | @end defvar | |
2331 | ||
2332 | @defvar char-set:iso-control | |
2333 | The ISO control characters with the codes 0--31 and 127. | |
2334 | @end defvar | |
2335 | ||
2336 | @defvar char-set:punctuation | |
2337 | The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}} | |
2338 | @end defvar | |
2339 | ||
2340 | @defvar char-set:symbol | |
2341 | The characters @code{$+<=>^`|~}. | |
2342 | @end defvar | |
2343 | ||
2344 | @defvar char-set:hex-digit | |
2345 | The hexadecimal digits @code{0123456789abcdefABCDEF}. | |
2346 | @end defvar | |
2347 | ||
2348 | @defvar char-set:ascii | |
2349 | All ASCII characters. | |
2350 | @end defvar | |
2351 | ||
2352 | @defvar char-set:empty | |
2353 | The empty character set. | |
2354 | @end defvar | |
2355 | ||
2356 | @defvar char-set:full | |
2357 | This character set contains all possible characters. | |
2358 | @end defvar | |
2359 | ||
2360 | @node SRFI-16 | |
3229f68b | 2361 | @subsection SRFI-16 - case-lambda |
8742c48b | 2362 | @cindex SRFI-16 |
a0e07ba4 NJ |
2363 | |
2364 | @c FIXME::martin: Review me! | |
2365 | ||
8742c48b | 2366 | @findex case-lambda |
a0e07ba4 NJ |
2367 | The syntactic form @code{case-lambda} creates procedures, just like |
2368 | @code{lambda}, but has syntactic extensions for writing procedures of | |
2369 | varying arity easier. | |
2370 | ||
2371 | The syntax of the @code{case-lambda} form is defined in the following | |
2372 | EBNF grammar. | |
2373 | ||
2374 | @example | |
2375 | @group | |
2376 | <case-lambda> | |
2377 | --> (case-lambda <case-lambda-clause>) | |
2378 | <case-lambda-clause> | |
2379 | --> (<formals> <definition-or-command>*) | |
2380 | <formals> | |
2381 | --> (<identifier>*) | |
2382 | | (<identifier>* . <identifier>) | |
2383 | | <identifier> | |
2384 | @end group | |
2385 | @end example | |
2386 | ||
2387 | The value returned by a @code{case-lambda} form is a procedure which | |
2388 | matches the number of actual arguments against the formals in the | |
2389 | various clauses, in order. @dfn{Formals} means a formal argument list | |
2390 | just like with @code{lambda} (@pxref{Lambda}). The first matching clause | |
2391 | is selected, the corresponding values from the actual parameter list are | |
2392 | bound to the variable names in the clauses and the body of the clause is | |
2393 | evaluated. If no clause matches, an error is signalled. | |
2394 | ||
2395 | The following (silly) definition creates a procedure @var{foo} which | |
2396 | acts differently, depending on the number of actual arguments. If one | |
2397 | argument is given, the constant @code{#t} is returned, two arguments are | |
2398 | added and if more arguments are passed, their product is calculated. | |
2399 | ||
2400 | @lisp | |
2401 | (define foo (case-lambda | |
2402 | ((x) #t) | |
2403 | ((x y) (+ x y)) | |
2404 | (z | |
2405 | (apply * z)))) | |
2406 | (foo 'bar) | |
2407 | @result{} | |
2408 | #t | |
2409 | (foo 2 4) | |
2410 | @result{} | |
2411 | 6 | |
2412 | (foo 3 3 3) | |
2413 | @result{} | |
2414 | 27 | |
2415 | (foo) | |
2416 | @result{} | |
2417 | 1 | |
2418 | @end lisp | |
2419 | ||
2420 | The last expression evaluates to 1 because the last clause is matched, | |
2421 | @var{z} is bound to the empty list and the following multiplication, | |
2422 | applied to zero arguments, yields 1. | |
2423 | ||
2424 | ||
2425 | @node SRFI-17 | |
3229f68b | 2426 | @subsection SRFI-17 - Generalized set! |
8742c48b | 2427 | @cindex SRFI-17 |
a0e07ba4 NJ |
2428 | |
2429 | This is an implementation of SRFI-17: Generalized set! | |
2430 | ||
8742c48b | 2431 | @findex getter-with-setter |
a0e07ba4 NJ |
2432 | It exports the Guile procedure @code{make-procedure-with-setter} under |
2433 | the SRFI name @code{getter-with-setter} and exports the standard | |
2434 | procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr}, | |
2435 | @code{string-ref} and @code{vector-ref} as procedures with setters, as | |
2436 | required by the SRFI. | |
2437 | ||
2438 | SRFI-17 was heavily criticized during its discussion period but it was | |
2439 | finalized anyway. One issue was its concept of globally associating | |
2440 | setter @dfn{properties} with (procedure) values, which is non-Schemy. | |
2441 | For this reason, this implementation chooses not to provide a way to set | |
2442 | the setter of a procedure. In fact, @code{(set! (setter @var{proc}) | |
2443 | @var{setter})} signals an error. The only way to attach a setter to a | |
2444 | procedure is to create a new object (a @dfn{procedure with setter}) via | |
2445 | the @code{getter-with-setter} procedure. This procedure is also | |
2446 | specified in the SRFI. Using it avoids the described problems. | |
2447 | ||
12991fed TTN |
2448 | |
2449 | @node SRFI-19 | |
3229f68b | 2450 | @subsection SRFI-19 - Time/Date Library |
8742c48b | 2451 | @cindex SRFI-19 |
12991fed | 2452 | |
85600a0f KR |
2453 | This is an implementation of the SRFI-19 time/date library. The |
2454 | functions and variables described here are provided by | |
12991fed TTN |
2455 | |
2456 | @example | |
85600a0f | 2457 | (use-modules (srfi srfi-19)) |
12991fed TTN |
2458 | @end example |
2459 | ||
85600a0f KR |
2460 | @menu |
2461 | * SRFI-19 Introduction:: | |
2462 | * SRFI-19 Time:: | |
2463 | * SRFI-19 Date:: | |
2464 | * SRFI-19 Time/Date conversions:: | |
2465 | * SRFI-19 Date to string:: | |
2466 | * SRFI-19 String to date:: | |
2467 | @end menu | |
12991fed | 2468 | |
85600a0f | 2469 | @node SRFI-19 Introduction |
3229f68b | 2470 | @subsubsection SRFI-19 Introduction |
85600a0f KR |
2471 | |
2472 | @cindex universal time | |
2473 | @cindex atomic time | |
2474 | @cindex UTC | |
2475 | @cindex TAI | |
2476 | This module implements time and date representations and calculations, | |
2477 | in various time systems, including universal time (UTC) and atomic | |
2478 | time (TAI). | |
2479 | ||
2480 | For those not familiar with these time systems, TAI is based on a | |
2481 | fixed length second derived from oscillations of certain atoms. UTC | |
2482 | differs from TAI by an integral number of seconds, which is increased | |
2483 | or decreased at announced times to keep UTC aligned to a mean solar | |
2484 | day (the orbit and rotation of the earth are not quite constant). | |
2485 | ||
2486 | @cindex leap second | |
2487 | So far, only increases in the TAI | |
2488 | @tex | |
2489 | $\leftrightarrow$ | |
2490 | @end tex | |
2491 | @ifnottex | |
2492 | <-> | |
2493 | @end ifnottex | |
2494 | UTC difference have been needed. Such an increase is a ``leap | |
2495 | second'', an extra second of TAI introduced at the end of a UTC day. | |
2496 | When working entirely within UTC this is never seen, every day simply | |
2497 | has 86400 seconds. But when converting from TAI to a UTC date, an | |
2498 | extra 23:59:60 is present, where normally a day would end at 23:59:59. | |
2499 | Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI | |
2500 | seconds. | |
2501 | ||
2502 | @cindex system clock | |
2503 | In the current implementation, the system clock is assumed to be UTC, | |
2504 | and a table of leap seconds in the code converts to TAI. See comments | |
2505 | in @file{srfi-19.scm} for how to update this table. | |
2506 | ||
2507 | @cindex julian day | |
2508 | @cindex modified julian day | |
2509 | Also, for those not familiar with the terminology, a @dfn{Julian Day} | |
2510 | is a real number which is a count of days and fraction of a day, in | |
2511 | UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan | |
2512 | 4713 B.C. And a @dfn{Modified Julian Day} is the same, but starting | |
2513 | from 1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC. | |
2514 | ||
2515 | @c The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at | |
2516 | @c noon, UTC), but this is incorrect. It looks like it might have | |
2517 | @c arisen from the code incorrectly treating years a multiple of 100 | |
2518 | @c but not 400 prior to 1582 as leap years, where instead the Julian | |
2519 | @c calendar should be used so all multiples of 4 before 1582 are leap | |
2520 | @c years. | |
2521 | ||
2522 | ||
2523 | @node SRFI-19 Time | |
3229f68b | 2524 | @subsubsection SRFI-19 Time |
85600a0f KR |
2525 | @cindex time |
2526 | ||
2527 | A @dfn{time} object has type, seconds and nanoseconds fields | |
2528 | representing a point in time starting from some epoch. This is an | |
2529 | arbitrary point in time, not just a time of day. Although times are | |
2530 | represented in nanoseconds, the actual resolution may be lower. | |
2531 | ||
2532 | The following variables hold the possible time types. For instance | |
2533 | @code{(current-time time-process)} would give the current CPU process | |
2534 | time. | |
2535 | ||
2536 | @defvar time-utc | |
2537 | Universal Coordinated Time (UTC). | |
2538 | @cindex UTC | |
2539 | @end defvar | |
12991fed | 2540 | |
85600a0f KR |
2541 | @defvar time-tai |
2542 | International Atomic Time (TAI). | |
2543 | @cindex TAI | |
2544 | @end defvar | |
12991fed | 2545 | |
85600a0f KR |
2546 | @defvar time-monotonic |
2547 | Monotonic time, meaning a monotonically increasing time starting from | |
2548 | an unspecified epoch. | |
12991fed | 2549 | |
85600a0f KR |
2550 | Note that in the current implementation @code{time-monotonic} is the |
2551 | same as @code{time-tai}, and unfortunately is therefore affected by | |
2552 | adjustments to the system clock. Perhaps this will change in the | |
2553 | future. | |
2554 | @end defvar | |
12991fed | 2555 | |
85600a0f KR |
2556 | @defvar time-duration |
2557 | A duration, meaning simply a difference between two times. | |
2558 | @end defvar | |
12991fed | 2559 | |
85600a0f KR |
2560 | @defvar time-process |
2561 | CPU time spent in the current process, starting from when the process | |
2562 | began. | |
2563 | @cindex process time | |
2564 | @end defvar | |
12991fed | 2565 | |
85600a0f KR |
2566 | @defvar time-thread |
2567 | CPU time spent in the current thread. Not currently implemented. | |
2568 | @cindex thread time | |
2569 | @end defvar | |
12991fed | 2570 | |
85600a0f KR |
2571 | @sp 1 |
2572 | @defun time? obj | |
2573 | Return @code{#t} if @var{obj} is a time object, or @code{#f} if not. | |
2574 | @end defun | |
2575 | ||
2576 | @defun make-time type nanoseconds seconds | |
2577 | Create a time object with the given @var{type}, @var{seconds} and | |
2578 | @var{nanoseconds}. | |
2579 | @end defun | |
2580 | ||
2581 | @defun time-type time | |
2582 | @defunx time-nanosecond time | |
2583 | @defunx time-second time | |
2584 | @defunx set-time-type! time type | |
2585 | @defunx set-time-nanosecond! time nsec | |
2586 | @defunx set-time-second! time sec | |
2587 | Get or set the type, seconds or nanoseconds fields of a time object. | |
2588 | ||
2589 | @code{set-time-type!} merely changes the field, it doesn't convert the | |
2590 | time value. For conversions, see @ref{SRFI-19 Time/Date conversions}. | |
2591 | @end defun | |
2592 | ||
2593 | @defun copy-time time | |
2594 | Return a new time object, which is a copy of the given @var{time}. | |
2595 | @end defun | |
2596 | ||
2597 | @defun current-time [type] | |
2598 | Return the current time of the given @var{type}. The default | |
2599 | @var{type} is @code{time-utc}. | |
2600 | ||
2601 | Note that the name @code{current-time} conflicts with the Guile core | |
2602 | @code{current-time} function (@pxref{Time}). Applications wanting to | |
2603 | use both will need to use a different name for one of them. | |
2604 | @end defun | |
2605 | ||
2606 | @defun time-resolution [type] | |
2607 | Return the resolution, in nanoseconds, of the given time @var{type}. | |
2608 | The default @var{type} is @code{time-utc}. | |
2609 | @end defun | |
2610 | ||
2611 | @defun time<=? t1 t2 | |
2612 | @defunx time<? t1 t2 | |
2613 | @defunx time=? t1 t2 | |
2614 | @defunx time>=? t1 t2 | |
2615 | @defunx time>? t1 t2 | |
2616 | Return @code{#t} or @code{#f} according to the respective relation | |
2617 | between time objects @var{t1} and @var{t2}. @var{t1} and @var{t2} | |
2618 | must be the same time type. | |
2619 | @end defun | |
2620 | ||
2621 | @defun time-difference t1 t2 | |
2622 | @defunx time-difference! t1 t2 | |
2623 | Return a time object of type @code{time-duration} representing the | |
2624 | period between @var{t1} and @var{t2}. @var{t1} and @var{t2} must be | |
2625 | the same time type. | |
2626 | ||
2627 | @code{time-difference} returns a new time object, | |
2628 | @code{time-difference!} may modify @var{t1} to form its return. | |
2629 | @end defun | |
2630 | ||
2631 | @defun add-duration time duration | |
2632 | @defunx add-duration! time duration | |
2633 | @defunx subtract-duration time duration | |
2634 | @defunx subtract-duration! time duration | |
2635 | Return a time object which is @var{time} with the given @var{duration} | |
2636 | added or subtracted. @var{duration} must be a time object of type | |
2637 | @code{time-duration}. | |
2638 | ||
2639 | @code{add-duration} and @code{subtract-duration} return a new time | |
2640 | object. @code{add-duration!} and @code{subtract-duration!} may modify | |
2641 | the given @var{time} to form their return. | |
2642 | @end defun | |
2643 | ||
2644 | ||
2645 | @node SRFI-19 Date | |
3229f68b | 2646 | @subsubsection SRFI-19 Date |
85600a0f KR |
2647 | @cindex date |
2648 | ||
2649 | A @dfn{date} object represents a date in the Gregorian calendar and a | |
2650 | time of day on that date in some timezone. | |
2651 | ||
2652 | The fields are year, month, day, hour, minute, second, nanoseconds and | |
2653 | timezone. A date object is immutable, its fields can be read but they | |
2654 | cannot be modified once the object is created. | |
2655 | ||
2656 | @defun date? obj | |
2657 | Return @code{#t} if @var{obj} is a date object, or @code{#f} if not. | |
2658 | @end defun | |
2659 | ||
2660 | @defun make-date nsecs seconds minutes hours date month year zone-offset | |
2661 | Create a new date object. | |
2662 | @c | |
2663 | @c FIXME: What can we say about the ranges of the values. The | |
2664 | @c current code looks it doesn't normalize, but expects then in their | |
2665 | @c usual range already. | |
2666 | @c | |
2667 | @end defun | |
2668 | ||
2669 | @defun date-nanosecond date | |
2670 | Nanoseconds, 0 to 999999999. | |
2671 | @end defun | |
2672 | ||
2673 | @defun date-second date | |
2674 | Seconds, 0 to 60. 0 to 59 is the usual range, 60 is for a leap second. | |
2675 | @end defun | |
2676 | ||
2677 | @defun date-minute date | |
2678 | Minutes, 0 to 59. | |
2679 | @end defun | |
2680 | ||
2681 | @defun date-hour date | |
2682 | Hour, 0 to 23. | |
2683 | @end defun | |
2684 | ||
2685 | @defun date-day date | |
2686 | Day of the month, 1 to 31 (or less, according to the month). | |
2687 | @end defun | |
2688 | ||
2689 | @defun date-month date | |
2690 | Month, 1 to 12. | |
2691 | @end defun | |
2692 | ||
2693 | @defun date-year date | |
2694 | Year, eg.@: 2003. | |
2695 | @end defun | |
2696 | ||
2697 | @defun date-zone-offset date | |
2698 | Time zone, an integer number of seconds east of Greenwich. | |
2699 | @end defun | |
2700 | ||
2701 | @defun date-year-day date | |
2702 | Day of the year, starting from 1 for 1st January. | |
2703 | @end defun | |
2704 | ||
2705 | @defun date-week-day date | |
2706 | Day of the week, starting from 0 for Sunday. | |
2707 | @end defun | |
2708 | ||
2709 | @defun date-week-number date dstartw | |
2710 | Week of the year, ignoring a first partial week. @var{dstartw} is the | |
2711 | day of the week which is taken to start a week, 0 for Sunday, 1 for | |
2712 | Monday, etc. | |
2713 | @c | |
2714 | @c FIXME: The spec doesn't say whether numbering starts at 0 or 1. | |
2715 | @c The code looks like it's 0, if that's the correct intention. | |
2716 | @c | |
2717 | @end defun | |
2718 | ||
2719 | @c The SRFI text doesn't actually give the default for tz-offset, but | |
2720 | @c the reference implementation has the local timezone and the | |
2721 | @c conversions functions all specify that, so it should be ok to | |
2722 | @c document it here. | |
2723 | @c | |
2724 | @defun current-date [tz-offset] | |
2725 | Return a date object representing the current date/time UTC. | |
2726 | @var{tz-offset} is seconds east of Greenwich, and defaults to the | |
2727 | local timezone. | |
2728 | @end defun | |
2729 | ||
2730 | @defun current-julian-day | |
2731 | @cindex julian day | |
2732 | Return the current Julian Day. | |
2733 | @end defun | |
2734 | ||
2735 | @defun current-modified-julian-day | |
2736 | @cindex modified julian day | |
2737 | Return the current Modified Julian Day. | |
2738 | @end defun | |
2739 | ||
2740 | ||
2741 | @node SRFI-19 Time/Date conversions | |
3229f68b | 2742 | @subsubsection SRFI-19 Time/Date conversions |
85600a0f KR |
2743 | |
2744 | @defun date->julian-day date | |
2745 | @defunx date->modified-julian-day date | |
2746 | @defunx date->time-monotonic date | |
2747 | @defunx date->time-tai date | |
2748 | @defunx date->time-utc date | |
2749 | @end defun | |
2750 | @defun julian-day->date jdn [tz-offset] | |
2751 | @defunx julian-day->time-monotonic jdn | |
2752 | @defunx julian-day->time-tai jdn | |
2753 | @defunx julian-day->time-utc jdn | |
2754 | @end defun | |
2755 | @defun modified-julian-day->date jdn [tz-offset] | |
2756 | @defunx modified-julian-day->time-monotonic jdn | |
2757 | @defunx modified-julian-day->time-tai jdn | |
2758 | @defunx modified-julian-day->time-utc jdn | |
2759 | @end defun | |
2760 | @defun time-monotonic->date time [tz-offset] | |
2761 | @defunx time-monotonic->time-tai time | |
2762 | @defunx time-monotonic->time-tai! time | |
2763 | @defunx time-monotonic->time-utc time | |
2764 | @defunx time-monotonic->time-utc! time | |
2765 | @end defun | |
2766 | @defun time-tai->date time [tz-offset] | |
2767 | @defunx time-tai->julian-day time | |
2768 | @defunx time-tai->modified-julian-day time | |
2769 | @defunx time-tai->time-monotonic time | |
2770 | @defunx time-tai->time-monotonic! time | |
2771 | @defunx time-tai->time-utc time | |
2772 | @defunx time-tai->time-utc! time | |
2773 | @end defun | |
2774 | @defun time-utc->date time [tz-offset] | |
2775 | @defunx time-utc->julian-day time | |
2776 | @defunx time-utc->modified-julian-day time | |
2777 | @defunx time-utc->time-monotonic time | |
2778 | @defunx time-utc->time-monotonic! time | |
2779 | @defunx time-utc->time-tai time | |
2780 | @defunx time-utc->time-tai! time | |
2781 | @sp 1 | |
2782 | Convert between dates, times and days of the respective types. For | |
2783 | instance @code{time-tai->time-utc} accepts a @var{time} object of type | |
2784 | @code{time-tai} and returns an object of type @code{time-utc}. | |
2785 | ||
2786 | For conversions to dates, @var{tz-offset} is seconds east of | |
2787 | Greenwich. The default is the local timezone. | |
2788 | ||
2789 | The @code{!} variants may modify their @var{time} argument to form | |
2790 | their return. The plain functions create a new object. | |
2791 | @end defun | |
2792 | ||
2793 | @node SRFI-19 Date to string | |
3229f68b | 2794 | @subsubsection SRFI-19 Date to string |
85600a0f KR |
2795 | @cindex date to string |
2796 | ||
2797 | @defun date->string date [format] | |
2798 | Convert a date to a string under the control of a format. | |
2799 | @var{format} should be a string containing @samp{~} escapes, which | |
2800 | will be expanded as per the following conversion table. The default | |
2801 | @var{format} is @samp{~c}, a locale-dependent date and time. | |
2802 | ||
2803 | Many of these conversion characters are the same as POSIX | |
2804 | @code{strftime} (@pxref{Time}), but there are some extras and some | |
2805 | variations. | |
2806 | ||
2807 | @multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} | |
2808 | @item @nicode{~~} @tab literal ~ | |
2809 | @item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun} | |
2810 | @item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday} | |
2811 | @item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan} | |
2812 | @item @nicode{~B} @tab locale full month, eg.@: @samp{January} | |
2813 | @item @nicode{~c} @tab locale date and time, eg.@: @* | |
2814 | @samp{Fri Jul 14 20:28:42-0400 2000} | |
2815 | @item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31} | |
2816 | ||
2817 | @c Spec says d/m/y, reference implementation says m/d/y. | |
2818 | @c Apparently the reference code was the intention, but would like to | |
2819 | @c see an errata published for the spec before contradicting it here. | |
2820 | @c | |
2821 | @c @item @nicode{~D} @tab date @nicode{~d/~m/~y} | |
2822 | ||
2823 | @item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31} | |
2824 | @item @nicode{~f} @tab seconds and fractional seconds, | |
2825 | with locale decimal point, eg.@: @samp{5.2} | |
2826 | @item @nicode{~h} @tab same as @nicode{~b} | |
2827 | @item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23} | |
2828 | @item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12} | |
2829 | @item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366} | |
2830 | @item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23} | |
2831 | @item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12} | |
2832 | @item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12} | |
2833 | @item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59} | |
2834 | @item @nicode{~n} @tab newline | |
2835 | @item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999} | |
2836 | @item @nicode{~p} @tab locale AM or PM | |
2837 | @item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p} | |
2838 | @item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC | |
2839 | @item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @* | |
2840 | (usual limit is 59, 60 is a leap second) | |
2841 | @item @nicode{~t} @tab horizontal tab character | |
2842 | @item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S} | |
2843 | @item @nicode{~U} @tab week of year, Sunday first day of week, | |
2844 | @samp{00} to @samp{52} | |
2845 | @item @nicode{~V} @tab week of year, Monday first day of week, | |
2846 | @samp{01} to @samp{53} | |
2847 | @item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6} | |
2848 | @item @nicode{~W} @tab week of year, Monday first day of week, | |
2849 | @samp{00} to @samp{52} | |
2850 | ||
2851 | @c The spec has ~x as an apparent duplicate of ~W, and ~X as a locale | |
2852 | @c date. The reference code has ~x as the locale date and ~X as a | |
2853 | @c locale time. The rule is apparently that the code should be | |
2854 | @c believed, but would like to see an errata for the spec before | |
2855 | @c contradicting it here. | |
2856 | @c | |
2857 | @c @item @nicode{~x} @tab week of year, Monday as first day of week, | |
2858 | @c @samp{00} to @samp{53} | |
2859 | @c @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00} | |
2860 | ||
2861 | @item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99} | |
2862 | @item @nicode{~Y} @tab year, full, eg.@: @samp{2003} | |
2863 | @item @nicode{~z} @tab time zone, RFC-822 style | |
2864 | @item @nicode{~Z} @tab time zone symbol (not currently implemented) | |
2865 | @item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d} | |
2866 | @item @nicode{~2} @tab ISO-8601 time+zone, @samp{~k:~M:~S~z} | |
2867 | @item @nicode{~3} @tab ISO-8601 time, @samp{~k:~M:~S} | |
2868 | @item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~k:~M:~S~z} | |
2869 | @item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~k:~M:~S} | |
2870 | @end multitable | |
2871 | @end defun | |
2872 | ||
2873 | Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently | |
2874 | described here, since the specification and reference implementation | |
2875 | differ. | |
2876 | ||
2877 | Currently Guile doesn't implement any localizations for the above, all | |
2878 | outputs are in English, and the @samp{~c} conversion is POSIX | |
2879 | @code{ctime} style @samp{~a ~b ~d ~H:~M:~S~z ~Y}. This may change in | |
2880 | the future. | |
2881 | ||
2882 | ||
2883 | @node SRFI-19 String to date | |
3229f68b | 2884 | @subsubsection SRFI-19 String to date |
85600a0f KR |
2885 | @cindex string to date |
2886 | ||
2887 | @c FIXME: Can we say what happens when an incomplete date is | |
2888 | @c converted? Ie. fields left as 0, or what? The spec seems to be | |
2889 | @c silent on this. | |
2890 | ||
2891 | @defun string->date input template | |
2892 | Convert an @var{input} string to a date under the control of a | |
2893 | @var{template} string. Return a newly created date object. | |
2894 | ||
2895 | Literal characters in @var{template} must match characters in | |
2896 | @var{input} and @samp{~} escapes must match the input forms described | |
2897 | in the table below. ``Skip to'' means characters up to one of the | |
2898 | given type are ignored, or ``no skip'' for no skipping. ``Read'' is | |
2899 | what's then read, and ``Set'' is the field affected in the date | |
2900 | object. | |
2901 | ||
2902 | For example @samp{~Y} skips input characters until a digit is reached, | |
2903 | at which point it expects a year and stores that to the year field of | |
2904 | the date. | |
2905 | ||
2906 | @multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}} | |
2907 | @item | |
2908 | @tab Skip to | |
2909 | @tab Read | |
2910 | @tab Set | |
2911 | ||
2912 | @item @nicode{~~} | |
2913 | @tab no skip | |
2914 | @tab literal ~ | |
2915 | @tab nothing | |
2916 | ||
2917 | @item @nicode{~a} | |
2918 | @tab @nicode{char-alphabetic?} | |
2919 | @tab locale abbreviated weekday name | |
2920 | @tab nothing | |
2921 | ||
2922 | @item @nicode{~A} | |
2923 | @tab @nicode{char-alphabetic?} | |
2924 | @tab locale full weekday name | |
2925 | @tab nothing | |
2926 | ||
2927 | @c Note that the SRFI spec says that ~b and ~B don't set anything, | |
2928 | @c but that looks like a mistake. The reference implementation sets | |
2929 | @c the month field, which seems sensible and is what we describe | |
2930 | @c here. | |
2931 | ||
2932 | @item @nicode{~b} | |
2933 | @tab @nicode{char-alphabetic?} | |
2934 | @tab locale abbreviated month name | |
2935 | @tab @nicode{date-month} | |
2936 | ||
2937 | @item @nicode{~B} | |
2938 | @tab @nicode{char-alphabetic?} | |
2939 | @tab locale full month name | |
2940 | @tab @nicode{date-month} | |
2941 | ||
2942 | @item @nicode{~d} | |
2943 | @tab @nicode{char-numeric?} | |
2944 | @tab day of month | |
2945 | @tab @nicode{date-day} | |
2946 | ||
2947 | @item @nicode{~e} | |
2948 | @tab no skip | |
2949 | @tab day of month, blank padded | |
2950 | @tab @nicode{date-day} | |
2951 | ||
2952 | @item @nicode{~h} | |
2953 | @tab same as @samp{~b} | |
2954 | ||
2955 | @item @nicode{~H} | |
2956 | @tab @nicode{char-numeric?} | |
2957 | @tab hour | |
2958 | @tab @nicode{date-hour} | |
2959 | ||
2960 | @item @nicode{~k} | |
2961 | @tab no skip | |
2962 | @tab hour, blank padded | |
2963 | @tab @nicode{date-hour} | |
2964 | ||
2965 | @item @nicode{~m} | |
2966 | @tab @nicode{char-numeric?} | |
2967 | @tab month | |
2968 | @tab @nicode{date-month} | |
2969 | ||
2970 | @item @nicode{~M} | |
2971 | @tab @nicode{char-numeric?} | |
2972 | @tab minute | |
2973 | @tab @nicode{date-minute} | |
2974 | ||
2975 | @item @nicode{~S} | |
2976 | @tab @nicode{char-numeric?} | |
2977 | @tab second | |
2978 | @tab @nicode{date-second} | |
2979 | ||
2980 | @item @nicode{~y} | |
2981 | @tab no skip | |
2982 | @tab 2-digit year | |
2983 | @tab @nicode{date-year} within 50 years | |
2984 | ||
2985 | @item @nicode{~Y} | |
2986 | @tab @nicode{char-numeric?} | |
2987 | @tab year | |
2988 | @tab @nicode{date-year} | |
2989 | ||
2990 | @item @nicode{~z} | |
2991 | @tab no skip | |
2992 | @tab time zone | |
2993 | @tab date-zone-offset | |
2994 | @end multitable | |
2995 | ||
2996 | Notice that the weekday matching forms don't affect the date object | |
2997 | returned, instead the weekday will be derived from the day, month and | |
2998 | year. | |
2999 | ||
3000 | Currently Guile doesn't implement any localizations for the above, | |
3001 | month and weekday names are always expected in English. This may | |
3002 | change in the future. | |
3003 | @end defun | |
12991fed | 3004 | |
1de8c1ae | 3005 | |
b0b55bd6 | 3006 | @node SRFI-26 |
3229f68b | 3007 | @subsection SRFI-26 - specializing parameters |
1de8c1ae KR |
3008 | @cindex SRFI-26 |
3009 | ||
3010 | This SRFI provides a syntax for conveniently specializing selected | |
3011 | parameters of a function. It can be used with, | |
3012 | ||
3013 | @example | |
3014 | (use-modules (srfi srfi-26)) | |
3015 | @end example | |
3016 | ||
3017 | @deffn {library syntax} cut slot @dots{} | |
3018 | @deffnx {library syntax} cute slot @dots{} | |
3019 | Return a new procedure which will make a call (@var{slot} @dots{}) but | |
3020 | with selected parameters specialized to given expressions. | |
3021 | ||
3022 | An example will illustrate the idea. The following is a | |
3023 | specialization of @code{write}, sending output to | |
3024 | @code{my-output-port}, | |
3025 | ||
3026 | @example | |
3027 | (cut write <> my-output-port) | |
3028 | @result{} | |
3029 | (lambda (obj) (write obj my-output-port)) | |
3030 | @end example | |
3031 | ||
3032 | The special symbol @code{<>} indicates a slot to be filled by an | |
3033 | argument to the new procedure. @code{my-output-port} on the other | |
3034 | hand is an expression to be evaluated and passed, ie.@: it specializes | |
3035 | the behaviour of @code{write}. | |
3036 | ||
3037 | @table @nicode | |
3038 | @item <> | |
3039 | A slot to be filled by an argument from the created procedure. | |
3040 | Arguments are assigned to @code{<>} slots in the order they appear in | |
3041 | the @code{cut} form, there's no way to re-arrange arguments. | |
3042 | ||
3043 | The first argument to @code{cut} is usually a procedure (or expression | |
3044 | giving a procedure), but @code{<>} is allowed there too. For example, | |
3045 | ||
3046 | @example | |
3047 | (cut <> 1 2 3) | |
3048 | @result{} | |
3049 | (lambda (proc) (proc 1 2 3)) | |
3050 | @end example | |
3051 | ||
3052 | @item <...> | |
3053 | A slot to be filled by all remaining arguments from the new procedure. | |
3054 | This can only occur at the end of a @code{cut} form. | |
3055 | ||
3056 | For example, a procedure taking a variable number of arguments like | |
3057 | @code{max} but in addition enforcing a lower bound, | |
3058 | ||
3059 | @example | |
3060 | (define my-lower-bound 123) | |
3061 | ||
3062 | (cut max my-lower-bound <...>) | |
3063 | @result{} | |
3064 | (lambda arglist (apply max my-lower-bound arglist)) | |
3065 | @end example | |
3066 | @end table | |
3067 | ||
3068 | For @code{cut} the specializing expressions are evaluated each time | |
3069 | the new procedure is called. For @code{cute} they're evaluated just | |
3070 | once, when the new procedure is created. The name @code{cute} stands | |
3071 | for ``@code{cut} with evaluated arguments''. In all cases the | |
3072 | evaluations take place in an unspecified order. | |
3073 | ||
3074 | The following illustrates the difference between @code{cut} and | |
3075 | @code{cute}, | |
3076 | ||
3077 | @example | |
3078 | (cut format <> "the time is ~s" (current-time)) | |
3079 | @result{} | |
3080 | (lambda (port) (format port "the time is ~s" (current-time))) | |
3081 | ||
3082 | (cute format <> "the time is ~s" (current-time)) | |
3083 | @result{} | |
3084 | (let ((val (current-time))) | |
3085 | (lambda (port) (format port "the time is ~s" val)) | |
3086 | @end example | |
3087 | ||
3088 | (There's no provision for a mixture of @code{cut} and @code{cute} | |
3089 | where some expressions would be evaluated every time but others | |
3090 | evaluated only once.) | |
3091 | ||
3092 | @code{cut} is really just a shorthand for the sort of @code{lambda} | |
3093 | forms shown in the above examples. But notice @code{cut} avoids the | |
3094 | need to name unspecialized parameters, and is more compact. Use in | |
3095 | functional programming style or just with @code{map}, @code{for-each} | |
3096 | or similar is typical. | |
3097 | ||
3098 | @example | |
3099 | (map (cut * 2 <>) '(1 2 3 4)) | |
3100 | ||
3101 | (for-each (cut write <> my-port) my-list) | |
3102 | @end example | |
3103 | @end deffn | |
b0b55bd6 | 3104 | |
8638c417 RB |
3105 | @node SRFI-31 |
3106 | @subsection SRFI-31 - A special form `rec' for recursive evaluation | |
3107 | @cindex SRFI-31 | |
3108 | @findex rec | |
3109 | ||
3110 | SRFI-31 defines a special form that can be used to create | |
3111 | self-referential expressions more conveniently. The syntax is as | |
3112 | follows: | |
3113 | ||
3114 | @example | |
3115 | @group | |
3116 | <rec expression> --> (rec <variable> <expression>) | |
3117 | <rec expression> --> (rec (<variable>+) <body>) | |
3118 | @end group | |
3119 | @end example | |
3120 | ||
3121 | The first syntax can be used to create self-referential expressions, | |
3122 | for example: | |
3123 | ||
3124 | @lisp | |
3125 | guile> (define tmp (rec ones (cons 1 (delay ones)))) | |
3126 | @end lisp | |
3127 | ||
3128 | The second syntax can be used to create anonymous recursive functions: | |
3129 | ||
3130 | @lisp | |
3131 | guile> (define tmp (rec (display-n item n) | |
3132 | (if (positive? n) | |
3133 | (begin (display n) (display-n (- n 1)))))) | |
3134 | guile> (tmp 42 3) | |
3135 | 424242 | |
3136 | guile> | |
3137 | @end lisp | |
12991fed TTN |
3138 | |
3139 | @c srfi-modules.texi ends here | |
193239f1 KR |
3140 | |
3141 | @c Local Variables: | |
3142 | @c TeX-master: "guile.texi" | |
3143 | @c End: |