2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2010, 2011, 2012, 2013,
4 @c 2014 Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
11 @xref{R6RS Libraries}, for more information on how to define R6RS libraries, and
12 their integration with Guile modules.
15 * R6RS Incompatibilities:: Guile mostly implements R6RS.
16 * R6RS Standard Libraries:: Modules defined by the R6RS.
19 @node R6RS Incompatibilities
20 @subsection Incompatibilities with the R6RS
22 There are some incompatibilities between Guile and the R6RS. Some of
23 them are intentional, some of them are bugs, and some are simply
24 unimplemented features. Please let the Guile developers know if you
25 find one that is not on this list.
29 The R6RS specifies many situations in which a conforming implementation
30 must signal a specific error. Guile doesn't really care about that too
31 much---if a correct R6RS program would not hit that error, we don't
32 bother checking for it.
35 Multiple @code{library} forms in one file are not yet supported. This
36 is because the expansion of @code{library} sets the current module, but
37 does not restore it. This is a bug.
40 R6RS unicode escapes within strings are disabled by default, because
41 they conflict with Guile's already-existing escapes. The same is the
42 case for R6RS treatment of escaped newlines in strings.
44 R6RS behavior can be turned on via a reader option. @xref{String
45 Syntax}, for more information.
48 A @code{set!} to a variable transformer may only expand to an
49 expression, not a definition---even if the original @code{set!}
50 expression was in definition context.
53 Instead of using the algorithm detailed in chapter 10 of the R6RS,
54 expansion of toplevel forms happens sequentially.
56 For example, while the expansion of the following set of toplevel
57 definitions does the correct thing:
63 (or (= x 0) (odd? (- x 1)))))
66 ((odd? x) (not (even? x)))))
72 The same definitions outside of the @code{begin} wrapper do not:
77 (or (= x 0) (odd? (- x 1)))))
80 ((odd? x) (not (even? x)))))
82 <unnamed port>:4:18: In procedure even?:
83 <unnamed port>:4:18: Wrong type to apply: #<syntax-transformer odd?>
86 This is because when expanding the right-hand-side of @code{even?}, the
87 reference to @code{odd?} is not yet marked as a syntax transformer, so
88 it is assumed to be a function.
90 This bug will only affect top-level programs, not code in @code{library}
91 forms. Fixing it for toplevel forms seems doable, but tricky to
92 implement in a backward-compatible way. Suggestions and/or patches would
96 The @code{(rnrs io ports)} module is incomplete. Work is
100 Guile does not prevent use of textual I/O procedures on binary ports.
101 More generally, it does not make a sharp distinction between binary and
102 textual ports (@pxref{R6RS Port Manipulation, binary-port?}).
105 Guile's implementation of @code{equal?} may fail to terminate when
106 applied to arguments containing cycles.
109 @node R6RS Standard Libraries
110 @subsection R6RS Standard Libraries
112 In contrast with earlier versions of the Revised Report, the R6RS
113 organizes the procedures and syntactic forms required of conforming
114 implementations into a set of ``standard libraries'' which can be
115 imported as necessary by user programs and libraries. Here we briefly
116 list the libraries that have been implemented for Guile.
118 We do not attempt to document these libraries fully here, as most of
119 their functionality is already available in Guile itself. The
120 expectation is that most Guile users will use the well-known and
121 well-documented Guile modules. These R6RS libraries are mostly useful
122 to users who want to port their code to other R6RS systems.
124 The documentation in the following sections reproduces some of the
125 content of the library section of the Report, but is mostly intended to
126 provide supplementary information about Guile's implementation of the
127 R6RS standard libraries. For complete documentation, design rationales
128 and further examples, we advise you to consult the ``Standard
129 Libraries'' section of the Report (@pxref{Standard Libraries,
130 R6RS Standard Libraries,, r6rs, The Revised^6 Report on the Algorithmic
134 * Library Usage:: What to know about Guile's library support.
135 * rnrs base:: The base library.
136 * rnrs unicode:: Access to Unicode operations.
137 * rnrs bytevectors:: Functions for working with binary data.
138 * rnrs lists:: List utilities.
139 * rnrs sorting:: Sorting for lists and vectors.
140 * rnrs control:: Additional control structures.
142 * R6RS Records:: A note about R6RS records.
143 * rnrs records syntactic:: Syntactic API for R6RS records.
144 * rnrs records procedural:: Procedural API for R6RS records.
145 * rnrs records inspection:: Reflection on R6RS records.
147 * rnrs exceptions:: Handling exceptional situations.
148 * rnrs conditions:: Data structures for exceptions.
150 * I/O Conditions:: Predefined I/O error types.
151 * rnrs io ports:: Support for port-based I/O.
152 * rnrs io simple:: High-level I/O API.
154 * rnrs files:: Functions for working with files.
155 * rnrs programs:: Functions for working with processes.
156 * rnrs arithmetic fixnums:: Fixed-precision arithmetic operations.
157 * rnrs arithmetic flonums:: Floating-point arithmetic operations.
158 * rnrs arithmetic bitwise:: Exact bitwise arithmetic operations.
159 * rnrs syntax-case:: Support for `syntax-case' macros.
160 * rnrs hashtables:: Hashtables.
161 * rnrs enums:: Enumerations.
162 * rnrs:: The composite library.
163 * rnrs eval:: Support for on-the-fly evaluation.
164 * rnrs mutable-pairs:: Support for mutable pairs.
165 * rnrs mutable-strings:: Support for mutable strings.
166 * rnrs r5rs:: Compatibility layer for R5RS Scheme.
171 @subsubsection Library Usage
173 Guile implements the R6RS `library' form as a transformation to a native
174 Guile module definition. As a consequence of this, all of the libraries
175 described in the following subsections, in addition to being available
176 for use by R6RS libraries and top-level programs, can also be imported
177 as if they were normal Guile modules---via a @code{use-modules} form,
178 say. For example, the R6RS ``composite'' library can be imported by:
185 (use-modules ((rnrs) :version (6)))
188 For more information on Guile's library implementation, see
189 (@pxref{R6RS Libraries}).
192 @subsubsection rnrs base
194 The @code{(rnrs base (6))} library exports the procedures and syntactic
195 forms described in the main section of the Report
196 (@pxref{Base library, R6RS Base library,, r6rs,
197 The Revised^6 Report on the Algorithmic Language Scheme}). They are
198 grouped below by the existing manual sections to which they correspond.
200 @deffn {Scheme Procedure} boolean? obj
201 @deffnx {Scheme Procedure} not x
202 @xref{Booleans}, for documentation.
205 @deffn {Scheme Procedure} symbol? obj
206 @deffnx {Scheme Procedure} symbol->string sym
207 @deffnx {Scheme Procedure} string->symbol str
208 @xref{Symbol Primitives}, for documentation.
211 @deffn {Scheme Procedure} char? obj
212 @deffnx {Scheme Procedure} char=?
213 @deffnx {Scheme Procedure} char<?
214 @deffnx {Scheme Procedure} char>?
215 @deffnx {Scheme Procedure} char<=?
216 @deffnx {Scheme Procedure} char>=?
217 @deffnx {Scheme Procedure} integer->char n
218 @deffnx {Scheme Procedure} char->integer chr
219 @xref{Characters}, for documentation.
222 @deffn {Scheme Procedure} list? x
223 @deffnx {Scheme Procedure} null? x
224 @xref{List Predicates}, for documentation.
227 @deffn {Scheme Procedure} pair? x
228 @deffnx {Scheme Procedure} cons x y
229 @deffnx {Scheme Procedure} car pair
230 @deffnx {Scheme Procedure} cdr pair
231 @deffnx {Scheme Procedure} caar pair
232 @deffnx {Scheme Procedure} cadr pair
233 @deffnx {Scheme Procedure} cdar pair
234 @deffnx {Scheme Procedure} cddr pair
235 @deffnx {Scheme Procedure} caaar pair
236 @deffnx {Scheme Procedure} caadr pair
237 @deffnx {Scheme Procedure} cadar pair
238 @deffnx {Scheme Procedure} cdaar pair
239 @deffnx {Scheme Procedure} caddr pair
240 @deffnx {Scheme Procedure} cdadr pair
241 @deffnx {Scheme Procedure} cddar pair
242 @deffnx {Scheme Procedure} cdddr pair
243 @deffnx {Scheme Procedure} caaaar pair
244 @deffnx {Scheme Procedure} caaadr pair
245 @deffnx {Scheme Procedure} caadar pair
246 @deffnx {Scheme Procedure} cadaar pair
247 @deffnx {Scheme Procedure} cdaaar pair
248 @deffnx {Scheme Procedure} cddaar pair
249 @deffnx {Scheme Procedure} cdadar pair
250 @deffnx {Scheme Procedure} cdaadr pair
251 @deffnx {Scheme Procedure} cadadr pair
252 @deffnx {Scheme Procedure} caaddr pair
253 @deffnx {Scheme Procedure} caddar pair
254 @deffnx {Scheme Procedure} cadddr pair
255 @deffnx {Scheme Procedure} cdaddr pair
256 @deffnx {Scheme Procedure} cddadr pair
257 @deffnx {Scheme Procedure} cdddar pair
258 @deffnx {Scheme Procedure} cddddr pair
259 @xref{Pairs}, for documentation.
262 @deffn {Scheme Procedure} number? obj
263 @xref{Numerical Tower}, for documentation.
266 @deffn {Scheme Procedure} string? obj
267 @xref{String Predicates}, for documentation.
270 @deffn {Scheme Procedure} procedure? obj
271 @xref{Procedure Properties}, for documentation.
274 @deffn {Scheme Syntax} define name value
275 @deffnx {Scheme Syntax} set! variable-name value
276 @xref{Definition}, for documentation.
279 @deffn {Scheme Syntax} define-syntax keyword expression
280 @deffnx {Scheme Syntax} let-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
281 @deffnx {Scheme Syntax} letrec-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
282 @xref{Defining Macros}, for documentation.
285 @deffn {Scheme Syntax} identifier-syntax exp
286 @xref{Identifier Macros}, for documentation.
289 @deffn {Scheme Syntax} syntax-rules literals (pattern template) ...
290 @xref{Syntax Rules}, for documentation.
293 @deffn {Scheme Syntax} lambda formals body
294 @xref{Lambda}, for documentation.
297 @deffn {Scheme Syntax} let bindings body
298 @deffnx {Scheme Syntax} let* bindings body
299 @deffnx {Scheme Syntax} letrec bindings body
300 @deffnx {Scheme Syntax} letrec* bindings body
301 @xref{Local Bindings}, for documentation.
304 @deffn {Scheme Syntax} let-values bindings body
305 @deffnx {Scheme Syntax} let*-values bindings body
306 @xref{SRFI-11}, for documentation.
309 @deffn {Scheme Syntax} begin expr1 expr2 ...
310 @xref{begin}, for documentation.
313 @deffn {Scheme Syntax} quote expr
314 @deffnx {Scheme Syntax} quasiquote expr
315 @deffnx {Scheme Syntax} unquote expr
316 @deffnx {Scheme Syntax} unquote-splicing expr
317 @xref{Expression Syntax}, for documentation.
320 @deffn {Scheme Syntax} if test consequence [alternate]
321 @deffnx {Scheme Syntax} cond clause1 clause2 ...
322 @deffnx {Scheme Syntax} case key clause1 clause2 ...
323 @xref{Conditionals}, for documentation.
326 @deffn {Scheme Syntax} and expr ...
327 @deffnx {Scheme Syntax} or expr ...
328 @xref{and or}, for documentation.
331 @deffn {Scheme Procedure} eq? x y
332 @deffnx {Scheme Procedure} eqv? x y
333 @deffnx {Scheme Procedure} equal? x y
334 @deffnx {Scheme Procedure} symbol=? symbol1 symbol2 ...
335 @xref{Equality}, for documentation.
337 @code{symbol=?} is identical to @code{eq?}.
340 @deffn {Scheme Procedure} complex? z
341 @xref{Complex Numbers}, for documentation.
344 @deffn {Scheme Procedure} real-part z
345 @deffnx {Scheme Procedure} imag-part z
346 @deffnx {Scheme Procedure} make-rectangular real_part imaginary_part
347 @deffnx {Scheme Procedure} make-polar x y
348 @deffnx {Scheme Procedure} magnitude z
349 @deffnx {Scheme Procedure} angle z
350 @xref{Complex}, for documentation.
353 @deffn {Scheme Procedure} sqrt z
354 @deffnx {Scheme Procedure} exp z
355 @deffnx {Scheme Procedure} expt z1 z2
356 @deffnx {Scheme Procedure} log z
357 @deffnx {Scheme Procedure} sin z
358 @deffnx {Scheme Procedure} cos z
359 @deffnx {Scheme Procedure} tan z
360 @deffnx {Scheme Procedure} asin z
361 @deffnx {Scheme Procedure} acos z
362 @deffnx {Scheme Procedure} atan z
363 @xref{Scientific}, for documentation.
366 @deffn {Scheme Procedure} real? x
367 @deffnx {Scheme Procedure} rational? x
368 @deffnx {Scheme Procedure} numerator x
369 @deffnx {Scheme Procedure} denominator x
370 @deffnx {Scheme Procedure} rationalize x eps
371 @xref{Reals and Rationals}, for documentation.
374 @deffn {Scheme Procedure} exact? x
375 @deffnx {Scheme Procedure} inexact? x
376 @deffnx {Scheme Procedure} exact z
377 @deffnx {Scheme Procedure} inexact z
378 @xref{Exactness}, for documentation. The @code{exact} and
379 @code{inexact} procedures are identical to the @code{inexact->exact} and
380 @code{exact->inexact} procedures provided by Guile's code library.
383 @deffn {Scheme Procedure} integer? x
384 @xref{Integers}, for documentation.
387 @deffn {Scheme Procedure} odd? n
388 @deffnx {Scheme Procedure} even? n
389 @deffnx {Scheme Procedure} gcd x ...
390 @deffnx {Scheme Procedure} lcm x ...
391 @deffnx {Scheme Procedure} exact-integer-sqrt k
392 @xref{Integer Operations}, for documentation.
395 @deffn {Scheme Procedure} =
396 @deffnx {Scheme Procedure} <
397 @deffnx {Scheme Procedure} >
398 @deffnx {Scheme Procedure} <=
399 @deffnx {Scheme Procedure} >=
400 @deffnx {Scheme Procedure} zero? x
401 @deffnx {Scheme Procedure} positive? x
402 @deffnx {Scheme Procedure} negative? x
403 @xref{Comparison}, for documentation.
406 @deffn {Scheme Procedure} for-each f lst1 lst2 ...
407 @xref{SRFI-1 Fold and Map}, for documentation.
410 @deffn {Scheme Procedure} list elem @dots{}
411 @xref{List Constructors}, for documentation.
414 @deffn {Scheme Procedure} length lst
415 @deffnx {Scheme Procedure} list-ref lst k
416 @deffnx {Scheme Procedure} list-tail lst k
417 @xref{List Selection}, for documentation.
420 @deffn {Scheme Procedure} append lst @dots{} obj
421 @deffnx {Scheme Procedure} append
422 @deffnx {Scheme Procedure} reverse lst
423 @xref{Append/Reverse}, for documentation.
426 @deffn {Scheme Procedure} number->string n [radix]
427 @deffnx {Scheme Procedure} string->number str [radix]
428 @xref{Conversion}, for documentation.
431 @deffn {Scheme Procedure} string char ...
432 @deffnx {Scheme Procedure} make-string k [chr]
433 @deffnx {Scheme Procedure} list->string lst
434 @xref{String Constructors}, for documentation.
437 @deffn {Scheme Procedure} string->list str [start [end]]
438 @xref{List/String Conversion}, for documentation.
441 @deffn {Scheme Procedure} string-length str
442 @deffnx {Scheme Procedure} string-ref str k
443 @deffnx {Scheme Procedure} string-copy str [start [end]]
444 @deffnx {Scheme Procedure} substring str start [end]
445 @xref{String Selection}, for documentation.
448 @deffn {Scheme Procedure} string=? s1 s2 s3 @dots{}
449 @deffnx {Scheme Procedure} string<? s1 s2 s3 @dots{}
450 @deffnx {Scheme Procedure} string>? s1 s2 s3 @dots{}
451 @deffnx {Scheme Procedure} string<=? s1 s2 s3 @dots{}
452 @deffnx {Scheme Procedure} string>=? s1 s2 s3 @dots{}
453 @xref{String Comparison}, for documentation.
456 @deffn {Scheme Procedure} string-append arg @dots{}
457 @xref{Reversing and Appending Strings}, for documentation.
460 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
461 @xref{Mapping Folding and Unfolding}, for documentation.
464 @deffn {Scheme Procedure} + z1 ...
465 @deffnx {Scheme Procedure} - z1 z2 ...
466 @deffnx {Scheme Procedure} * z1 ...
467 @deffnx {Scheme Procedure} / z1 z2 ...
468 @deffnx {Scheme Procedure} max x1 x2 ...
469 @deffnx {Scheme Procedure} min x1 x2 ...
470 @deffnx {Scheme Procedure} abs x
471 @deffnx {Scheme Procedure} truncate x
472 @deffnx {Scheme Procedure} floor x
473 @deffnx {Scheme Procedure} ceiling x
474 @deffnx {Scheme Procedure} round x
475 @xref{Arithmetic}, for documentation.
481 @deffn {Scheme Procedure} div x y
482 @deffnx {Scheme Procedure} mod x y
483 @deffnx {Scheme Procedure} div-and-mod x y
484 These procedures accept two real numbers @var{x} and @var{y}, where the
485 divisor @var{y} must be non-zero. @code{div} returns the integer @var{q}
486 and @code{mod} returns the real number @var{r} such that
487 @math{@var{x} = @var{q}*@var{y} + @var{r}} and @math{0 <= @var{r} < abs(@var{y})}.
488 @code{div-and-mod} returns both @var{q} and @var{r}, and is more
489 efficient than computing each separately. Note that when @math{@var{y} > 0},
490 @code{div} returns @math{floor(@var{x}/@var{y})}, otherwise
491 it returns @math{ceiling(@var{x}/@var{y})}.
494 (div 123 10) @result{} 12
495 (mod 123 10) @result{} 3
496 (div-and-mod 123 10) @result{} 12 and 3
497 (div-and-mod 123 -10) @result{} -12 and 3
498 (div-and-mod -123 10) @result{} -13 and 7
499 (div-and-mod -123 -10) @result{} 13 and 7
500 (div-and-mod -123.2 -63.5) @result{} 2.0 and 3.8
501 (div-and-mod 16/3 -10/7) @result{} -3 and 22/21
507 @rnindex div0-and-mod0
508 @deffn {Scheme Procedure} div0 x y
509 @deffnx {Scheme Procedure} mod0 x y
510 @deffnx {Scheme Procedure} div0-and-mod0 x y
511 These procedures accept two real numbers @var{x} and @var{y}, where the
512 divisor @var{y} must be non-zero. @code{div0} returns the
513 integer @var{q} and @code{mod0} returns the real number
514 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
515 @math{-abs(@var{y}/2) <= @var{r} < abs(@var{y}/2)}. @code{div0-and-mod0}
516 returns both @var{q} and @var{r}, and is more efficient than computing
519 Note that @code{div0} returns @math{@var{x}/@var{y}} rounded to the
520 nearest integer. When @math{@var{x}/@var{y}} lies exactly half-way
521 between two integers, the tie is broken according to the sign of
522 @var{y}. If @math{@var{y} > 0}, ties are rounded toward positive
523 infinity, otherwise they are rounded toward negative infinity.
524 This is a consequence of the requirement that
525 @math{-abs(@var{y}/2) <= @var{r} < abs(@var{y}/2)}.
528 (div0 123 10) @result{} 12
529 (mod0 123 10) @result{} 3
530 (div0-and-mod0 123 10) @result{} 12 and 3
531 (div0-and-mod0 123 -10) @result{} -12 and 3
532 (div0-and-mod0 -123 10) @result{} -12 and -3
533 (div0-and-mod0 -123 -10) @result{} 12 and -3
534 (div0-and-mod0 -123.2 -63.5) @result{} 2.0 and 3.8
535 (div0-and-mod0 16/3 -10/7) @result{} -4 and -8/21
539 @deffn {Scheme Procedure} real-valued? obj
540 @deffnx {Scheme Procedure} rational-valued? obj
541 @deffnx {Scheme Procedure} integer-valued? obj
542 These procedures return @code{#t} if and only if their arguments can,
543 respectively, be coerced to a real, rational, or integer value without a
544 loss of numerical precision.
546 @code{real-valued?} will return @code{#t} for complex numbers whose
547 imaginary parts are zero.
550 @deffn {Scheme Procedure} nan? x
551 @deffnx {Scheme Procedure} infinite? x
552 @deffnx {Scheme Procedure} finite? x
553 @code{nan?} returns @code{#t} if @var{x} is a NaN value, @code{#f}
554 otherwise. @code{infinite?} returns @code{#t} if @var{x} is an infinite
555 value, @code{#f} otherwise. @code{finite?} returns @code{#t} if @var{x}
556 is neither infinite nor a NaN value, otherwise it returns @code{#f}.
557 Every real number satisfies exactly one of these predicates. An
558 exception is raised if @var{x} is not real.
561 @deffn {Scheme Syntax} assert expr
562 Raises an @code{&assertion} condition if @var{expr} evaluates to
563 @code{#f}; otherwise evaluates to the value of @var{expr}.
566 @deffn {Scheme Procedure} error who message irritant1 ...
567 @deffnx {Scheme Procedure} assertion-violation who message irritant1 ...
568 These procedures raise compound conditions based on their arguments:
569 If @var{who} is not @code{#f}, the condition will include a @code{&who}
570 condition whose @code{who} field is set to @var{who}; a @code{&message}
571 condition will be included with a @code{message} field equal to
572 @var{message}; an @code{&irritants} condition will be included with its
573 @code{irritants} list given by @code{irritant1 ...}.
575 @code{error} produces a compound condition with the simple conditions
576 described above, as well as an @code{&error} condition;
577 @code{assertion-violation} produces one that includes an
578 @code{&assertion} condition.
581 @deffn {Scheme Procedure} vector-map proc v
582 @deffnx {Scheme Procedure} vector-for-each proc v
583 These procedures implement the @code{map} and @code{for-each} contracts
587 @deffn {Scheme Procedure} vector arg @dots{}
588 @deffnx {Scheme Procedure} vector? obj
589 @deffnx {Scheme Procedure} make-vector len
590 @deffnx {Scheme Procedure} make-vector len fill
591 @deffnx {Scheme Procedure} list->vector l
592 @deffnx {Scheme Procedure} vector->list v
593 @xref{Vector Creation}, for documentation.
596 @deffn {Scheme Procedure} vector-length vector
597 @deffnx {Scheme Procedure} vector-ref vector k
598 @deffnx {Scheme Procedure} vector-set! vector k obj
599 @deffnx {Scheme Procedure} vector-fill! v fill
600 @xref{Vector Accessors}, for documentation.
603 @deffn {Scheme Procedure} call-with-current-continuation proc
604 @deffnx {Scheme Procedure} call/cc proc
605 @xref{Continuations}, for documentation.
608 @deffn {Scheme Procedure} values arg @dots{}
609 @deffnx {Scheme Procedure} call-with-values producer consumer
610 @xref{Multiple Values}, for documentation.
613 @deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
614 @xref{Dynamic Wind}, for documentation.
617 @deffn {Scheme Procedure} apply proc arg @dots{} arglst
618 @xref{Fly Evaluation}, for documentation.
622 @subsubsection rnrs unicode
624 The @code{(rnrs unicode (6))} library provides procedures for
625 manipulating Unicode characters and strings.
627 @deffn {Scheme Procedure} char-upcase char
628 @deffnx {Scheme Procedure} char-downcase char
629 @deffnx {Scheme Procedure} char-titlecase char
630 @deffnx {Scheme Procedure} char-foldcase char
631 These procedures translate their arguments from one Unicode character
632 set to another. @code{char-upcase}, @code{char-downcase}, and
633 @code{char-titlecase} are identical to their counterparts in the
634 Guile core library; @xref{Characters}, for documentation.
636 @code{char-foldcase} returns the result of applying @code{char-upcase}
637 to its argument, followed by @code{char-downcase}---except in the case
638 of the Turkic characters @code{U+0130} and @code{U+0131}, for which the
639 procedure acts as the identity function.
642 @deffn {Scheme Procedure} char-ci=? char1 char2 char3 ...
643 @deffnx {Scheme Procedure} char-ci<? char1 char2 char3 ...
644 @deffnx {Scheme Procedure} char-ci>? char1 char2 char3 ...
645 @deffnx {Scheme Procedure} char-ci<=? char1 char2 char3 ...
646 @deffnx {Scheme Procedure} char-ci>=? char1 char2 char3 ...
647 These procedures facilitate case-insensitive comparison of Unicode
648 characters. They are identical to the procedures provided by Guile's
649 core library. @xref{Characters}, for documentation.
652 @deffn {Scheme Procedure} char-alphabetic? char
653 @deffnx {Scheme Procedure} char-numeric? char
654 @deffnx {Scheme Procedure} char-whitespace? char
655 @deffnx {Scheme Procedure} char-upper-case? char
656 @deffnx {Scheme Procedure} char-lower-case? char
657 @deffnx {Scheme Procedure} char-title-case? char
658 These procedures implement various Unicode character set predicates.
659 They are identical to the procedures provided by Guile's core library.
660 @xref{Characters}, for documentation.
663 @deffn {Scheme Procedure} char-general-category char
664 @xref{Characters}, for documentation.
667 @deffn {Scheme Procedure} string-upcase string
668 @deffnx {Scheme Procedure} string-downcase string
669 @deffnx {Scheme Procedure} string-titlecase string
670 @deffnx {Scheme Procedure} string-foldcase string
671 These procedures perform Unicode case folding operations on their input.
672 @xref{Alphabetic Case Mapping}, for documentation.
675 @deffn {Scheme Procedure} string-ci=? string1 string2 string3 ...
676 @deffnx {Scheme Procedure} string-ci<? string1 string2 string3 ...
677 @deffnx {Scheme Procedure} string-ci>? string1 string2 string3 ...
678 @deffnx {Scheme Procedure} string-ci<=? string1 string2 string3 ...
679 @deffnx {Scheme Procedure} string-ci>=? string1 string2 string3 ...
680 These procedures perform case-insensitive comparison on their input.
681 @xref{String Comparison}, for documentation.
684 @deffn {Scheme Procedure} string-normalize-nfd string
685 @deffnx {Scheme Procedure} string-normalize-nfkd string
686 @deffnx {Scheme Procedure} string-normalize-nfc string
687 @deffnx {Scheme Procedure} string-normalize-nfkc string
688 These procedures perform Unicode string normalization operations on
689 their input. @xref{String Comparison}, for documentation.
692 @node rnrs bytevectors
693 @subsubsection rnrs bytevectors
695 The @code{(rnrs bytevectors (6))} library provides procedures for
696 working with blocks of binary data. This functionality is documented
697 in its own section of the manual; @xref{Bytevectors}.
700 @subsubsection rnrs lists
702 The @code{(rnrs lists (6))} library provides procedures additional
703 procedures for working with lists.
705 @deffn {Scheme Procedure} find proc list
706 This procedure is identical to the one defined in Guile's SRFI-1
707 implementation. @xref{SRFI-1 Searching}, for documentation.
710 @deffn {Scheme Procedure} for-all proc list1 list2 ...
711 @deffnx {Scheme Procedure} exists proc list1 list2 ...
713 The @code{for-all} procedure is identical to the @code{every} procedure
714 defined by SRFI-1; the @code{exists} procedure is identical to SRFI-1's
715 @code{any}. @xref{SRFI-1 Searching}, for documentation.
718 @deffn {Scheme Procedure} filter proc list
719 @deffnx {Scheme Procedure} partition proc list
720 These procedures are identical to the ones provided by SRFI-1.
721 @xref{List Modification}, for a description of @code{filter};
722 @xref{SRFI-1 Filtering and Partitioning}, for @code{partition}.
725 @deffn {Scheme Procedure} fold-left combine nil list1 list2 @dots{}
726 @deffnx {Scheme Procedure} fold-right combine nil list1 list2 @dots{}
727 These procedures are identical to the @code{fold} and @code{fold-right}
728 procedures provided by SRFI-1. @xref{SRFI-1 Fold and Map}, for
732 @deffn {Scheme Procedure} remp proc list
733 @deffnx {Scheme Procedure} remove obj list
734 @deffnx {Scheme Procedure} remv obj list
735 @deffnx {Scheme Procedure} remq obj list
736 @code{remove}, @code{remv}, and @code{remq} are identical to the
737 @code{delete}, @code{delv}, and @code{delq} procedures provided by
738 Guile's core library, (@pxref{List Modification}). @code{remp} is
739 identical to the alternate @code{remove} procedure provided by SRFI-1;
740 @xref{SRFI-1 Deleting}.
743 @deffn {Scheme Procedure} memp proc list
744 @deffnx {Scheme Procedure} member obj list
745 @deffnx {Scheme Procedure} memv obj list
746 @deffnx {Scheme Procedure} memq obj list
747 @code{member}, @code{memv}, and @code{memq} are identical to the
748 procedures provided by Guile's core library; @xref{List Searching},
749 for their documentation. @code{memp} uses the specified predicate
750 function @code{proc} to test elements of the list @var{list}---it
751 behaves similarly to @code{find}, except that it returns the first
752 sublist of @var{list} whose @code{car} satisfies @var{proc}.
755 @deffn {Scheme Procedure} assp proc alist
756 @deffnx {Scheme Procedure} assoc obj alist
757 @deffnx {Scheme Procedure} assv obj alist
758 @deffnx {Scheme Procedure} assq obj alist
759 @code{assoc}, @code{assv}, and @code{assq} are identical to the
760 procedures provided by Guile's core library;
761 @xref{Alist Key Equality}, for their documentation. @code{assp} uses
762 the specified predicate function @code{proc} to test keys in the
763 association list @var{alist}.
766 @deffn {Scheme Procedure} cons* obj1 ... obj
767 @deffnx {Scheme Procedure} cons* obj
768 This procedure is identical to the one exported by Guile's core
769 library. @xref{List Constructors}, for documentation.
773 @subsubsection rnrs sorting
775 The @code{(rnrs sorting (6))} library provides procedures for sorting
778 @deffn {Scheme Procedure} list-sort proc list
779 @deffnx {Scheme Procedure} vector-sort proc vector
780 These procedures return their input sorted in ascending order, without
781 modifying the original data. @var{proc} must be a procedure that takes
782 two elements from the input list or vector as arguments, and returns a
783 true value if the first is ``less'' than the second, @code{#f}
784 otherwise. @code{list-sort} returns a list; @code{vector-sort} returns
787 Both @code{list-sort} and @code{vector-sort} are implemented in terms of
788 the @code{stable-sort} procedure from Guile's core library.
789 @xref{Sorting}, for a discussion of the behavior of that procedure.
792 @deffn {Scheme Procedure} vector-sort! proc vector
793 Performs a destructive, ``in-place'' sort of @var{vector}, using
794 @var{proc} as described above to determine an ascending ordering of
795 elements. @code{vector-sort!} returns an unspecified value.
797 This procedure is implemented in terms of the @code{sort!} procedure
798 from Guile's core library. @xref{Sorting}, for more information.
802 @subsubsection rnrs control
804 The @code{(rnrs control (6))} library provides syntactic forms useful
805 for constructing conditional expressions and controlling the flow of
808 @deffn {Scheme Syntax} when test expression1 expression2 ...
809 @deffnx {Scheme Syntax} unless test expression1 expression2 ...
810 The @code{when} form is evaluated by evaluating the specified @var{test}
811 expression; if the result is a true value, the @var{expression}s that
812 follow it are evaluated in order, and the value of the final
813 @var{expression} becomes the value of the entire @code{when} expression.
815 The @code{unless} form behaves similarly, with the exception that the
816 specified @var{expression}s are only evaluated if the value of
820 @deffn {Scheme Syntax} do ((variable init step) ...) (test expression ...) command ...
821 This form is identical to the one provided by Guile's core library.
822 @xref{while do}, for documentation.
825 @deffn {Scheme Syntax} case-lambda clause ...
826 This form is identical to the one provided by Guile's core library.
827 @xref{Case-lambda}, for documentation.
831 @subsubsection R6RS Records
833 The manual sections below describe Guile's implementation of R6RS
834 records, which provide support for user-defined data types. The R6RS
835 records API provides a superset of the features provided by Guile's
836 ``native'' records, as well as those of the SRFI-9 records API;
837 @xref{Records}, and @ref{SRFI-9 Records}, for a description of those
840 As with SRFI-9 and Guile's native records, R6RS records are constructed
841 using a record-type descriptor that specifies attributes like the
842 record's name, its fields, and the mutability of those fields.
844 R6RS records extend this framework to support single inheritance via the
845 specification of a ``parent'' type for a record type at definition time.
846 Accessors and mutator procedures for the fields of a parent type may be
847 applied to records of a subtype of this parent. A record type may be
848 @dfn{sealed}, in which case it cannot be used as the parent of another
851 The inheritance mechanism for record types also informs the process of
852 initializing the fields of a record and its parents. Constructor
853 procedures that generate new instances of a record type are obtained
854 from a record constructor descriptor, which encapsulates the record-type
855 descriptor of the record to be constructed along with a @dfn{protocol}
856 procedure that defines how constructors for record subtypes delegate to
857 the constructors of their parent types.
859 A protocol is a procedure used by the record system at construction time
860 to bind arguments to the fields of the record being constructed. The
861 protocol procedure is passed a procedure @var{n} that accepts the
862 arguments required to construct the record's parent type; this
863 procedure, when invoked, will return a procedure @var{p} that accepts
864 the arguments required to construct a new instance of the record type
865 itself and returns a new instance of the record type.
867 The protocol should in turn return a procedure that uses @var{n} and
868 @var{p} to initialize the fields of the record type and its parent
869 type(s). This procedure will be the constructor returned by
871 As a trivial example, consider the hypothetical record type
872 @code{pixel}, which encapsulates an x-y location on a screen, and
873 @code{voxel}, which has @code{pixel} as its parent type and stores an
874 additional coordinate. The following protocol produces a constructor
875 procedure that accepts all three coordinates, uses the first two to
876 initialize the fields of @code{pixel}, and binds the third to the single
877 field of @code{voxel}.
886 It may be helpful to think of protocols as ``constructor factories''
887 that produce chains of delegating constructors glued together by the
888 helper procedure @var{n}.
890 An R6RS record type may be declared to be @dfn{nongenerative} via the
891 use of a unique generated or user-supplied symbol---or
892 @dfn{uid}---such that subsequent record type declarations with the same
893 uid and attributes will return the previously-declared record-type
896 R6RS record types may also be declared to be @dfn{opaque}, in which case
897 the various predicates and introspection procedures defined in
898 @code{(rnrs records introspection)} will behave as if records of this
899 type are not records at all.
901 Note that while the R6RS records API shares much of its namespace with
902 both the SRFI-9 and native Guile records APIs, it is not currently
903 compatible with either.
905 @node rnrs records syntactic
906 @subsubsection rnrs records syntactic
908 The @code{(rnrs records syntactic (6))} library exports the syntactic
909 API for working with R6RS records.
911 @deffn {Scheme Syntax} define-record-type name-spec record-clause @dots{}
912 Defines a new record type, introducing bindings for a record-type
913 descriptor, a record constructor descriptor, a constructor procedure,
914 a record predicate, and accessor and mutator procedures for the new
915 record type's fields.
917 @var{name-spec} must either be an identifier or must take the form
918 @code{(record-name constructor-name predicate-name)}, where
919 @var{record-name}, @var{constructor-name}, and @var{predicate-name} are
920 all identifiers and specify the names to which, respectively, the
921 record-type descriptor, constructor, and predicate procedures will be
922 bound. If @var{name-spec} is only an identifier, it specifies the name
923 to which the generated record-type descriptor will be bound.
925 Each @var{record-clause} must be one of the following:
929 @code{(fields field-spec*)}, where each @var{field-spec} specifies a
930 field of the new record type and takes one of the following forms:
933 @code{(immutable field-name accessor-name)}, which specifies an
934 immutable field with the name @var{field-name} and binds an accessor
935 procedure for it to the name given by @var{accessor-name}
937 @code{(mutable field-name accessor-name mutator-name)}, which specifies
938 a mutable field with the name @var{field-name} and binds accessor and
939 mutator procedures to @var{accessor-name} and @var{mutator-name},
942 @code{(immutable field-name)}, which specifies an immutable field with
943 the name @var{field-name}; an accessor procedure for it will be created
944 and named by appending record name and @var{field-name} with a hyphen
947 @code{(mutable field-name}), which specifies a mutable field with the
948 name @var{field-name}; an accessor procedure for it will be created and
949 named as described above; a mutator procedure will also be created and
950 named by appending @code{-set!} to the accessor name
952 @code{field-name}, which specifies an immutable field with the name
953 @var{field-name}; an access procedure for it will be created and named
957 @code{(parent parent-name)}, where @var{parent-name} is a symbol giving
958 the name of the record type to be used as the parent of the new record
961 @code{(protocol expression)}, where @var{expression} evaluates to a
962 protocol procedure which behaves as described above, and is used to
963 create a record constructor descriptor for the new record type
965 @code{(sealed sealed?)}, where @var{sealed?} is a boolean value that
966 specifies whether or not the new record type is sealed
968 @code{(opaque opaque?)}, where @var{opaque?} is a boolean value that
969 specifies whether or not the new record type is opaque
971 @code{(nongenerative [uid])}, which specifies that the record type is
972 nongenerative via the optional uid @var{uid}. If @var{uid} is not
973 specified, a unique uid will be generated at expansion time
975 @code{(parent-rtd parent-rtd parent-cd)}, a more explicit form of the
976 @code{parent} form above; @var{parent-rtd} and @var{parent-cd} should
977 evaluate to a record-type descriptor and a record constructor
978 descriptor, respectively
982 @deffn {Scheme Syntax} record-type-descriptor record-name
983 Evaluates to the record-type descriptor associated with the type
984 specified by @var{record-name}.
987 @deffn {Scheme Syntax} record-constructor-descriptor record-name
988 Evaluates to the record-constructor descriptor associated with the type
989 specified by @var{record-name}.
992 @node rnrs records procedural
993 @subsubsection rnrs records procedural
995 The @code{(rnrs records procedural (6))} library exports the procedural
996 API for working with R6RS records.
998 @deffn {Scheme Procedure} make-record-type-descriptor name parent uid sealed? opaque? fields
999 Returns a new record-type descriptor with the specified characteristics:
1000 @var{name} must be a symbol giving the name of the new record type;
1001 @var{parent} must be either @code{#f} or a non-sealed record-type
1002 descriptor for the returned record type to extend; @var{uid} must be
1003 either @code{#f}, indicating that the record type is generative, or
1004 a symbol giving the type's nongenerative uid; @var{sealed?} and
1005 @var{opaque?} must be boolean values that specify the sealedness and
1006 opaqueness of the record type; @var{fields} must be a vector of zero or
1007 more field specifiers of the form @code{(mutable name)} or
1008 @code{(immutable name)}, where name is a symbol giving a name for the
1011 If @var{uid} is not @code{#f}, it must be a symbol
1014 @deffn {Scheme Procedure} record-type-descriptor? obj
1015 Returns @code{#t} if @var{obj} is a record-type descriptor, @code{#f}
1019 @deffn {Scheme Procedure} make-record-constructor-descriptor rtd parent-constructor-descriptor protocol
1020 Returns a new record constructor descriptor that can be used to produce
1021 constructors for the record type specified by the record-type descriptor
1022 @var{rtd} and whose delegation and binding behavior are specified by the
1023 protocol procedure @var{protocol}.
1025 @var{parent-constructor-descriptor} specifies a record constructor
1026 descriptor for the parent type of @var{rtd}, if one exists. If
1027 @var{rtd} represents a base type, then
1028 @var{parent-constructor-descriptor} must be @code{#f}. If @var{rtd}
1029 is an extension of another type, @var{parent-constructor-descriptor} may
1030 still be @code{#f}, but protocol must also be @code{#f} in this case.
1033 @deffn {Scheme Procedure} record-constructor rcd
1034 Returns a record constructor procedure by invoking the protocol
1035 defined by the record-constructor descriptor @var{rcd}.
1038 @deffn {Scheme Procedure} record-predicate rtd
1039 Returns the record predicate procedure for the record-type descriptor
1043 @deffn {Scheme Procedure} record-accessor rtd k
1044 Returns the record field accessor procedure for the @var{k}th field of
1045 the record-type descriptor @var{rtd}.
1048 @deffn {Scheme Procedure} record-mutator rtd k
1049 Returns the record field mutator procedure for the @var{k}th field of
1050 the record-type descriptor @var{rtd}. An @code{&assertion} condition
1051 will be raised if this field is not mutable.
1054 @node rnrs records inspection
1055 @subsubsection rnrs records inspection
1057 The @code{(rnrs records inspection (6))} library provides procedures
1058 useful for accessing metadata about R6RS records.
1060 @deffn {Scheme Procedure} record? obj
1061 Return @code{#t} if the specified object is a non-opaque R6RS record,
1062 @code{#f} otherwise.
1065 @deffn {Scheme Procedure} record-rtd record
1066 Returns the record-type descriptor for @var{record}. An
1067 @code{&assertion} is raised if @var{record} is opaque.
1070 @deffn {Scheme Procedure} record-type-name rtd
1071 Returns the name of the record-type descriptor @var{rtd}.
1074 @deffn {Scheme Procedure} record-type-parent rtd
1075 Returns the parent of the record-type descriptor @var{rtd}, or @code{#f}
1079 @deffn {Scheme Procedure} record-type-uid rtd
1080 Returns the uid of the record-type descriptor @var{rtd}, or @code{#f} if
1084 @deffn {Scheme Procedure} record-type-generative? rtd
1085 Returns @code{#t} if the record-type descriptor @var{rtd} is generative,
1086 @code{#f} otherwise.
1089 @deffn {Scheme Procedure} record-type-sealed? rtd
1090 Returns @code{#t} if the record-type descriptor @var{rtd} is sealed,
1091 @code{#f} otherwise.
1094 @deffn {Scheme Procedure} record-type-opaque? rtd
1095 Returns @code{#t} if the record-type descriptor @var{rtd} is opaque,
1096 @code{#f} otherwise.
1099 @deffn {Scheme Procedure} record-type-field-names rtd
1100 Returns a vector of symbols giving the names of the fields defined by
1101 the record-type descriptor @var{rtd} (and not any of its sub- or
1105 @deffn {Scheme Procedure} record-field-mutable? rtd k
1106 Returns @code{#t} if the field at index @var{k} of the record-type
1107 descriptor @var{rtd} (and not any of its sub- or supertypes) is mutable.
1110 @node rnrs exceptions
1111 @subsubsection rnrs exceptions
1113 The @code{(rnrs exceptions (6))} library provides functionality related
1114 to signaling and handling exceptional situations. This functionality is
1115 similar to the exception handling systems provided by Guile's core
1116 library @xref{Exceptions}, and by the SRFI-18 and SRFI-34
1117 modules---@xref{SRFI-18 Exceptions}, and @ref{SRFI-34},
1118 respectively---but there are some key differences in concepts and
1121 A raised exception may be @dfn{continuable} or @dfn{non-continuable}.
1122 When an exception is raised non-continuably, another exception, with the
1123 condition type @code{&non-continuable}, will be raised when the
1124 exception handler returns locally. Raising an exception continuably
1125 captures the current continuation and invokes it after a local return
1126 from the exception handler.
1128 Like SRFI-18 and SRFI-34, R6RS exceptions are implemented on top of
1129 Guile's native @code{throw} and @code{catch} forms, and use custom
1130 ``throw keys'' to identify their exception types. As a consequence,
1131 Guile's @code{catch} form can handle exceptions thrown by these APIs,
1132 but the reverse is not true: Handlers registered by the
1133 @code{with-exception-handler} procedure described below will only be
1134 called on exceptions thrown by the corresponding @code{raise} procedure.
1136 @deffn {Scheme Procedure} with-exception-handler handler thunk
1137 Installs @var{handler}, which must be a procedure taking one argument,
1138 as the current exception handler during the invocation of @var{thunk}, a
1139 procedure taking zero arguments. The handler in place at the time
1140 @code{with-exception-handler} is called is made current again once
1141 either @var{thunk} returns or @var{handler} is invoked after an
1142 exception is thrown from within @var{thunk}.
1144 This procedure is similar to the @code{with-throw-handler} procedure
1145 provided by Guile's code library; (@pxref{Throw Handlers}).
1148 @deffn {Scheme Syntax} guard (variable clause1 clause2 ...) body
1149 Evaluates the expression given by @var{body}, first creating an ad hoc
1150 exception handler that binds a raised exception to @var{variable} and
1151 then evaluates the specified @var{clause}s as if they were part of a
1152 @code{cond} expression, with the value of the first matching clause
1153 becoming the value of the @code{guard} expression
1154 (@pxref{Conditionals}). If none of the clause's test expressions
1155 evaluates to @code{#t}, the exception is re-raised, with the exception
1156 handler that was current before the evaluation of the @code{guard} form.
1158 For example, the expression
1161 (guard (ex ((eq? ex 'foo) 'bar) ((eq? ex 'bar) 'baz))
1165 evaluates to @code{baz}.
1168 @deffn {Scheme Procedure} raise obj
1169 Raises a non-continuable exception by invoking the currently-installed
1170 exception handler on @var{obj}. If the handler returns, a
1171 @code{&non-continuable} exception will be raised in the dynamic context
1172 in which the handler was installed.
1175 @deffn {Scheme Procedure} raise-continuable obj
1176 Raises a continuable exception by invoking currently-installed exception
1177 handler on @var{obj}.
1180 @node rnrs conditions
1181 @subsubsection rnrs conditions
1183 The @code{(rnrs condition (6))} library provides forms and procedures
1184 for constructing new condition types, as well as a library of
1185 pre-defined condition types that represent a variety of common
1186 exceptional situations. Conditions are records of a subtype of the
1187 @code{&condition} record type, which is neither sealed nor opaque.
1188 @xref{R6RS Records}.
1190 Conditions may be manipulated singly, as @dfn{simple conditions}, or
1191 when composed with other conditions to form @dfn{compound conditions}.
1192 Compound conditions do not ``nest''---constructing a new compound
1193 condition out of existing compound conditions will ``flatten'' them
1194 into their component simple conditions. For example, making a new
1195 condition out of a @code{&message} condition and a compound condition
1196 that contains an @code{&assertion} condition and another @code{&message}
1197 condition will produce a compound condition that contains two
1198 @code{&message} conditions and one @code{&assertion} condition.
1200 The record type predicates and field accessors described below can
1201 operate on either simple or compound conditions. In the latter case,
1202 the predicate returns @code{#t} if the compound condition contains a
1203 component simple condition of the appropriate type; the field accessors
1204 return the requisite fields from the first component simple condition
1205 found to be of the appropriate type.
1207 This library is quite similar to the SRFI-35 conditions module
1208 (@pxref{SRFI-35}). Among other minor differences, the
1209 @code{(rnrs conditions)} library features slightly different semantics
1210 around condition field accessors, and comes with a larger number of
1211 pre-defined condition types. The two APIs are not currently compatible,
1212 however; the @code{condition?} predicate from one API will return
1213 @code{#f} when applied to a condition object created in the other.
1215 @deffn {Condition Type} &condition
1216 @deffnx {Scheme Procedure} condition? obj
1217 The base record type for conditions.
1220 @deffn {Scheme Procedure} condition condition1 ...
1221 @deffnx {Scheme Procedure} simple-conditions condition
1222 The @code{condition} procedure creates a new compound condition out of
1223 its condition arguments, flattening any specified compound conditions
1224 into their component simple conditions as described above.
1226 @code{simple-conditions} returns a list of the component simple
1227 conditions of the compound condition @code{condition}, in the order in
1228 which they were specified at construction time.
1231 @deffn {Scheme Procedure} condition-predicate rtd
1232 @deffnx {Scheme Procedure} condition-accessor rtd proc
1233 These procedures return condition predicate and accessor procedures for
1234 the specified condition record type @var{rtd}.
1237 @deffn {Scheme Syntax} define-condition-type condition-type supertype constructor predicate field-spec ...
1238 Evaluates to a new record type definition for a condition type with the
1239 name @var{condition-type} that has the condition type @var{supertype} as
1240 its parent. A default constructor, which binds its arguments to the
1241 fields of this type and its parent types, will be bound to the
1242 identifier @var{constructor}; a condition predicate will be bound to
1243 @var{predicate}. The fields of the new type, which are immutable, are
1244 specified by the @var{field-spec}s, each of which must be of the form:
1248 where @var{field} gives the name of the field and @var{accessor} gives
1249 the name for a binding to an accessor procedure created for this field.
1252 @deffn {Condition Type} &message
1253 @deffnx {Scheme Procedure} make-message-condition message
1254 @deffnx {Scheme Procedure} message-condition? obj
1255 @deffnx {Scheme Procedure} condition-message condition
1256 A type that includes a message describing the condition that occurred.
1259 @deffn {Condition Type} &warning
1260 @deffnx {Scheme Procedure} make-warning
1261 @deffnx {Scheme Procedure} warning? obj
1262 A base type for representing non-fatal conditions during execution.
1265 @deffn {Condition Type} &serious
1266 @deffnx {Scheme Procedure} make-serious-condition
1267 @deffnx {Scheme Procedure} serious-condition? obj
1268 A base type for conditions representing errors serious enough that
1272 @deffn {Condition Type} &error
1273 @deffnx {Scheme Procedure} make-error
1274 @deffnx {Scheme Procedure} error? obj
1275 A base type for conditions representing errors.
1278 @deffn {Condition Type} &violation
1279 @deffnx {Scheme Procedure} make-violation
1280 @deffnx {Scheme Procedure} violation?
1281 A subtype of @code{&serious} that can be used to represent violations
1282 of a language or library standard.
1285 @deffn {Condition Type} &assertion
1286 @deffnx {Scheme Procedure} make-assertion-violation
1287 @deffnx {Scheme Procedure} assertion-violation? obj
1288 A subtype of @code{&violation} that indicates an invalid call to a
1292 @deffn {Condition Type} &irritants
1293 @deffnx {Scheme Procedure} make-irritants-condition irritants
1294 @deffnx {Scheme Procedure} irritants-condition? obj
1295 @deffnx {Scheme Procedure} condition-irritants condition
1296 A base type used for storing information about the causes of another
1297 condition in a compound condition.
1300 @deffn {Condition Type} &who
1301 @deffnx {Scheme Procedure} make-who-condition who
1302 @deffnx {Scheme Procedure} who-condition? obj
1303 @deffnx {Scheme Procedure} condition-who condition
1304 A base type used for storing the identity, a string or symbol, of the
1305 entity responsible for another condition in a compound condition.
1308 @deffn {Condition Type} &non-continuable
1309 @deffnx {Scheme Procedure} make-non-continuable-violation
1310 @deffnx {Scheme Procedure} non-continuable-violation? obj
1311 A subtype of @code{&violation} used to indicate that an exception
1312 handler invoked by @code{raise} has returned locally.
1315 @deffn {Condition Type} &implementation-restriction
1316 @deffnx {Scheme Procedure} make-implementation-restriction-violation
1317 @deffnx {Scheme Procedure} implementation-restriction-violation? obj
1318 A subtype of @code{&violation} used to indicate a violation of an
1319 implementation restriction.
1322 @deffn {Condition Type} &lexical
1323 @deffnx {Scheme Procedure} make-lexical-violation
1324 @deffnx {Scheme Procedure} lexical-violation? obj
1325 A subtype of @code{&violation} used to indicate a syntax violation at
1326 the level of the datum syntax.
1329 @deffn {Condition Type} &syntax
1330 @deffnx {Scheme Procedure} make-syntax-violation form subform
1331 @deffnx {Scheme Procedure} syntax-violation? obj
1332 @deffnx {Scheme Procedure} syntax-violation-form condition
1333 @deffnx {Scheme Procedure} syntax-violation-subform condition
1334 A subtype of @code{&violation} that indicates a syntax violation. The
1335 @var{form} and @var{subform} fields, which must be datum values,
1336 indicate the syntactic form responsible for the condition.
1339 @deffn {Condition Type} &undefined
1340 @deffnx {Scheme Procedure} make-undefined-violation
1341 @deffnx {Scheme Procedure} undefined-violation? obj
1342 A subtype of @code{&violation} that indicates a reference to an unbound
1346 @node I/O Conditions
1347 @subsubsection I/O Conditions
1349 These condition types are exported by both the
1350 @code{(rnrs io ports (6))} and @code{(rnrs io simple (6))} libraries.
1352 @deffn {Condition Type} &i/o
1353 @deffnx {Scheme Procedure} make-i/o-error
1354 @deffnx {Scheme Procedure} i/o-error? obj
1355 A condition supertype for more specific I/O errors.
1358 @deffn {Condition Type} &i/o-read
1359 @deffnx {Scheme Procedure} make-i/o-read-error
1360 @deffnx {Scheme Procedure} i/o-read-error? obj
1361 A subtype of @code{&i/o}; represents read-related I/O errors.
1364 @deffn {Condition Type} &i/o-write
1365 @deffnx {Scheme Procedure} make-i/o-write-error
1366 @deffnx {Scheme Procedure} i/o-write-error? obj
1367 A subtype of @code{&i/o}; represents write-related I/O errors.
1370 @deffn {Condition Type} &i/o-invalid-position
1371 @deffnx {Scheme Procedure} make-i/o-invalid-position-error position
1372 @deffnx {Scheme Procedure} i/o-invalid-position-error? obj
1373 @deffnx {Scheme Procedure} i/o-error-position condition
1374 A subtype of @code{&i/o}; represents an error related to an attempt to
1375 set the file position to an invalid position.
1378 @deffn {Condition Type} &i/o-filename
1379 @deffnx {Scheme Procedure} make-io-filename-error filename
1380 @deffnx {Scheme Procedure} i/o-filename-error? obj
1381 @deffnx {Scheme Procedure} i/o-error-filename condition
1382 A subtype of @code{&i/o}; represents an error related to an operation on
1386 @deffn {Condition Type} &i/o-file-protection
1387 @deffnx {Scheme Procedure} make-i/o-file-protection-error filename
1388 @deffnx {Scheme Procedure} i/o-file-protection-error? obj
1389 A subtype of @code{&i/o-filename}; represents an error resulting from an
1390 attempt to access a named file for which the caller had insufficient
1394 @deffn {Condition Type} &i/o-file-is-read-only
1395 @deffnx {Scheme Procedure} make-i/o-file-is-read-only-error filename
1396 @deffnx {Scheme Procedure} i/o-file-is-read-only-error? obj
1397 A subtype of @code{&i/o-file-protection}; represents an error related to
1398 an attempt to write to a read-only file.
1401 @deffn {Condition Type} &i/o-file-already-exists
1402 @deffnx {Scheme Procedure} make-i/o-file-already-exists-error filename
1403 @deffnx {Scheme Procedure} i/o-file-already-exists-error? obj
1404 A subtype of @code{&i/o-filename}; represents an error related to an
1405 operation on an existing file that was assumed not to exist.
1408 @deffn {Condition Type} &i/o-file-does-not-exist
1409 @deffnx {Scheme Procedure} make-i/o-file-does-not-exist-error
1410 @deffnx {Scheme Procedure} i/o-file-does-not-exist-error? obj
1411 A subtype of @code{&i/o-filename}; represents an error related to an
1412 operation on a non-existent file that was assumed to exist.
1415 @deffn {Condition Type} &i/o-port
1416 @deffnx {Scheme Procedure} make-i/o-port-error port
1417 @deffnx {Scheme Procedure} i/o-port-error? obj
1418 @deffnx {Scheme Procedure} i/o-error-port condition
1419 A subtype of @code{&i/o}; represents an error related to an operation on
1420 the port @var{port}.
1424 @subsubsection rnrs io ports
1426 The @code{(rnrs io ports (6))} library provides various procedures and
1427 syntactic forms for use in writing to and reading from ports. This
1428 functionality is documented in its own section of the manual;
1429 (@pxref{R6RS I/O Ports}).
1431 @node rnrs io simple
1432 @subsubsection rnrs io simple
1434 The @code{(rnrs io simple (6))} library provides convenience functions
1435 for performing textual I/O on ports. This library also exports all of
1436 the condition types and associated procedures described in (@pxref{I/O
1437 Conditions}). In the context of this section, when stating that a
1438 procedure behaves ``identically'' to the corresponding procedure in
1439 Guile's core library, this is modulo the behavior wrt. conditions: such
1440 procedures raise the appropriate R6RS conditions in case of error, but
1441 otherwise behave identically.
1443 @c FIXME: remove the following note when proper condition behavior has
1447 There are still known issues regarding condition-correctness; some
1448 errors may still be thrown as native Guile exceptions instead of the
1449 appropriate R6RS conditions.
1452 @deffn {Scheme Procedure} eof-object
1453 @deffnx {Scheme Procedure} eof-object? obj
1454 These procedures are identical to the ones provided by the
1455 @code{(rnrs io ports (6))} library. @xref{R6RS I/O Ports}, for
1459 @deffn {Scheme Procedure} input-port? obj
1460 @deffnx {Scheme Procedure} output-port? obj
1461 These procedures are identical to the ones provided by Guile's core
1462 library. @xref{Ports}, for documentation.
1465 @deffn {Scheme Procedure} call-with-input-file filename proc
1466 @deffnx {Scheme Procedure} call-with-output-file filename proc
1467 @deffnx {Scheme Procedure} open-input-file filename
1468 @deffnx {Scheme Procedure} open-output-file filename
1469 @deffnx {Scheme Procedure} with-input-from-file filename thunk
1470 @deffnx {Scheme Procedure} with-output-to-file filename thunk
1471 These procedures are identical to the ones provided by Guile's core
1472 library. @xref{File Ports}, for documentation.
1475 @deffn {Scheme Procedure} close-input-port input-port
1476 @deffnx {Scheme Procedure} close-output-port output-port
1477 These procedures are identical to the ones provided by Guile's core
1478 library. @xref{Closing}, for documentation.
1481 @deffn {Scheme Procedure} peek-char
1482 @deffnx {Scheme Procedure} peek-char textual-input-port
1483 @deffnx {Scheme Procedure} read-char
1484 @deffnx {Scheme Procedure} read-char textual-input-port
1485 These procedures are identical to the ones provided by Guile's core
1486 library. @xref{Reading}, for documentation.
1489 @deffn {Scheme Procedure} read
1490 @deffnx {Scheme Procedure} read textual-input-port
1491 This procedure is identical to the one provided by Guile's core library.
1492 @xref{Scheme Read}, for documentation.
1495 @deffn {Scheme Procedure} display obj
1496 @deffnx {Scheme Procedure} display obj textual-output-port
1497 @deffnx {Scheme Procedure} newline
1498 @deffnx {Scheme Procedure} newline textual-output-port
1499 @deffnx {Scheme Procedure} write obj
1500 @deffnx {Scheme Procedure} write obj textual-output-port
1501 @deffnx {Scheme Procedure} write-char char
1502 @deffnx {Scheme Procedure} write-char char textual-output-port
1503 These procedures are identical to the ones provided by Guile's core
1504 library. @xref{Writing}, for documentation.
1508 @subsubsection rnrs files
1510 The @code{(rnrs files (6))} library provides the @code{file-exists?} and
1511 @code{delete-file} procedures, which test for the existence of a file
1512 and allow the deletion of files from the file system, respectively.
1514 These procedures are identical to the ones provided by Guile's core
1515 library. @xref{File System}, for documentation.
1518 @subsubsection rnrs programs
1520 The @code{(rnrs programs (6))} library provides procedures for
1521 process management and introspection.
1523 @deffn {Scheme Procedure} command-line
1524 This procedure is identical to the one provided by Guile's core library.
1525 @xref{Runtime Environment}, for documentation.
1528 @deffn {Scheme Procedure} exit [status]
1529 This procedure is identical to the one provided by Guile's core
1530 library. @xref{Processes}, for documentation.
1533 @node rnrs arithmetic fixnums
1534 @subsubsection rnrs arithmetic fixnums
1536 The @code{(rnrs arithmetic fixnums (6))} library provides procedures for
1537 performing arithmetic operations on an implementation-dependent range of
1538 exact integer values, which R6RS refers to as @dfn{fixnums}. In Guile,
1539 the size of a fixnum is determined by the size of the @code{SCM} type; a
1540 single SCM struct is guaranteed to be able to hold an entire fixnum,
1541 making fixnum computations particularly
1542 efficient---(@pxref{The SCM Type}). On 32-bit systems, the most
1543 negative and most positive fixnum values are, respectively, -536870912
1546 Unless otherwise specified, all of the procedures below take fixnums as
1547 arguments, and will raise an @code{&assertion} condition if passed a
1548 non-fixnum argument or an @code{&implementation-restriction} condition
1549 if their result is not itself a fixnum.
1551 @deffn {Scheme Procedure} fixnum? obj
1552 Returns @code{#t} if @var{obj} is a fixnum, @code{#f} otherwise.
1555 @deffn {Scheme Procedure} fixnum-width
1556 @deffnx {Scheme Procedure} least-fixnum
1557 @deffnx {Scheme Procedure} greatest-fixnum
1558 These procedures return, respectively, the maximum number of bits
1559 necessary to represent a fixnum value in Guile, the minimum fixnum
1560 value, and the maximum fixnum value.
1563 @deffn {Scheme Procedure} fx=? fx1 fx2 fx3 ...
1564 @deffnx {Scheme Procedure} fx>? fx1 fx2 fx3 ...
1565 @deffnx {Scheme Procedure} fx<? fx1 fx2 fx3 ...
1566 @deffnx {Scheme Procedure} fx>=? fx1 fx2 fx3 ...
1567 @deffnx {Scheme Procedure} fx<=? fx1 fx2 fx3 ...
1568 These procedures return @code{#t} if their fixnum arguments are
1569 (respectively): equal, monotonically increasing, monotonically
1570 decreasing, monotonically nondecreasing, or monotonically nonincreasing;
1571 @code{#f} otherwise.
1574 @deffn {Scheme Procedure} fxzero? fx
1575 @deffnx {Scheme Procedure} fxpositive? fx
1576 @deffnx {Scheme Procedure} fxnegative? fx
1577 @deffnx {Scheme Procedure} fxodd? fx
1578 @deffnx {Scheme Procedure} fxeven? fx
1579 These numerical predicates return @code{#t} if @var{fx} is,
1580 respectively, zero, greater than zero, less than zero, odd, or even;
1581 @code{#f} otherwise.
1584 @deffn {Scheme Procedure} fxmax fx1 fx2 ...
1585 @deffnx {Scheme Procedure} fxmin fx1 fx2 ...
1586 These procedures return the maximum or minimum of their arguments.
1589 @deffn {Scheme Procedure} fx+ fx1 fx2
1590 @deffnx {Scheme Procedure} fx* fx1 fx2
1591 These procedures return the sum or product of their arguments.
1594 @deffn {Scheme Procedure} fx- fx1 fx2
1595 @deffnx {Scheme Procedure} fx- fx
1596 Returns the difference of @var{fx1} and @var{fx2}, or the negation of
1597 @var{fx}, if called with a single argument.
1599 An @code{&assertion} condition is raised if the result is not itself a
1603 @deffn {Scheme Procedure} fxdiv-and-mod fx1 fx2
1604 @deffnx {Scheme Procedure} fxdiv fx1 fx2
1605 @deffnx {Scheme Procedure} fxmod fx1 fx2
1606 @deffnx {Scheme Procedure} fxdiv0-and-mod0 fx1 fx2
1607 @deffnx {Scheme Procedure} fxdiv0 fx1 fx2
1608 @deffnx {Scheme Procedure} fxmod0 fx1 fx2
1609 These procedures implement number-theoretic division on fixnums;
1610 @xref{(rnrs base)}, for a description of their semantics.
1613 @deffn {Scheme Procedure} fx+/carry fx1 fx2 fx3
1614 Returns the two fixnum results of the following computation:
1616 (let* ((s (+ fx1 fx2 fx3))
1617 (s0 (mod0 s (expt 2 (fixnum-width))))
1618 (s1 (div0 s (expt 2 (fixnum-width)))))
1623 @deffn {Scheme Procedure} fx-/carry fx1 fx2 fx3
1624 Returns the two fixnum results of the following computation:
1626 (let* ((d (- fx1 fx2 fx3))
1627 (d0 (mod0 d (expt 2 (fixnum-width))))
1628 (d1 (div0 d (expt 2 (fixnum-width)))))
1633 @deffn {Scheme Procedure} fx*/carry fx1 fx2 fx3
1635 Returns the two fixnum results of the following computation:
1636 (let* ((s (+ (* fx1 fx2) fx3))
1637 (s0 (mod0 s (expt 2 (fixnum-width))))
1638 (s1 (div0 s (expt 2 (fixnum-width)))))
1643 @deffn {Scheme Procedure} fxnot fx
1644 @deffnx {Scheme Procedure} fxand fx1 ...
1645 @deffnx {Scheme Procedure} fxior fx1 ...
1646 @deffnx {Scheme Procedure} fxxor fx1 ...
1647 These procedures are identical to the @code{lognot}, @code{logand},
1648 @code{logior}, and @code{logxor} procedures provided by Guile's core
1649 library. @xref{Bitwise Operations}, for documentation.
1652 @deffn {Scheme Procedure} fxif fx1 fx2 fx3
1653 Returns the bitwise ``if'' of its fixnum arguments. The bit at position
1654 @code{i} in the return value will be the @code{i}th bit from @var{fx2}
1655 if the @code{i}th bit of @var{fx1} is 1, the @code{i}th bit from
1659 @deffn {Scheme Procedure} fxbit-count fx
1660 Returns the number of 1 bits in the two's complement representation of
1664 @deffn {Scheme Procedure} fxlength fx
1665 Returns the number of bits necessary to represent @var{fx}.
1668 @deffn {Scheme Procedure} fxfirst-bit-set fx
1669 Returns the index of the least significant 1 bit in the two's complement
1670 representation of @var{fx}.
1673 @deffn {Scheme Procedure} fxbit-set? fx1 fx2
1674 Returns @code{#t} if the @var{fx2}th bit in the two's complement
1675 representation of @var{fx1} is 1, @code{#f} otherwise.
1678 @deffn {Scheme Procedure} fxcopy-bit fx1 fx2 fx3
1679 Returns the result of setting the @var{fx2}th bit of @var{fx1} to the
1680 @var{fx2}th bit of @var{fx3}.
1683 @deffn {Scheme Procedure} fxbit-field fx1 fx2 fx3
1684 Returns the integer representation of the contiguous sequence of bits in
1685 @var{fx1} that starts at position @var{fx2} (inclusive) and ends at
1686 position @var{fx3} (exclusive).
1689 @deffn {Scheme Procedure} fxcopy-bit-field fx1 fx2 fx3 fx4
1690 Returns the result of replacing the bit field in @var{fx1} with start
1691 and end positions @var{fx2} and @var{fx3} with the corresponding bit
1692 field from @var{fx4}.
1695 @deffn {Scheme Procedure} fxarithmetic-shift fx1 fx2
1696 @deffnx {Scheme Procedure} fxarithmetic-shift-left fx1 fx2
1697 @deffnx {Scheme Procedure} fxarithmetic-shift-right fx1 fx2
1698 Returns the result of shifting the bits of @var{fx1} right or left by
1699 the @var{fx2} positions. @code{fxarithmetic-shift} is identical
1700 to @code{fxarithmetic-shift-left}.
1703 @deffn {Scheme Procedure} fxrotate-bit-field fx1 fx2 fx3 fx4
1704 Returns the result of cyclically permuting the bit field in @var{fx1}
1705 with start and end positions @var{fx2} and @var{fx3} by @var{fx4} bits
1706 in the direction of more significant bits.
1709 @deffn {Scheme Procedure} fxreverse-bit-field fx1 fx2 fx3
1710 Returns the result of reversing the order of the bits of @var{fx1}
1711 between position @var{fx2} (inclusive) and position @var{fx3}
1715 @node rnrs arithmetic flonums
1716 @subsubsection rnrs arithmetic flonums
1718 The @code{(rnrs arithmetic flonums (6))} library provides procedures for
1719 performing arithmetic operations on inexact representations of real
1720 numbers, which R6RS refers to as @dfn{flonums}.
1722 Unless otherwise specified, all of the procedures below take flonums as
1723 arguments, and will raise an @code{&assertion} condition if passed a
1724 non-flonum argument.
1726 @deffn {Scheme Procedure} flonum? obj
1727 Returns @code{#t} if @var{obj} is a flonum, @code{#f} otherwise.
1730 @deffn {Scheme Procedure} real->flonum x
1731 Returns the flonum that is numerically closest to the real number
1735 @deffn {Scheme Procedure} fl=? fl1 fl2 fl3 ...
1736 @deffnx {Scheme Procedure} fl<? fl1 fl2 fl3 ...
1737 @deffnx {Scheme Procedure} fl<=? fl1 fl2 fl3 ...
1738 @deffnx {Scheme Procedure} fl>? fl1 fl2 fl3 ...
1739 @deffnx {Scheme Procedure} fl>=? fl1 fl2 fl3 ...
1740 These procedures return @code{#t} if their flonum arguments are
1741 (respectively): equal, monotonically increasing, monotonically
1742 decreasing, monotonically nondecreasing, or monotonically nonincreasing;
1743 @code{#f} otherwise.
1746 @deffn {Scheme Procedure} flinteger? fl
1747 @deffnx {Scheme Procedure} flzero? fl
1748 @deffnx {Scheme Procedure} flpositive? fl
1749 @deffnx {Scheme Procedure} flnegative? fl
1750 @deffnx {Scheme Procedure} flodd? fl
1751 @deffnx {Scheme Procedure} fleven? fl
1752 These numerical predicates return @code{#t} if @var{fl} is,
1753 respectively, an integer, zero, greater than zero, less than zero, odd,
1754 even, @code{#f} otherwise. In the case of @code{flodd?} and
1755 @code{fleven?}, @var{fl} must be an integer-valued flonum.
1758 @deffn {Scheme Procedure} flfinite? fl
1759 @deffnx {Scheme Procedure} flinfinite? fl
1760 @deffnx {Scheme Procedure} flnan? fl
1761 These numerical predicates return @code{#t} if @var{fl} is,
1762 respectively, not infinite, infinite, or a @code{NaN} value.
1765 @deffn {Scheme Procedure} flmax fl1 fl2 ...
1766 @deffnx {Scheme Procedure} flmin fl1 fl2 ...
1767 These procedures return the maximum or minimum of their arguments.
1770 @deffn {Scheme Procedure} fl+ fl1 ...
1771 @deffnx {Scheme Procedure} fl* fl ...
1772 These procedures return the sum or product of their arguments.
1775 @deffn {Scheme Procedure} fl- fl1 fl2 ...
1776 @deffnx {Scheme Procedure} fl- fl
1777 @deffnx {Scheme Procedure} fl/ fl1 fl2 ...
1778 @deffnx {Scheme Procedure} fl/ fl
1779 These procedures return, respectively, the difference or quotient of
1780 their arguments when called with two arguments; when called with a
1781 single argument, they return the additive or multiplicative inverse of
1785 @deffn {Scheme Procedure} flabs fl
1786 Returns the absolute value of @var{fl}.
1789 @deffn {Scheme Procedure} fldiv-and-mod fl1 fl2
1790 @deffnx {Scheme Procedure} fldiv fl1 fl2
1791 @deffnx {Scheme Procedure} fldmod fl1 fl2
1792 @deffnx {Scheme Procedure} fldiv0-and-mod0 fl1 fl2
1793 @deffnx {Scheme Procedure} fldiv0 fl1 fl2
1794 @deffnx {Scheme Procedure} flmod0 fl1 fl2
1795 These procedures implement number-theoretic division on flonums;
1796 @xref{(rnrs base)}, for a description for their semantics.
1799 @deffn {Scheme Procedure} flnumerator fl
1800 @deffnx {Scheme Procedure} fldenominator fl
1801 These procedures return the numerator or denominator of @var{fl} as a
1805 @deffn {Scheme Procedure} flfloor fl1
1806 @deffnx {Scheme Procedure} flceiling fl
1807 @deffnx {Scheme Procedure} fltruncate fl
1808 @deffnx {Scheme Procedure} flround fl
1809 These procedures are identical to the @code{floor}, @code{ceiling},
1810 @code{truncate}, and @code{round} procedures provided by Guile's core
1811 library. @xref{Arithmetic}, for documentation.
1814 @deffn {Scheme Procedure} flexp fl
1815 @deffnx {Scheme Procedure} fllog fl
1816 @deffnx {Scheme Procedure} fllog fl1 fl2
1817 @deffnx {Scheme Procedure} flsin fl
1818 @deffnx {Scheme Procedure} flcos fl
1819 @deffnx {Scheme Procedure} fltan fl
1820 @deffnx {Scheme Procedure} flasin fl
1821 @deffnx {Scheme Procedure} flacos fl
1822 @deffnx {Scheme Procedure} flatan fl
1823 @deffnx {Scheme Procedure} flatan fl1 fl2
1824 These procedures, which compute the usual transcendental functions, are
1825 the flonum variants of the procedures provided by the R6RS base library
1826 (@pxref{(rnrs base)}).
1829 @deffn {Scheme Procedure} flsqrt fl
1830 Returns the square root of @var{fl}. If @var{fl} is @code{-0.0},
1831 @var{-0.0} is returned; for other negative values, a @code{NaN} value
1835 @deffn {Scheme Procedure} flexpt fl1 fl2
1836 Returns the value of @var{fl1} raised to the power of @var{fl2}.
1839 The following condition types are provided to allow Scheme
1840 implementations that do not support infinities or @code{NaN} values
1841 to indicate that a computation resulted in such a value. Guile supports
1842 both of these, so these conditions will never be raised by Guile's
1843 standard libraries implementation.
1845 @deffn {Condition Type} &no-infinities
1846 @deffnx {Scheme Procedure} make-no-infinities-violation obj
1847 @deffnx {Scheme Procedure} no-infinities-violation?
1848 A condition type indicating that a computation resulted in an infinite
1849 value on a Scheme implementation incapable of representing infinities.
1852 @deffn {Condition Type} &no-nans
1853 @deffnx {Scheme Procedure} make-no-nans-violation obj
1854 @deffnx {Scheme Procedure} no-nans-violation? obj
1855 A condition type indicating that a computation resulted in a @code{NaN}
1856 value on a Scheme implementation incapable of representing @code{NaN}s.
1859 @deffn {Scheme Procedure} fixnum->flonum fx
1860 Returns the flonum that is numerically closest to the fixnum @var{fx}.
1863 @node rnrs arithmetic bitwise
1864 @subsubsection rnrs arithmetic bitwise
1866 The @code{(rnrs arithmetic bitwise (6))} library provides procedures for
1867 performing bitwise arithmetic operations on the two's complement
1868 representations of fixnums.
1870 This library and the procedures it exports share functionality with
1871 SRFI-60, which provides support for bitwise manipulation of integers
1874 @deffn {Scheme Procedure} bitwise-not ei
1875 @deffnx {Scheme Procedure} bitwise-and ei1 ...
1876 @deffnx {Scheme Procedure} bitwise-ior ei1 ...
1877 @deffnx {Scheme Procedure} bitwise-xor ei1 ...
1878 These procedures are identical to the @code{lognot}, @code{logand},
1879 @code{logior}, and @code{logxor} procedures provided by Guile's core
1880 library. @xref{Bitwise Operations}, for documentation.
1883 @deffn {Scheme Procedure} bitwise-if ei1 ei2 ei3
1884 Returns the bitwise ``if'' of its arguments. The bit at position
1885 @code{i} in the return value will be the @code{i}th bit from @var{ei2}
1886 if the @code{i}th bit of @var{ei1} is 1, the @code{i}th bit from
1890 @deffn {Scheme Procedure} bitwise-bit-count ei
1891 Returns the number of 1 bits in the two's complement representation of
1895 @deffn {Scheme Procedure} bitwise-length ei
1896 Returns the number of bits necessary to represent @var{ei}.
1899 @deffn {Scheme Procedure} bitwise-first-bit-set ei
1900 Returns the index of the least significant 1 bit in the two's complement
1901 representation of @var{ei}.
1904 @deffn {Scheme Procedure} bitwise-bit-set? ei1 ei2
1905 Returns @code{#t} if the @var{ei2}th bit in the two's complement
1906 representation of @var{ei1} is 1, @code{#f} otherwise.
1909 @deffn {Scheme Procedure} bitwise-copy-bit ei1 ei2 ei3
1910 Returns the result of setting the @var{ei2}th bit of @var{ei1} to the
1911 @var{ei2}th bit of @var{ei3}.
1914 @deffn {Scheme Procedure} bitwise-bit-field ei1 ei2 ei3
1915 Returns the integer representation of the contiguous sequence of bits in
1916 @var{ei1} that starts at position @var{ei2} (inclusive) and ends at
1917 position @var{ei3} (exclusive).
1920 @deffn {Scheme Procedure} bitwise-copy-bit-field ei1 ei2 ei3 ei4
1921 Returns the result of replacing the bit field in @var{ei1} with start
1922 and end positions @var{ei2} and @var{ei3} with the corresponding bit
1923 field from @var{ei4}.
1926 @deffn {Scheme Procedure} bitwise-arithmetic-shift ei1 ei2
1927 @deffnx {Scheme Procedure} bitwise-arithmetic-shift-left ei1 ei2
1928 @deffnx {Scheme Procedure} bitwise-arithmetic-shift-right ei1 ei2
1929 Returns the result of shifting the bits of @var{ei1} right or left by
1930 the @var{ei2} positions. @code{bitwise-arithmetic-shift} is identical
1931 to @code{bitwise-arithmetic-shift-left}.
1934 @deffn {Scheme Procedure} bitwise-rotate-bit-field ei1 ei2 ei3 ei4
1935 Returns the result of cyclically permuting the bit field in @var{ei1}
1936 with start and end positions @var{ei2} and @var{ei3} by @var{ei4} bits
1937 in the direction of more significant bits.
1940 @deffn {Scheme Procedure} bitwise-reverse-bit-field ei1 ei2 ei3
1941 Returns the result of reversing the order of the bits of @var{ei1}
1942 between position @var{ei2} (inclusive) and position @var{ei3}
1946 @node rnrs syntax-case
1947 @subsubsection rnrs syntax-case
1949 The @code{(rnrs syntax-case (6))} library provides access to the
1950 @code{syntax-case} system for writing hygienic macros. With one
1951 exception, all of the forms and procedures exported by this library
1952 are ``re-exports'' of Guile's native support for @code{syntax-case};
1953 @xref{Syntax Case}, for documentation, examples, and rationale.
1955 @deffn {Scheme Procedure} make-variable-transformer proc
1956 Creates a new variable transformer out of @var{proc}, a procedure that
1957 takes a syntax object as input and returns a syntax object. If an
1958 identifier to which the result of this procedure is bound appears on the
1959 left-hand side of a @code{set!} expression, @var{proc} will be called
1960 with a syntax object representing the entire @code{set!} expression,
1961 and its return value will replace that @code{set!} expression.
1964 @deffn {Scheme Syntax} syntax-case expression (literal ...) clause ...
1965 The @code{syntax-case} pattern matching form.
1968 @deffn {Scheme Syntax} syntax template
1969 @deffnx {Scheme Syntax} quasisyntax template
1970 @deffnx {Scheme Syntax} unsyntax template
1971 @deffnx {Scheme Syntax} unsyntax-splicing template
1972 These forms allow references to be made in the body of a syntax-case
1973 output expression subform to datum and non-datum values. They are
1974 identical to the forms provided by Guile's core library;
1975 @xref{Syntax Case}, for documentation.
1978 @deffn {Scheme Procedure} identifier? obj
1979 @deffnx {Scheme Procedure} bound-identifier=? id1 id2
1980 @deffnx {Scheme Procedure} free-identifier=? id1 id2
1981 These predicate procedures operate on syntax objects representing
1982 Scheme identifiers. @code{identifier?} returns @code{#t} if @var{obj}
1983 represents an identifier, @code{#f} otherwise.
1984 @code{bound-identifier=?} returns @code{#t} if and only if a binding for
1985 @var{id1} would capture a reference to @var{id2} in the transformer's
1986 output, or vice-versa. @code{free-identifier=?} returns @code{#t} if
1987 and only @var{id1} and @var{id2} would refer to the same binding in the
1988 output of the transformer, independent of any bindings introduced by the
1992 @deffn {Scheme Procedure} generate-temporaries l
1993 Returns a list, of the same length as @var{l}, which must be a list or
1994 a syntax object representing a list, of globally unique symbols.
1997 @deffn {Scheme Procedure} syntax->datum syntax-object
1998 @deffnx {Scheme Procedure} datum->syntax template-id datum
1999 These procedures convert wrapped syntax objects to and from Scheme datum
2000 values. The syntax object returned by @code{datum->syntax} shares
2001 contextual information with the syntax object @var{template-id}.
2004 @deffn {Scheme Procedure} syntax-violation whom message form
2005 @deffnx {Scheme Procedure} syntax-violation whom message form subform
2006 Constructs a new compound condition that includes the following
2010 If @var{whom} is not @code{#f}, a @code{&who} condition with the
2011 @var{whom} as its field
2013 A @code{&message} condition with the specified @var{message}
2015 A @code{&syntax} condition with the specified @var{form} and optional
2016 @var{subform} fields
2020 @node rnrs hashtables
2021 @subsubsection rnrs hashtables
2023 The @code{(rnrs hashtables (6))} library provides structures and
2024 procedures for creating and accessing hash tables. The hash tables API
2025 defined by R6RS is substantially similar to both Guile's native hash
2026 tables implementation as well as the one provided by SRFI-69;
2027 @xref{Hash Tables}, and @ref{SRFI-69}, respectively. Note that you can
2028 write portable R6RS library code that manipulates SRFI-69 hash tables
2029 (by importing the @code{(srfi :69)} library); however, hash tables
2030 created by one API cannot be used by another.
2032 Like SRFI-69 hash tables---and unlike Guile's native ones---R6RS hash
2033 tables associate hash and equality functions with a hash table at the
2034 time of its creation. Additionally, R6RS allows for the creation
2035 (via @code{hashtable-copy}; see below) of immutable hash tables.
2037 @deffn {Scheme Procedure} make-eq-hashtable
2038 @deffnx {Scheme Procedure} make-eq-hashtable k
2039 Returns a new hash table that uses @code{eq?} to compare keys and
2040 Guile's @code{hashq} procedure as a hash function. If @var{k} is given,
2041 it specifies the initial capacity of the hash table.
2044 @deffn {Scheme Procedure} make-eqv-hashtable
2045 @deffnx {Scheme Procedure} make-eqv-hashtable k
2046 Returns a new hash table that uses @code{eqv?} to compare keys and
2047 Guile's @code{hashv} procedure as a hash function. If @var{k} is given,
2048 it specifies the initial capacity of the hash table.
2051 @deffn {Scheme Procedure} make-hashtable hash-function equiv
2052 @deffnx {Scheme Procedure} make-hashtable hash-function equiv k
2053 Returns a new hash table that uses @var{equiv} to compare keys and
2054 @var{hash-function} as a hash function. @var{equiv} must be a procedure
2055 that accepts two arguments and returns a true value if they are
2056 equivalent, @code{#f} otherwise; @var{hash-function} must be a procedure
2057 that accepts one argument and returns a non-negative integer.
2059 If @var{k} is given, it specifies the initial capacity of the hash
2063 @deffn {Scheme Procedure} hashtable? obj
2064 Returns @code{#t} if @var{obj} is an R6RS hash table, @code{#f}
2068 @deffn {Scheme Procedure} hashtable-size hashtable
2069 Returns the number of keys currently in the hash table @var{hashtable}.
2072 @deffn {Scheme Procedure} hashtable-ref hashtable key default
2073 Returns the value associated with @var{key} in the hash table
2074 @var{hashtable}, or @var{default} if none is found.
2077 @deffn {Scheme Procedure} hashtable-set! hashtable key obj
2078 Associates the key @var{key} with the value @var{obj} in the hash table
2079 @var{hashtable}, and returns an unspecified value. An @code{&assertion}
2080 condition is raised if @var{hashtable} is immutable.
2083 @deffn {Scheme Procedure} hashtable-delete! hashtable key
2084 Removes any association found for the key @var{key} in the hash table
2085 @var{hashtable}, and returns an unspecified value. An @code{&assertion}
2086 condition is raised if @var{hashtable} is immutable.
2089 @deffn {Scheme Procedure} hashtable-contains? hashtable key
2090 Returns @code{#t} if the hash table @var{hashtable} contains an
2091 association for the key @var{key}, @code{#f} otherwise.
2094 @deffn {Scheme Procedure} hashtable-update! hashtable key proc default
2095 Associates with @var{key} in the hash table @var{hashtable} the result
2096 of calling @var{proc}, which must be a procedure that takes one
2097 argument, on the value currently associated @var{key} in
2098 @var{hashtable}---or on @var{default} if no such association exists.
2099 An @code{&assertion} condition is raised if @var{hashtable} is
2103 @deffn {Scheme Procedure} hashtable-copy hashtable
2104 @deffnx {Scheme Procedure} hashtable-copy hashtable mutable
2105 Returns a copy of the hash table @var{hashtable}. If the optional
2106 argument @var{mutable} is provided and is a true value, the new hash
2107 table will be mutable.
2110 @deffn {Scheme Procedure} hashtable-clear! hashtable
2111 @deffnx {Scheme Procedure} hashtable-clear! hashtable k
2112 Removes all of the associations from the hash table @var{hashtable}.
2113 The optional argument @var{k}, which specifies a new capacity for the
2114 hash table, is accepted by Guile's @code{(rnrs hashtables)}
2115 implementation, but is ignored.
2118 @deffn {Scheme Procedure} hashtable-keys hashtable
2119 Returns a vector of the keys with associations in the hash table
2120 @var{hashtable}, in an unspecified order.
2123 @deffn {Scheme Procedure} hashtable-entries hashtable
2124 Return two values---a vector of the keys with associations in the hash
2125 table @var{hashtable}, and a vector of the values to which these keys
2126 are mapped, in corresponding but unspecified order.
2129 @deffn {Scheme Procedure} hashtable-equivalence-function hashtable
2130 Returns the equivalence predicated use by @var{hashtable}. This
2131 procedure returns @code{eq?} and @code{eqv?}, respectively, for hash
2132 tables created by @code{make-eq-hashtable} and
2133 @code{make-eqv-hashtable}.
2136 @deffn {Scheme Procedure} hashtable-hash-function hashtable
2137 Returns the hash function used by @var{hashtable}. For hash tables
2138 created by @code{make-eq-hashtable} or @code{make-eqv-hashtable},
2139 @code{#f} is returned.
2142 @deffn {Scheme Procedure} hashtable-mutable? hashtable
2143 Returns @code{#t} if @var{hashtable} is mutable, @code{#f} otherwise.
2146 A number of hash functions are provided for convenience:
2148 @deffn {Scheme Procedure} equal-hash obj
2149 Returns an integer hash value for @var{obj}, based on its structure and
2150 current contents. This hash function is suitable for use with
2151 @code{equal?} as an equivalence function.
2154 @deffn {Scheme Procedure} string-hash string
2155 @deffnx {Scheme Procedure} symbol-hash symbol
2156 These procedures are identical to the ones provided by Guile's core
2157 library. @xref{Hash Table Reference}, for documentation.
2160 @deffn {Scheme Procedure} string-ci-hash string
2161 Returns an integer hash value for @var{string} based on its contents,
2162 ignoring case. This hash function is suitable for use with
2163 @code{string-ci=?} as an equivalence function.
2167 @subsubsection rnrs enums
2169 The @code{(rnrs enums (6))} library provides structures and procedures
2170 for working with enumerable sets of symbols. Guile's implementation
2171 defines an @dfn{enum-set} record type that encapsulates a finite set of
2172 distinct symbols, the @dfn{universe}, and a subset of these symbols,
2173 which define the enumeration set.
2175 The SRFI-1 list library provides a number of procedures for performing
2176 set operations on lists; Guile's @code{(rnrs enums)} implementation
2177 makes use of several of them. @xref{SRFI-1 Set Operations}, for
2180 @deffn {Scheme Procedure} make-enumeration symbol-list
2181 Returns a new enum-set whose universe and enumeration set are both equal
2182 to @var{symbol-list}, a list of symbols.
2185 @deffn {Scheme Procedure} enum-set-universe enum-set
2186 Returns an enum-set representing the universe of @var{enum-set},
2190 @deffn {Scheme Procedure} enum-set-indexer enum-set
2191 Returns a procedure that takes a single argument and returns the
2192 zero-indexed position of that argument in the universe of
2193 @var{enum-set}, or @code{#f} if its argument is not a member of that
2197 @deffn {Scheme Procedure} enum-set-constructor enum-set
2198 Returns a procedure that takes a single argument, a list of symbols
2199 from the universe of @var{enum-set}, an enum-set, and returns a new
2200 enum-set with the same universe that represents a subset containing the
2204 @deffn {Scheme Procedure} enum-set->list enum-set
2205 Returns a list containing the symbols of the set represented by
2206 @var{enum-set}, an enum-set, in the order that they appear in the
2207 universe of @var{enum-set}.
2210 @deffn {Scheme Procedure} enum-set-member? symbol enum-set
2211 @deffnx {Scheme Procedure} enum-set-subset? enum-set1 enum-set2
2212 @deffnx {Scheme Procedure} enum-set=? enum-set1 enum-set2
2213 These procedures test for membership of symbols and enum-sets in other
2214 enum-sets. @code{enum-set-member?} returns @code{#t} if and only if
2215 @var{symbol} is a member of the subset specified by @var{enum-set}.
2216 @code{enum-set-subset?} returns @code{#t} if and only if the universe of
2217 @var{enum-set1} is a subset of the universe of @var{enum-set2} and
2218 every symbol in @var{enum-set1} is present in @var{enum-set2}.
2219 @code{enum-set=?} returns @code{#t} if and only if @var{enum-set1} is a
2220 subset, as per @code{enum-set-subset?} of @var{enum-set2} and vice
2224 @deffn {Scheme Procedure} enum-set-union enum-set1 enum-set2
2225 @deffnx {Scheme Procedure} enum-set-intersection enum-set1 enum-set2
2226 @deffnx {Scheme Procedure} enum-set-difference enum-set1 enum-set2
2227 These procedures return, respectively, the union, intersection, and
2228 difference of their enum-set arguments.
2231 @deffn {Scheme Procedure} enum-set-complement enum-set
2232 Returns @var{enum-set}'s complement (an enum-set), with regard to its
2236 @deffn {Scheme Procedure} enum-set-projection enum-set1 enum-set2
2237 Returns the projection of the enum-set @var{enum-set1} onto the universe
2238 of the enum-set @var{enum-set2}.
2241 @deffn {Scheme Syntax} define-enumeration type-name (symbol ...) constructor-syntax
2242 Evaluates to two new definitions: A constructor bound to
2243 @var{constructor-syntax} that behaves similarly to constructors created
2244 by @code{enum-set-constructor}, above, and creates new @var{enum-set}s
2245 in the universe specified by @code{(symbol ...)}; and a ``predicate
2246 macro'' bound to @var{type-name}, which has the following form:
2249 (@var{type-name} sym)
2252 If @var{sym} is a member of the universe specified by the @var{symbol}s
2253 above, this form evaluates to @var{sym}. Otherwise, a @code{&syntax}
2254 condition is raised.
2260 The @code{(rnrs (6))} library is a composite of all of the other R6RS
2261 standard libraries---it imports and re-exports all of their exported
2262 procedures and syntactic forms---with the exception of the following
2266 @item @code{(rnrs eval (6))}
2267 @item @code{(rnrs mutable-pairs (6))}
2268 @item @code{(rnrs mutable-strings (6))}
2269 @item @code{(rnrs r5rs (6))}
2273 @subsubsection rnrs eval
2275 The @code{(rnrs eval (6)} library provides procedures for performing
2276 ``on-the-fly'' evaluation of expressions.
2278 @deffn {Scheme Procedure} eval expression environment
2279 Evaluates @var{expression}, which must be a datum representation of a
2280 valid Scheme expression, in the environment specified by
2281 @var{environment}. This procedure is identical to the one provided by
2282 Guile's code library; @xref{Fly Evaluation}, for documentation.
2285 @deffn {Scheme Procedure} environment import-spec ...
2286 Constructs and returns a new environment based on the specified
2287 @var{import-spec}s, which must be datum representations of the import
2288 specifications used with the @code{import} form. @xref{R6RS Libraries},
2292 @node rnrs mutable-pairs
2293 @subsubsection rnrs mutable-pairs
2295 The @code{(rnrs mutable-pairs (6))} library provides the @code{set-car!}
2296 and @code{set-cdr!} procedures, which allow the @code{car} and
2297 @code{cdr} fields of a pair to be modified.
2299 These procedures are identical to the ones provide by Guile's core
2300 library. @xref{Pairs}, for documentation. All pairs in Guile are
2301 mutable; consequently, these procedures will never throw the
2302 @code{&assertion} condition described in the R6RS libraries
2305 @node rnrs mutable-strings
2306 @subsubsection rnrs mutable-strings
2308 The @code{(rnrs mutable-strings (6))} library provides the
2309 @code{string-set!} and @code{string-fill!} procedures, which allow the
2310 content of strings to be modified ``in-place.''
2312 These procedures are identical to the ones provided by Guile's core
2313 library. @xref{String Modification}, for documentation. All strings in
2314 Guile are mutable; consequently, these procedures will never throw the
2315 @code{&assertion} condition described in the R6RS libraries
2319 @subsubsection rnrs r5rs
2321 The @code{(rnrs r5rs (6))} library exports bindings for some procedures
2322 present in R5RS but omitted from the R6RS base library specification.
2324 @deffn {Scheme Procedure} exact->inexact z
2325 @deffnx {Scheme Procedure} inexact->exact z
2326 These procedures are identical to the ones provided by Guile's core
2327 library. @xref{Exactness}, for documentation.
2330 @deffn {Scheme Procedure} quotient n1 n2
2331 @deffnx {Scheme Procedure} remainder n1 n2
2332 @deffnx {Scheme Procedure} modulo n1 n2
2333 These procedures are identical to the ones provided by Guile's core
2334 library. @xref{Integer Operations}, for documentation.
2337 @deffn {Scheme Syntax} delay expr
2338 @deffnx {Scheme Procedure} force promise
2339 The @code{delay} form and the @code{force} procedure are identical to
2340 their counterparts in Guile's core library. @xref{Delayed Evaluation},
2344 @deffn {Scheme Procedure} null-environment n
2345 @deffnx {Scheme Procedure} scheme-report-environment n
2346 These procedures are identical to the ones provided by the
2347 @code{(ice-9 r5rs)} Guile module. @xref{Environments}, for
2351 @c r6rs.texi ends here
2354 @c TeX-master: "guile.texi"