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.
9 @section Pretty Printing
11 @c FIXME::martin: Review me!
13 @cindex pretty printing
14 The module @code{(ice-9 pretty-print)} provides the procedure
15 @code{pretty-print}, which provides nicely formatted output of Scheme
16 objects. This is especially useful for deeply nested or complex data
17 structures, such as lists and vectors.
19 The module is loaded by simply saying.
22 (use-modules (ice-9 pretty-print))
25 This makes the procedure @code{pretty-print} available. As an example
26 how @code{pretty-print} will format the output, see the following:
29 (pretty-print '(define (foo) (lambda (x)
30 (cond ((zero? x) #t) ((negative? x) -x) (else
31 (if (= x 1) 2 (* x x x)))))))
37 (else (if (= x 1) 2 (* x x x))))))
40 @deffn {Scheme Procedure} pretty-print obj [port] [keyword-options]
41 Print the textual representation of the Scheme object @var{obj} to
42 @var{port}. @var{port} defaults to the current output port, if not
45 The further @var{keyword-options} are keywords and parameters as
49 @item @nicode{#:display?} @var{flag}
50 If @var{flag} is true then print using @code{display}. The default is
51 @code{#f} which means use @code{write} style. (@pxref{Writing})
53 @item @nicode{#:per-line-prefix} @var{string}
54 Print the given @var{string} as a prefix on each line. The default is
57 @item @nicode{#:width} @var{columns}
58 Print within the given @var{columns}. The default is 79.
64 @node Formatted Output
65 @section Formatted Output
66 @cindex formatted output
68 @c For reference, in this section escapes like ~a are given in
69 @c @nicode, to give code font in TeX etc, but leave them unadorned in
72 @c The idea is to reduce clutter around what's shown, and avoid any
73 @c possible confusion over whether the ` ' quotes are part of what
74 @c should be entered. (In particular for instance of course ' is
75 @c meaningful in a format string, introducing a char parameter).
77 The @code{format} function is a powerful way to print numbers, strings
78 and other objects together with literal text under the control of a
79 format string. This function is available from
82 (use-modules (ice-9 format))
85 A format string is generally more compact and easier than using just
86 the standard procedures like @code{display}, @code{write} and
87 @code{newline}. Parameters in the output string allow various output
88 styles, and parameters can be taken from the arguments for runtime
91 @code{format} is similar to the Common Lisp procedure of the same
92 name, but it's not identical and doesn't have quite all the features
95 C programmers will note the similarity between @code{format} and
96 @code{printf}, though escape sequences are marked with @nicode{~}
97 instead of @nicode{%}, and are more powerful.
100 @deffn {Scheme Procedure} format dest fmt [args@dots{}]
101 Write output specified by the @var{fmt} string to @var{dest}.
102 @var{dest} can be an output port, @code{#t} for
103 @code{current-output-port} (@pxref{Default Ports}), a number for
104 @code{current-error-port}, or @code{#f} to return the output as a
107 @var{fmt} can contain literal text to be output, and @nicode{~}
108 escapes. Each escape has the form
111 ~ [param [, param@dots{}] [:] [@@] code
114 @nicode{code} is a character determining the escape sequence. The
115 @nicode{:} and @nicode{@@} characters are optional modifiers, one or
116 both of which change the way various codes operate. Optional
117 parameters are accepted by some codes too. Parameters have the
121 @item @nicode{[+/-] number}
122 An integer, with optional @nicode{+} or @nicode{-}.
123 @item @nicode{'} (apostrophe)
124 The following character in the format string, for instance @nicode{'z}
127 The next function argument as the parameter. @nicode{v} stands for
128 ``variable'', a parameter can be calculated at runtime and included in
129 the arguments. Upper case @nicode{V} can be used too.
131 The number of arguments remaining. (See @nicode{~*} below for some
135 Parameters are separated by commas (@nicode{,}). A parameter can be
136 left empty to keep its default value when supplying later parameters.
139 The following escapes are available. The code letters are not
140 case-sensitive, upper and lower case are the same.
145 Object output. Parameters: @var{minwidth}, @var{padinc},
146 @var{minpad}, @var{padchar}.
148 @nicode{~a} outputs an argument like @code{display}, @nicode{~s}
149 outputs an argument like @code{write} (@pxref{Writing}).
152 (format #t "~a" "foo") @print{} foo
153 (format #t "~s" "foo") @print{} "foo"
156 With the @nicode{:} modifier, objects which don't have an external
157 representation are put in quotes like a string.
160 (format #t "~:a" car) @print{} "#<primitive-procedure car>"
163 If the output is less than @var{minwidth} characters (default 0), it's
164 padded on the right with @var{padchar} (default space). The
165 @nicode{@@} modifier puts the padding on the left instead.
168 (format #f "~5a" 'abc) @result{} "abc "
169 (format #f "~5,,,'-@@a" 'abc) @result{} "--abc"
172 @var{minpad} is a minimum for the padding then plus a multiple of
173 @var{padinc}. Ie.@: the padding is @math{@var{minpad} + @var{N} *
174 @var{padinc}}, where @var{n} is the smallest integer making the total
175 object plus padding greater than or equal to @var{minwidth}. The
176 default @var{minpad} is 0 and the default @var{padinc} is 1 (imposing
177 no minimum or multiple).
180 (format #f "~5,1,4a" 'abc) @result{} "abc "
184 Character. Parameter: @var{charnum}.
186 Output a character. The default is to simply output, as per
187 @code{write-char} (@pxref{Writing}). With the @nicode{@@} modifier
188 output is in @code{write} style. Or with the @nicode{:} modifier
189 control characters (ASCII 0 to 31) are printed in @nicode{^X} form.
192 (format #t "~c" #\z) @print{} z
193 (format #t "~@@c" #\z) @print{} #\z
194 (format #t "~:c" #\newline) @print{} ^J
197 If the @var{charnum} parameter is given then an argument is not taken
198 but instead the character is @code{(integer->char @var{charnum})}
199 (@pxref{Characters}). This can be used for instance to output
200 characters given by their ASCII code.
203 (format #t "~65c") @print{} A
210 Integer. Parameters: @var{minwidth}, @var{padchar}, @var{commachar},
213 Output an integer argument as a decimal, hexadecimal, octal or binary
214 integer (respectively).
217 (format #t "~d" 123) @print{} 123
220 With the @nicode{@@} modifier, a @nicode{+} sign is shown on positive
223 @c FIXME: "+" is not shown on zero, unlike in Common Lisp. Should
224 @c that be changed in the code, or is it too late and should just be
225 @c documented that way?
228 (format #t "~@@b" 12) @print{} +1100
231 If the output is less than the @var{minwidth} parameter (default no
232 minimum), it's padded on the left with the @var{padchar} parameter
236 (format #t "~5,'*d" 12) @print{} ***12
237 (format #t "~5,'0d" 12) @print{} 00012
238 (format #t "~3d" 1234) @print{} 1234
241 The @nicode{:} modifier adds commas (or the @var{commachar} parameter)
242 every three digits (or the @var{commawidth} parameter many).
245 (format #t "~:d" 1234567) @print{} 1,234,567
246 (format #t "~10,'*,'/,2:d" 12345) @print{} ***1/23/45
249 Hexadecimal @nicode{~x} output is in lower case, but the @nicode{~(}
250 and @nicode{~)} case conversion directives described below can be used
254 (format #t "~x" 65261) @print{} feed
255 (format #t "~:@@(~x~)" 65261) @print{} FEED
259 Integer in words, roman numerals, or a specified radix. Parameters:
260 @var{radix}, @var{minwidth}, @var{padchar}, @var{commachar},
263 With no parameters output is in words as a cardinal like ``ten'', or
264 with the @nicode{:} modifier as an ordinal like ``tenth''.
267 (format #t "~r" 9) @print{} nine ;; cardinal
268 (format #t "~r" -9) @print{} minus nine ;; cardinal
269 (format #t "~:r" 9) @print{} ninth ;; ordinal
272 And also with no parameters, the @nicode{@@} modifier gives roman
273 numerals and @nicode{@@} and @nicode{:} together give old roman
274 numerals. In old roman numerals there's no ``subtraction'', so 9 is
275 @nicode{VIIII} instead of @nicode{IX}. In both cases only positive
276 numbers can be output.
279 (format #t "~@@r" 89) @print{} LXXXIX ;; roman
280 (format #t "~@@:r" 89) @print{} LXXXVIIII ;; old roman
283 When a parameter is given it means numeric output in the specified
284 @var{radix}. The modifiers and parameters following the radix are the
285 same as described for @nicode{~d} etc above.
288 (format #f "~3r" 27) @result{} "1000" ;; base 3
289 (format #f "~3,5r" 26) @result{} " 222" ;; base 3 width 5
293 Fixed-point float. Parameters: @var{width}, @var{decimals},
294 @var{scale}, @var{overflowchar}, @var{padchar}.
296 Output a number or number string in fixed-point format, ie.@: with a
300 (format #t "~f" 5) @print{} 5.0
301 (format #t "~f" "123") @print{} 123.0
302 (format #t "~f" "1e-1") @print{} 0.1
305 With the @nicode{@@} modifier a @nicode{+} sign is shown on positive
306 numbers (including zero).
309 (format #t "~@@f" 0) @print{} +0.0
312 If the output is less than @var{width} characters it's padded on the
313 left with @var{padchar} (space by default). If the output equals or
314 exceeds @var{width} then there's no padding. The default for
315 @var{width} is no padding.
318 (format #f "~6f" -1.5) @result{} " -1.5"
319 (format #f "~6,,,,'*f" 23) @result{} "**23.0"
320 (format #f "~6f" 1234567.0) @result{} "1234567.0"
323 @var{decimals} is how many digits to print after the decimal point,
324 with the value rounded or padded with zeros as necessary. (The
325 default is to output as many decimals as required.)
328 (format #t "~1,2f" 3.125) @print{} 3.13
329 (format #t "~1,2f" 1.5) @print{} 1.50
332 @var{scale} is a power of 10 applied to the value, moving the decimal
333 point that many places. A positive @var{scale} increases the value
334 shown, a negative decreases it.
337 (format #t "~,,2f" 1234) @print{} 123400.0
338 (format #t "~,,-2f" 1234) @print{} 12.34
341 If @var{overflowchar} and @var{width} are both given and if the output
342 would exceed @var{width}, then that many @var{overflowchar}s are
343 printed instead of the value.
346 (format #t "~5,,,'xf" 12345) @print{} 12345
347 (format #t "~4,,,'xf" 12345) @print{} xxxx
351 Exponential float. Parameters: @var{width}, @var{mantdigits},
352 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
355 Output a number or number string in exponential notation.
358 (format #t "~e" 5000.25) @print{} 5.00025E+3
359 (format #t "~e" "123.4") @print{} 1.234E+2
360 (format #t "~e" "1e4") @print{} 1.0E+4
363 With the @nicode{@@} modifier a @nicode{+} sign is shown on positive
364 numbers (including zero). (This is for the mantissa, a @nicode{+} or
365 @nicode{-} sign is always shown on the exponent.)
368 (format #t "~@@e" 5000.0) @print{} +5.0E+3
371 If the output is less than @var{width} characters it's padded on the
372 left with @var{padchar} (space by default). The default for
373 @var{width} is to output with no padding.
376 (format #f "~10e" 1234.0) @result{} " 1.234E+3"
377 (format #f "~10,,,,,'*e" 0.5) @result{} "****5.0E-1"
380 @c FIXME: Describe what happens when the number is bigger than WIDTH.
381 @c There seems to be a bit of dodginess about this, or some deviation
384 @var{mantdigits} is the number of digits shown in the mantissa after
385 the decimal point. The value is rounded or trailing zeros are added
386 as necessary. The default @var{mantdigits} is to show as much as
390 (format #f "~,3e" 11111.0) @result{} "1.111E+4"
391 (format #f "~,8e" 123.0) @result{} "1.23000000E+2"
394 @var{expdigits} is the minimum number of digits shown for the
395 exponent, with leading zeros added if necessary. The default for
396 @var{expdigits} is to show only as many digits as required. At least
397 1 digit is always shown.
400 (format #f "~,,1e" 1.0e99) @result{} "1.0E+99"
401 (format #f "~,,6e" 1.0e99) @result{} "1.0E+000099"
404 @var{intdigits} (default 1) is the number of digits to show before the
405 decimal point in the mantissa. @var{intdigits} can be zero, in which
406 case the integer part is a single @nicode{0}, or it can be negative,
407 in which case leading zeros are shown after the decimal point.
409 @c FIXME: When INTDIGITS is 0, Common Lisp format apparently only
410 @c shows the single 0 digit if it fits in WIDTH. format.scm seems to
411 @c show it always. Is it meant to?
414 (format #t "~,,,3e" 12345.0) @print{} 123.45E+2
415 (format #t "~,,,0e" 12345.0) @print{} 0.12345E+5
416 (format #t "~,,,-3e" 12345.0) @print{} 0.00012345E+8
419 @c FIXME: MANTDIGITS with negative INTDIGITS doesn't match CL spec,
420 @c believe the spec says it ought to still show mantdigits+1 sig
421 @c figures, ie. leading zeros don't count towards MANTDIGITS, but it
422 @c seems to just treat MANTDIGITS as how many digits after the
425 If @var{overflowchar} is given then @var{width} is a hard limit. If
426 the output would exceed @var{width} then instead that many
427 @var{overflowchar}s are printed.
430 (format #f "~6,,,,'xe" 100.0) @result{} "1.0E+2"
431 (format #f "~3,,,,'xe" 100.0) @result{} "xxx"
434 @var{expchar} is the exponent marker character (default @nicode{E}).
437 (format #t "~,,,,,,'ee" 100.0) @print{} 1.0e+2
441 General float. Parameters: @var{width}, @var{mantdigits},
442 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
445 Output a number or number string in either exponential format the same
446 as @nicode{~e}, or fixed-point format like @nicode{~f} but aligned
447 where the mantissa would have been and followed by padding where the
448 exponent would have been.
450 @c FIXME: The default MANTDIGITS is apparently max(needed,min(n,7))
451 @c where 10^(n-1)<=abs(x)<=10^n. But the Common Lisp spec seems to
452 @c ask for "needed" to be without leading or trailing zeros, whereas
453 @c format.scm seems to include trailing zeros, ending up with it
454 @c using fixed format for bigger values than it should.
456 Fixed-point is used when the absolute value is 0.1 or more and it
457 takes no more space than the mantissa in exponential format, ie.@:
458 basically up to @var{mantdigits} digits.
461 (format #f "~12,4,2g" 999.0) @result{} " 999.0 "
462 (format #f "~12,4,2g" "100000") @result{} " 1.0000E+05"
465 The parameters are interpreted as per @nicode{~e} above. When
466 fixed-point is used, the @var{decimals} parameter to @nicode{~f} is
467 established from @var{mantdigits}, so as to give a total
468 @math{@var{mantdigits}+1} figures.
471 Monetary style fixed-point float. Parameters: @var{decimals},
472 @var{intdigits}, @var{width}, @var{padchar}.
474 @c For reference, fmtdoc.txi from past versions of slib showed the
475 @c INTDIGITS parameter as SCALE. That looks like a typo, in the code
476 @c and in the Common Lisp spec it's a minimum digits for the integer
477 @c part, it isn't a power of 10 like in ~f.
479 Output a number or number string in fixed-point format, ie.@: with a
480 decimal point. @var{decimals} is the number of decimal places to
484 (format #t "~$" 5) @print{} 5.00
485 (format #t "~4$" "2.25") @print{} 2.2500
486 (format #t "~4$" "1e-2") @print{} 0.0100
489 With the @nicode{@@} modifier a @nicode{+} sign is shown on positive
490 numbers (including zero).
493 (format #t "~@@$" 0) @print{} +0.00
496 @var{intdigits} is a minimum number of digits to show in the integer
497 part of the value (default 1).
500 (format #t "~,3$" 9.5) @print{} 009.50
501 (format #t "~,0$" 0.125) @print{} .13
504 If the output is less than @var{width} characters (default 0), it's
505 padded on the left with @var{padchar} (default space). With the
506 @nicode{:} modifier the padding is output after the sign.
509 (format #f "~,,8$" -1.5) @result{} " -1.50"
510 (format #f "~,,8:$" -1.5) @result{} "- 1.50"
511 (format #f "~,,8,'.@@:$" 3) @result{} "+...3.00"
514 Note that floating point for dollar amounts is generally not a good
515 idea, because a cent @math{0.01} cannot be represented exactly in the
516 binary floating point Guile uses, which leads to slowly accumulating
517 rounding errors. Keeping values as cents (or fractions of a cent) in
518 integers then printing with the scale option in @nicode{~f} may be a
521 @c For reference, fractions don't work with ~$ (or any of the float
522 @c conversions) currently. If they did work then we could perhaps
523 @c suggest keeping dollar amounts as rationals, which would of course
524 @c give exact cents. An integer as cents is probably still a better
525 @c recommendation though, since it forces one to think about where
526 @c and when rounding can or should occur.
529 Complex fixed-point float. Parameters: @var{width}, @var{decimals},
530 @var{scale}, @var{overflowchar}, @var{padchar}.
532 @c For reference, in Common Lisp ~i is an indent, but slib fmtdoc.txi
533 @c described it as complex number output, so we keep that.
535 Output the argument as a complex number, with both real and imaginary
536 part shown (even if one or both are zero).
538 The parameters and modifiers are the same as for fixed-point
539 @nicode{~f} described above. The real and imaginary parts are both
540 output with the same given parameters and modifiers, except that for
541 the imaginary part the @nicode{@@} modifier is always enabled, so as
542 to print a @nicode{+} sign between the real and imaginary parts.
545 (format #t "~i" 1) @print{} 1.0+0.0i
549 Plural. No parameters.
551 Output nothing if the argument is 1, or @samp{s} for any other
555 (format #t "enter name~p" 1) @print{} enter name
556 (format #t "enter name~p" 2) @print{} enter names
559 With the @nicode{@@} modifier, the output is @samp{y} for 1 or
560 @samp{ies} otherwise.
563 (format #t "pupp~@@p" 1) @print{} puppy
564 (format #t "pupp~@@p" 2) @print{} puppies
567 The @nicode{:} modifier means re-use the preceding argument instead of
568 taking a new one, which can be convenient when printing some sort of
572 (format #t "~d cat~:p" 9) @print{} 9 cats
576 Pretty print. No parameters.
578 Output an argument with @code{pretty-print} (@pxref{Pretty Printing}).
582 Sub-format. No parameters.
584 Take a format string argument and a second argument which is a list of
585 arguments for it, and output the result. With the @nicode{@@}
586 modifier, the arguments for the sub-format are taken directly rather
590 (format #t "~?" "~d ~d" '(1 2)) @print{} 1 2
591 (format #t "~@@? ~s" "~d ~d" 1 2 "foo") @print{} 1 2 "foo"
594 @nicode{~?} and @nicode{~k} are the same, @nicode{~k} is provided for
595 T-Scheme compatibility.
598 Argument jumping. Parameter: @var{N}.
600 Move forward @var{N} arguments (default 1) in the argument list. With
601 the @nicode{:} modifier move backwards. (@var{N} cannot be negative.)
604 (format #f "~d ~2*~d" 1 2 3 4) @result{} "1 4"
605 (format #f "~d ~:*~d" 6) @result{} "6 6"
608 With the @nicode{@@} modifier, move to argument number @var{N}. The
609 first argument is number 0 (and that's the default for @var{N}).
612 (format #f "~d~d again ~@@*~d~d" 1 2) @result{} "12 again 12"
613 (format #f "~d~d~d ~1@@*~d~d" 1 2 3) @result{} "123 23"
616 A @nicode{#} move to the end followed by a @nicode{:} modifier move
617 back can be used for an absolute position relative to the end of the
618 argument list, a reverse of what the @nicode{@@} modifier does.
621 (format #t "~#*~2:*~a" 'a 'b 'c 'd) @print{} c
624 At the end of the format string, the current argument postion doesn't
625 matter, any further arguments are ignored.
628 Advance to a column position. Parameters: @var{colnum}, @var{colinc},
631 Output @var{padchar} (space by default) to move to the given
632 @var{colnum} column. The start of the line is column 0, the default
633 for @var{colnum} is 1.
636 (format #f "~tX") @result{} " X"
637 (format #f "~3tX") @result{} " X"
640 If the current column is already past @var{colnum}, then the move is
641 to there plus a multiple of @var{colinc}, ie.@: column
642 @math{@var{colnum} + @var{N} * @var{colinc}} for the smallest @var{N}
643 which makes that value greater than or equal to the current column.
644 The default @var{colinc} is 1 (which means no further move).
647 (format #f "abcd~2,5,'.tx") @result{} "abcd...x"
650 With the @nicode{@@} modifier, @var{colnum} is relative to the current
651 column. @var{colnum} many padding characters are output, then further
652 padding to make the current column a multiple of @var{colinc}, if it
656 (format #f "a~3,5'*@@tx") @result{} "a****x"
659 @nicode{~t} is implemented using @code{port-column} (@pxref{Reading}),
660 so it works even there has been other output before @code{format}.
663 Tilde character. Parameter: @var{n}.
665 Output a tilde character @nicode{~}, or @var{n} many if a parameter is
666 given. Normally @nicode{~} introduces an escape sequence, @nicode{~~}
667 is the way to output a literal tilde.
670 Newline. Parameter: @var{n}.
672 Output a newline character, or @var{n} many if a parameter is given.
673 A newline (or a few newlines) can of course be output just by
674 including them in the format string.
677 Start a new line. Parameter: @var{n}.
679 Output a newline if not already at the start of a line. With a
680 parameter, output that many newlines, but with the first only if not
681 already at the start of a line. So for instance 3 would be a newline
682 if not already at the start of a line, and 2 further newlines.
685 Space character. Parameter: @var{n}.
687 @c For reference, in Common Lisp ~_ is a conditional newline, but
688 @c slib fmtdoc.txi described it as a space, so we keep that.
690 Output a space character, or @var{n} many if a parameter is given.
692 With a variable parameter this is one way to insert runtime calculated
693 padding (@nicode{~t} or the various field widths can do similar
697 (format #f "~v_foo" 4) @result{} " foo"
701 Tab character. Parameter: @var{n}.
703 Output a tab character, or @var{n} many if a parameter is given.
706 Formfeed character. Parameter: @var{n}.
708 Output a formfeed character, or @var{n} many if a parameter is given.
711 Force output. No parameters.
713 At the end of output, call @code{force-output} to flush any buffers on
714 the destination (@pxref{Writing}). @nicode{~!} can occur anywhere in
715 the format string, but the force is done at the end of output.
717 When output is to a string (destination @code{#f}), @nicode{~!} does
720 @item @nicode{~newline} (ie.@: newline character)
721 Continuation line. No parameters.
723 Skip this newline and any following whitespace in the format string,
724 don't send it to the output. With the @nicode{:} modifier the newline
725 is not output but any further following whitespace is. With the
726 @nicode{@@} modifier the newline is output but not any following
729 This escape can be used to break up a long format string into multiple
730 lines for readability, but supress that extra whitespace.
735 ~d" 1 2) @result{} "abc1 def2"
738 @item @nicode{~(} @nicode{~)}
739 Case conversion. No parameters.
741 Between @nicode{~(} and @nicode{~)} the case of all output is changed.
742 The modifiers on @nicode{~(} control the conversion.
746 no modifiers --- lower case.
748 @c FIXME: The : and @ modifiers are not yet documented because the
749 @c code applies string-capitalize and string-capitalize-first to each
750 @c separate format:out-str call, which has various subtly doubtful
751 @c effects. And worse they're applied to individual characters,
752 @c including literal characters in the format string, which has the
753 @c silly effect of being always an upcase.
755 @c The Common Lisp spec is apparently for the capitalization to be
756 @c applied in one hit to the whole of the output between ~( and ~).
757 @c (This can no doubt be implemented without accumulating all that
758 @c text, just by keeping a state or the previous char to tell whether
762 @c @nicode{:} --- first letter of each word upper case, the rest lower
763 @c case, as per the @code{string-capitalize} function (@pxref{Alphabetic
766 @c @nicode{@@} --- first letter of just the first word upper case, the
770 @nicode{:} and @nicode{@@} together --- upper case.
776 (format #t "~(Hello~)") @print{} hello
777 (format #t "~@@:(Hello~)") @print{} HELLO
780 In the future it's intended the modifiers @nicode{:} and @nicode{@@}
781 alone will capitalize the first letters of words, as per Common Lisp
782 @code{format}, but the current implementation of this is flawed and
783 not recommended for use.
785 Case conversions do not nest, currently. This might change in the
786 future, but if it does then it will be to Common Lisp style where the
787 outermost conversion has priority, overriding inner ones (making those
790 @item @nicode{~@{} @nicode{~@}}
791 Iteration. Parameter: @var{maxreps} (for @nicode{~@{}).
793 The format between @nicode{~@{} and @nicode{~@}} is iterated. The
794 modifiers to @nicode{~@{} determine how arguments are taken. The
795 default is a list argument with each iteration successively consuming
796 elements from it. This is a convenient way to output a whole list.
799 (format #t "~@{~d~@}" '(1 2 3)) @print{} 123
800 (format #t "~@{~s=~d ~@}" '("x" 1 "y" 2)) @print{} "x"=1 "y"=2
803 With the @nicode{:} modifier a list of lists argument is taken, each
804 of those lists gives the arguments for the iterated format.
807 (format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6))) @print{} 1x2 3x4 5x6
810 With the @nicode{@@} modifier, the remaining arguments are used, each
811 iteration successively consuming elements.
814 (format #t "~@@@{~d~@}" 1 2 3) @print{} 123
815 (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2
818 With both @nicode{:} and @nicode{@@} modifiers, the remaining
819 arguments are used, each is a list of arguments for the format.
822 (format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6)) @print{} 1x2 3x4 5x6
825 Iterating stops when there are no more arguments or when the
826 @var{maxreps} parameter to @nicode{~@{} is reached (default no
830 (format #t "~2@{~d~@}" '(1 2 3 4)) @print{} 12
833 If the format between @nicode{~@{} and @nicode{~@}} is empty, then a
834 format string argument is taken (before iteration argument(s)) and
835 used instead. This allows a sub-format (like @nicode{~?} above) to be
839 (format #t "~@{~@}" "~d" '(1 2 3)) @print{} 123
842 @c FIXME: What is the @nicode{:} modifier to ~} meant to do? The
843 @c Common Lisp spec says it's a minimum of 1 iteration, but the
844 @c format.scm code seems to merely make it have MAXREPS default to 1.
846 Iterations can be nested, an inner iteration operates in the same way
847 as described, but of course on the arguments the outer iteration
848 provides it. This can be used to work into nested list structures.
849 For example in the following the inner @nicode{~@{~d~@}x} is applied
850 to @code{(1 2)} then @code{(3 4 5)} etc.
853 (format #t "~@{~@{~d~@}x~@}" '((1 2) (3 4 5))) @print{} 12x345x
856 @item @nicode{~[} @nicode{~;} @nicode{~]}
857 Conditional. Parameter: @var{selector}.
859 A conditional block is delimited by @nicode{~[} and @nicode{~]}, and
860 @nicode{~;} separates clauses within the block. @nicode{~[} takes an
861 integer argument and that number clause is used. The first clause is
865 (format #f "~[peach~;banana~;mango~]" 1) @result{} "banana"
868 The @var{selector} parameter can be used for the clause number,
869 instead of taking an argument.
872 (format #f "~2[peach~;banana~;mango~]") @result{} "mango"
875 If the clause number is out of range then nothing is output. Or the
876 last @nicode{~;} can have a @nicode{:} modifier to make it the default
877 for a number out of range.
880 (format #f "~[banana~;mango~]" 99) @result{} ""
881 (format #f "~[banana~;mango~:;fruit~]" 99) @result{} "fruit"
884 The @nicode{:} modifier to @nicode{~[} treats the argument as a flag,
885 and expects two clauses. The first is used if the argument is
886 @code{#f} or the second otherwise.
889 (format #f "~:[false~;not false~]" #f) @result{} "false"
890 (format #f "~:[false~;not false~]" 'abc) @result{} "not false"
893 (format #t "~d gnu~:[s are~; is~] here" n (= 1 n)))
894 @print{} 3 gnus are here
897 The @nicode{@@} modifier to @nicode{~[} also treats the argument as a
898 flag, and expects one clause. If the argument is @code{#f} then no
899 output is produced and the argument is consumed, otherwise the clause
900 is used and the argument is not consumed by @nicode{~[}, it's left for
901 the clause. This can be used for instance to suppress output if
902 @code{#f} means something not available.
905 (format #f "~@@[temperature=~d~]" 27) @result{} "temperature=27"
906 (format #f "~@@[temperature=~d~]" #f) @result{} ""
910 Escape. Parameters: @var{val1}, @var{val2}, @var{val3}.
912 Stop formatting if there are no more arguments. This can be used for
913 instance to let a format string adapt to a variable number of
917 (format #t "~d~^ ~d" 1) @print{} 1
918 (format #t "~d~^ ~d" 1 2) @print{} 1 2
921 Within a @nicode{~@{} @nicode{~@}} iteration, @nicode{~^} stops the
922 current iteration step if there are no more arguments to that step,
923 continuing with possible further steps (for instance in the case of
924 the @nicode{:} modifier to @nicode{~@{}) and the rest of the format.
927 (format #f "~@{~d~^/~@} go" '(1 2 3)) @result{} "1/2/3 go"
928 (format #f "~:@{ ~d~^~d~@} go" '((1) (2 3))) @result{} " 1 23 go"
931 @c For reference, format.scm doesn't implement that Common Lisp ~:^
932 @c modifier which stops the entire iterating of ~:{ or ~@:{.
934 @c FIXME: Believe the Common Lisp spec is for ~^ within ~[ ~]
935 @c conditional to terminate the whole format (or iteration step if in
936 @c an iteration). But format.scm seems to terminate just the
939 @c (format #f "~[abc~^def~;ghi~] blah" 0)
940 @c @result{} "abc blah" ;; looks wrong
942 @c FIXME: Believe the Common Lisp spec is for ~^ within ~( ~) to end
943 @c that case conversion and then also terminate the whole format (or
944 @c iteration step if in an iteration). But format.scm doesn't seem
945 @c to do that quite right.
947 @c (format #f "~d ~^ ~d" 1) @result{} "1 "
948 @c (format #f "~(~d ~^ ~d~)" 1) @result{} ERROR
950 Within a @nicode{~?} sub-format, @nicode{~^} operates just on that
951 sub-format. If it terminates the sub-format then the originating
952 format will still continue.
955 (format #t "~? items" "~d~^ ~d" '(1)) @print{} 1 items
956 (format #t "~? items" "~d~^ ~d" '(1 2)) @print{} 1 2 items
959 The parameters to @nicode{~^} (which are numbers) change the condition
960 used to terminate. For a single parameter, termination is when that
961 value is zero (notice this makes plain @nicode{~^} equivalent to
962 @nicode{~#^}). For two parameters, termination is when those two are
963 equal. For three parameters, termination is when @math{@var{val1}
964 @le{} @var{val2}} and @math{@var{val2} @le{} @var{val3}}.
966 @c FIXME: Good examples of these?
969 Inquiry message. Insert a copyright message into the output. With
970 the @nicode{:} modifier insert the format implementation version.
974 It's an error if there are not enough arguments for the escapes in the
975 format string, but any excess arguments are ignored.
977 Iterations @nicode{~@{} @nicode{~@}} and conditionals @nicode{~[}
978 @nicode{~;} @nicode{~]} can be nested, but must be properly nested,
979 meaning the inner form must be entirely within the outer form. So
980 it's not possible, for instance, to try to conditionalize the endpoint
984 (format #t "~@{ ~[ ... ~] ~@}" ...) ;; good
985 (format #t "~@{ ~[ ... ~@} ... ~]" ...) ;; bad
988 The same applies to case conversions @nicode{~(} @nicode{~)}, they
989 must properly nest with respect to iterations and conditionals (though
990 currently a case conversion cannot nest within another case
993 When a sub-format (@nicode{~?}) is used, that sub-format string must
994 be self-contained. It cannot for instance give a @nicode{~@{} to
995 begin an iteration form and have the @nicode{~@}} up in the
996 originating format, or similar.
1000 Guile contains a @code{format} procedure even when the module
1001 @code{(ice-9 format)} is not loaded. The default @code{format} is
1002 @code{simple-format} (@pxref{Writing}), it doesn't support all escape
1003 sequences documented in this section, and will signal an error if you
1004 try to use one of them. The reason for two versions is that the full
1005 @code{format} is fairly large and requires some time to load.
1006 @code{simple-format} is often adequate too.
1011 @section The Rx Regular Expression Library
1013 [FIXME: this is taken from Gary and Mark's quick summaries and should be
1014 reviewed and expanded. Rx is pretty stable, so could already be done!]
1017 @cindex finite automaton
1019 The @file{guile-lang-allover} package provides an interface to Tom
1020 Lord's Rx library (currently only to POSIX regular expressions). Use of
1021 the library requires a two step process: compile a regular expression
1022 into an efficient structure, then use the structure in any number of
1025 For example, given the regular expression @samp{abc.} (which matches any
1026 string containing @samp{abc} followed by any single character):
1029 guile> @kbd{(define r (regcomp "abc."))}
1032 guile> @kbd{(regexec r "abc")}
1034 guile> @kbd{(regexec r "abcd")}
1039 The definitions of @code{regcomp} and @code{regexec} are as follows:
1041 @deffn {Scheme Procedure} regcomp pattern [flags]
1042 Compile the regular expression pattern using POSIX rules. Flags is
1043 optional and should be specified using symbolic names:
1044 @defvar REG_EXTENDED
1045 use extended POSIX syntax
1048 use case-insensitive matching
1051 allow anchors to match after newline characters in the
1052 string and prevents @code{.} or @code{[^...]} from matching newlines.
1055 The @code{logior} procedure can be used to combine multiple flags.
1056 The default is to use
1057 POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+}
1059 operators. Backslashes in @var{pattern} must be escaped if specified in a
1060 literal string e.g., @code{"\\(a\\)\\?"}.
1063 @deffn {Scheme Procedure} regexec regex string [match-pick] [flags]
1064 Match @var{string} against the compiled POSIX regular expression
1066 @var{match-pick} and @var{flags} are optional. Possible flags (which can be
1067 combined using the logior procedure) are:
1070 The beginning of line operator won't match the beginning of
1071 @var{string} (presumably because it's not the beginning of a line)
1075 Similar to REG_NOTBOL, but prevents the end of line operator
1076 from matching the end of @var{string}.
1079 If no match is possible, regexec returns #f. Otherwise @var{match-pick}
1080 determines the return value:
1082 @code{#t} or unspecified: a newly-allocated vector is returned,
1083 containing pairs with the indices of the matched part of @var{string} and any
1086 @code{""}: a list is returned: the first element contains a nested list
1087 with the matched part of @var{string} surrounded by the the unmatched parts.
1088 Remaining elements are matched substrings (if any). All returned
1089 substrings share memory with @var{string}.
1091 @code{#f}: regexec returns #t if a match is made, otherwise #f.
1093 vector: the supplied vector is returned, with the first element replaced
1094 by a pair containing the indices of the matched portion of @var{string} and
1095 further elements replaced by pairs containing the indices of matched
1096 substrings (if any).
1098 list: a list will be returned, with each member of the list
1099 specified by a code in the corresponding position of the supplied list:
1101 a number: the numbered matching substring (0 for the entire match).
1103 @code{#\<}: the beginning of @var{string} to the beginning of the part matched
1106 @code{#\>}: the end of the matched part of @var{string} to the end of
1109 @code{#\c}: the "final tag", which seems to be associated with the "cut
1110 operator", which doesn't seem to be available through the posix
1113 e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
1117 Here are some other procedures that might be used when using regular
1120 @deffn {Scheme Procedure} compiled-regexp? obj
1121 Test whether obj is a compiled regular expression.
1124 @deffn {Scheme Procedure} regexp->dfa regex [flags]
1127 @deffn {Scheme Procedure} dfa-fork dfa
1130 @deffn {Scheme Procedure} reset-dfa! dfa
1133 @deffn {Scheme Procedure} dfa-final-tag dfa
1136 @deffn {Scheme Procedure} dfa-continuable? dfa
1139 @deffn {Scheme Procedure} advance-dfa! dfa string
1143 @node File Tree Walk
1144 @section File Tree Walk
1145 @cindex file tree walk
1147 The functions in this section traverse a tree of files and
1148 directories, in a fashion similar to the C @code{ftw} and @code{nftw}
1149 routines (@pxref{Working with Directory Trees,,, libc, GNU C Library
1153 (use-modules (ice-9 ftw))
1157 @defun ftw startname proc ['hash-size n]
1158 Walk the filesystem tree descending from @var{startname}, calling
1159 @var{proc} for each file and directory.
1161 Hard links and symbolic links are followed. A file or directory is
1162 reported to @var{proc} only once, and skipped if seen again in another
1163 place. One consequence of this is that @code{ftw} is safe against
1164 circularly linked directory structures.
1166 Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and
1167 it should return @code{#t} to continue, or any other value to stop.
1169 @var{filename} is the item visited, being @var{startname} plus a
1170 further path and the name of the item. @var{statinfo} is the return
1171 from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag}
1172 is one of the following symbols,
1176 @var{filename} is a file, this includes special files like devices,
1180 @var{filename} is a directory.
1183 An error occurred when calling @code{stat}, so nothing is known.
1184 @var{statinfo} is @code{#f} in this case.
1186 @item directory-not-readable
1187 @var{filename} is a directory, but one which cannot be read and hence
1188 won't be recursed into.
1191 @var{filename} is a dangling symbolic link. Symbolic links are
1192 normally followed and their target reported, the link itself is
1193 reported if the target does not exist.
1196 The return value from @code{ftw} is @code{#t} if it ran to completion,
1197 or otherwise the non-@code{#t} value from @var{proc} which caused the
1200 Optional argument symbol @code{hash-size} and an integer can be given
1201 to set the size of the hash table used to track items already visited.
1202 (@pxref{Hash Table Reference})
1204 @c Actually, it's probably safe to escape from ftw, just need to
1207 In the current implementation, returning non-@code{#t} from @var{proc}
1208 is the only valid way to terminate @code{ftw}. @var{proc} must not
1209 use @code{throw} or similar to escape.
1213 @defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
1214 Walk the filesystem tree starting at @var{startname}, calling
1215 @var{proc} for each file and directory. @code{nftw} has extra
1216 features over the basic @code{ftw} described above.
1218 Hard links and symbolic links are followed, but a file or directory is
1219 reported to @var{proc} only once, and skipped if seen again in another
1220 place. One consequence of this is that @code{nftw} is safe against
1221 circular linked directory structures.
1223 Each @var{proc} call is @code{(@var{proc} filename statinfo flag
1224 basename level)} and it should return @code{#t} to continue, or any
1225 other value to stop.
1227 @var{filename} is the item visited, being @var{startname} plus a
1228 further path and the name of the item. @var{statinfo} is the return
1229 from @code{stat} on @var{filename} (@pxref{File System}).
1230 @var{basename} it the item name without any path. @var{level} is an
1231 integer giving the directory nesting level, starting from 0 for the
1232 contents of @var{startname} (or that item itself if it's a file).
1233 @var{flag} is one of the following symbols,
1237 @var{filename} is a file, this includes special files like devices,
1241 @var{filename} is a directory.
1243 @item directory-processed
1244 @var{filename} is a directory, and its contents have all been visited.
1245 This flag is given instead of @code{directory} when the @code{depth}
1246 option below is used.
1249 An error occurred when applying @code{stat} to @var{filename}, so
1250 nothing is known about it. @var{statinfo} is @code{#f} in this case.
1252 @item directory-not-readable
1253 @var{filename} is a directory, but one which cannot be read and hence
1254 won't be recursed into.
1257 @var{filename} is a dangling symbolic link. Symbolic links are
1258 normally followed and their target reported, the link itself is
1259 reported if the target does not exist.
1261 Under the @code{physical} option described below, @code{symlink} is
1262 instead given for symbolic links whose target does exist.
1265 Under the @code{physical} option described below, this indicates
1266 @var{filename} is a dangling symbolic link, meaning its target does
1267 not exist. Without the @code{physical} option plain @code{symlink}
1271 The following optional arguments can be given to modify the way
1272 @code{nftw} works. Each is passed as a symbol (and @code{hash-size}
1273 takes a following integer value).
1277 Change to the directory containing the item before calling @var{proc}.
1278 When @code{nftw} returns the original current directory is restored.
1280 Under this option, generally the @var{basename} parameter should be
1281 used to access the item in each @var{proc} call. The @var{filename}
1282 parameter still has a path as normal and this will only be valid if
1283 the @var{startname} directory was absolute.
1286 Visit files ``depth first'', meaning @var{proc} is called for the
1287 contents of each directory before it's called for the directory
1288 itself. Normally a directory is reported first, then its contents.
1290 Under this option, the @var{flag} to @var{proc} for a directory is
1291 @code{directory-processed} instead of @code{directory}.
1293 @item @code{hash-size @var{n}}
1294 Set the size of the hash table used to track items already visited.
1295 (@pxref{Hash Table Reference})
1298 Don't cross a mount point, meaning only visit items on the same
1299 filesystem as @var{startname}. (Ie.@: the same @code{stat:dev}.)
1301 @item @code{physical}
1302 Don't follow symbolic links, instead report them to @var{proc} as
1303 @code{symlink}, and report dangling links as @code{stale-symlink}.
1306 The return value from @code{nftw} is @code{#t} if it ran to
1307 completion, or otherwise the non-@code{#t} value from @var{proc} which
1310 @c For reference, one reason not to esacpe is that the current
1311 @c directory is not saved and restored with dynamic-wind. Maybe
1312 @c changing that would be enough to allow escaping.
1314 In the current implementation, returning non-@code{#t} from @var{proc}
1315 is the only valid way to terminate @code{ftw}. @var{proc} must not
1316 use @code{throw} or similar to escape.
1326 The functions in this section are provided by
1329 (use-modules (ice-9 q))
1332 This module implements queues holding arbitrary scheme objects and
1333 designed for efficient first-in / first-out operations.
1335 @code{make-q} creates a queue, and objects are entered and removed
1336 with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!}
1337 can be used too, treating the front of the queue like a stack.
1341 @deffn {Scheme Procedure} make-q
1345 @deffn {Scheme Procedure} q? obj
1346 Return @code{#t} if @var{obj} is a queue, or @code{#f} if not.
1348 Note that queues are not a distinct class of objects but are
1349 implemented with cons cells. For that reason certain list structures
1350 can get @code{#t} from @code{q?}.
1353 @deffn {Scheme Procedure} enq! q obj
1354 Add @var{obj} to the rear of @var{q}, and return @var{q}.
1357 @deffn {Scheme Procedure} deq! q
1358 @deffnx {Scheme Procedure} q-pop! q
1359 Remove and return the front element from @var{q}. If @var{q} is
1360 empty, a @code{q-empty} exception is thrown.
1362 @code{deq!} and @code{q-pop!} are the same operation, the two names
1363 just let an application match @code{enq!} with @code{deq!}, or
1364 @code{q-push!} with @code{q-pop!}.
1367 @deffn {Scheme Procedure} q-push! q obj
1368 Add @var{obj} to the front of @var{q}, and return @var{q}.
1371 @deffn {Scheme Procedure} q-length q
1372 Return the number of elements in @var{q}.
1375 @deffn {Scheme Procedure} q-empty? q
1376 Return true if @var{q} is empty.
1379 @deffn {Scheme Procedure} q-empty-check q
1380 Throw a @code{q-empty} exception if @var{q} is empty.
1383 @deffn {Scheme Procedure} q-front q
1384 Return the first element of @var{q} (without removing it). If @var{q}
1385 is empty, a @code{q-empty} exception is thrown.
1388 @deffn {Scheme Procedure} q-rear q
1389 Return the last element of @var{q} (without removing it). If @var{q}
1390 is empty, a @code{q-empty} exception is thrown.
1393 @deffn {Scheme Procedure} q-remove! q obj
1394 Remove all occurences of @var{obj} from @var{q}, and return @var{q}.
1395 @var{obj} is compared to queue elements using @code{eq?}.
1399 @cindex @code{q-empty}
1400 The @code{q-empty} exceptions described above are thrown just as
1401 @code{(throw 'q-empty)}, there's no message etc like an error throw.
1403 A queue is implemented as a cons cell, the @code{car} containing a
1404 list of queued elements, and the @code{cdr} being the last cell in
1405 that list (for ease of enqueuing).
1408 (@var{list} . @var{last-cell})
1412 If the queue is empty, @var{list} is the empty list and
1413 @var{last-cell} is @code{#f}.
1415 An application can directly access the queue list if desired, for
1416 instance to search the elements or to insert at a specific point.
1418 @deffn {Scheme Procedure} sync-q! q
1419 Recompute the @var{last-cell} field in @var{q}.
1421 All the operations above maintain @var{last-cell} as described, so
1422 normally there's no need for @code{sync-q!}. But if an application
1423 modifies the queue @var{list} then it must either maintain
1424 @var{last-cell} similarly, or call @code{sync-q!} to recompute it.
1432 A stream represents a sequence of values, each of which is calculated
1433 only when required. This allows large or even infinite sequences to
1434 be represented and manipulated with familiar operations like ``car'',
1435 ``cdr'', ``map'' or ``fold''. In such manipulations only as much as
1436 needed is actually held in memory at any one time. The functions in
1437 this section are available from
1440 (use-modules (ice-9 streams))
1443 Streams are implemented using promises (@pxref{Delayed Evaluation}),
1444 which is how the underlying calculation of values is made only when
1445 needed, and the values then retained so the calculation is not
1449 Here is a simple example producing a stream of all odd numbers,
1452 (define odds (make-stream (lambda (state)
1453 (cons state (+ state 2)))
1455 (stream-car odds) @result{} 1
1456 (stream-car (stream-cdr odds)) @result{} 3
1460 @code{stream-map} could be used to derive a stream of odd squares,
1463 (define (square n) (* n n))
1464 (define oddsquares (stream-map square odds))
1467 These are infinite sequences, so it's not possible to convert them to
1468 a list, but they could be printed (infinitely) with for example
1471 (stream-for-each (lambda (n sq)
1472 (format #t "~a squared is ~a\n" n sq))
1483 @defun make-stream proc initial-state
1484 Return a new stream, formed by calling @var{proc} successively.
1486 Each call is @code{(@var{proc} @var{state})}, it should return a pair,
1487 the @code{car} being the value for the stream, and the @code{cdr}
1488 being the new @var{state} for the next call. For the first call
1489 @var{state} is the given @var{initial-state}. At the end of the
1490 stream, @var{proc} should return some non-pair object.
1493 @defun stream-car stream
1494 Return the first element from @var{stream}. @var{stream} must not be
1498 @defun stream-cdr stream
1499 Return a stream which is the second and subsequent elements of
1500 @var{stream}. @var{stream} must not be empty.
1503 @defun stream-null? stream
1504 Return true if @var{stream} is empty.
1507 @defun list->stream list
1508 @defunx vector->stream vector
1509 Return a stream with the contents of @var{list} or @var{vector}.
1511 @var{list} or @var{vector} should not be modified subsequently, since
1512 it's unspecified whether changes there will be reflected in the stream
1516 @defun port->stream port readproc
1517 Return a stream which is the values obtained by reading from
1518 @var{port} using @var{readproc}. Each read call is
1519 @code{(@var{readproc} @var{port})}, and it should return an EOF object
1520 (@pxref{Reading}) at the end of input.
1522 For example a stream of characters from a file,
1525 (port->stream (open-input-file "/foo/bar.txt") read-char)
1529 @defun stream->list stream
1530 Return a list which is the entire contents of @var{stream}.
1533 @defun stream->reversed-list stream
1534 Return a list which is the entire contents of @var{stream}, but in
1538 @defun stream->list&length stream
1539 Return two values (@pxref{Multiple Values}) being a list which is the
1540 entire contents of @var{stream}, and the number of elements in that
1544 @defun stream->reversed-list&length stream
1545 Return two values (@pxref{Multiple Values}) being a list which is the
1546 entire contents of @var{stream}, but in reverse order, and the number
1547 of elements in that list.
1550 @defun stream->vector stream
1551 Return a vector which is the entire contents of @var{stream}.
1554 @defun stream-fold proc init stream0 @dots{} streamN
1555 Apply @var{proc} successively over the elements of the given streams,
1556 from first to last until the end of the shortest stream is reached.
1557 Return the result from the last @var{proc} call.
1559 Each call is @code{(@var{proc} elem0 @dots{} elemN prev)}, where each
1560 @var{elem} is from the corresponding @var{stream}. @var{prev} is the
1561 return from the previous @var{proc} call, or the given @var{init} for
1565 @defun stream-for-each proc stream0 @dots{} streamN
1566 Call @var{proc} on the elements from the given @var{stream}s. The
1567 return value is unspecified.
1569 Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
1570 @var{elem} is from the corresponding @var{stream}.
1571 @code{stream-for-each} stops when it reaches the end of the shortest
1575 @defun stream-map proc stream0 @dots{} streamN
1576 Return a new stream which is the results of applying @var{proc} to the
1577 elements of the given @var{stream}s.
1579 Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
1580 @var{elem} is from the corresponding @var{stream}. The new stream
1581 ends when the end of teh shortest given @var{stream} is reached.
1586 @c TeX-master: "guile.texi"