Left inf? in its place, since wants to be here so much.
[bpt/guile.git] / doc / ref / srfi-modules.texi
CommitLineData
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
12SRFI is an acronym for Scheme Request For Implementation. The SRFI
13documents define a lot of syntactic and procedure extensions to standard
14Scheme as defined in R5RS.
15
16Guile has support for a number of SRFIs. This chapter gives an overview
17over the available SRFIs and some usage hints. For complete
18documentation, design rationales and further examples, we advise you to
19get 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
48SRFI support in Guile is currently implemented partly in the core
49library, and partly as add-on modules. That means that some SRFIs are
50automatically available when the interpreter is started, whereas the
51other SRFIs require you to use the appropriate support module
12991fed 52explicitly.
a0e07ba4
NJ
53
54There are several reasons for this inconsistency. First, the feature
55checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
56available immediately, because it must be there when the user wants to
57check for the Scheme implementation, that is, before she can know that
58it is safe to use @code{use-modules} to load SRFI support modules. The
59second reason is that some features defined in SRFIs had been
60implemented in Guile before the developers started to add SRFI
61implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In
62the future, it is possible that SRFIs in the core library might be
63factored out into separate modules, requiring explicit module loading
64when 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
66you want, you can do that already. We have included the module
67@code{(srfi srfi-6)} in the distribution, which currently does nothing,
68but ensures that you can write future-safe code.
69
70Generally, support for a specific SRFI is made available by using
71modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
72number of the SRFI needed. Another possibility is to use the command
73line option @code{--use-srfi}, which will load the necessary modules
74automatically (@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
81This SRFI lets a portable Scheme program test for the presence of
82certain features, and adapt itself by using different blocks of code,
83or fail if the necessary features are not available. There's no
84module to load, this is in the Guile core.
a0e07ba4 85
5eef0f61
KR
86A program designed only for Guile will generally not need this
87mechanism, such a program can of course directly use the various
88documented parts of Guile.
a0e07ba4 89
5eef0f61
KR
90@deffn syntax cond-expand (feature body@dots{}) @dots{}
91Expand to the @var{body} of the first clause whose @var{feature}
92specification is satisfied. It is an error if no @var{feature} is
a0e07ba4
NJ
93satisfied.
94
5eef0f61
KR
95Features are symbols such as @code{srfi-1}, and a feature
96specification can use @code{and}, @code{or} and @code{not} forms to
97test combinations. The last clause can be an @code{else}, to be used
98if no other passes.
a0e07ba4 99
5eef0f61
KR
100For example, define a private version of @code{alist-cons} if SRFI-1
101is 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
111Or demand a certain set of SRFIs (list operations, string ports,
112@code{receive} and string operations), failing if they're not
113available.
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
121The Guile core provides features @code{guile}, @code{r5rs},
122@code{srfi-0} and @code{srfi-6} initially. Other SRFI feature symbols
123are defined once their code has been loaded with @code{use-modules},
124since only then are their bindings available.
a0e07ba4 125
5eef0f61
KR
126The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is
127a good way to load SRFIs to satisfy @code{cond-expand} when running a
128portable program.
a0e07ba4 129
5eef0f61
KR
130Testing the @code{guile} feature allows a program to adapt itself to
131the Guile module system, but still run on other Scheme systems. For
132example the following demands SRFI-8 (@code{receive}), but also knows
133how 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
142It should be noted that @code{cond-expand} is separate from the
143@code{*features*} mechanism (@pxref{Feature Tracking}), feature
144symbols 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
153The list library defined in SRFI-1 contains a lot of useful list
154processing procedures for construction, examining, destructuring and
155manipulating lists and pairs.
156
157Since SRFI-1 also defines some procedures which are already contained
158in R5RS and thus are supported by the Guile core library, some list
159and pair procedures which appear in the SRFI-1 document may not appear
160in this section. So when looking for a particular list/pair
161processing 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
182New lists can be constructed by calling one of the following
183procedures.
184
8f85c0c6 185@deffn {Scheme Procedure} xcons d a
a0e07ba4
NJ
186Like @code{cons}, but with interchanged arguments. Useful mostly when
187passed to higher-order procedures.
188@end deffn
189
8f85c0c6 190@deffn {Scheme Procedure} list-tabulate n init-proc
a0e07ba4
NJ
191Return an @var{n}-element list, where each list element is produced by
192applying the procedure @var{init-proc} to the corresponding list
193index. The order in which @var{init-proc} is applied to the indices
194is not specified.
195@end deffn
196
57066448
KR
197@deffn {Scheme Procedure} list-copy lst
198Return a new list containing the elements of the list @var{lst}.
199
200This function differs from the core @code{list-copy} (@pxref{List
201Constructors}) in accepting improper lists too. And if @var{lst} is
202not a pair at all then it's treated as the final tail of an improper
203list and simply returned.
204@end deffn
205
8f85c0c6 206@deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
a0e07ba4
NJ
207Return 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
212Return a list containing @var{count} numbers, starting from
213@var{start} and adding @var{step} each time. The default @var{start}
214is 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
221This function takes its name from the corresponding primitive in the
222APL 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
231The procedures in this section test specific properties of lists.
232
8f85c0c6 233@deffn {Scheme Procedure} proper-list? obj
a0e07ba4
NJ
234Return @code{#t} if @var{obj} is a proper list, that is a finite list,
235terminated with the empty list. Otherwise, return @code{#f}.
236@end deffn
237
8f85c0c6 238@deffn {Scheme Procedure} circular-list? obj
a0e07ba4
NJ
239Return @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
244Return @code{#t} if @var{obj} is a dotted list, return @code{#f}
245otherwise. A dotted list is a finite list which is not terminated by
246the empty list, but some other value.
247@end deffn
248
8f85c0c6 249@deffn {Scheme Procedure} null-list? lst
a0e07ba4
NJ
250Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
251otherwise. If something else than a proper or circular list is passed
85a9b4ed 252as @var{lst}, an error is signalled. This procedure is recommended
a0e07ba4
NJ
253for checking for the end of a list in contexts where dotted lists are
254not allowed.
255@end deffn
256
8f85c0c6 257@deffn {Scheme Procedure} not-pair? obj
a0e07ba4
NJ
258Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
259This is shorthand notation @code{(not (pair? @var{obj}))} and is
260supposed to be used for end-of-list checking in contexts where dotted
261lists are allowed.
262@end deffn
263
8f85c0c6 264@deffn {Scheme Procedure} list= elt= list1 @dots{}
a0e07ba4
NJ
265Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
266List equality is determined by testing whether all lists have the same
267length and the corresponding elements are equal in the sense of the
268equality 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
288These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
289@end deffn
290
8f85c0c6 291@deffn {Scheme Procedure} car+cdr pair
a0e07ba4
NJ
292Return 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
297Return 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}
300in order to produce the result.
301@end deffn
302
8f85c0c6 303@deffn {Scheme Procedure} drop lst i
a0e07ba4
NJ
304Return 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
309Return 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
314Return 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
323Return two values, a list containing the first @var{i} elements of the
324list @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
331Return 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
341Return the length of the argument list @var{lst}. When @var{lst} is a
342circular 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
347Construct a list by appending all lists in @var{list-of-lists}.
348
349@code{concatenate!} may modify the structure of the given lists in
350order 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
355Reverse @var{rev-head}, append @var{tail} and return the result. This
356is equivalent to @code{(append (reverse @var{rev-head}) @var{tail})},
357but more efficient.
358
359@code{append-reverse!} may modify @var{rev-head} in order to produce
360the result.
361@end deffn
362
8f85c0c6 363@deffn {Scheme Procedure} zip lst1 lst2 @dots{}
a0e07ba4
NJ
364Return a list as long as the shortest of the argument lists, where
365each element is a list. The first list contains the first elements of
366the argument lists, the second list contains the second elements, and
367so 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
376first elements of each list, @code{unzip2} returns two lists, the
377first containing the first elements of each lists and the second
378containing the second elements of each lists, and so on.
379@end deffn
380
e508c863
KR
381@deffn {Scheme Procedure} count pred lst1 @dots{} lstN
382Return a count of the number of times @var{pred} returns true when
383called 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
387corresponding @var{lst1} @dots{} @var{lstN}. The first call is with
388the first element of each list, the second with the second element
389from each, and so on.
390
391Counting stops when the end of the shortest list is reached. At least
392one 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
402Fold 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
408if @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
413Similar to @code{fold}, but applies @var{kons} in right-to-left order
414to 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
421Like @code{fold}, but apply @var{kons} to the pairs of the list
422instead of the list elements.
423@end deffn
424
8f85c0c6 425@deffn {Scheme Procedure} pair-fold-right kons knil lst1 lst2 @dots{}
a0e07ba4
NJ
426Like @code{fold-right}, but apply @var{kons} to the pairs of the list
427instead 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 437This 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
452Determines when to stop unfolding.
453
454@item f
455Maps each seed value to the corresponding list element.
456
457@item g
458Maps each seed value to next seed valu.
459
460@item seed
461The state value for the unfold.
462
463@item tail-gen
464Creates 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
468elements by @var{f}. These elements are put into a list in
469left-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
473Construct 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
484Determines when to stop unfolding.
485
486@item f
487Maps each seed value to the corresponding list element.
488
489@item g
490Maps each seed value to next seed valu.
491
492@item seed
493The state value for the unfold.
494
495@item tail-gen
496Creates 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
502Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
503return a list containing the results of the procedure applications.
504This procedure is extended with respect to R5RS, because the argument
505lists may have different lengths. The result list will have the same
506length as the shortest argument lists. The order in which @var{f}
507will 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
511Apply the procedure @var{f} to each pair of corresponding elements of
512the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not
513specified. This procedure is extended with respect to R5RS, because
514the argument lists may have different lengths. The shortest argument
515list determines the number of times @var{f} is called. @var{f} will
85a9b4ed 516be 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 522Equivalent to
a0e07ba4
NJ
523
524@lisp
12991fed 525(apply append (map f clist1 clist2 ...))
a0e07ba4
NJ
526@end lisp
527
12991fed 528and
a0e07ba4
NJ
529
530@lisp
12991fed 531(apply append! (map f clist1 clist2 ...))
a0e07ba4
NJ
532@end lisp
533
534Map @var{f} over the elements of the lists, just as in the @code{map}
535function. However, the results of the applications are appended
536together 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
540The dynamic order in which the various applications of @var{f} are
541made is not specified.
542@end deffn
543
8f85c0c6 544@deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
a0e07ba4
NJ
545Linear-update variant of @code{map} -- @code{map!} is allowed, but not
546required, to alter the cons cells of @var{lst1} to construct the
547result list.
548
549The dynamic order in which the various applications of @var{f} are
550made 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
555Like @code{for-each}, but applies the procedure @var{f} to the pairs
556from which the argument lists are constructed, instead of the list
557elements. The return value is not specified.
558@end deffn
559
8f85c0c6 560@deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
a0e07ba4
NJ
561Like @code{map}, but only results from the applications of @var{f}
562which 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
571Filtering means to collect all elements from a list which satisfy a
572specific condition. Partitioning a list means to make two groups of
573list elements, one which contains the elements satisfying a condition,
574and the other for the elements which don't.
575
60e25dc4
KR
576The @code{filter} and @code{filter!} functions are implemented in the
577Guile core, @xref{List Modification}.
a0e07ba4 578
8f85c0c6
NJ
579@deffn {Scheme Procedure} partition pred lst
580@deffnx {Scheme Procedure} partition! pred lst
193239f1
KR
581Split @var{lst} into those elements which do and don't satisfy the
582predicate @var{pred}.
a0e07ba4 583
193239f1
KR
584The return is two values (@pxref{Multiple Values}), the first being a
585list of all elements from @var{lst} which satisfy @var{pred}, the
586second a list of those which do not.
587
588The elements in the result lists are in the same order as in @var{lst}
589but the order in which the calls @code{(@var{pred} elem)} are made on
590the list elements is unspecified.
591
592@code{partition} does not change @var{lst}, but one of the returned
593lists 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
599Return a list containing all elements from @var{lst} which do not
600satisfy the predicate @var{pred}. The elements in the result list
601have the same order as in @var{lst}. The order in which @var{pred} is
602applied to the list elements is not specified.
603
604@code{remove!} is allowed, but not required to modify the structure of
605the 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
614The procedures for searching elements in lists either accept a
615predicate or a comparison object for determining which elements are to
616be searched.
617
8f85c0c6 618@deffn {Scheme Procedure} find pred lst
a0e07ba4
NJ
619Return 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
624Return the first pair of @var{lst} whose @sc{car} satisfies the
625predicate @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
630Return the longest initial prefix of @var{lst} whose elements all
631satisfy the predicate @var{pred}.
632
633@code{take-while!} is allowed, but not required to modify the input
634list while producing the result.
635@end deffn
636
8f85c0c6 637@deffn {Scheme Procedure} drop-while pred lst
a0e07ba4
NJ
638Drop the longest initial prefix of @var{lst} whose elements all
639satisfy 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
647whose elements all satisfy the predicate @var{pred}, and the remaining
648tail. @code{break} inverts the sense of the predicate.
649
650@code{span!} and @code{break!} are allowed, but not required to modify
651the structure of the input list @var{lst} in order to produce the
652result.
3e73b6f9
KR
653
654Note that the name @code{break} conflicts with the @code{break}
655binding established by @code{while} (@pxref{while do}). Applications
656wanting to use @code{break} from within a @code{while} loop will need
657to 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
661Apply @var{pred} across the lists and return a true value if the
662predicate returns true for any of the list elements(s); return
663@code{#f} otherwise. The true value returned is always the result of
85a9b4ed 664the first successful application of @var{pred}.
a0e07ba4
NJ
665@end deffn
666
8f85c0c6 667@deffn {Scheme Procedure} every pred lst1 lst2 @dots{}
a0e07ba4
NJ
668Apply @var{pred} across the lists and return a true value if the
669predicate returns true for every of the list elements(s); return
670@code{#f} otherwise. The true value returned is always the result of
85a9b4ed 671the 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
675Return the index of the leftmost element that satisfies @var{pred}.
676@end deffn
677
8f85c0c6 678@deffn {Scheme Procedure} member x lst [=]
a0e07ba4
NJ
679Return 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}.
681Equality is determined by the equality predicate @var{=}, or
682@code{equal?} if @var{=} is not given.
ea6ea01b
KR
683
684This function extends the core @code{member} by accepting an equality
685predicate. (@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
696Return a list containing the elements of @var{lst} but with those
697equal to @var{x} deleted. The returned elements will be in the same
698order as they were in @var{lst}.
699
700Equality is determined by the @var{=} predicate, or @code{equal?} if
701not given. An equality call is made just once for each element, but
702the order in which the calls are made on the elements is unspecified.
a0e07ba4 703
243bdb63 704The equality calls are always @code{(= x elem)}, ie.@: the given @var{x}
b6b9376a
KR
705is first. This means for instance elements greater than 5 can be
706deleted with @code{(delete 5 lst <)}.
707
708@code{delete} does not modify @var{lst}, but the return might share a
709common tail with @var{lst}. @code{delete!} may modify the structure
710of @var{lst} to construct its return.
ea6ea01b
KR
711
712These functions extend the core @code{delete} and @code{delete!} in
713accepting 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
718Return a list containing the elements of @var{lst} but without
719duplicates.
720
721When elements are equal, only the first in @var{lst} is retained.
722Equal elements can be anywhere in @var{lst}, they don't have to be
723adjacent. The returned list will have the retained elements in the
724same order as they were in @var{lst}.
725
726Equality is determined by the @var{=} predicate, or @code{equal?} if
727not given. Calls @code{(= x y)} are made with element @var{x} being
728before @var{y} in @var{lst}. A call is made at most once for each
729combination, but the sequence of the calls across the elements is
730unspecified.
731
732@code{delete-duplicates} does not modify @var{lst}, but the return
733might share a common tail with @var{lst}. @code{delete-duplicates!}
734may modify the structure of @var{lst} to construct its return.
735
736In the worst case, this is an @math{O(N^2)} algorithm because it must
737check each element against all those preceding it. For long lists it
738is 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
747Association lists are described in detail in section @ref{Association
748Lists}. The present section only documents the additional procedures
749for dealing with association lists defined by SRFI-1.
750
8f85c0c6 751@deffn {Scheme Procedure} assoc key alist [=]
a0e07ba4
NJ
752Return the pair from @var{alist} which matches @var{key}. Equality is
753determined 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
756This function extends the core @code{assoc} by accepting an equality
757predicate. (@pxref{Association Lists})
a0e07ba4
NJ
758@end deffn
759
8f85c0c6 760@deffn {Scheme Procedure} alist-cons key datum alist
a0e07ba4
NJ
761Equivalent to
762
763@lisp
764(cons (cons @var{key} @var{datum}) @var{alist})
765@end lisp
766
767This procedure is used to coons a new pair onto an existing
768association list.
769@end deffn
770
8f85c0c6 771@deffn {Scheme Procedure} alist-copy alist
a0e07ba4
NJ
772Return a newly allocated copy of @var{alist}, that means that the
773spine 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
778Return a list containing the elements of @var{alist} but with those
779elements whose keys are equal to @var{key} deleted. The returned
780elements will be in the same order as they were in @var{alist}.
a0e07ba4 781
bd35f1f0
KR
782Equality is determined by the @var{=} predicate, or @code{equal?} if
783not given. The order in which elements are tested is unspecified, but
784each equality call is made @code{(= key alistkey)}, ie. the given
785@var{key} parameter is first and the key from @var{alist} second.
786This means for instance all associations with a key greater than 5 can
787be removed with @code{(alist-delete 5 alist <)}.
788
789@code{alist-delete} does not modify @var{alist}, but the return might
790share a common tail with @var{alist}. @code{alist-delete!} may modify
791the 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
800Lists can be used for representing sets of objects. The procedures
801documented in this section can be used for such set representations.
85a9b4ed 802Man combining several sets or adding elements, they make sure that no
a0e07ba4
NJ
803object is contained more than once in a given list. Please note that
804lists are not a too efficient implementation method for sets, so if
805you need high performance, you should think about implementing a
806custom data structure for representing sets, such as trees, bitsets,
807hash tables or something similar.
808
809All these procedures accept an equality predicate as the first
810argument. This predicate is used for testing the objects in the list
811sets for sameness.
812
8f85c0c6 813@deffn {Scheme Procedure} lset<= = list1 @dots{}
a0e07ba4
NJ
814Return @code{#t} if every @var{listi} is a subset of @var{listi+1},
815otherwise return @code{#f}. Returns @code{#t} if called with less
816than two arguments. @var{=} is used for testing element equality.
817@end deffn
818
8f85c0c6 819@deffn {Scheme Procedure} lset= = list1 list2 @dots{}
a0e07ba4
NJ
820Return @code{#t} if all argument lists are equal. @var{=} is used for
821testing 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
826Add all @var{elts} to the list @var{list}, suppressing duplicates and
827return the resulting list. @code{lset-adjoin!} is allowed, but not
828required to modify its first argument. @var{=} is used for testing
829element 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
834Return the union of all argument list sets. The union is the set of
835all elements which appear in any of the argument sets.
836@code{lset-union!} is allowed, but not required to modify its first
837argument. @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
842Return the intersection of all argument list sets. The intersection
843is the set containing all elements which appear in all argument sets.
844@code{lset-intersection!} is allowed, but not required to modify its
845first 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
850Return the difference of all argument list sets. The difference is
851the the set containing all elements of the first list which do not
852appear in the other lists. @code{lset-difference!} is allowed, but
853not required to modify its first argument. @var{=} is used for testing
854element 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
859Return the set containing all elements which appear in the first
860argument list set, but not in the second; or, more generally: which
861appear in an odd number of sets. @code{lset-xor!} is allowed, but
862not required to modify its first argument. @var{=} is used for testing
863element 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
868Return two values, the difference and the intersection of the argument
869list 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
872its first argument. @var{=} is used for testing element equality. You
873have to use some means to deal with the multiple values these
874procedures 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
883The 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{}
890A combination of @code{and} and @code{let*}.
891
892Each @var{clause} is evaluated in turn, and if @code{#f} is obtained
893then evaluation stops and @code{#f} is returned. If all are
894non-@code{#f} then @var{body} is evaluated and the last form gives the
895return value. Each @var{clause} should be one of the following,
896
897@table @code
898@item (symbol expr)
899Evaluate @var{expr}, check for @code{#f}, and bind it to @var{symbol}.
900Like @code{let*}, that binding is available to subsequent clauses.
901@item (expr)
902Evaluate @var{expr} and check for @code{#f}.
903@item symbol
904Get the value bound to @var{symbol} and check for @code{#f}.
905@end table
a0e07ba4 906
4fd0db14
KR
907Notice that @code{(expr)} has an ``extra'' pair of parentheses, for
908instance @code{((eq? x y))}. One way to remember this is to imagine
909the @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
912termination, but where a non-@code{#f} value is going to be needed in
913subsequent expressions.
914
915The 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
926The following shows plain variables and expressions tested too.
927@code{diagnostic-levels} is taken to be an alist associating a
928diagnostic type with a level. @code{str} is printed only if the type
929is 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
939The advantage of @code{and-let*} is that an extended sequence of
940expressions and tests doesn't require lots of nesting as would arise
941from 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
953SRFI-4 defines a set of datatypes and functions for vectors whose
954elements are numbers, all of the same numeric type. Vectors for
955signed and unsigned exact integers and inexact reals in several
956precisions are available. Being homogeneous means they require less
957memory than normal vectors.
a0e07ba4 958
f85f9591
KR
959The functions and the read syntax in this section are made available
960with
a0e07ba4 961
f85f9591
KR
962@lisp
963(use-modules (srfi srfi-4))
964@end lisp
a0e07ba4 965
f85f9591
KR
966Procedures similar to the vector procedures (@pxref{Vectors}) are
967provided for handling these homogeneous vectors, but they are distinct
968datatypes and the two cannot be inter-mixed.
a0e07ba4
NJ
969
970Ten vector data types are provided: Unsigned and signed integer values
971with 8, 16, 32 and 64 bits and floating point values with 32 and 64
f85f9591
KR
972bits. 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
976The external representation (ie.@: read syntax) for these vectors is
977similar to normal Scheme vectors, but with an additional tag
978indiciating 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
985Note 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
988module @code{(1 #f3)} is invalid. @code{(1 #f 3)} is almost certainly
989what one should write anyway to make the intention clear, so this is
990rarely 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
1002Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1003indicated 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]
1016Return a newly allocated homogeneous numeric vector holding @var{n}
1017elements of the indicated type. If @var{value} is given, the vector
1018is initialized with that value, otherwise the contents are
1019unspecified.
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{}
1032Return a newly allocated homogeneous numeric vector of the indicated
1033type, holding the given parameter @var{value}s. The vector length is
1034the 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
1047Return 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
1060Return the element at index @var{i} in @var{vec}. The first element
1061in @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
1074Set the element at index @var{i} in @var{vec} to @var{value}. The
1075first element in @var{vec} is index 0. The return value is
1076unspecified.
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
1089Return 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
1102Return a newly allocated homogeneous numeric vector of the indicated type,
a0e07ba4
NJ
1103initialized 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
1111SRFI-6 defines the procedures @code{open-input-string},
1112@code{open-output-string} and @code{get-output-string}. These
1113procedures are included in the Guile core, so using this module does not
1114make any difference at the moment. But it is possible that support for
1115SRFI-6 will be factored out of the core library in the future, so using
1116this 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
1123procedures 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
1130This SRFI is a syntax for defining new record types and creating
1131predicate, constructor, and field getter and setter functions. In
1132Guile this is simply an alternate interface to the core record
1133functionality (@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
1141Create a new record type, and make various @code{define}s for using
1142it. This syntax can only occur at the top-level, not nested within
1143some other form.
1144
1145@var{type} is bound to the record type, which is as per the return
1146from the core @code{make-record-type}. @var{type} also provides the
1147name 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
1151this type. The arguments are initial values for the fields, one
1152argument for each field, in the order they appear in the
1153@code{define-record-type} form.
1154
1155The @var{fieldname}s provide the names for the record fields, as per
1156the core @code{record-type-fields} etc, and are referred to in the
1157subsequent 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}
1161according to whether @var{obj} is a record of this type.
1162
1163Each @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
1166be called @code{(@var{modifier} record val)} to set the respective
1167field in a @var{record}.
1168@end deffn
1169
1170@noindent
1171An 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
1182This creates a new employee data type, with name, age and salary
1183fields. Accessor functions are created for each field, but no
1184modifier function for the name (the intention in this example being
1185that it's established only when an employee object is created). These
1186can all then be used as for example,
a0e07ba4
NJ
1187
1188@example
6afe385d
KR
1189employee-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
1198The functions created by @code{define-record-type} are ordinary
1199top-level @code{define}s. They can be redefined or @code{set!} as
1200desired, 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 #,()
1209The module @code{(srfi srfi-10)} implements the syntax extension
1210@code{#,()}, also called hash-comma, which is defined in SRFI-10.
1211
1212The support for SRFI-10 consists of the procedure
1213@code{define-reader-ctor} for defining new reader constructors and the
1214read syntax form
1215
1216@example
1217#,(@var{ctor} @var{datum} ...)
1218@end example
1219
1220where @var{ctor} must be a symbol for which a read constructor was
85a9b4ed 1221defined previously, using @code{define-reader-ctor}.
a0e07ba4
NJ
1222
1223Example:
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
1234Please note the quote before the @code{#,(file ...)} expression. This
1235is necessary because ports are not self-evaluating in Guile.
1236
8f85c0c6 1237@deffn {Scheme Procedure} define-reader-ctor symbol proc
a0e07ba4
NJ
1238Define @var{proc} as the reader constructor for hash-comma forms with a
1239tag @var{symbol}. @var{proc} will be applied to the datum(s) following
1240the tag in the hash-comma expression after the complete form has been
1241read 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
1251This 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
1254binding of the values returned by multiple-valued expressions.
1255
1256Write @code{(use-modules (srfi srfi-11))} to make the bindings
1257available.
1258
1259@lisp
1260(let-values (((x y) (values 1 2))
1261 ((z f) (values 3 4)))
1262 (+ x y z f))
1263@result{}
126410
1265@end lisp
1266
1267@code{let-values} performs all bindings simultaneously, which means that
1268no expression in the binding clauses may refer to variables bound in the
1269same clause list. @code{let-values*}, on the other hand, performs the
1270bindings sequentially, just like @code{let*} does for single-valued
1271expressions.
1272
1273
1274@node SRFI-13
3229f68b 1275@subsection SRFI-13 - String Library
8742c48b 1276@cindex SRFI-13
a0e07ba4
NJ
1277
1278In this section, we will describe all procedures defined in SRFI-13
1279(string library) and implemented by the module @code{(srfi srfi-13)}.
1280
1281Note that only the procedures from SRFI-13 are documented here which are
1282not already contained in Guile. For procedures not documented here
1283please refer to the relevant chapters in the Guile Reference Manual, for
1284example the documentation of strings and string procedures
1285(@pxref{Strings}).
1286
40f316d0
MG
1287All of the procedures defined in SRFI-13, which are not already
1288included in the Guile core library, are implemented in the module
1289@code{(srfi srfi-13)}. The procedures which are both in Guile and in
1290SRFI-13 are slightly extended in this module. Their bindings
1291overwrite those in the Guile core.
a0e07ba4
NJ
1292
1293The procedures which are defined in the section @emph{Low-level
1294procedures} of SRFI-13 for parsing optional string indices, substring
1295specification checking and Knuth-Morris-Pratt-Searching are not
1296implemented.
1297
1298The procedures @code{string-contains} and @code{string-contains-ci} are
1299not implemented very efficiently at the moment. This will be changed as
1300soon 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
1324When Guile is properly installed, SRFI-13 support can be loaded into a
1325running Guile by using the @code{(srfi srfi-13)} module.
1326
1327@example
1328$ guile
1329guile> (use-modules (srfi srfi-13))
1330guile>
1331@end example
1332
1333When this step causes any errors, Guile is not properly installed.
1334
1335One possible reason is that Guile cannot find either the Scheme module
1336file @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
1338Guile load path and that the latter is either installed in some default
1339location like @file{/usr/local/lib} or that the directory it was
1340installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to
1341@file{srfi-14.scm}.
1342
1343Now you can test whether the SRFI-13 procedures are working by calling
1344the @code{string-concatenate} procedure.
1345
1346@example
1347guile> (string-concatenate '("Hello" " " "World!"))
1348"Hello World!"
1349@end example
1350
1351@node SRFI-13 Predicates
3229f68b 1352@subsubsection Predicates
a0e07ba4
NJ
1353
1354In addition to the primitives @code{string?} and @code{string-null?},
1355which 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]
1359Return true if @code{char_pred} is satisfied for any character in the
1360string @var{s}. @var{char_pred} can be
1361
1362@itemize @bullet
1363@item
1364A character, to to test for any in @var{s} equal to that.
1365@item
1366A character set (@pxref{SRFI-14}), to test for any character in
1367@var{s} in that character set.
1368@item
1369A predicate function, called as @code{(@var{char_pred} c)} for each
1370character in @var{s}, from left to right, to test for any on which
1371@var{char_pred} returns true.
1372
1373When @var{char_pred} does return true (ie.@: non-@code{#f}), that
1374value is the value returned by @code{string-any}.
1375@end itemize
c1ab7397 1376
6ae50c71
KR
1377If there are no characters in @var{s} (ie.@: @var{start} equals
1378@var{end}) then the return is @code{#f}.
1379
1380SRFI-13 specifies that when @var{char_pred} is a predicate function,
1381the call on the last character of @var{s} (assuming that point is
1382reached) 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]
1386Return true if @var{char_pred} is satisifed for every character in the
1387string @var{s}. @var{char_pred} can be
1388
1389@itemize @bullet
1390@item
1391A character, to to test for every character in @var{s} equal to that.
1392@item
1393A character set (@pxref{SRFI-14}), to test for every character in
1394@var{s} being in that character set.
1395@item
1396A predicate function, called as @code{(@var{char_pred} c)} for each
1397character in @var{s}, from left to right, to test that it returns true
1398for every character in @var{s}.
c1ab7397 1399
6ae50c71
KR
1400When @var{char_pred} does return true (ie.@: non-@code{#f}) for every
1401character, the return from the last call is the value returned by
5b4dba24 1402@code{string-every}.
6ae50c71 1403@end itemize
c1ab7397
KR
1404
1405If there are no characters in @var{s} (ie.@: @var{start} equals
1406@var{end}) then the return is @code{#t}.
a0e07ba4 1407
6ae50c71
KR
1408SRFI-13 specifies that when @var{char_pred} is a predicate function,
1409the call on the last character of @var{s} (assuming that point is
1410reached) 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
1418SRFI-13 defines several procedures for constructing new strings. In
1419addition to @code{make-string} and @code{string} (available in the Guile
1420core 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
1424of size @var{len} by applying @var{proc} to each index to
1425produce 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
1435The procedure @code{string->list} is extended by SRFI-13, that is why it
1436is included in @code{(srfi srfi-13)}. The other procedures are new.
1437The Guile core already contains the procedure @code{list->string} for
1438converting a list of characters into a string (@pxref{List/String
1439Conversion}).
1440
8f85c0c6 1441@deffn {Scheme Procedure} string->list str [start end]
a0e07ba4
NJ
1442Convert the string @var{str} into a list of characters.
1443@end deffn
1444
8f85c0c6 1445@deffn {Scheme Procedure} reverse-list->string chrs
a0e07ba4
NJ
1446An efficient implementation of @code{(compose string->list
1447reverse)}:
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
1455Append 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
1458placed between the strings, and defaults to the symbol
1459@code{infix}.
1460
1461@table @code
1462@item infix
1463Insert the separator between list elements. An empty string
1464will produce an empty list.
1465
1466@item string-infix
1467Like @code{infix}, but will raise an error if given the empty
1468list.
1469
1470@item suffix
1471Insert the separator after every list element.
1472
1473@item prefix
1474Insert 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
1484These procedures are called @dfn{selectors}, because they access
1485information about the string or select pieces of a given string.
1486
1487Additional 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
1492accepts additional start/end indices.
1493
8f85c0c6 1494@deffn {Scheme Procedure} string-copy str [start end]
a0e07ba4
NJ
1495Return a freshly allocated copy of the string @var{str}. If
1496given, @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
1501Like @code{substring}, but the result may share memory with the
1502argument @var{str}.
1503@end deffn
1504
8f85c0c6 1505@deffn {Scheme Procedure} string-copy! target tstart s [start end]
a0e07ba4
NJ
1506Copy the sequence of characters from index range [@var{start},
1507@var{end}) in string @var{s} to string @var{target}, beginning
1508at index @var{tstart}. The characters are copied left-to-right
1509or right-to-left as needed - the copy is guaranteed to work,
1510even if @var{target} and @var{s} are the same string. It is an
1511error if the copy operation runs off the end of the target
1512string.
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
1517Return 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
1522Return 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
1527Take that characters from @var{start} to @var{end} from the
1528string @var{s} and return a new string, right(left)-padded by the
1529character @var{chr} to length @var{len}. If the resulting
1530string 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
1536Trim @var{s} by skipping over all characters on the left/right/both
1537sides of the string that satisfy the parameter @var{char_pred}:
1538
1539@itemize @bullet
1540@item
1541if it is the character @var{ch}, characters equal to
1542@var{ch} are trimmed,
1543
1544@item
1545if it is a procedure @var{pred} characters that
1546satisfy @var{pred} are trimmed,
1547
1548@item
1549if it is a character set, characters in that set are trimmed.
1550@end itemize
1551
1552If called without a @var{char_pred} argument, all whitespace is
1553trimmed.
1554@end deffn
1555
1556
1557@c ===================================================================
1558
1559@node SRFI-13 Modification
3229f68b 1560@subsubsection Modification
a0e07ba4
NJ
1561
1562The procedure @code{string-fill!} is extended from R5RS because it
1563accepts optional start/end indices. This bindings shadows the procedure
1564of the same name in the Guile core. The second modification procedure
1565@code{string-set!} is documented in the Strings section (@pxref{String
1566Modification}).
1567
8f85c0c6 1568@deffn {Scheme Procedure} string-fill! str chr [start end]
a0e07ba4
NJ
1569Stores @var{chr} in every element of the given @var{str} and
1570returns an unspecified value.
1571@end deffn
1572
1573
1574@c ===================================================================
1575
1576@node SRFI-13 Comparison
3229f68b 1577@subsubsection Comparison
a0e07ba4
NJ
1578
1579The procedures in this section are used for comparing strings in
1580different ways. The comparison predicates differ from those in R5RS in
1581that they do not only return @code{#t} or @code{#f}, but the mismatch
1582index in the case of a true return value.
1583
1584@code{string-hash} and @code{string-hash-ci} are for calculating hash
1585values 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
1589Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
1590mismatch index, depending upon whether @var{s1} is less than,
1591equal to, or greater than @var{s2}. The mismatch index is the
1592largest 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
1595character 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
1604Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
1605fails. Otherwise, the mismatch index is returned (or @var{end1} in the
1606case 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
1615Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
1616fails. Otherwise, the mismatch index is returned (or @var{end1} in the
1617case 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
1622Return 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
1632Using these procedures you can determine whether a given string is a
1633prefix or suffix of another string or how long a common prefix/suffix
1634is.
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
1640Return the length of the longest common prefix/suffix of the two
1641strings. @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
1649Is @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
1659Use these procedures to find out whether a string contains a given
1660character 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 1664Search through the string @var{s} from left to right (right to left),
85a9b4ed 1665returning the index of the first (last) occurrence of a character which
a0e07ba4
NJ
1666
1667@itemize @bullet
1668@item
1669equals @var{char_pred}, if it is character,
1670
1671@item
85a9b4ed 1672satisfies the predicate @var{char_pred}, if it is a
a0e07ba4
NJ
1673procedure,
1674
1675@item
1676is 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 1682Search through the string @var{s} from left to right (right to left),
85a9b4ed 1683returning the index of the first (last) occurrence of a character which
a0e07ba4
NJ
1684
1685@itemize @bullet
1686@item
1687does not equal @var{char_pred}, if it is character,
1688
1689@item
85a9b4ed 1690does not satisfy the predicate @var{char_pred}, if it is
a0e07ba4
NJ
1691a procedure.
1692
1693@item
1694is 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
1699Return the count of the number of characters in the string
1700@var{s} which
1701
1702@itemize @bullet
1703@item
1704equals @var{char_pred}, if it is character,
1705
1706@item
85a9b4ed 1707satisfies the predicate @var{char_pred}, if it is a procedure.
a0e07ba4
NJ
1708
1709@item
1710is 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
1716Does string @var{s1} contain string @var{s2}? Return the index
1717in @var{s1} where @var{s2} occurs as a substring, or false.
1718The optional start/end indices restrict the operation to the
1719indicated 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
1730These procedures convert the alphabetic case of strings. They are
1731similar to the procedures in the Guile core, but are extended to handle
1732optional 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
1736Upcase every character in @var{s}. @code{string-upcase!} is the
1737side-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
1742Downcase every character in @var{s}. @code{string-downcase!} is the
1743side-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
1748Upcase every first character in every word in @var{s}, downcase the
1749other characters. @code{string-titlecase!} is the side-effecting
1750variant.
1751@end deffn
1752
1753
1754@c ===================================================================
1755
1756@node SRFI-13 Reverse/Append
3229f68b 1757@subsubsection Reverse/Append
a0e07ba4
NJ
1758
1759One appending procedure, @code{string-append} is the same in R5RS and in
1760SRFI-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
1764Reverse the string @var{str}. The optional arguments
1765@var{start} and @var{end} delimit the region of @var{str} to
1766operate on.
1767
1768@code{string-reverse!} modifies the argument string and returns an
1769unspecified value.
1770@end deffn
1771
8f85c0c6 1772@deffn {Scheme Procedure} string-append/shared ls @dots{}
a0e07ba4
NJ
1773Like @code{string-append}, but the result may share memory
1774with the argument strings.
1775@end deffn
1776
8f85c0c6 1777@deffn {Scheme Procedure} string-concatenate ls
a0e07ba4
NJ
1778Append the elements of @var{ls} (which must be strings)
1779together into a single string. Guaranteed to return a freshly
1780allocated string.
1781@end deffn
1782
8f85c0c6 1783@deffn {Scheme Procedure} string-concatenate/shared ls
a0e07ba4
NJ
1784Like @code{string-concatenate}, but the result may share memory
1785with 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
1789Without optional arguments, this procedure is equivalent to
1790
1791@smalllisp
1792(string-concatenate (reverse ls))
1793@end smalllisp
1794
1795If the optional argument @var{final_string} is specified, it is
1796consed onto the beginning to @var{ls} before performing the
1797list-reverse and string-concatenate operations. If @var{end}
1798is given, only the characters of @var{final_string} up to index
1799@var{end} are used.
1800
1801Guaranteed 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
1805Like @code{string-concatenate-reverse}, but the result may
1806share 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
1816the characters a string is composed of. The fold and unfold procedures
1817are 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
1822string 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
1828string elements is not specified. The string @var{s} is
1829modified 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
1834Fold @var{kons} over the characters of @var{s}, with @var{knil} as the
1835terminating element, from left to right (or right to left, for
1836@code{string-fold-right}). @var{kons} must expect two arguments: The
1837actual 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
1842These are the fundamental string constructors.
1843@itemize @bullet
1844@item @var{g} is used to generate a series of @emph{seed}
1845values 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
1849when applied to one of these seed values.
12991fed 1850@item @var{f} maps each seed value to the corresponding
a0e07ba4
NJ
1851character in the result string. These chars are assembled into the
1852string 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
1856value (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
1864return value is not specified.
1865@end deffn
1866
050ab45f
MV
1867@deffn {Scheme Procedure} string-for-each-index proc s [start [end]]
1868@deffnx {C Function} scm_string_for_each_index (proc, s, start, end)
1869@var{proc} is mapped over @var{s} in left-to-right order. The
1870return value is not specified.
1871@end deffn
1872
a0e07ba4
NJ
1873
1874@c ===================================================================
1875
1876@node SRFI-13 Replicate/Rotate
3229f68b 1877@subsubsection Replicate/Rotate
a0e07ba4
NJ
1878
1879These procedures are special substring procedures, which can also be
1880used for replicating strings. They are a bit tricky to use, but
1881consider this code fragment, which replicates the input string
1882@code{"foo"} so often that the resulting string has a length of six.
1883
1884@lisp
1885(xsubstring "foo" 0 6)
1886@result{}
1887"foofoo"
1888@end lisp
1889
8f85c0c6 1890@deffn {Scheme Procedure} xsubstring s from [to start end]
a0e07ba4
NJ
1891This is the @emph{extended substring} procedure that implements
1892replicated copying of a substring of some string.
1893
1894@var{s} is a string, @var{start} and @var{end} are optional
1895arguments that demarcate a substring of @var{s}, defaulting to
18960 and the length of @var{s}. Replicate this substring up and
1897down index space, in both the positive and negative directions.
1898@code{xsubstring} returns the substring of this string
1899beginning at index @var{from}, and ending at @var{to}, which
1900defaults to @var{from} + (@var{end} - @var{start}).
1901@end deffn
1902
8f85c0c6 1903@deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto start end]
a0e07ba4
NJ
1904Exactly the same as @code{xsubstring}, but the extracted text
1905is written into the string @var{target} starting at index
1906@var{tstart}. The operation is not defined if @code{(eq?
1907@var{target} @var{s})} or these arguments share storage - you
1908cannot copy a string on top of itself.
1909@end deffn
1910
1911
1912@c ===================================================================
1913
1914@node SRFI-13 Miscellaneous
3229f68b 1915@subsubsection Miscellaneous
a0e07ba4
NJ
1916
1917@code{string-replace} is for replacing a portion of a string with
1918another string and @code{string-tokenize} splits a string into a list of
1919strings, breaking it up at a specified character.
1920
8c24f46e 1921@deffn {Scheme Procedure} string-replace s1 s2 [start1 end1 start2 end2]
a0e07ba4
NJ
1922Return the string @var{s1}, but with the characters
1923@var{start1} @dots{} @var{end1} replaced by the characters
1924@var{start2} @dots{} @var{end2} from @var{s2}.
5519096e
KR
1925
1926For reference, note that SRFI-13 specifies @var{start1} and @var{end1}
1927as mandatory, but in Guile they are optional.
a0e07ba4
NJ
1928@end deffn
1929
c0ab7f13 1930@deffn {Scheme Procedure} string-tokenize s [token-set start end]
a0e07ba4 1931Split the string @var{s} into a list of substrings, where each
c0ab7f13
MV
1932substring is a maximal non-empty contiguous sequence of characters
1933from the character set @var{token_set}, which defaults to an
1934equivalent of @code{char-set:graphic}. If @var{start} or @var{end}
1935indices are provided, they restrict @code{string-tokenize} to
1936operating on the indicated substring of @var{s}.
a0e07ba4
NJ
1937@end deffn
1938
1939
1940@c ===================================================================
1941
1942@node SRFI-13 Filtering/Deleting
3229f68b 1943@subsubsection Filtering/Deleting
a0e07ba4
NJ
1944
1945@dfn{Filtering} means to remove all characters from a string which do
1946not match a given criteria, @dfn{deleting} means the opposite.
1947
8f85c0c6 1948@deffn {Scheme Procedure} string-filter s char_pred [start end]
a0e07ba4
NJ
1949Filter the string @var{s}, retaining only those characters that
1950satisfy the @var{char_pred} argument. If the argument is a
1951procedure, it is applied to each character as a predicate, if
1952it is a character, it is tested for equality and if it is a
1953character set, it is tested for membership.
1954@end deffn
1955
8f85c0c6 1956@deffn {Scheme Procedure} string-delete s char_pred [start end]
a0e07ba4
NJ
1957Filter the string @var{s}, retaining only those characters that
1958do not satisfy the @var{char_pred} argument. If the argument
1959is a procedure, it is applied to each character as a predicate,
1960if it is a character, it is tested for equality and if it is a
1961character set, it is tested for membership.
1962@end deffn
1963
1964
1965@node SRFI-14
3229f68b 1966@subsection SRFI-14 - Character-set Library
8742c48b 1967@cindex SRFI-14
a0e07ba4 1968
050ab45f
MV
1969The SRFI-14 data type and procedures are always available,
1970@xref{Character Sets}.
a0e07ba4
NJ
1971
1972@node SRFI-16
3229f68b 1973@subsection SRFI-16 - case-lambda
8742c48b 1974@cindex SRFI-16
a0e07ba4
NJ
1975
1976@c FIXME::martin: Review me!
1977
8742c48b 1978@findex case-lambda
a0e07ba4
NJ
1979The syntactic form @code{case-lambda} creates procedures, just like
1980@code{lambda}, but has syntactic extensions for writing procedures of
1981varying arity easier.
1982
1983The syntax of the @code{case-lambda} form is defined in the following
1984EBNF grammar.
1985
1986@example
1987@group
1988<case-lambda>
1989 --> (case-lambda <case-lambda-clause>)
1990<case-lambda-clause>
1991 --> (<formals> <definition-or-command>*)
1992<formals>
1993 --> (<identifier>*)
1994 | (<identifier>* . <identifier>)
1995 | <identifier>
1996@end group
1997@end example
1998
1999The value returned by a @code{case-lambda} form is a procedure which
2000matches the number of actual arguments against the formals in the
2001various clauses, in order. @dfn{Formals} means a formal argument list
2002just like with @code{lambda} (@pxref{Lambda}). The first matching clause
2003is selected, the corresponding values from the actual parameter list are
2004bound to the variable names in the clauses and the body of the clause is
2005evaluated. If no clause matches, an error is signalled.
2006
2007The following (silly) definition creates a procedure @var{foo} which
2008acts differently, depending on the number of actual arguments. If one
2009argument is given, the constant @code{#t} is returned, two arguments are
2010added and if more arguments are passed, their product is calculated.
2011
2012@lisp
2013(define foo (case-lambda
2014 ((x) #t)
2015 ((x y) (+ x y))
2016 (z
2017 (apply * z))))
2018(foo 'bar)
2019@result{}
2020#t
2021(foo 2 4)
2022@result{}
20236
2024(foo 3 3 3)
2025@result{}
202627
2027(foo)
2028@result{}
20291
2030@end lisp
2031
2032The last expression evaluates to 1 because the last clause is matched,
2033@var{z} is bound to the empty list and the following multiplication,
2034applied to zero arguments, yields 1.
2035
2036
2037@node SRFI-17
3229f68b 2038@subsection SRFI-17 - Generalized set!
8742c48b 2039@cindex SRFI-17
a0e07ba4
NJ
2040
2041This is an implementation of SRFI-17: Generalized set!
2042
8742c48b 2043@findex getter-with-setter
a0e07ba4
NJ
2044It exports the Guile procedure @code{make-procedure-with-setter} under
2045the SRFI name @code{getter-with-setter} and exports the standard
2046procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr},
2047@code{string-ref} and @code{vector-ref} as procedures with setters, as
2048required by the SRFI.
2049
2050SRFI-17 was heavily criticized during its discussion period but it was
2051finalized anyway. One issue was its concept of globally associating
2052setter @dfn{properties} with (procedure) values, which is non-Schemy.
2053For this reason, this implementation chooses not to provide a way to set
2054the setter of a procedure. In fact, @code{(set! (setter @var{proc})
2055@var{setter})} signals an error. The only way to attach a setter to a
2056procedure is to create a new object (a @dfn{procedure with setter}) via
2057the @code{getter-with-setter} procedure. This procedure is also
2058specified in the SRFI. Using it avoids the described problems.
2059
12991fed
TTN
2060
2061@node SRFI-19
3229f68b 2062@subsection SRFI-19 - Time/Date Library
8742c48b 2063@cindex SRFI-19
12991fed 2064
85600a0f
KR
2065This is an implementation of the SRFI-19 time/date library. The
2066functions and variables described here are provided by
12991fed
TTN
2067
2068@example
85600a0f 2069(use-modules (srfi srfi-19))
12991fed
TTN
2070@end example
2071
85600a0f
KR
2072@menu
2073* SRFI-19 Introduction::
2074* SRFI-19 Time::
2075* SRFI-19 Date::
2076* SRFI-19 Time/Date conversions::
2077* SRFI-19 Date to string::
2078* SRFI-19 String to date::
2079@end menu
12991fed 2080
85600a0f 2081@node SRFI-19 Introduction
3229f68b 2082@subsubsection SRFI-19 Introduction
85600a0f
KR
2083
2084@cindex universal time
2085@cindex atomic time
2086@cindex UTC
2087@cindex TAI
2088This module implements time and date representations and calculations,
2089in various time systems, including universal time (UTC) and atomic
2090time (TAI).
2091
2092For those not familiar with these time systems, TAI is based on a
2093fixed length second derived from oscillations of certain atoms. UTC
2094differs from TAI by an integral number of seconds, which is increased
2095or decreased at announced times to keep UTC aligned to a mean solar
2096day (the orbit and rotation of the earth are not quite constant).
2097
2098@cindex leap second
2099So far, only increases in the TAI
2100@tex
2101$\leftrightarrow$
2102@end tex
2103@ifnottex
2104<->
2105@end ifnottex
2106UTC difference have been needed. Such an increase is a ``leap
2107second'', an extra second of TAI introduced at the end of a UTC day.
2108When working entirely within UTC this is never seen, every day simply
2109has 86400 seconds. But when converting from TAI to a UTC date, an
2110extra 23:59:60 is present, where normally a day would end at 23:59:59.
2111Effectively the UTC second from 23:59:59 to 00:00:00 has taken two TAI
2112seconds.
2113
2114@cindex system clock
2115In the current implementation, the system clock is assumed to be UTC,
2116and a table of leap seconds in the code converts to TAI. See comments
2117in @file{srfi-19.scm} for how to update this table.
2118
2119@cindex julian day
2120@cindex modified julian day
2121Also, for those not familiar with the terminology, a @dfn{Julian Day}
2122is a real number which is a count of days and fraction of a day, in
2123UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan
21244713 B.C. And a @dfn{Modified Julian Day} is the same, but starting
2125from 1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC.
2126
2127@c The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at
2128@c noon, UTC), but this is incorrect. It looks like it might have
2129@c arisen from the code incorrectly treating years a multiple of 100
2130@c but not 400 prior to 1582 as leap years, where instead the Julian
2131@c calendar should be used so all multiples of 4 before 1582 are leap
2132@c years.
2133
2134
2135@node SRFI-19 Time
3229f68b 2136@subsubsection SRFI-19 Time
85600a0f
KR
2137@cindex time
2138
2139A @dfn{time} object has type, seconds and nanoseconds fields
2140representing a point in time starting from some epoch. This is an
2141arbitrary point in time, not just a time of day. Although times are
2142represented in nanoseconds, the actual resolution may be lower.
2143
2144The following variables hold the possible time types. For instance
2145@code{(current-time time-process)} would give the current CPU process
2146time.
2147
2148@defvar time-utc
2149Universal Coordinated Time (UTC).
2150@cindex UTC
2151@end defvar
12991fed 2152
85600a0f
KR
2153@defvar time-tai
2154International Atomic Time (TAI).
2155@cindex TAI
2156@end defvar
12991fed 2157
85600a0f
KR
2158@defvar time-monotonic
2159Monotonic time, meaning a monotonically increasing time starting from
2160an unspecified epoch.
12991fed 2161
85600a0f
KR
2162Note that in the current implementation @code{time-monotonic} is the
2163same as @code{time-tai}, and unfortunately is therefore affected by
2164adjustments to the system clock. Perhaps this will change in the
2165future.
2166@end defvar
12991fed 2167
85600a0f
KR
2168@defvar time-duration
2169A duration, meaning simply a difference between two times.
2170@end defvar
12991fed 2171
85600a0f
KR
2172@defvar time-process
2173CPU time spent in the current process, starting from when the process
2174began.
2175@cindex process time
2176@end defvar
12991fed 2177
85600a0f
KR
2178@defvar time-thread
2179CPU time spent in the current thread. Not currently implemented.
2180@cindex thread time
2181@end defvar
12991fed 2182
85600a0f
KR
2183@sp 1
2184@defun time? obj
2185Return @code{#t} if @var{obj} is a time object, or @code{#f} if not.
2186@end defun
2187
2188@defun make-time type nanoseconds seconds
2189Create a time object with the given @var{type}, @var{seconds} and
2190@var{nanoseconds}.
2191@end defun
2192
2193@defun time-type time
2194@defunx time-nanosecond time
2195@defunx time-second time
2196@defunx set-time-type! time type
2197@defunx set-time-nanosecond! time nsec
2198@defunx set-time-second! time sec
2199Get or set the type, seconds or nanoseconds fields of a time object.
2200
2201@code{set-time-type!} merely changes the field, it doesn't convert the
2202time value. For conversions, see @ref{SRFI-19 Time/Date conversions}.
2203@end defun
2204
2205@defun copy-time time
2206Return a new time object, which is a copy of the given @var{time}.
2207@end defun
2208
2209@defun current-time [type]
2210Return the current time of the given @var{type}. The default
2211@var{type} is @code{time-utc}.
2212
2213Note that the name @code{current-time} conflicts with the Guile core
2214@code{current-time} function (@pxref{Time}). Applications wanting to
2215use both will need to use a different name for one of them.
2216@end defun
2217
2218@defun time-resolution [type]
2219Return the resolution, in nanoseconds, of the given time @var{type}.
2220The default @var{type} is @code{time-utc}.
2221@end defun
2222
2223@defun time<=? t1 t2
2224@defunx time<? t1 t2
2225@defunx time=? t1 t2
2226@defunx time>=? t1 t2
2227@defunx time>? t1 t2
2228Return @code{#t} or @code{#f} according to the respective relation
2229between time objects @var{t1} and @var{t2}. @var{t1} and @var{t2}
2230must be the same time type.
2231@end defun
2232
2233@defun time-difference t1 t2
2234@defunx time-difference! t1 t2
2235Return a time object of type @code{time-duration} representing the
2236period between @var{t1} and @var{t2}. @var{t1} and @var{t2} must be
2237the same time type.
2238
2239@code{time-difference} returns a new time object,
2240@code{time-difference!} may modify @var{t1} to form its return.
2241@end defun
2242
2243@defun add-duration time duration
2244@defunx add-duration! time duration
2245@defunx subtract-duration time duration
2246@defunx subtract-duration! time duration
2247Return a time object which is @var{time} with the given @var{duration}
2248added or subtracted. @var{duration} must be a time object of type
2249@code{time-duration}.
2250
2251@code{add-duration} and @code{subtract-duration} return a new time
2252object. @code{add-duration!} and @code{subtract-duration!} may modify
2253the given @var{time} to form their return.
2254@end defun
2255
2256
2257@node SRFI-19 Date
3229f68b 2258@subsubsection SRFI-19 Date
85600a0f
KR
2259@cindex date
2260
2261A @dfn{date} object represents a date in the Gregorian calendar and a
2262time of day on that date in some timezone.
2263
2264The fields are year, month, day, hour, minute, second, nanoseconds and
2265timezone. A date object is immutable, its fields can be read but they
2266cannot be modified once the object is created.
2267
2268@defun date? obj
2269Return @code{#t} if @var{obj} is a date object, or @code{#f} if not.
2270@end defun
2271
2272@defun make-date nsecs seconds minutes hours date month year zone-offset
2273Create a new date object.
2274@c
2275@c FIXME: What can we say about the ranges of the values. The
2276@c current code looks it doesn't normalize, but expects then in their
2277@c usual range already.
2278@c
2279@end defun
2280
2281@defun date-nanosecond date
2282Nanoseconds, 0 to 999999999.
2283@end defun
2284
2285@defun date-second date
2286Seconds, 0 to 60. 0 to 59 is the usual range, 60 is for a leap second.
2287@end defun
2288
2289@defun date-minute date
2290Minutes, 0 to 59.
2291@end defun
2292
2293@defun date-hour date
2294Hour, 0 to 23.
2295@end defun
2296
2297@defun date-day date
2298Day of the month, 1 to 31 (or less, according to the month).
2299@end defun
2300
2301@defun date-month date
2302Month, 1 to 12.
2303@end defun
2304
2305@defun date-year date
2306Year, eg.@: 2003.
2307@end defun
2308
2309@defun date-zone-offset date
2310Time zone, an integer number of seconds east of Greenwich.
2311@end defun
2312
2313@defun date-year-day date
2314Day of the year, starting from 1 for 1st January.
2315@end defun
2316
2317@defun date-week-day date
2318Day of the week, starting from 0 for Sunday.
2319@end defun
2320
2321@defun date-week-number date dstartw
2322Week of the year, ignoring a first partial week. @var{dstartw} is the
2323day of the week which is taken to start a week, 0 for Sunday, 1 for
2324Monday, etc.
2325@c
2326@c FIXME: The spec doesn't say whether numbering starts at 0 or 1.
2327@c The code looks like it's 0, if that's the correct intention.
2328@c
2329@end defun
2330
2331@c The SRFI text doesn't actually give the default for tz-offset, but
2332@c the reference implementation has the local timezone and the
2333@c conversions functions all specify that, so it should be ok to
2334@c document it here.
2335@c
2336@defun current-date [tz-offset]
2337Return a date object representing the current date/time UTC.
2338@var{tz-offset} is seconds east of Greenwich, and defaults to the
2339local timezone.
2340@end defun
2341
2342@defun current-julian-day
2343@cindex julian day
2344Return the current Julian Day.
2345@end defun
2346
2347@defun current-modified-julian-day
2348@cindex modified julian day
2349Return the current Modified Julian Day.
2350@end defun
2351
2352
2353@node SRFI-19 Time/Date conversions
3229f68b 2354@subsubsection SRFI-19 Time/Date conversions
85600a0f
KR
2355
2356@defun date->julian-day date
2357@defunx date->modified-julian-day date
2358@defunx date->time-monotonic date
2359@defunx date->time-tai date
2360@defunx date->time-utc date
2361@end defun
2362@defun julian-day->date jdn [tz-offset]
2363@defunx julian-day->time-monotonic jdn
2364@defunx julian-day->time-tai jdn
2365@defunx julian-day->time-utc jdn
2366@end defun
2367@defun modified-julian-day->date jdn [tz-offset]
2368@defunx modified-julian-day->time-monotonic jdn
2369@defunx modified-julian-day->time-tai jdn
2370@defunx modified-julian-day->time-utc jdn
2371@end defun
2372@defun time-monotonic->date time [tz-offset]
2373@defunx time-monotonic->time-tai time
2374@defunx time-monotonic->time-tai! time
2375@defunx time-monotonic->time-utc time
2376@defunx time-monotonic->time-utc! time
2377@end defun
2378@defun time-tai->date time [tz-offset]
2379@defunx time-tai->julian-day time
2380@defunx time-tai->modified-julian-day time
2381@defunx time-tai->time-monotonic time
2382@defunx time-tai->time-monotonic! time
2383@defunx time-tai->time-utc time
2384@defunx time-tai->time-utc! time
2385@end defun
2386@defun time-utc->date time [tz-offset]
2387@defunx time-utc->julian-day time
2388@defunx time-utc->modified-julian-day time
2389@defunx time-utc->time-monotonic time
2390@defunx time-utc->time-monotonic! time
2391@defunx time-utc->time-tai time
2392@defunx time-utc->time-tai! time
2393@sp 1
2394Convert between dates, times and days of the respective types. For
2395instance @code{time-tai->time-utc} accepts a @var{time} object of type
2396@code{time-tai} and returns an object of type @code{time-utc}.
2397
2398For conversions to dates, @var{tz-offset} is seconds east of
2399Greenwich. The default is the local timezone.
2400
2401The @code{!} variants may modify their @var{time} argument to form
2402their return. The plain functions create a new object.
2403@end defun
2404
2405@node SRFI-19 Date to string
3229f68b 2406@subsubsection SRFI-19 Date to string
85600a0f
KR
2407@cindex date to string
2408
2409@defun date->string date [format]
2410Convert a date to a string under the control of a format.
2411@var{format} should be a string containing @samp{~} escapes, which
2412will be expanded as per the following conversion table. The default
2413@var{format} is @samp{~c}, a locale-dependent date and time.
2414
2415Many of these conversion characters are the same as POSIX
2416@code{strftime} (@pxref{Time}), but there are some extras and some
2417variations.
2418
2419@multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM}
2420@item @nicode{~~} @tab literal ~
2421@item @nicode{~a} @tab locale abbreviated weekday, eg.@: @samp{Sun}
2422@item @nicode{~A} @tab locale full weekday, eg.@: @samp{Sunday}
2423@item @nicode{~b} @tab locale abbreviated month, eg.@: @samp{Jan}
2424@item @nicode{~B} @tab locale full month, eg.@: @samp{January}
2425@item @nicode{~c} @tab locale date and time, eg.@: @*
2426@samp{Fri Jul 14 20:28:42-0400 2000}
2427@item @nicode{~d} @tab day of month, zero padded, @samp{01} to @samp{31}
2428
2429@c Spec says d/m/y, reference implementation says m/d/y.
2430@c Apparently the reference code was the intention, but would like to
2431@c see an errata published for the spec before contradicting it here.
2432@c
2433@c @item @nicode{~D} @tab date @nicode{~d/~m/~y}
2434
2435@item @nicode{~e} @tab day of month, blank padded, @samp{ 1} to @samp{31}
2436@item @nicode{~f} @tab seconds and fractional seconds,
2437with locale decimal point, eg.@: @samp{5.2}
2438@item @nicode{~h} @tab same as @nicode{~b}
2439@item @nicode{~H} @tab hour, 24-hour clock, zero padded, @samp{00} to @samp{23}
2440@item @nicode{~I} @tab hour, 12-hour clock, zero padded, @samp{01} to @samp{12}
2441@item @nicode{~j} @tab day of year, zero padded, @samp{001} to @samp{366}
2442@item @nicode{~k} @tab hour, 24-hour clock, blank padded, @samp{ 0} to @samp{23}
2443@item @nicode{~l} @tab hour, 12-hour clock, blank padded, @samp{ 1} to @samp{12}
2444@item @nicode{~m} @tab month, zero padded, @samp{01} to @samp{12}
2445@item @nicode{~M} @tab minute, zero padded, @samp{00} to @samp{59}
2446@item @nicode{~n} @tab newline
2447@item @nicode{~N} @tab nanosecond, zero padded, @samp{000000000} to @samp{999999999}
2448@item @nicode{~p} @tab locale AM or PM
2449@item @nicode{~r} @tab time, 12 hour clock, @samp{~I:~M:~S ~p}
2450@item @nicode{~s} @tab number of full seconds since ``the epoch'' in UTC
2451@item @nicode{~S} @tab second, zero padded @samp{00} to @samp{60} @*
2452(usual limit is 59, 60 is a leap second)
2453@item @nicode{~t} @tab horizontal tab character
2454@item @nicode{~T} @tab time, 24 hour clock, @samp{~H:~M:~S}
2455@item @nicode{~U} @tab week of year, Sunday first day of week,
2456@samp{00} to @samp{52}
2457@item @nicode{~V} @tab week of year, Monday first day of week,
2458@samp{01} to @samp{53}
2459@item @nicode{~w} @tab day of week, 0 for Sunday, @samp{0} to @samp{6}
2460@item @nicode{~W} @tab week of year, Monday first day of week,
2461@samp{00} to @samp{52}
2462
2463@c The spec has ~x as an apparent duplicate of ~W, and ~X as a locale
2464@c date. The reference code has ~x as the locale date and ~X as a
2465@c locale time. The rule is apparently that the code should be
2466@c believed, but would like to see an errata for the spec before
2467@c contradicting it here.
2468@c
2469@c @item @nicode{~x} @tab week of year, Monday as first day of week,
2470@c @samp{00} to @samp{53}
2471@c @item @nicode{~X} @tab locale date, eg.@: @samp{07/31/00}
2472
2473@item @nicode{~y} @tab year, two digits, @samp{00} to @samp{99}
2474@item @nicode{~Y} @tab year, full, eg.@: @samp{2003}
2475@item @nicode{~z} @tab time zone, RFC-822 style
2476@item @nicode{~Z} @tab time zone symbol (not currently implemented)
2477@item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d}
2478@item @nicode{~2} @tab ISO-8601 time+zone, @samp{~k:~M:~S~z}
2479@item @nicode{~3} @tab ISO-8601 time, @samp{~k:~M:~S}
2480@item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~k:~M:~S~z}
2481@item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~k:~M:~S}
2482@end multitable
2483@end defun
2484
2485Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently
2486described here, since the specification and reference implementation
2487differ.
2488
2489Currently Guile doesn't implement any localizations for the above, all
2490outputs are in English, and the @samp{~c} conversion is POSIX
2491@code{ctime} style @samp{~a ~b ~d ~H:~M:~S~z ~Y}. This may change in
2492the future.
2493
2494
2495@node SRFI-19 String to date
3229f68b 2496@subsubsection SRFI-19 String to date
85600a0f
KR
2497@cindex string to date
2498
2499@c FIXME: Can we say what happens when an incomplete date is
2500@c converted? Ie. fields left as 0, or what? The spec seems to be
2501@c silent on this.
2502
2503@defun string->date input template
2504Convert an @var{input} string to a date under the control of a
2505@var{template} string. Return a newly created date object.
2506
2507Literal characters in @var{template} must match characters in
2508@var{input} and @samp{~} escapes must match the input forms described
2509in the table below. ``Skip to'' means characters up to one of the
2510given type are ignored, or ``no skip'' for no skipping. ``Read'' is
2511what's then read, and ``Set'' is the field affected in the date
2512object.
2513
2514For example @samp{~Y} skips input characters until a digit is reached,
2515at which point it expects a year and stores that to the year field of
2516the date.
2517
2518@multitable {MMMM} {@nicode{char-alphabetic?}} {MMMMMMMMMMMMMMMMMMMMMMMMM} {@nicode{date-zone-offset}}
2519@item
2520@tab Skip to
2521@tab Read
2522@tab Set
2523
2524@item @nicode{~~}
2525@tab no skip
2526@tab literal ~
2527@tab nothing
2528
2529@item @nicode{~a}
2530@tab @nicode{char-alphabetic?}
2531@tab locale abbreviated weekday name
2532@tab nothing
2533
2534@item @nicode{~A}
2535@tab @nicode{char-alphabetic?}
2536@tab locale full weekday name
2537@tab nothing
2538
2539@c Note that the SRFI spec says that ~b and ~B don't set anything,
2540@c but that looks like a mistake. The reference implementation sets
2541@c the month field, which seems sensible and is what we describe
2542@c here.
2543
2544@item @nicode{~b}
2545@tab @nicode{char-alphabetic?}
2546@tab locale abbreviated month name
2547@tab @nicode{date-month}
2548
2549@item @nicode{~B}
2550@tab @nicode{char-alphabetic?}
2551@tab locale full month name
2552@tab @nicode{date-month}
2553
2554@item @nicode{~d}
2555@tab @nicode{char-numeric?}
2556@tab day of month
2557@tab @nicode{date-day}
2558
2559@item @nicode{~e}
2560@tab no skip
2561@tab day of month, blank padded
2562@tab @nicode{date-day}
2563
2564@item @nicode{~h}
2565@tab same as @samp{~b}
2566
2567@item @nicode{~H}
2568@tab @nicode{char-numeric?}
2569@tab hour
2570@tab @nicode{date-hour}
2571
2572@item @nicode{~k}
2573@tab no skip
2574@tab hour, blank padded
2575@tab @nicode{date-hour}
2576
2577@item @nicode{~m}
2578@tab @nicode{char-numeric?}
2579@tab month
2580@tab @nicode{date-month}
2581
2582@item @nicode{~M}
2583@tab @nicode{char-numeric?}
2584@tab minute
2585@tab @nicode{date-minute}
2586
2587@item @nicode{~S}
2588@tab @nicode{char-numeric?}
2589@tab second
2590@tab @nicode{date-second}
2591
2592@item @nicode{~y}
2593@tab no skip
2594@tab 2-digit year
2595@tab @nicode{date-year} within 50 years
2596
2597@item @nicode{~Y}
2598@tab @nicode{char-numeric?}
2599@tab year
2600@tab @nicode{date-year}
2601
2602@item @nicode{~z}
2603@tab no skip
2604@tab time zone
2605@tab date-zone-offset
2606@end multitable
2607
2608Notice that the weekday matching forms don't affect the date object
2609returned, instead the weekday will be derived from the day, month and
2610year.
2611
2612Currently Guile doesn't implement any localizations for the above,
2613month and weekday names are always expected in English. This may
2614change in the future.
2615@end defun
12991fed 2616
1de8c1ae 2617
b0b55bd6 2618@node SRFI-26
3229f68b 2619@subsection SRFI-26 - specializing parameters
1de8c1ae
KR
2620@cindex SRFI-26
2621
2622This SRFI provides a syntax for conveniently specializing selected
2623parameters of a function. It can be used with,
2624
2625@example
2626(use-modules (srfi srfi-26))
2627@end example
2628
2629@deffn {library syntax} cut slot @dots{}
2630@deffnx {library syntax} cute slot @dots{}
2631Return a new procedure which will make a call (@var{slot} @dots{}) but
2632with selected parameters specialized to given expressions.
2633
2634An example will illustrate the idea. The following is a
2635specialization of @code{write}, sending output to
2636@code{my-output-port},
2637
2638@example
2639(cut write <> my-output-port)
2640@result{}
2641(lambda (obj) (write obj my-output-port))
2642@end example
2643
2644The special symbol @code{<>} indicates a slot to be filled by an
2645argument to the new procedure. @code{my-output-port} on the other
2646hand is an expression to be evaluated and passed, ie.@: it specializes
2647the behaviour of @code{write}.
2648
2649@table @nicode
2650@item <>
2651A slot to be filled by an argument from the created procedure.
2652Arguments are assigned to @code{<>} slots in the order they appear in
2653the @code{cut} form, there's no way to re-arrange arguments.
2654
2655The first argument to @code{cut} is usually a procedure (or expression
2656giving a procedure), but @code{<>} is allowed there too. For example,
2657
2658@example
2659(cut <> 1 2 3)
2660@result{}
2661(lambda (proc) (proc 1 2 3))
2662@end example
2663
2664@item <...>
2665A slot to be filled by all remaining arguments from the new procedure.
2666This can only occur at the end of a @code{cut} form.
2667
2668For example, a procedure taking a variable number of arguments like
2669@code{max} but in addition enforcing a lower bound,
2670
2671@example
2672(define my-lower-bound 123)
2673
2674(cut max my-lower-bound <...>)
2675@result{}
2676(lambda arglist (apply max my-lower-bound arglist))
2677@end example
2678@end table
2679
2680For @code{cut} the specializing expressions are evaluated each time
2681the new procedure is called. For @code{cute} they're evaluated just
2682once, when the new procedure is created. The name @code{cute} stands
2683for ``@code{cut} with evaluated arguments''. In all cases the
2684evaluations take place in an unspecified order.
2685
2686The following illustrates the difference between @code{cut} and
2687@code{cute},
2688
2689@example
2690(cut format <> "the time is ~s" (current-time))
2691@result{}
2692(lambda (port) (format port "the time is ~s" (current-time)))
2693
2694(cute format <> "the time is ~s" (current-time))
2695@result{}
2696(let ((val (current-time)))
2697 (lambda (port) (format port "the time is ~s" val))
2698@end example
2699
2700(There's no provision for a mixture of @code{cut} and @code{cute}
2701where some expressions would be evaluated every time but others
2702evaluated only once.)
2703
2704@code{cut} is really just a shorthand for the sort of @code{lambda}
2705forms shown in the above examples. But notice @code{cut} avoids the
2706need to name unspecialized parameters, and is more compact. Use in
2707functional programming style or just with @code{map}, @code{for-each}
2708or similar is typical.
2709
2710@example
2711(map (cut * 2 <>) '(1 2 3 4))
2712
2713(for-each (cut write <> my-port) my-list)
2714@end example
2715@end deffn
b0b55bd6 2716
8638c417
RB
2717@node SRFI-31
2718@subsection SRFI-31 - A special form `rec' for recursive evaluation
2719@cindex SRFI-31
2720@findex rec
2721
2722SRFI-31 defines a special form that can be used to create
2723self-referential expressions more conveniently. The syntax is as
2724follows:
2725
2726@example
2727@group
2728<rec expression> --> (rec <variable> <expression>)
2729<rec expression> --> (rec (<variable>+) <body>)
2730@end group
2731@end example
2732
2733The first syntax can be used to create self-referential expressions,
2734for example:
2735
2736@lisp
2737 guile> (define tmp (rec ones (cons 1 (delay ones))))
2738@end lisp
2739
2740The second syntax can be used to create anonymous recursive functions:
2741
2742@lisp
2743 guile> (define tmp (rec (display-n item n)
2744 (if (positive? n)
2745 (begin (display n) (display-n (- n 1))))))
2746 guile> (tmp 42 3)
2747 424242
2748 guile>
2749@end lisp
12991fed
TTN
2750
2751@c srfi-modules.texi ends here
193239f1
KR
2752
2753@c Local Variables:
2754@c TeX-master: "guile.texi"
2755@c End: