2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2010, 2011, 2012, 2013
4 @c 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 @node R6RS Standard Libraries
106 @subsection R6RS Standard Libraries
108 In contrast with earlier versions of the Revised Report, the R6RS
109 organizes the procedures and syntactic forms required of conforming
110 implementations into a set of ``standard libraries'' which can be
111 imported as necessary by user programs and libraries. Here we briefly
112 list the libraries that have been implemented for Guile.
114 We do not attempt to document these libraries fully here, as most of
115 their functionality is already available in Guile itself. The
116 expectation is that most Guile users will use the well-known and
117 well-documented Guile modules. These R6RS libraries are mostly useful
118 to users who want to port their code to other R6RS systems.
120 The documentation in the following sections reproduces some of the
121 content of the library section of the Report, but is mostly intended to
122 provide supplementary information about Guile's implementation of the
123 R6RS standard libraries. For complete documentation, design rationales
124 and further examples, we advise you to consult the ``Standard
125 Libraries'' section of the Report (@pxref{Standard Libraries,
126 R6RS Standard Libraries,, r6rs, The Revised^6 Report on the Algorithmic
130 * Library Usage:: What to know about Guile's library support.
131 * rnrs base:: The base library.
132 * rnrs unicode:: Access to Unicode operations.
133 * rnrs bytevectors:: Functions for working with binary data.
134 * rnrs lists:: List utilities.
135 * rnrs sorting:: Sorting for lists and vectors.
136 * rnrs control:: Additional control structures.
138 * R6RS Records:: A note about R6RS records.
139 * rnrs records syntactic:: Syntactic API for R6RS records.
140 * rnrs records procedural:: Procedural API for R6RS records.
141 * rnrs records inspection:: Reflection on R6RS records.
143 * rnrs exceptions:: Handling exceptional situations.
144 * rnrs conditions:: Data structures for exceptions.
146 * I/O Conditions:: Predefined I/O error types.
147 * rnrs io ports:: Support for port-based I/O.
148 * rnrs io simple:: High-level I/O API.
150 * rnrs files:: Functions for working with files.
151 * rnrs programs:: Functions for working with processes.
152 * rnrs arithmetic fixnums:: Fixed-precision arithmetic operations.
153 * rnrs arithmetic flonums:: Floating-point arithmetic operations.
154 * rnrs arithmetic bitwise:: Exact bitwise arithmetic operations.
155 * rnrs syntax-case:: Support for `syntax-case' macros.
156 * rnrs hashtables:: Hashtables.
157 * rnrs enums:: Enumerations.
158 * rnrs:: The composite library.
159 * rnrs eval:: Support for on-the-fly evaluation.
160 * rnrs mutable-pairs:: Support for mutable pairs.
161 * rnrs mutable-strings:: Support for mutable strings.
162 * rnrs r5rs:: Compatibility layer for R5RS Scheme.
167 @subsubsection Library Usage
169 Guile implements the R6RS `library' form as a transformation to a native
170 Guile module definition. As a consequence of this, all of the libraries
171 described in the following subsections, in addition to being available
172 for use by R6RS libraries and top-level programs, can also be imported
173 as if they were normal Guile modules---via a @code{use-modules} form,
174 say. For example, the R6RS ``composite'' library can be imported by:
181 (use-modules ((rnrs) :version (6)))
184 For more information on Guile's library implementation, see
185 (@pxref{R6RS Libraries}).
188 @subsubsection rnrs base
190 The @code{(rnrs base (6))} library exports the procedures and syntactic
191 forms described in the main section of the Report
192 (@pxref{Base library, R6RS Base library,, r6rs,
193 The Revised^6 Report on the Algorithmic Language Scheme}). They are
194 grouped below by the existing manual sections to which they correspond.
196 @deffn {Scheme Procedure} boolean? obj
197 @deffnx {Scheme Procedure} not x
198 @xref{Booleans}, for documentation.
201 @deffn {Scheme Procedure} symbol? obj
202 @deffnx {Scheme Procedure} symbol->string sym
203 @deffnx {Scheme Procedure} string->symbol str
204 @xref{Symbol Primitives}, for documentation.
207 @deffn {Scheme Procedure} char? obj
208 @deffnx {Scheme Procedure} char=?
209 @deffnx {Scheme Procedure} char<?
210 @deffnx {Scheme Procedure} char>?
211 @deffnx {Scheme Procedure} char<=?
212 @deffnx {Scheme Procedure} char>=?
213 @deffnx {Scheme Procedure} integer->char n
214 @deffnx {Scheme Procedure} char->integer chr
215 @xref{Characters}, for documentation.
218 @deffn {Scheme Procedure} list? x
219 @deffnx {Scheme Procedure} null? x
220 @xref{List Predicates}, for documentation.
223 @deffn {Scheme Procedure} pair? x
224 @deffnx {Scheme Procedure} cons x y
225 @deffnx {Scheme Procedure} car pair
226 @deffnx {Scheme Procedure} cdr pair
227 @deffnx {Scheme Procedure} caar pair
228 @deffnx {Scheme Procedure} cadr pair
229 @deffnx {Scheme Procedure} cdar pair
230 @deffnx {Scheme Procedure} cddr pair
231 @deffnx {Scheme Procedure} caaar pair
232 @deffnx {Scheme Procedure} caadr pair
233 @deffnx {Scheme Procedure} cadar pair
234 @deffnx {Scheme Procedure} cdaar pair
235 @deffnx {Scheme Procedure} caddr pair
236 @deffnx {Scheme Procedure} cdadr pair
237 @deffnx {Scheme Procedure} cddar pair
238 @deffnx {Scheme Procedure} cdddr pair
239 @deffnx {Scheme Procedure} caaaar pair
240 @deffnx {Scheme Procedure} caaadr pair
241 @deffnx {Scheme Procedure} caadar pair
242 @deffnx {Scheme Procedure} cadaar pair
243 @deffnx {Scheme Procedure} cdaaar pair
244 @deffnx {Scheme Procedure} cddaar pair
245 @deffnx {Scheme Procedure} cdadar pair
246 @deffnx {Scheme Procedure} cdaadr pair
247 @deffnx {Scheme Procedure} cadadr pair
248 @deffnx {Scheme Procedure} caaddr pair
249 @deffnx {Scheme Procedure} caddar pair
250 @deffnx {Scheme Procedure} cadddr pair
251 @deffnx {Scheme Procedure} cdaddr pair
252 @deffnx {Scheme Procedure} cddadr pair
253 @deffnx {Scheme Procedure} cdddar pair
254 @deffnx {Scheme Procedure} cddddr pair
255 @xref{Pairs}, for documentation.
258 @deffn {Scheme Procedure} number? obj
259 @xref{Numerical Tower}, for documentation.
262 @deffn {Scheme Procedure} string? obj
263 @xref{String Predicates}, for documentation.
266 @deffn {Scheme Procedure} procedure? obj
267 @xref{Procedure Properties}, for documentation.
270 @deffn {Scheme Syntax} define name value
271 @deffnx {Scheme Syntax} set! variable-name value
272 @xref{Definition}, for documentation.
275 @deffn {Scheme Syntax} define-syntax keyword expression
276 @deffnx {Scheme Syntax} let-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
277 @deffnx {Scheme Syntax} letrec-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
278 @xref{Defining Macros}, for documentation.
281 @deffn {Scheme Syntax} identifier-syntax exp
282 @xref{Identifier Macros}, for documentation.
285 @deffn {Scheme Syntax} syntax-rules literals (pattern template) ...
286 @xref{Syntax Rules}, for documentation.
289 @deffn {Scheme Syntax} lambda formals body
290 @xref{Lambda}, for documentation.
293 @deffn {Scheme Syntax} let bindings body
294 @deffnx {Scheme Syntax} let* bindings body
295 @deffnx {Scheme Syntax} letrec bindings body
296 @deffnx {Scheme Syntax} letrec* bindings body
297 @xref{Local Bindings}, for documentation.
300 @deffn {Scheme Syntax} let-values bindings body
301 @deffnx {Scheme Syntax} let*-values bindings body
302 @xref{SRFI-11}, for documentation.
305 @deffn {Scheme Syntax} begin expr1 expr2 ...
306 @xref{begin}, for documentation.
309 @deffn {Scheme Syntax} quote expr
310 @deffnx {Scheme Syntax} quasiquote expr
311 @deffnx {Scheme Syntax} unquote expr
312 @deffnx {Scheme Syntax} unquote-splicing expr
313 @xref{Expression Syntax}, for documentation.
316 @deffn {Scheme Syntax} if test consequence [alternate]
317 @deffnx {Scheme Syntax} cond clause1 clause2 ...
318 @deffnx {Scheme Syntax} case key clause1 clause2 ...
319 @xref{Conditionals}, for documentation.
322 @deffn {Scheme Syntax} and expr ...
323 @deffnx {Scheme Syntax} or expr ...
324 @xref{and or}, for documentation.
327 @deffn {Scheme Procedure} eq? x y
328 @deffnx {Scheme Procedure} eqv? x y
329 @deffnx {Scheme Procedure} equal? x y
330 @deffnx {Scheme Procedure} symbol=? symbol1 symbol2 ...
331 @xref{Equality}, for documentation.
333 @code{symbol=?} is identical to @code{eq?}.
336 @deffn {Scheme Procedure} complex? z
337 @xref{Complex Numbers}, for documentation.
340 @deffn {Scheme Procedure} real-part z
341 @deffnx {Scheme Procedure} imag-part z
342 @deffnx {Scheme Procedure} make-rectangular real_part imaginary_part
343 @deffnx {Scheme Procedure} make-polar x y
344 @deffnx {Scheme Procedure} magnitude z
345 @deffnx {Scheme Procedure} angle z
346 @xref{Complex}, for documentation.
349 @deffn {Scheme Procedure} sqrt z
350 @deffnx {Scheme Procedure} exp z
351 @deffnx {Scheme Procedure} expt z1 z2
352 @deffnx {Scheme Procedure} log z
353 @deffnx {Scheme Procedure} sin z
354 @deffnx {Scheme Procedure} cos z
355 @deffnx {Scheme Procedure} tan z
356 @deffnx {Scheme Procedure} asin z
357 @deffnx {Scheme Procedure} acos z
358 @deffnx {Scheme Procedure} atan z
359 @xref{Scientific}, for documentation.
362 @deffn {Scheme Procedure} real? x
363 @deffnx {Scheme Procedure} rational? x
364 @deffnx {Scheme Procedure} numerator x
365 @deffnx {Scheme Procedure} denominator x
366 @deffnx {Scheme Procedure} rationalize x eps
367 @xref{Reals and Rationals}, for documentation.
370 @deffn {Scheme Procedure} exact? x
371 @deffnx {Scheme Procedure} inexact? x
372 @deffnx {Scheme Procedure} exact z
373 @deffnx {Scheme Procedure} inexact z
374 @xref{Exactness}, for documentation. The @code{exact} and
375 @code{inexact} procedures are identical to the @code{inexact->exact} and
376 @code{exact->inexact} procedures provided by Guile's code library.
379 @deffn {Scheme Procedure} integer? x
380 @xref{Integers}, for documentation.
383 @deffn {Scheme Procedure} odd? n
384 @deffnx {Scheme Procedure} even? n
385 @deffnx {Scheme Procedure} gcd x ...
386 @deffnx {Scheme Procedure} lcm x ...
387 @deffnx {Scheme Procedure} exact-integer-sqrt k
388 @xref{Integer Operations}, for documentation.
391 @deffn {Scheme Procedure} =
392 @deffnx {Scheme Procedure} <
393 @deffnx {Scheme Procedure} >
394 @deffnx {Scheme Procedure} <=
395 @deffnx {Scheme Procedure} >=
396 @deffnx {Scheme Procedure} zero? x
397 @deffnx {Scheme Procedure} positive? x
398 @deffnx {Scheme Procedure} negative? x
399 @xref{Comparison}, for documentation.
402 @deffn {Scheme Procedure} for-each f lst1 lst2 ...
403 @xref{SRFI-1 Fold and Map}, for documentation.
406 @deffn {Scheme Procedure} list elem @dots{}
407 @xref{List Constructors}, for documentation.
410 @deffn {Scheme Procedure} length lst
411 @deffnx {Scheme Procedure} list-ref lst k
412 @deffnx {Scheme Procedure} list-tail lst k
413 @xref{List Selection}, for documentation.
416 @deffn {Scheme Procedure} append lst @dots{} obj
417 @deffnx {Scheme Procedure} append
418 @deffnx {Scheme Procedure} reverse lst
419 @xref{Append/Reverse}, for documentation.
422 @deffn {Scheme Procedure} number->string n [radix]
423 @deffnx {Scheme Procedure} string->number str [radix]
424 @xref{Conversion}, for documentation.
427 @deffn {Scheme Procedure} string char ...
428 @deffnx {Scheme Procedure} make-string k [chr]
429 @deffnx {Scheme Procedure} list->string lst
430 @xref{String Constructors}, for documentation.
433 @deffn {Scheme Procedure} string->list str [start [end]]
434 @xref{List/String Conversion}, for documentation.
437 @deffn {Scheme Procedure} string-length str
438 @deffnx {Scheme Procedure} string-ref str k
439 @deffnx {Scheme Procedure} string-copy str [start [end]]
440 @deffnx {Scheme Procedure} substring str start [end]
441 @xref{String Selection}, for documentation.
444 @deffn {Scheme Procedure} string=? s1 s2 s3 @dots{}
445 @deffnx {Scheme Procedure} string<? s1 s2 s3 @dots{}
446 @deffnx {Scheme Procedure} string>? s1 s2 s3 @dots{}
447 @deffnx {Scheme Procedure} string<=? s1 s2 s3 @dots{}
448 @deffnx {Scheme Procedure} string>=? s1 s2 s3 @dots{}
449 @xref{String Comparison}, for documentation.
452 @deffn {Scheme Procedure} string-append arg @dots{}
453 @xref{Reversing and Appending Strings}, for documentation.
456 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
457 @xref{Mapping Folding and Unfolding}, for documentation.
460 @deffn {Scheme Procedure} + z1 ...
461 @deffnx {Scheme Procedure} - z1 z2 ...
462 @deffnx {Scheme Procedure} * z1 ...
463 @deffnx {Scheme Procedure} / z1 z2 ...
464 @deffnx {Scheme Procedure} max x1 x2 ...
465 @deffnx {Scheme Procedure} min x1 x2 ...
466 @deffnx {Scheme Procedure} abs x
467 @deffnx {Scheme Procedure} truncate x
468 @deffnx {Scheme Procedure} floor x
469 @deffnx {Scheme Procedure} ceiling x
470 @deffnx {Scheme Procedure} round x
471 @xref{Arithmetic}, for documentation.
477 @deffn {Scheme Procedure} div x y
478 @deffnx {Scheme Procedure} mod x y
479 @deffnx {Scheme Procedure} div-and-mod x y
480 These procedures accept two real numbers @var{x} and @var{y}, where the
481 divisor @var{y} must be non-zero. @code{div} returns the integer @var{q}
482 and @code{mod} returns the real number @var{r} such that
483 @math{@var{x} = @var{q}*@var{y} + @var{r}} and @math{0 <= @var{r} < abs(@var{y})}.
484 @code{div-and-mod} returns both @var{q} and @var{r}, and is more
485 efficient than computing each separately. Note that when @math{@var{y} > 0},
486 @code{div} returns @math{floor(@var{x}/@var{y})}, otherwise
487 it returns @math{ceiling(@var{x}/@var{y})}.
490 (div 123 10) @result{} 12
491 (mod 123 10) @result{} 3
492 (div-and-mod 123 10) @result{} 12 and 3
493 (div-and-mod 123 -10) @result{} -12 and 3
494 (div-and-mod -123 10) @result{} -13 and 7
495 (div-and-mod -123 -10) @result{} 13 and 7
496 (div-and-mod -123.2 -63.5) @result{} 2.0 and 3.8
497 (div-and-mod 16/3 -10/7) @result{} -3 and 22/21
503 @rnindex div0-and-mod0
504 @deffn {Scheme Procedure} div0 x y
505 @deffnx {Scheme Procedure} mod0 x y
506 @deffnx {Scheme Procedure} div0-and-mod0 x y
507 These procedures accept two real numbers @var{x} and @var{y}, where the
508 divisor @var{y} must be non-zero. @code{div0} returns the
509 integer @var{q} and @code{mod0} returns the real number
510 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
511 @math{-abs(@var{y}/2) <= @var{r} < abs(@var{y}/2)}. @code{div0-and-mod0}
512 returns both @var{q} and @var{r}, and is more efficient than computing
515 Note that @code{div0} returns @math{@var{x}/@var{y}} rounded to the
516 nearest integer. When @math{@var{x}/@var{y}} lies exactly half-way
517 between two integers, the tie is broken according to the sign of
518 @var{y}. If @math{@var{y} > 0}, ties are rounded toward positive
519 infinity, otherwise they are rounded toward negative infinity.
520 This is a consequence of the requirement that
521 @math{-abs(@var{y}/2) <= @var{r} < abs(@var{y}/2)}.
524 (div0 123 10) @result{} 12
525 (mod0 123 10) @result{} 3
526 (div0-and-mod0 123 10) @result{} 12 and 3
527 (div0-and-mod0 123 -10) @result{} -12 and 3
528 (div0-and-mod0 -123 10) @result{} -12 and -3
529 (div0-and-mod0 -123 -10) @result{} 12 and -3
530 (div0-and-mod0 -123.2 -63.5) @result{} 2.0 and 3.8
531 (div0-and-mod0 16/3 -10/7) @result{} -4 and -8/21
535 @deffn {Scheme Procedure} real-valued? obj
536 @deffnx {Scheme Procedure} rational-valued? obj
537 @deffnx {Scheme Procedure} integer-valued? obj
538 These procedures return @code{#t} if and only if their arguments can,
539 respectively, be coerced to a real, rational, or integer value without a
540 loss of numerical precision.
542 @code{real-valued?} will return @code{#t} for complex numbers whose
543 imaginary parts are zero.
546 @deffn {Scheme Procedure} nan? x
547 @deffnx {Scheme Procedure} infinite? x
548 @deffnx {Scheme Procedure} finite? x
549 @code{nan?} returns @code{#t} if @var{x} is a NaN value, @code{#f}
550 otherwise. @code{infinite?} returns @code{#t} if @var{x} is an infinite
551 value, @code{#f} otherwise. @code{finite?} returns @code{#t} if @var{x}
552 is neither infinite nor a NaN value, otherwise it returns @code{#f}.
553 Every real number satisfies exactly one of these predicates. An
554 exception is raised if @var{x} is not real.
557 @deffn {Scheme Syntax} assert expr
558 Raises an @code{&assertion} condition if @var{expr} evaluates to
559 @code{#f}; otherwise evaluates to the value of @var{expr}.
562 @deffn {Scheme Procedure} error who message irritant1 ...
563 @deffnx {Scheme Procedure} assertion-violation who message irritant1 ...
564 These procedures raise compound conditions based on their arguments:
565 If @var{who} is not @code{#f}, the condition will include a @code{&who}
566 condition whose @code{who} field is set to @var{who}; a @code{&message}
567 condition will be included with a @code{message} field equal to
568 @var{message}; an @code{&irritants} condition will be included with its
569 @code{irritants} list given by @code{irritant1 ...}.
571 @code{error} produces a compound condition with the simple conditions
572 described above, as well as an @code{&error} condition;
573 @code{assertion-violation} produces one that includes an
574 @code{&assertion} condition.
577 @deffn {Scheme Procedure} vector-map proc v
578 @deffnx {Scheme Procedure} vector-for-each proc v
579 These procedures implement the @code{map} and @code{for-each} contracts
583 @deffn {Scheme Procedure} vector arg @dots{}
584 @deffnx {Scheme Procedure} vector? obj
585 @deffnx {Scheme Procedure} make-vector len
586 @deffnx {Scheme Procedure} make-vector len fill
587 @deffnx {Scheme Procedure} list->vector l
588 @deffnx {Scheme Procedure} vector->list v
589 @xref{Vector Creation}, for documentation.
592 @deffn {Scheme Procedure} vector-length vector
593 @deffnx {Scheme Procedure} vector-ref vector k
594 @deffnx {Scheme Procedure} vector-set! vector k obj
595 @deffnx {Scheme Procedure} vector-fill! v fill
596 @xref{Vector Accessors}, for documentation.
599 @deffn {Scheme Procedure} call-with-current-continuation proc
600 @deffnx {Scheme Procedure} call/cc proc
601 @xref{Continuations}, for documentation.
604 @deffn {Scheme Procedure} values arg @dots{}
605 @deffnx {Scheme Procedure} call-with-values producer consumer
606 @xref{Multiple Values}, for documentation.
609 @deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
610 @xref{Dynamic Wind}, for documentation.
613 @deffn {Scheme Procedure} apply proc arg @dots{} arglst
614 @xref{Fly Evaluation}, for documentation.
618 @subsubsection rnrs unicode
620 The @code{(rnrs unicode (6))} library provides procedures for
621 manipulating Unicode characters and strings.
623 @deffn {Scheme Procedure} char-upcase char
624 @deffnx {Scheme Procedure} char-downcase char
625 @deffnx {Scheme Procedure} char-titlecase char
626 @deffnx {Scheme Procedure} char-foldcase char
627 These procedures translate their arguments from one Unicode character
628 set to another. @code{char-upcase}, @code{char-downcase}, and
629 @code{char-titlecase} are identical to their counterparts in the
630 Guile core library; @xref{Characters}, for documentation.
632 @code{char-foldcase} returns the result of applying @code{char-upcase}
633 to its argument, followed by @code{char-downcase}---except in the case
634 of the Turkic characters @code{U+0130} and @code{U+0131}, for which the
635 procedure acts as the identity function.
638 @deffn {Scheme Procedure} char-ci=? char1 char2 char3 ...
639 @deffnx {Scheme Procedure} char-ci<? char1 char2 char3 ...
640 @deffnx {Scheme Procedure} char-ci>? char1 char2 char3 ...
641 @deffnx {Scheme Procedure} char-ci<=? char1 char2 char3 ...
642 @deffnx {Scheme Procedure} char-ci>=? char1 char2 char3 ...
643 These procedures facilitate case-insensitive comparison of Unicode
644 characters. They are identical to the procedures provided by Guile's
645 core library. @xref{Characters}, for documentation.
648 @deffn {Scheme Procedure} char-alphabetic? char
649 @deffnx {Scheme Procedure} char-numeric? char
650 @deffnx {Scheme Procedure} char-whitespace? char
651 @deffnx {Scheme Procedure} char-upper-case? char
652 @deffnx {Scheme Procedure} char-lower-case? char
653 @deffnx {Scheme Procedure} char-title-case? char
654 These procedures implement various Unicode character set predicates.
655 They are identical to the procedures provided by Guile's core library.
656 @xref{Characters}, for documentation.
659 @deffn {Scheme Procedure} char-general-category char
660 @xref{Characters}, for documentation.
663 @deffn {Scheme Procedure} string-upcase string
664 @deffnx {Scheme Procedure} string-downcase string
665 @deffnx {Scheme Procedure} string-titlecase string
666 @deffnx {Scheme Procedure} string-foldcase string
667 These procedures perform Unicode case folding operations on their input.
668 @xref{Alphabetic Case Mapping}, for documentation.
671 @deffn {Scheme Procedure} string-ci=? string1 string2 string3 ...
672 @deffnx {Scheme Procedure} string-ci<? string1 string2 string3 ...
673 @deffnx {Scheme Procedure} string-ci>? string1 string2 string3 ...
674 @deffnx {Scheme Procedure} string-ci<=? string1 string2 string3 ...
675 @deffnx {Scheme Procedure} string-ci>=? string1 string2 string3 ...
676 These procedures perform case-insensitive comparison on their input.
677 @xref{String Comparison}, for documentation.
680 @deffn {Scheme Procedure} string-normalize-nfd string
681 @deffnx {Scheme Procedure} string-normalize-nfkd string
682 @deffnx {Scheme Procedure} string-normalize-nfc string
683 @deffnx {Scheme Procedure} string-normalize-nfkc string
684 These procedures perform Unicode string normalization operations on
685 their input. @xref{String Comparison}, for documentation.
688 @node rnrs bytevectors
689 @subsubsection rnrs bytevectors
691 The @code{(rnrs bytevectors (6))} library provides procedures for
692 working with blocks of binary data. This functionality is documented
693 in its own section of the manual; @xref{Bytevectors}.
696 @subsubsection rnrs lists
698 The @code{(rnrs lists (6))} library provides procedures additional
699 procedures for working with lists.
701 @deffn {Scheme Procedure} find proc list
702 This procedure is identical to the one defined in Guile's SRFI-1
703 implementation. @xref{SRFI-1 Searching}, for documentation.
706 @deffn {Scheme Procedure} for-all proc list1 list2 ...
707 @deffnx {Scheme Procedure} exists proc list1 list2 ...
709 The @code{for-all} procedure is identical to the @code{every} procedure
710 defined by SRFI-1; the @code{exists} procedure is identical to SRFI-1's
711 @code{any}. @xref{SRFI-1 Searching}, for documentation.
714 @deffn {Scheme Procedure} filter proc list
715 @deffnx {Scheme Procedure} partition proc list
716 These procedures are identical to the ones provided by SRFI-1.
717 @xref{List Modification}, for a description of @code{filter};
718 @xref{SRFI-1 Filtering and Partitioning}, for @code{partition}.
721 @deffn {Scheme Procedure} fold-left combine nil list1 list2 @dots{}
722 @deffnx {Scheme Procedure} fold-right combine nil list1 list2 @dots{}
723 These procedures are identical to the @code{fold} and @code{fold-right}
724 procedures provided by SRFI-1. @xref{SRFI-1 Fold and Map}, for
728 @deffn {Scheme Procedure} remp proc list
729 @deffnx {Scheme Procedure} remove obj list
730 @deffnx {Scheme Procedure} remv obj list
731 @deffnx {Scheme Procedure} remq obj list
732 @code{remove}, @code{remv}, and @code{remq} are identical to the
733 @code{delete}, @code{delv}, and @code{delq} procedures provided by
734 Guile's core library, (@pxref{List Modification}). @code{remp} is
735 identical to the alternate @code{remove} procedure provided by SRFI-1;
736 @xref{SRFI-1 Deleting}.
739 @deffn {Scheme Procedure} memp proc list
740 @deffnx {Scheme Procedure} member obj list
741 @deffnx {Scheme Procedure} memv obj list
742 @deffnx {Scheme Procedure} memq obj list
743 @code{member}, @code{memv}, and @code{memq} are identical to the
744 procedures provided by Guile's core library; @xref{List Searching},
745 for their documentation. @code{memp} uses the specified predicate
746 function @code{proc} to test elements of the list @var{list}---it
747 behaves similarly to @code{find}, except that it returns the first
748 sublist of @var{list} whose @code{car} satisfies @var{proc}.
751 @deffn {Scheme Procedure} assp proc alist
752 @deffnx {Scheme Procedure} assoc obj alist
753 @deffnx {Scheme Procedure} assv obj alist
754 @deffnx {Scheme Procedure} assq obj alist
755 @code{assoc}, @code{assv}, and @code{assq} are identical to the
756 procedures provided by Guile's core library;
757 @xref{Alist Key Equality}, for their documentation. @code{assp} uses
758 the specified predicate function @code{proc} to test keys in the
759 association list @var{alist}.
762 @deffn {Scheme Procedure} cons* obj1 ... obj
763 @deffnx {Scheme Procedure} cons* obj
764 This procedure is identical to the one exported by Guile's core
765 library. @xref{List Constructors}, for documentation.
769 @subsubsection rnrs sorting
771 The @code{(rnrs sorting (6))} library provides procedures for sorting
774 @deffn {Scheme Procedure} list-sort proc list
775 @deffnx {Scheme Procedure} vector-sort proc vector
776 These procedures return their input sorted in ascending order, without
777 modifying the original data. @var{proc} must be a procedure that takes
778 two elements from the input list or vector as arguments, and returns a
779 true value if the first is ``less'' than the second, @code{#f}
780 otherwise. @code{list-sort} returns a list; @code{vector-sort} returns
783 Both @code{list-sort} and @code{vector-sort} are implemented in terms of
784 the @code{stable-sort} procedure from Guile's core library.
785 @xref{Sorting}, for a discussion of the behavior of that procedure.
788 @deffn {Scheme Procedure} vector-sort! proc vector
789 Performs a destructive, ``in-place'' sort of @var{vector}, using
790 @var{proc} as described above to determine an ascending ordering of
791 elements. @code{vector-sort!} returns an unspecified value.
793 This procedure is implemented in terms of the @code{sort!} procedure
794 from Guile's core library. @xref{Sorting}, for more information.
798 @subsubsection rnrs control
800 The @code{(rnrs control (6))} library provides syntactic forms useful
801 for constructing conditional expressions and controlling the flow of
804 @deffn {Scheme Syntax} when test expression1 expression2 ...
805 @deffnx {Scheme Syntax} unless test expression1 expression2 ...
806 The @code{when} form is evaluated by evaluating the specified @var{test}
807 expression; if the result is a true value, the @var{expression}s that
808 follow it are evaluated in order, and the value of the final
809 @var{expression} becomes the value of the entire @code{when} expression.
811 The @code{unless} form behaves similarly, with the exception that the
812 specified @var{expression}s are only evaluated if the value of
816 @deffn {Scheme Syntax} do ((variable init step) ...) (test expression ...) command ...
817 This form is identical to the one provided by Guile's core library.
818 @xref{while do}, for documentation.
821 @deffn {Scheme Syntax} case-lambda clause ...
822 This form is identical to the one provided by Guile's core library.
823 @xref{Case-lambda}, for documentation.
827 @subsubsection R6RS Records
829 The manual sections below describe Guile's implementation of R6RS
830 records, which provide support for user-defined data types. The R6RS
831 records API provides a superset of the features provided by Guile's
832 ``native'' records, as well as those of the SRFI-9 records API;
833 @xref{Records}, and @ref{SRFI-9 Records}, for a description of those
836 As with SRFI-9 and Guile's native records, R6RS records are constructed
837 using a record-type descriptor that specifies attributes like the
838 record's name, its fields, and the mutability of those fields.
840 R6RS records extend this framework to support single inheritance via the
841 specification of a ``parent'' type for a record type at definition time.
842 Accessors and mutator procedures for the fields of a parent type may be
843 applied to records of a subtype of this parent. A record type may be
844 @dfn{sealed}, in which case it cannot be used as the parent of another
847 The inheritance mechanism for record types also informs the process of
848 initializing the fields of a record and its parents. Constructor
849 procedures that generate new instances of a record type are obtained
850 from a record constructor descriptor, which encapsulates the record-type
851 descriptor of the record to be constructed along with a @dfn{protocol}
852 procedure that defines how constructors for record subtypes delegate to
853 the constructors of their parent types.
855 A protocol is a procedure used by the record system at construction time
856 to bind arguments to the fields of the record being constructed. The
857 protocol procedure is passed a procedure @var{n} that accepts the
858 arguments required to construct the record's parent type; this
859 procedure, when invoked, will return a procedure @var{p} that accepts
860 the arguments required to construct a new instance of the record type
861 itself and returns a new instance of the record type.
863 The protocol should in turn return a procedure that uses @var{n} and
864 @var{p} to initialize the fields of the record type and its parent
865 type(s). This procedure will be the constructor returned by
867 As a trivial example, consider the hypothetical record type
868 @code{pixel}, which encapsulates an x-y location on a screen, and
869 @code{voxel}, which has @code{pixel} as its parent type and stores an
870 additional coordinate. The following protocol produces a constructor
871 procedure that accepts all three coordinates, uses the first two to
872 initialize the fields of @code{pixel}, and binds the third to the single
873 field of @code{voxel}.
882 It may be helpful to think of protocols as ``constructor factories''
883 that produce chains of delegating constructors glued together by the
884 helper procedure @var{n}.
886 An R6RS record type may be declared to be @dfn{nongenerative} via the
887 use of a unique generated or user-supplied symbol---or
888 @dfn{uid}---such that subsequent record type declarations with the same
889 uid and attributes will return the previously-declared record-type
892 R6RS record types may also be declared to be @dfn{opaque}, in which case
893 the various predicates and introspection procedures defined in
894 @code{(rnrs records introspection)} will behave as if records of this
895 type are not records at all.
897 Note that while the R6RS records API shares much of its namespace with
898 both the SRFI-9 and native Guile records APIs, it is not currently
899 compatible with either.
901 @node rnrs records syntactic
902 @subsubsection rnrs records syntactic
904 The @code{(rnrs records syntactic (6))} library exports the syntactic
905 API for working with R6RS records.
907 @deffn {Scheme Syntax} define-record-type name-spec record-clause @dots{}
908 Defines a new record type, introducing bindings for a record-type
909 descriptor, a record constructor descriptor, a constructor procedure,
910 a record predicate, and accessor and mutator procedures for the new
911 record type's fields.
913 @var{name-spec} must either be an identifier or must take the form
914 @code{(record-name constructor-name predicate-name)}, where
915 @var{record-name}, @var{constructor-name}, and @var{predicate-name} are
916 all identifiers and specify the names to which, respectively, the
917 record-type descriptor, constructor, and predicate procedures will be
918 bound. If @var{name-spec} is only an identifier, it specifies the name
919 to which the generated record-type descriptor will be bound.
921 Each @var{record-clause} must be one of the following:
925 @code{(fields field-spec*)}, where each @var{field-spec} specifies a
926 field of the new record type and takes one of the following forms:
929 @code{(immutable field-name accessor-name)}, which specifies an
930 immutable field with the name @var{field-name} and binds an accessor
931 procedure for it to the name given by @var{accessor-name}
933 @code{(mutable field-name accessor-name mutator-name)}, which specifies
934 a mutable field with the name @var{field-name} and binds accessor and
935 mutator procedures to @var{accessor-name} and @var{mutator-name},
938 @code{(immutable field-name)}, which specifies an immutable field with
939 the name @var{field-name}; an accessor procedure for it will be created
940 and named by appending record name and @var{field-name} with a hyphen
943 @code{(mutable field-name}), which specifies a mutable field with the
944 name @var{field-name}; an accessor procedure for it will be created and
945 named as described above; a mutator procedure will also be created and
946 named by appending @code{-set!} to the accessor name
948 @code{field-name}, which specifies an immutable field with the name
949 @var{field-name}; an access procedure for it will be created and named
953 @code{(parent parent-name)}, where @var{parent-name} is a symbol giving
954 the name of the record type to be used as the parent of the new record
957 @code{(protocol expression)}, where @var{expression} evaluates to a
958 protocol procedure which behaves as described above, and is used to
959 create a record constructor descriptor for the new record type
961 @code{(sealed sealed?)}, where @var{sealed?} is a boolean value that
962 specifies whether or not the new record type is sealed
964 @code{(opaque opaque?)}, where @var{opaque?} is a boolean value that
965 specifies whether or not the new record type is opaque
967 @code{(nongenerative [uid])}, which specifies that the record type is
968 nongenerative via the optional uid @var{uid}. If @var{uid} is not
969 specified, a unique uid will be generated at expansion time
971 @code{(parent-rtd parent-rtd parent-cd)}, a more explicit form of the
972 @code{parent} form above; @var{parent-rtd} and @var{parent-cd} should
973 evaluate to a record-type descriptor and a record constructor
974 descriptor, respectively
978 @deffn {Scheme Syntax} record-type-descriptor record-name
979 Evaluates to the record-type descriptor associated with the type
980 specified by @var{record-name}.
983 @deffn {Scheme Syntax} record-constructor-descriptor record-name
984 Evaluates to the record-constructor descriptor associated with the type
985 specified by @var{record-name}.
988 @node rnrs records procedural
989 @subsubsection rnrs records procedural
991 The @code{(rnrs records procedural (6))} library exports the procedural
992 API for working with R6RS records.
994 @deffn {Scheme Procedure} make-record-type-descriptor name parent uid sealed? opaque? fields
995 Returns a new record-type descriptor with the specified characteristics:
996 @var{name} must be a symbol giving the name of the new record type;
997 @var{parent} must be either @code{#f} or a non-sealed record-type
998 descriptor for the returned record type to extend; @var{uid} must be
999 either @code{#f}, indicating that the record type is generative, or
1000 a symbol giving the type's nongenerative uid; @var{sealed?} and
1001 @var{opaque?} must be boolean values that specify the sealedness and
1002 opaqueness of the record type; @var{fields} must be a vector of zero or
1003 more field specifiers of the form @code{(mutable name)} or
1004 @code{(immutable name)}, where name is a symbol giving a name for the
1007 If @var{uid} is not @code{#f}, it must be a symbol
1010 @deffn {Scheme Procedure} record-type-descriptor? obj
1011 Returns @code{#t} if @var{obj} is a record-type descriptor, @code{#f}
1015 @deffn {Scheme Procedure} make-record-constructor-descriptor rtd parent-constructor-descriptor protocol
1016 Returns a new record constructor descriptor that can be used to produce
1017 constructors for the record type specified by the record-type descriptor
1018 @var{rtd} and whose delegation and binding behavior are specified by the
1019 protocol procedure @var{protocol}.
1021 @var{parent-constructor-descriptor} specifies a record constructor
1022 descriptor for the parent type of @var{rtd}, if one exists. If
1023 @var{rtd} represents a base type, then
1024 @var{parent-constructor-descriptor} must be @code{#f}. If @var{rtd}
1025 is an extension of another type, @var{parent-constructor-descriptor} may
1026 still be @code{#f}, but protocol must also be @code{#f} in this case.
1029 @deffn {Scheme Procedure} record-constructor rcd
1030 Returns a record constructor procedure by invoking the protocol
1031 defined by the record-constructor descriptor @var{rcd}.
1034 @deffn {Scheme Procedure} record-predicate rtd
1035 Returns the record predicate procedure for the record-type descriptor
1039 @deffn {Scheme Procedure} record-accessor rtd k
1040 Returns the record field accessor procedure for the @var{k}th field of
1041 the record-type descriptor @var{rtd}.
1044 @deffn {Scheme Procedure} record-mutator rtd k
1045 Returns the record field mutator procedure for the @var{k}th field of
1046 the record-type descriptor @var{rtd}. An @code{&assertion} condition
1047 will be raised if this field is not mutable.
1050 @node rnrs records inspection
1051 @subsubsection rnrs records inspection
1053 The @code{(rnrs records inspection (6))} library provides procedures
1054 useful for accessing metadata about R6RS records.
1056 @deffn {Scheme Procedure} record? obj
1057 Return @code{#t} if the specified object is a non-opaque R6RS record,
1058 @code{#f} otherwise.
1061 @deffn {Scheme Procedure} record-rtd record
1062 Returns the record-type descriptor for @var{record}. An
1063 @code{&assertion} is raised if @var{record} is opaque.
1066 @deffn {Scheme Procedure} record-type-name rtd
1067 Returns the name of the record-type descriptor @var{rtd}.
1070 @deffn {Scheme Procedure} record-type-parent rtd
1071 Returns the parent of the record-type descriptor @var{rtd}, or @code{#f}
1075 @deffn {Scheme Procedure} record-type-uid rtd
1076 Returns the uid of the record-type descriptor @var{rtd}, or @code{#f} if
1080 @deffn {Scheme Procedure} record-type-generative? rtd
1081 Returns @code{#t} if the record-type descriptor @var{rtd} is generative,
1082 @code{#f} otherwise.
1085 @deffn {Scheme Procedure} record-type-sealed? rtd
1086 Returns @code{#t} if the record-type descriptor @var{rtd} is sealed,
1087 @code{#f} otherwise.
1090 @deffn {Scheme Procedure} record-type-opaque? rtd
1091 Returns @code{#t} if the record-type descriptor @var{rtd} is opaque,
1092 @code{#f} otherwise.
1095 @deffn {Scheme Procedure} record-type-field-names rtd
1096 Returns a vector of symbols giving the names of the fields defined by
1097 the record-type descriptor @var{rtd} (and not any of its sub- or
1101 @deffn {Scheme Procedure} record-field-mutable? rtd k
1102 Returns @code{#t} if the field at index @var{k} of the record-type
1103 descriptor @var{rtd} (and not any of its sub- or supertypes) is mutable.
1106 @node rnrs exceptions
1107 @subsubsection rnrs exceptions
1109 The @code{(rnrs exceptions (6))} library provides functionality related
1110 to signaling and handling exceptional situations. This functionality is
1111 similar to the exception handling systems provided by Guile's core
1112 library @xref{Exceptions}, and by the SRFI-18 and SRFI-34
1113 modules---@xref{SRFI-18 Exceptions}, and @ref{SRFI-34},
1114 respectively---but there are some key differences in concepts and
1117 A raised exception may be @dfn{continuable} or @dfn{non-continuable}.
1118 When an exception is raised non-continuably, another exception, with the
1119 condition type @code{&non-continuable}, will be raised when the
1120 exception handler returns locally. Raising an exception continuably
1121 captures the current continuation and invokes it after a local return
1122 from the exception handler.
1124 Like SRFI-18 and SRFI-34, R6RS exceptions are implemented on top of
1125 Guile's native @code{throw} and @code{catch} forms, and use custom
1126 ``throw keys'' to identify their exception types. As a consequence,
1127 Guile's @code{catch} form can handle exceptions thrown by these APIs,
1128 but the reverse is not true: Handlers registered by the
1129 @code{with-exception-handler} procedure described below will only be
1130 called on exceptions thrown by the corresponding @code{raise} procedure.
1132 @deffn {Scheme Procedure} with-exception-handler handler thunk
1133 Installs @var{handler}, which must be a procedure taking one argument,
1134 as the current exception handler during the invocation of @var{thunk}, a
1135 procedure taking zero arguments. The handler in place at the time
1136 @code{with-exception-handler} is called is made current again once
1137 either @var{thunk} returns or @var{handler} is invoked after an
1138 exception is thrown from within @var{thunk}.
1140 This procedure is similar to the @code{with-throw-handler} procedure
1141 provided by Guile's code library; (@pxref{Throw Handlers}).
1144 @deffn {Scheme Syntax} guard (variable clause1 clause2 ...) body
1145 Evaluates the expression given by @var{body}, first creating an ad hoc
1146 exception handler that binds a raised exception to @var{variable} and
1147 then evaluates the specified @var{clause}s as if they were part of a
1148 @code{cond} expression, with the value of the first matching clause
1149 becoming the value of the @code{guard} expression
1150 (@pxref{Conditionals}). If none of the clause's test expressions
1151 evaluates to @code{#t}, the exception is re-raised, with the exception
1152 handler that was current before the evaluation of the @code{guard} form.
1154 For example, the expression
1157 (guard (ex ((eq? ex 'foo) 'bar) ((eq? ex 'bar) 'baz))
1161 evaluates to @code{baz}.
1164 @deffn {Scheme Procedure} raise obj
1165 Raises a non-continuable exception by invoking the currently-installed
1166 exception handler on @var{obj}. If the handler returns, a
1167 @code{&non-continuable} exception will be raised in the dynamic context
1168 in which the handler was installed.
1171 @deffn {Scheme Procedure} raise-continuable obj
1172 Raises a continuable exception by invoking currently-installed exception
1173 handler on @var{obj}.
1176 @node rnrs conditions
1177 @subsubsection rnrs conditions
1179 The @code{(rnrs condition (6))} library provides forms and procedures
1180 for constructing new condition types, as well as a library of
1181 pre-defined condition types that represent a variety of common
1182 exceptional situations. Conditions are records of a subtype of the
1183 @code{&condition} record type, which is neither sealed nor opaque.
1184 @xref{R6RS Records}.
1186 Conditions may be manipulated singly, as @dfn{simple conditions}, or
1187 when composed with other conditions to form @dfn{compound conditions}.
1188 Compound conditions do not ``nest''---constructing a new compound
1189 condition out of existing compound conditions will ``flatten'' them
1190 into their component simple conditions. For example, making a new
1191 condition out of a @code{&message} condition and a compound condition
1192 that contains an @code{&assertion} condition and another @code{&message}
1193 condition will produce a compound condition that contains two
1194 @code{&message} conditions and one @code{&assertion} condition.
1196 The record type predicates and field accessors described below can
1197 operate on either simple or compound conditions. In the latter case,
1198 the predicate returns @code{#t} if the compound condition contains a
1199 component simple condition of the appropriate type; the field accessors
1200 return the requisite fields from the first component simple condition
1201 found to be of the appropriate type.
1203 This library is quite similar to the SRFI-35 conditions module
1204 (@pxref{SRFI-35}). Among other minor differences, the
1205 @code{(rnrs conditions)} library features slightly different semantics
1206 around condition field accessors, and comes with a larger number of
1207 pre-defined condition types. The two APIs are not currently compatible,
1208 however; the @code{condition?} predicate from one API will return
1209 @code{#f} when applied to a condition object created in the other.
1211 @deffn {Condition Type} &condition
1212 @deffnx {Scheme Procedure} condition? obj
1213 The base record type for conditions.
1216 @deffn {Scheme Procedure} condition condition1 ...
1217 @deffnx {Scheme Procedure} simple-conditions condition
1218 The @code{condition} procedure creates a new compound condition out of
1219 its condition arguments, flattening any specified compound conditions
1220 into their component simple conditions as described above.
1222 @code{simple-conditions} returns a list of the component simple
1223 conditions of the compound condition @code{condition}, in the order in
1224 which they were specified at construction time.
1227 @deffn {Scheme Procedure} condition-predicate rtd
1228 @deffnx {Scheme Procedure} condition-accessor rtd proc
1229 These procedures return condition predicate and accessor procedures for
1230 the specified condition record type @var{rtd}.
1233 @deffn {Scheme Syntax} define-condition-type condition-type supertype constructor predicate field-spec ...
1234 Evaluates to a new record type definition for a condition type with the
1235 name @var{condition-type} that has the condition type @var{supertype} as
1236 its parent. A default constructor, which binds its arguments to the
1237 fields of this type and its parent types, will be bound to the
1238 identifier @var{constructor}; a condition predicate will be bound to
1239 @var{predicate}. The fields of the new type, which are immutable, are
1240 specified by the @var{field-spec}s, each of which must be of the form:
1244 where @var{field} gives the name of the field and @var{accessor} gives
1245 the name for a binding to an accessor procedure created for this field.
1248 @deffn {Condition Type} &message
1249 @deffnx {Scheme Procedure} make-message-condition message
1250 @deffnx {Scheme Procedure} message-condition? obj
1251 @deffnx {Scheme Procedure} condition-message condition
1252 A type that includes a message describing the condition that occurred.
1255 @deffn {Condition Type} &warning
1256 @deffnx {Scheme Procedure} make-warning
1257 @deffnx {Scheme Procedure} warning? obj
1258 A base type for representing non-fatal conditions during execution.
1261 @deffn {Condition Type} &serious
1262 @deffnx {Scheme Procedure} make-serious-condition
1263 @deffnx {Scheme Procedure} serious-condition? obj
1264 A base type for conditions representing errors serious enough that
1268 @deffn {Condition Type} &error
1269 @deffnx {Scheme Procedure} make-error
1270 @deffnx {Scheme Procedure} error? obj
1271 A base type for conditions representing errors.
1274 @deffn {Condition Type} &violation
1275 @deffnx {Scheme Procedure} make-violation
1276 @deffnx {Scheme Procedure} violation?
1277 A subtype of @code{&serious} that can be used to represent violations
1278 of a language or library standard.
1281 @deffn {Condition Type} &assertion
1282 @deffnx {Scheme Procedure} make-assertion-violation
1283 @deffnx {Scheme Procedure} assertion-violation? obj
1284 A subtype of @code{&violation} that indicates an invalid call to a
1288 @deffn {Condition Type} &irritants
1289 @deffnx {Scheme Procedure} make-irritants-condition irritants
1290 @deffnx {Scheme Procedure} irritants-condition? obj
1291 @deffnx {Scheme Procedure} condition-irritants condition
1292 A base type used for storing information about the causes of another
1293 condition in a compound condition.
1296 @deffn {Condition Type} &who
1297 @deffnx {Scheme Procedure} make-who-condition who
1298 @deffnx {Scheme Procedure} who-condition? obj
1299 @deffnx {Scheme Procedure} condition-who condition
1300 A base type used for storing the identity, a string or symbol, of the
1301 entity responsible for another condition in a compound condition.
1304 @deffn {Condition Type} &non-continuable
1305 @deffnx {Scheme Procedure} make-non-continuable-violation
1306 @deffnx {Scheme Procedure} non-continuable-violation? obj
1307 A subtype of @code{&violation} used to indicate that an exception
1308 handler invoked by @code{raise} has returned locally.
1311 @deffn {Condition Type} &implementation-restriction
1312 @deffnx {Scheme Procedure} make-implementation-restriction-violation
1313 @deffnx {Scheme Procedure} implementation-restriction-violation? obj
1314 A subtype of @code{&violation} used to indicate a violation of an
1315 implementation restriction.
1318 @deffn {Condition Type} &lexical
1319 @deffnx {Scheme Procedure} make-lexical-violation
1320 @deffnx {Scheme Procedure} lexical-violation? obj
1321 A subtype of @code{&violation} used to indicate a syntax violation at
1322 the level of the datum syntax.
1325 @deffn {Condition Type} &syntax
1326 @deffnx {Scheme Procedure} make-syntax-violation form subform
1327 @deffnx {Scheme Procedure} syntax-violation? obj
1328 @deffnx {Scheme Procedure} syntax-violation-form condition
1329 @deffnx {Scheme Procedure} syntax-violation-subform condition
1330 A subtype of @code{&violation} that indicates a syntax violation. The
1331 @var{form} and @var{subform} fields, which must be datum values,
1332 indicate the syntactic form responsible for the condition.
1335 @deffn {Condition Type} &undefined
1336 @deffnx {Scheme Procedure} make-undefined-violation
1337 @deffnx {Scheme Procedure} undefined-violation? obj
1338 A subtype of @code{&violation} that indicates a reference to an unbound
1342 @node I/O Conditions
1343 @subsubsection I/O Conditions
1345 These condition types are exported by both the
1346 @code{(rnrs io ports (6))} and @code{(rnrs io simple (6))} libraries.
1348 @deffn {Condition Type} &i/o
1349 @deffnx {Scheme Procedure} make-i/o-error
1350 @deffnx {Scheme Procedure} i/o-error? obj
1351 A condition supertype for more specific I/O errors.
1354 @deffn {Condition Type} &i/o-read
1355 @deffnx {Scheme Procedure} make-i/o-read-error
1356 @deffnx {Scheme Procedure} i/o-read-error? obj
1357 A subtype of @code{&i/o}; represents read-related I/O errors.
1360 @deffn {Condition Type} &i/o-write
1361 @deffnx {Scheme Procedure} make-i/o-write-error
1362 @deffnx {Scheme Procedure} i/o-write-error? obj
1363 A subtype of @code{&i/o}; represents write-related I/O errors.
1366 @deffn {Condition Type} &i/o-invalid-position
1367 @deffnx {Scheme Procedure} make-i/o-invalid-position-error position
1368 @deffnx {Scheme Procedure} i/o-invalid-position-error? obj
1369 @deffnx {Scheme Procedure} i/o-error-position condition
1370 A subtype of @code{&i/o}; represents an error related to an attempt to
1371 set the file position to an invalid position.
1374 @deffn {Condition Type} &i/o-filename
1375 @deffnx {Scheme Procedure} make-io-filename-error filename
1376 @deffnx {Scheme Procedure} i/o-filename-error? obj
1377 @deffnx {Scheme Procedure} i/o-error-filename condition
1378 A subtype of @code{&i/o}; represents an error related to an operation on
1382 @deffn {Condition Type} &i/o-file-protection
1383 @deffnx {Scheme Procedure} make-i/o-file-protection-error filename
1384 @deffnx {Scheme Procedure} i/o-file-protection-error? obj
1385 A subtype of @code{&i/o-filename}; represents an error resulting from an
1386 attempt to access a named file for which the caller had insufficient
1390 @deffn {Condition Type} &i/o-file-is-read-only
1391 @deffnx {Scheme Procedure} make-i/o-file-is-read-only-error filename
1392 @deffnx {Scheme Procedure} i/o-file-is-read-only-error? obj
1393 A subtype of @code{&i/o-file-protection}; represents an error related to
1394 an attempt to write to a read-only file.
1397 @deffn {Condition Type} &i/o-file-already-exists
1398 @deffnx {Scheme Procedure} make-i/o-file-already-exists-error filename
1399 @deffnx {Scheme Procedure} i/o-file-already-exists-error? obj
1400 A subtype of @code{&i/o-filename}; represents an error related to an
1401 operation on an existing file that was assumed not to exist.
1404 @deffn {Condition Type} &i/o-file-does-not-exist
1405 @deffnx {Scheme Procedure} make-i/o-file-does-not-exist-error
1406 @deffnx {Scheme Procedure} i/o-file-does-not-exist-error? obj
1407 A subtype of @code{&i/o-filename}; represents an error related to an
1408 operation on a non-existent file that was assumed to exist.
1411 @deffn {Condition Type} &i/o-port
1412 @deffnx {Scheme Procedure} make-i/o-port-error port
1413 @deffnx {Scheme Procedure} i/o-port-error? obj
1414 @deffnx {Scheme Procedure} i/o-error-port condition
1415 A subtype of @code{&i/o}; represents an error related to an operation on
1416 the port @var{port}.
1420 @subsubsection rnrs io ports
1422 The @code{(rnrs io ports (6))} library provides various procedures and
1423 syntactic forms for use in writing to and reading from ports. This
1424 functionality is documented in its own section of the manual;
1425 (@pxref{R6RS I/O Ports}).
1427 @node rnrs io simple
1428 @subsubsection rnrs io simple
1430 The @code{(rnrs io simple (6))} library provides convenience functions
1431 for performing textual I/O on ports. This library also exports all of
1432 the condition types and associated procedures described in (@pxref{I/O
1433 Conditions}). In the context of this section, when stating that a
1434 procedure behaves ``identically'' to the corresponding procedure in
1435 Guile's core library, this is modulo the behavior wrt. conditions: such
1436 procedures raise the appropriate R6RS conditions in case of error, but
1437 otherwise behave identically.
1439 @c FIXME: remove the following note when proper condition behavior has
1443 There are still known issues regarding condition-correctness; some
1444 errors may still be thrown as native Guile exceptions instead of the
1445 appropriate R6RS conditions.
1448 @deffn {Scheme Procedure} eof-object
1449 @deffnx {Scheme Procedure} eof-object? obj
1450 These procedures are identical to the ones provided by the
1451 @code{(rnrs io ports (6))} library. @xref{R6RS I/O Ports}, for
1455 @deffn {Scheme Procedure} input-port? obj
1456 @deffnx {Scheme Procedure} output-port? obj
1457 These procedures are identical to the ones provided by Guile's core
1458 library. @xref{Ports}, for documentation.
1461 @deffn {Scheme Procedure} call-with-input-file filename proc
1462 @deffnx {Scheme Procedure} call-with-output-file filename proc
1463 @deffnx {Scheme Procedure} open-input-file filename
1464 @deffnx {Scheme Procedure} open-output-file filename
1465 @deffnx {Scheme Procedure} with-input-from-file filename thunk
1466 @deffnx {Scheme Procedure} with-output-to-file filename thunk
1467 These procedures are identical to the ones provided by Guile's core
1468 library. @xref{File Ports}, for documentation.
1471 @deffn {Scheme Procedure} close-input-port input-port
1472 @deffnx {Scheme Procedure} close-output-port output-port
1473 These procedures are identical to the ones provided by Guile's core
1474 library. @xref{Closing}, for documentation.
1477 @deffn {Scheme Procedure} peek-char
1478 @deffnx {Scheme Procedure} peek-char textual-input-port
1479 @deffnx {Scheme Procedure} read-char
1480 @deffnx {Scheme Procedure} read-char textual-input-port
1481 These procedures are identical to the ones provided by Guile's core
1482 library. @xref{Reading}, for documentation.
1485 @deffn {Scheme Procedure} read
1486 @deffnx {Scheme Procedure} read textual-input-port
1487 This procedure is identical to the one provided by Guile's core library.
1488 @xref{Scheme Read}, for documentation.
1491 @deffn {Scheme Procedure} display obj
1492 @deffnx {Scheme Procedure} display obj textual-output-port
1493 @deffnx {Scheme Procedure} newline
1494 @deffnx {Scheme Procedure} newline textual-output-port
1495 @deffnx {Scheme Procedure} write obj
1496 @deffnx {Scheme Procedure} write obj textual-output-port
1497 @deffnx {Scheme Procedure} write-char char
1498 @deffnx {Scheme Procedure} write-char char textual-output-port
1499 These procedures are identical to the ones provided by Guile's core
1500 library. @xref{Writing}, for documentation.
1504 @subsubsection rnrs files
1506 The @code{(rnrs files (6))} library provides the @code{file-exists?} and
1507 @code{delete-file} procedures, which test for the existence of a file
1508 and allow the deletion of files from the file system, respectively.
1510 These procedures are identical to the ones provided by Guile's core
1511 library. @xref{File System}, for documentation.
1514 @subsubsection rnrs programs
1516 The @code{(rnrs programs (6))} library provides procedures for
1517 process management and introspection.
1519 @deffn {Scheme Procedure} command-line
1520 This procedure is identical to the one provided by Guile's core library.
1521 @xref{Runtime Environment}, for documentation.
1524 @deffn {Scheme Procedure} exit [status]
1525 This procedure is identical to the one provided by Guile's core
1526 library. @xref{Processes}, for documentation.
1529 @node rnrs arithmetic fixnums
1530 @subsubsection rnrs arithmetic fixnums
1532 The @code{(rnrs arithmetic fixnums (6))} library provides procedures for
1533 performing arithmetic operations on an implementation-dependent range of
1534 exact integer values, which R6RS refers to as @dfn{fixnums}. In Guile,
1535 the size of a fixnum is determined by the size of the @code{SCM} type; a
1536 single SCM struct is guaranteed to be able to hold an entire fixnum,
1537 making fixnum computations particularly
1538 efficient---(@pxref{The SCM Type}). On 32-bit systems, the most
1539 negative and most positive fixnum values are, respectively, -536870912
1542 Unless otherwise specified, all of the procedures below take fixnums as
1543 arguments, and will raise an @code{&assertion} condition if passed a
1544 non-fixnum argument or an @code{&implementation-restriction} condition
1545 if their result is not itself a fixnum.
1547 @deffn {Scheme Procedure} fixnum? obj
1548 Returns @code{#t} if @var{obj} is a fixnum, @code{#f} otherwise.
1551 @deffn {Scheme Procedure} fixnum-width
1552 @deffnx {Scheme Procedure} least-fixnum
1553 @deffnx {Scheme Procedure} greatest-fixnum
1554 These procedures return, respectively, the maximum number of bits
1555 necessary to represent a fixnum value in Guile, the minimum fixnum
1556 value, and the maximum fixnum value.
1559 @deffn {Scheme Procedure} fx=? fx1 fx2 fx3 ...
1560 @deffnx {Scheme Procedure} fx>? fx1 fx2 fx3 ...
1561 @deffnx {Scheme Procedure} fx<? fx1 fx2 fx3 ...
1562 @deffnx {Scheme Procedure} fx>=? fx1 fx2 fx3 ...
1563 @deffnx {Scheme Procedure} fx<=? fx1 fx2 fx3 ...
1564 These procedures return @code{#t} if their fixnum arguments are
1565 (respectively): equal, monotonically increasing, monotonically
1566 decreasing, monotonically nondecreasing, or monotonically nonincreasing;
1567 @code{#f} otherwise.
1570 @deffn {Scheme Procedure} fxzero? fx
1571 @deffnx {Scheme Procedure} fxpositive? fx
1572 @deffnx {Scheme Procedure} fxnegative? fx
1573 @deffnx {Scheme Procedure} fxodd? fx
1574 @deffnx {Scheme Procedure} fxeven? fx
1575 These numerical predicates return @code{#t} if @var{fx} is,
1576 respectively, zero, greater than zero, less than zero, odd, or even;
1577 @code{#f} otherwise.
1580 @deffn {Scheme Procedure} fxmax fx1 fx2 ...
1581 @deffnx {Scheme Procedure} fxmin fx1 fx2 ...
1582 These procedures return the maximum or minimum of their arguments.
1585 @deffn {Scheme Procedure} fx+ fx1 fx2
1586 @deffnx {Scheme Procedure} fx* fx1 fx2
1587 These procedures return the sum or product of their arguments.
1590 @deffn {Scheme Procedure} fx- fx1 fx2
1591 @deffnx {Scheme Procedure} fx- fx
1592 Returns the difference of @var{fx1} and @var{fx2}, or the negation of
1593 @var{fx}, if called with a single argument.
1595 An @code{&assertion} condition is raised if the result is not itself a
1599 @deffn {Scheme Procedure} fxdiv-and-mod fx1 fx2
1600 @deffnx {Scheme Procedure} fxdiv fx1 fx2
1601 @deffnx {Scheme Procedure} fxmod fx1 fx2
1602 @deffnx {Scheme Procedure} fxdiv0-and-mod0 fx1 fx2
1603 @deffnx {Scheme Procedure} fxdiv0 fx1 fx2
1604 @deffnx {Scheme Procedure} fxmod0 fx1 fx2
1605 These procedures implement number-theoretic division on fixnums;
1606 @xref{(rnrs base)}, for a description of their semantics.
1609 @deffn {Scheme Procedure} fx+/carry fx1 fx2 fx3
1610 Returns the two fixnum results of the following computation:
1612 (let* ((s (+ fx1 fx2 fx3))
1613 (s0 (mod0 s (expt 2 (fixnum-width))))
1614 (s1 (div0 s (expt 2 (fixnum-width)))))
1619 @deffn {Scheme Procedure} fx-/carry fx1 fx2 fx3
1620 Returns the two fixnum results of the following computation:
1622 (let* ((d (- fx1 fx2 fx3))
1623 (d0 (mod0 d (expt 2 (fixnum-width))))
1624 (d1 (div0 d (expt 2 (fixnum-width)))))
1629 @deffn {Scheme Procedure} fx*/carry fx1 fx2 fx3
1631 Returns the two fixnum results of the following computation:
1632 (let* ((s (+ (* fx1 fx2) fx3))
1633 (s0 (mod0 s (expt 2 (fixnum-width))))
1634 (s1 (div0 s (expt 2 (fixnum-width)))))
1639 @deffn {Scheme Procedure} fxnot fx
1640 @deffnx {Scheme Procedure} fxand fx1 ...
1641 @deffnx {Scheme Procedure} fxior fx1 ...
1642 @deffnx {Scheme Procedure} fxxor fx1 ...
1643 These procedures are identical to the @code{lognot}, @code{logand},
1644 @code{logior}, and @code{logxor} procedures provided by Guile's core
1645 library. @xref{Bitwise Operations}, for documentation.
1648 @deffn {Scheme Procedure} fxif fx1 fx2 fx3
1649 Returns the bitwise ``if'' of its fixnum arguments. The bit at position
1650 @code{i} in the return value will be the @code{i}th bit from @var{fx2}
1651 if the @code{i}th bit of @var{fx1} is 1, the @code{i}th bit from
1655 @deffn {Scheme Procedure} fxbit-count fx
1656 Returns the number of 1 bits in the two's complement representation of
1660 @deffn {Scheme Procedure} fxlength fx
1661 Returns the number of bits necessary to represent @var{fx}.
1664 @deffn {Scheme Procedure} fxfirst-bit-set fx
1665 Returns the index of the least significant 1 bit in the two's complement
1666 representation of @var{fx}.
1669 @deffn {Scheme Procedure} fxbit-set? fx1 fx2
1670 Returns @code{#t} if the @var{fx2}th bit in the two's complement
1671 representation of @var{fx1} is 1, @code{#f} otherwise.
1674 @deffn {Scheme Procedure} fxcopy-bit fx1 fx2 fx3
1675 Returns the result of setting the @var{fx2}th bit of @var{fx1} to the
1676 @var{fx2}th bit of @var{fx3}.
1679 @deffn {Scheme Procedure} fxbit-field fx1 fx2 fx3
1680 Returns the integer representation of the contiguous sequence of bits in
1681 @var{fx1} that starts at position @var{fx2} (inclusive) and ends at
1682 position @var{fx3} (exclusive).
1685 @deffn {Scheme Procedure} fxcopy-bit-field fx1 fx2 fx3 fx4
1686 Returns the result of replacing the bit field in @var{fx1} with start
1687 and end positions @var{fx2} and @var{fx3} with the corresponding bit
1688 field from @var{fx4}.
1691 @deffn {Scheme Procedure} fxarithmetic-shift fx1 fx2
1692 @deffnx {Scheme Procedure} fxarithmetic-shift-left fx1 fx2
1693 @deffnx {Scheme Procedure} fxarithmetic-shift-right fx1 fx2
1694 Returns the result of shifting the bits of @var{fx1} right or left by
1695 the @var{fx2} positions. @code{fxarithmetic-shift} is identical
1696 to @code{fxarithmetic-shift-left}.
1699 @deffn {Scheme Procedure} fxrotate-bit-field fx1 fx2 fx3 fx4
1700 Returns the result of cyclically permuting the bit field in @var{fx1}
1701 with start and end positions @var{fx2} and @var{fx3} by @var{fx4} bits
1702 in the direction of more significant bits.
1705 @deffn {Scheme Procedure} fxreverse-bit-field fx1 fx2 fx3
1706 Returns the result of reversing the order of the bits of @var{fx1}
1707 between position @var{fx2} (inclusive) and position @var{fx3}
1711 @node rnrs arithmetic flonums
1712 @subsubsection rnrs arithmetic flonums
1714 The @code{(rnrs arithmetic flonums (6))} library provides procedures for
1715 performing arithmetic operations on inexact representations of real
1716 numbers, which R6RS refers to as @dfn{flonums}.
1718 Unless otherwise specified, all of the procedures below take flonums as
1719 arguments, and will raise an @code{&assertion} condition if passed a
1720 non-flonum argument.
1722 @deffn {Scheme Procedure} flonum? obj
1723 Returns @code{#t} if @var{obj} is a flonum, @code{#f} otherwise.
1726 @deffn {Scheme Procedure} real->flonum x
1727 Returns the flonum that is numerically closest to the real number
1731 @deffn {Scheme Procedure} fl=? fl1 fl2 fl3 ...
1732 @deffnx {Scheme Procedure} fl<? fl1 fl2 fl3 ...
1733 @deffnx {Scheme Procedure} fl<=? fl1 fl2 fl3 ...
1734 @deffnx {Scheme Procedure} fl>? fl1 fl2 fl3 ...
1735 @deffnx {Scheme Procedure} fl>=? fl1 fl2 fl3 ...
1736 These procedures return @code{#t} if their flonum arguments are
1737 (respectively): equal, monotonically increasing, monotonically
1738 decreasing, monotonically nondecreasing, or monotonically nonincreasing;
1739 @code{#f} otherwise.
1742 @deffn {Scheme Procedure} flinteger? fl
1743 @deffnx {Scheme Procedure} flzero? fl
1744 @deffnx {Scheme Procedure} flpositive? fl
1745 @deffnx {Scheme Procedure} flnegative? fl
1746 @deffnx {Scheme Procedure} flodd? fl
1747 @deffnx {Scheme Procedure} fleven? fl
1748 These numerical predicates return @code{#t} if @var{fl} is,
1749 respectively, an integer, zero, greater than zero, less than zero, odd,
1750 even, @code{#f} otherwise. In the case of @code{flodd?} and
1751 @code{fleven?}, @var{fl} must be an integer-valued flonum.
1754 @deffn {Scheme Procedure} flfinite? fl
1755 @deffnx {Scheme Procedure} flinfinite? fl
1756 @deffnx {Scheme Procedure} flnan? fl
1757 These numerical predicates return @code{#t} if @var{fl} is,
1758 respectively, not infinite, infinite, or a @code{NaN} value.
1761 @deffn {Scheme Procedure} flmax fl1 fl2 ...
1762 @deffnx {Scheme Procedure} flmin fl1 fl2 ...
1763 These procedures return the maximum or minimum of their arguments.
1766 @deffn {Scheme Procedure} fl+ fl1 ...
1767 @deffnx {Scheme Procedure} fl* fl ...
1768 These procedures return the sum or product of their arguments.
1771 @deffn {Scheme Procedure} fl- fl1 fl2 ...
1772 @deffnx {Scheme Procedure} fl- fl
1773 @deffnx {Scheme Procedure} fl/ fl1 fl2 ...
1774 @deffnx {Scheme Procedure} fl/ fl
1775 These procedures return, respectively, the difference or quotient of
1776 their arguments when called with two arguments; when called with a
1777 single argument, they return the additive or multiplicative inverse of
1781 @deffn {Scheme Procedure} flabs fl
1782 Returns the absolute value of @var{fl}.
1785 @deffn {Scheme Procedure} fldiv-and-mod fl1 fl2
1786 @deffnx {Scheme Procedure} fldiv fl1 fl2
1787 @deffnx {Scheme Procedure} fldmod fl1 fl2
1788 @deffnx {Scheme Procedure} fldiv0-and-mod0 fl1 fl2
1789 @deffnx {Scheme Procedure} fldiv0 fl1 fl2
1790 @deffnx {Scheme Procedure} flmod0 fl1 fl2
1791 These procedures implement number-theoretic division on flonums;
1792 @xref{(rnrs base)}, for a description for their semantics.
1795 @deffn {Scheme Procedure} flnumerator fl
1796 @deffnx {Scheme Procedure} fldenominator fl
1797 These procedures return the numerator or denominator of @var{fl} as a
1801 @deffn {Scheme Procedure} flfloor fl1
1802 @deffnx {Scheme Procedure} flceiling fl
1803 @deffnx {Scheme Procedure} fltruncate fl
1804 @deffnx {Scheme Procedure} flround fl
1805 These procedures are identical to the @code{floor}, @code{ceiling},
1806 @code{truncate}, and @code{round} procedures provided by Guile's core
1807 library. @xref{Arithmetic}, for documentation.
1810 @deffn {Scheme Procedure} flexp fl
1811 @deffnx {Scheme Procedure} fllog fl
1812 @deffnx {Scheme Procedure} fllog fl1 fl2
1813 @deffnx {Scheme Procedure} flsin fl
1814 @deffnx {Scheme Procedure} flcos fl
1815 @deffnx {Scheme Procedure} fltan fl
1816 @deffnx {Scheme Procedure} flasin fl
1817 @deffnx {Scheme Procedure} flacos fl
1818 @deffnx {Scheme Procedure} flatan fl
1819 @deffnx {Scheme Procedure} flatan fl1 fl2
1820 These procedures, which compute the usual transcendental functions, are
1821 the flonum variants of the procedures provided by the R6RS base library
1822 (@pxref{(rnrs base)}).
1825 @deffn {Scheme Procedure} flsqrt fl
1826 Returns the square root of @var{fl}. If @var{fl} is @code{-0.0},
1827 @var{-0.0} is returned; for other negative values, a @code{NaN} value
1831 @deffn {Scheme Procedure} flexpt fl1 fl2
1832 Returns the value of @var{fl1} raised to the power of @var{fl2}.
1835 The following condition types are provided to allow Scheme
1836 implementations that do not support infinities or @code{NaN} values
1837 to indicate that a computation resulted in such a value. Guile supports
1838 both of these, so these conditions will never be raised by Guile's
1839 standard libraries implementation.
1841 @deffn {Condition Type} &no-infinities
1842 @deffnx {Scheme Procedure} make-no-infinities-violation obj
1843 @deffnx {Scheme Procedure} no-infinities-violation?
1844 A condition type indicating that a computation resulted in an infinite
1845 value on a Scheme implementation incapable of representing infinities.
1848 @deffn {Condition Type} &no-nans
1849 @deffnx {Scheme Procedure} make-no-nans-violation obj
1850 @deffnx {Scheme Procedure} no-nans-violation? obj
1851 A condition type indicating that a computation resulted in a @code{NaN}
1852 value on a Scheme implementation incapable of representing @code{NaN}s.
1855 @deffn {Scheme Procedure} fixnum->flonum fx
1856 Returns the flonum that is numerically closest to the fixnum @var{fx}.
1859 @node rnrs arithmetic bitwise
1860 @subsubsection rnrs arithmetic bitwise
1862 The @code{(rnrs arithmetic bitwise (6))} library provides procedures for
1863 performing bitwise arithmetic operations on the two's complement
1864 representations of fixnums.
1866 This library and the procedures it exports share functionality with
1867 SRFI-60, which provides support for bitwise manipulation of integers
1870 @deffn {Scheme Procedure} bitwise-not ei
1871 @deffnx {Scheme Procedure} bitwise-and ei1 ...
1872 @deffnx {Scheme Procedure} bitwise-ior ei1 ...
1873 @deffnx {Scheme Procedure} bitwise-xor ei1 ...
1874 These procedures are identical to the @code{lognot}, @code{logand},
1875 @code{logior}, and @code{logxor} procedures provided by Guile's core
1876 library. @xref{Bitwise Operations}, for documentation.
1879 @deffn {Scheme Procedure} bitwise-if ei1 ei2 ei3
1880 Returns the bitwise ``if'' of its arguments. The bit at position
1881 @code{i} in the return value will be the @code{i}th bit from @var{ei2}
1882 if the @code{i}th bit of @var{ei1} is 1, the @code{i}th bit from
1886 @deffn {Scheme Procedure} bitwise-bit-count ei
1887 Returns the number of 1 bits in the two's complement representation of
1891 @deffn {Scheme Procedure} bitwise-length ei
1892 Returns the number of bits necessary to represent @var{ei}.
1895 @deffn {Scheme Procedure} bitwise-first-bit-set ei
1896 Returns the index of the least significant 1 bit in the two's complement
1897 representation of @var{ei}.
1900 @deffn {Scheme Procedure} bitwise-bit-set? ei1 ei2
1901 Returns @code{#t} if the @var{ei2}th bit in the two's complement
1902 representation of @var{ei1} is 1, @code{#f} otherwise.
1905 @deffn {Scheme Procedure} bitwise-copy-bit ei1 ei2 ei3
1906 Returns the result of setting the @var{ei2}th bit of @var{ei1} to the
1907 @var{ei2}th bit of @var{ei3}.
1910 @deffn {Scheme Procedure} bitwise-bit-field ei1 ei2 ei3
1911 Returns the integer representation of the contiguous sequence of bits in
1912 @var{ei1} that starts at position @var{ei2} (inclusive) and ends at
1913 position @var{ei3} (exclusive).
1916 @deffn {Scheme Procedure} bitwise-copy-bit-field ei1 ei2 ei3 ei4
1917 Returns the result of replacing the bit field in @var{ei1} with start
1918 and end positions @var{ei2} and @var{ei3} with the corresponding bit
1919 field from @var{ei4}.
1922 @deffn {Scheme Procedure} bitwise-arithmetic-shift ei1 ei2
1923 @deffnx {Scheme Procedure} bitwise-arithmetic-shift-left ei1 ei2
1924 @deffnx {Scheme Procedure} bitwise-arithmetic-shift-right ei1 ei2
1925 Returns the result of shifting the bits of @var{ei1} right or left by
1926 the @var{ei2} positions. @code{bitwise-arithmetic-shift} is identical
1927 to @code{bitwise-arithmetic-shift-left}.
1930 @deffn {Scheme Procedure} bitwise-rotate-bit-field ei1 ei2 ei3 ei4
1931 Returns the result of cyclically permuting the bit field in @var{ei1}
1932 with start and end positions @var{ei2} and @var{ei3} by @var{ei4} bits
1933 in the direction of more significant bits.
1936 @deffn {Scheme Procedure} bitwise-reverse-bit-field ei1 ei2 ei3
1937 Returns the result of reversing the order of the bits of @var{ei1}
1938 between position @var{ei2} (inclusive) and position @var{ei3}
1942 @node rnrs syntax-case
1943 @subsubsection rnrs syntax-case
1945 The @code{(rnrs syntax-case (6))} library provides access to the
1946 @code{syntax-case} system for writing hygienic macros. With one
1947 exception, all of the forms and procedures exported by this library
1948 are ``re-exports'' of Guile's native support for @code{syntax-case};
1949 @xref{Syntax Case}, for documentation, examples, and rationale.
1951 @deffn {Scheme Procedure} make-variable-transformer proc
1952 Creates a new variable transformer out of @var{proc}, a procedure that
1953 takes a syntax object as input and returns a syntax object. If an
1954 identifier to which the result of this procedure is bound appears on the
1955 left-hand side of a @code{set!} expression, @var{proc} will be called
1956 with a syntax object representing the entire @code{set!} expression,
1957 and its return value will replace that @code{set!} expression.
1960 @deffn {Scheme Syntax} syntax-case expression (literal ...) clause ...
1961 The @code{syntax-case} pattern matching form.
1964 @deffn {Scheme Syntax} syntax template
1965 @deffnx {Scheme Syntax} quasisyntax template
1966 @deffnx {Scheme Syntax} unsyntax template
1967 @deffnx {Scheme Syntax} unsyntax-splicing template
1968 These forms allow references to be made in the body of a syntax-case
1969 output expression subform to datum and non-datum values. They are
1970 identical to the forms provided by Guile's core library;
1971 @xref{Syntax Case}, for documentation.
1974 @deffn {Scheme Procedure} identifier? obj
1975 @deffnx {Scheme Procedure} bound-identifier=? id1 id2
1976 @deffnx {Scheme Procedure} free-identifier=? id1 id2
1977 These predicate procedures operate on syntax objects representing
1978 Scheme identifiers. @code{identifier?} returns @code{#t} if @var{obj}
1979 represents an identifier, @code{#f} otherwise.
1980 @code{bound-identifier=?} returns @code{#t} if and only if a binding for
1981 @var{id1} would capture a reference to @var{id2} in the transformer's
1982 output, or vice-versa. @code{free-identifier=?} returns @code{#t} if
1983 and only @var{id1} and @var{id2} would refer to the same binding in the
1984 output of the transformer, independent of any bindings introduced by the
1988 @deffn {Scheme Procedure} generate-temporaries l
1989 Returns a list, of the same length as @var{l}, which must be a list or
1990 a syntax object representing a list, of globally unique symbols.
1993 @deffn {Scheme Procedure} syntax->datum syntax-object
1994 @deffnx {Scheme Procedure} datum->syntax template-id datum
1995 These procedures convert wrapped syntax objects to and from Scheme datum
1996 values. The syntax object returned by @code{datum->syntax} shares
1997 contextual information with the syntax object @var{template-id}.
2000 @deffn {Scheme Procedure} syntax-violation whom message form
2001 @deffnx {Scheme Procedure} syntax-violation whom message form subform
2002 Constructs a new compound condition that includes the following
2006 If @var{whom} is not @code{#f}, a @code{&who} condition with the
2007 @var{whom} as its field
2009 A @code{&message} condition with the specified @var{message}
2011 A @code{&syntax} condition with the specified @var{form} and optional
2012 @var{subform} fields
2016 @node rnrs hashtables
2017 @subsubsection rnrs hashtables
2019 The @code{(rnrs hashtables (6))} library provides structures and
2020 procedures for creating and accessing hash tables. The hash tables API
2021 defined by R6RS is substantially similar to both Guile's native hash
2022 tables implementation as well as the one provided by SRFI-69;
2023 @xref{Hash Tables}, and @ref{SRFI-69}, respectively. Note that you can
2024 write portable R6RS library code that manipulates SRFI-69 hash tables
2025 (by importing the @code{(srfi :69)} library); however, hash tables
2026 created by one API cannot be used by another.
2028 Like SRFI-69 hash tables---and unlike Guile's native ones---R6RS hash
2029 tables associate hash and equality functions with a hash table at the
2030 time of its creation. Additionally, R6RS allows for the creation
2031 (via @code{hashtable-copy}; see below) of immutable hash tables.
2033 @deffn {Scheme Procedure} make-eq-hashtable
2034 @deffnx {Scheme Procedure} make-eq-hashtable k
2035 Returns a new hash table that uses @code{eq?} to compare keys and
2036 Guile's @code{hashq} procedure as a hash function. If @var{k} is given,
2037 it specifies the initial capacity of the hash table.
2040 @deffn {Scheme Procedure} make-eqv-hashtable
2041 @deffnx {Scheme Procedure} make-eqv-hashtable k
2042 Returns a new hash table that uses @code{eqv?} to compare keys and
2043 Guile's @code{hashv} procedure as a hash function. If @var{k} is given,
2044 it specifies the initial capacity of the hash table.
2047 @deffn {Scheme Procedure} make-hashtable hash-function equiv
2048 @deffnx {Scheme Procedure} make-hashtable hash-function equiv k
2049 Returns a new hash table that uses @var{equiv} to compare keys and
2050 @var{hash-function} as a hash function. @var{equiv} must be a procedure
2051 that accepts two arguments and returns a true value if they are
2052 equivalent, @code{#f} otherwise; @var{hash-function} must be a procedure
2053 that accepts one argument and returns a non-negative integer.
2055 If @var{k} is given, it specifies the initial capacity of the hash
2059 @deffn {Scheme Procedure} hashtable? obj
2060 Returns @code{#t} if @var{obj} is an R6RS hash table, @code{#f}
2064 @deffn {Scheme Procedure} hashtable-size hashtable
2065 Returns the number of keys currently in the hash table @var{hashtable}.
2068 @deffn {Scheme Procedure} hashtable-ref hashtable key default
2069 Returns the value associated with @var{key} in the hash table
2070 @var{hashtable}, or @var{default} if none is found.
2073 @deffn {Scheme Procedure} hashtable-set! hashtable key obj
2074 Associates the key @var{key} with the value @var{obj} in the hash table
2075 @var{hashtable}, and returns an unspecified value. An @code{&assertion}
2076 condition is raised if @var{hashtable} is immutable.
2079 @deffn {Scheme Procedure} hashtable-delete! hashtable key
2080 Removes any association found for the key @var{key} in the hash table
2081 @var{hashtable}, and returns an unspecified value. An @code{&assertion}
2082 condition is raised if @var{hashtable} is immutable.
2085 @deffn {Scheme Procedure} hashtable-contains? hashtable key
2086 Returns @code{#t} if the hash table @var{hashtable} contains an
2087 association for the key @var{key}, @code{#f} otherwise.
2090 @deffn {Scheme Procedure} hashtable-update! hashtable key proc default
2091 Associates with @var{key} in the hash table @var{hashtable} the result
2092 of calling @var{proc}, which must be a procedure that takes one
2093 argument, on the value currently associated @var{key} in
2094 @var{hashtable}---or on @var{default} if no such association exists.
2095 An @code{&assertion} condition is raised if @var{hashtable} is
2099 @deffn {Scheme Procedure} hashtable-copy hashtable
2100 @deffnx {Scheme Procedure} hashtable-copy hashtable mutable
2101 Returns a copy of the hash table @var{hashtable}. If the optional
2102 argument @var{mutable} is provided and is a true value, the new hash
2103 table will be mutable.
2106 @deffn {Scheme Procedure} hashtable-clear! hashtable
2107 @deffnx {Scheme Procedure} hashtable-clear! hashtable k
2108 Removes all of the associations from the hash table @var{hashtable}.
2109 The optional argument @var{k}, which specifies a new capacity for the
2110 hash table, is accepted by Guile's @code{(rnrs hashtables)}
2111 implementation, but is ignored.
2114 @deffn {Scheme Procedure} hashtable-keys hashtable
2115 Returns a vector of the keys with associations in the hash table
2116 @var{hashtable}, in an unspecified order.
2119 @deffn {Scheme Procedure} hashtable-entries hashtable
2120 Return two values---a vector of the keys with associations in the hash
2121 table @var{hashtable}, and a vector of the values to which these keys
2122 are mapped, in corresponding but unspecified order.
2125 @deffn {Scheme Procedure} hashtable-equivalence-function hashtable
2126 Returns the equivalence predicated use by @var{hashtable}. This
2127 procedure returns @code{eq?} and @code{eqv?}, respectively, for hash
2128 tables created by @code{make-eq-hashtable} and
2129 @code{make-eqv-hashtable}.
2132 @deffn {Scheme Procedure} hashtable-hash-function hashtable
2133 Returns the hash function used by @var{hashtable}. For hash tables
2134 created by @code{make-eq-hashtable} or @code{make-eqv-hashtable},
2135 @code{#f} is returned.
2138 @deffn {Scheme Procedure} hashtable-mutable? hashtable
2139 Returns @code{#t} if @var{hashtable} is mutable, @code{#f} otherwise.
2142 A number of hash functions are provided for convenience:
2144 @deffn {Scheme Procedure} equal-hash obj
2145 Returns an integer hash value for @var{obj}, based on its structure and
2146 current contents. This hash function is suitable for use with
2147 @code{equal?} as an equivalence function.
2150 @deffn {Scheme Procedure} string-hash string
2151 @deffnx {Scheme Procedure} symbol-hash symbol
2152 These procedures are identical to the ones provided by Guile's core
2153 library. @xref{Hash Table Reference}, for documentation.
2156 @deffn {Scheme Procedure} string-ci-hash string
2157 Returns an integer hash value for @var{string} based on its contents,
2158 ignoring case. This hash function is suitable for use with
2159 @code{string-ci=?} as an equivalence function.
2163 @subsubsection rnrs enums
2165 The @code{(rnrs enums (6))} library provides structures and procedures
2166 for working with enumerable sets of symbols. Guile's implementation
2167 defines an @dfn{enum-set} record type that encapsulates a finite set of
2168 distinct symbols, the @dfn{universe}, and a subset of these symbols,
2169 which define the enumeration set.
2171 The SRFI-1 list library provides a number of procedures for performing
2172 set operations on lists; Guile's @code{(rnrs enums)} implementation
2173 makes use of several of them. @xref{SRFI-1 Set Operations}, for
2176 @deffn {Scheme Procedure} make-enumeration symbol-list
2177 Returns a new enum-set whose universe and enumeration set are both equal
2178 to @var{symbol-list}, a list of symbols.
2181 @deffn {Scheme Procedure} enum-set-universe enum-set
2182 Returns an enum-set representing the universe of @var{enum-set},
2186 @deffn {Scheme Procedure} enum-set-indexer enum-set
2187 Returns a procedure that takes a single argument and returns the
2188 zero-indexed position of that argument in the universe of
2189 @var{enum-set}, or @code{#f} if its argument is not a member of that
2193 @deffn {Scheme Procedure} enum-set-constructor enum-set
2194 Returns a procedure that takes a single argument, a list of symbols
2195 from the universe of @var{enum-set}, an enum-set, and returns a new
2196 enum-set with the same universe that represents a subset containing the
2200 @deffn {Scheme Procedure} enum-set->list enum-set
2201 Returns a list containing the symbols of the set represented by
2202 @var{enum-set}, an enum-set, in the order that they appear in the
2203 universe of @var{enum-set}.
2206 @deffn {Scheme Procedure} enum-set-member? symbol enum-set
2207 @deffnx {Scheme Procedure} enum-set-subset? enum-set1 enum-set2
2208 @deffnx {Scheme Procedure} enum-set=? enum-set1 enum-set2
2209 These procedures test for membership of symbols and enum-sets in other
2210 enum-sets. @code{enum-set-member?} returns @code{#t} if and only if
2211 @var{symbol} is a member of the subset specified by @var{enum-set}.
2212 @code{enum-set-subset?} returns @code{#t} if and only if the universe of
2213 @var{enum-set1} is a subset of the universe of @var{enum-set2} and
2214 every symbol in @var{enum-set1} is present in @var{enum-set2}.
2215 @code{enum-set=?} returns @code{#t} if and only if @var{enum-set1} is a
2216 subset, as per @code{enum-set-subset?} of @var{enum-set2} and vice
2220 @deffn {Scheme Procedure} enum-set-union enum-set1 enum-set2
2221 @deffnx {Scheme Procedure} enum-set-intersection enum-set1 enum-set2
2222 @deffnx {Scheme Procedure} enum-set-difference enum-set1 enum-set2
2223 These procedures return, respectively, the union, intersection, and
2224 difference of their enum-set arguments.
2227 @deffn {Scheme Procedure} enum-set-complement enum-set
2228 Returns @var{enum-set}'s complement (an enum-set), with regard to its
2232 @deffn {Scheme Procedure} enum-set-projection enum-set1 enum-set2
2233 Returns the projection of the enum-set @var{enum-set1} onto the universe
2234 of the enum-set @var{enum-set2}.
2237 @deffn {Scheme Syntax} define-enumeration type-name (symbol ...) constructor-syntax
2238 Evaluates to two new definitions: A constructor bound to
2239 @var{constructor-syntax} that behaves similarly to constructors created
2240 by @code{enum-set-constructor}, above, and creates new @var{enum-set}s
2241 in the universe specified by @code{(symbol ...)}; and a ``predicate
2242 macro'' bound to @var{type-name}, which has the following form:
2245 (@var{type-name} sym)
2248 If @var{sym} is a member of the universe specified by the @var{symbol}s
2249 above, this form evaluates to @var{sym}. Otherwise, a @code{&syntax}
2250 condition is raised.
2256 The @code{(rnrs (6))} library is a composite of all of the other R6RS
2257 standard libraries---it imports and re-exports all of their exported
2258 procedures and syntactic forms---with the exception of the following
2262 @item @code{(rnrs eval (6))}
2263 @item @code{(rnrs mutable-pairs (6))}
2264 @item @code{(rnrs mutable-strings (6))}
2265 @item @code{(rnrs r5rs (6))}
2269 @subsubsection rnrs eval
2271 The @code{(rnrs eval (6)} library provides procedures for performing
2272 ``on-the-fly'' evaluation of expressions.
2274 @deffn {Scheme Procedure} eval expression environment
2275 Evaluates @var{expression}, which must be a datum representation of a
2276 valid Scheme expression, in the environment specified by
2277 @var{environment}. This procedure is identical to the one provided by
2278 Guile's code library; @xref{Fly Evaluation}, for documentation.
2281 @deffn {Scheme Procedure} environment import-spec ...
2282 Constructs and returns a new environment based on the specified
2283 @var{import-spec}s, which must be datum representations of the import
2284 specifications used with the @code{import} form. @xref{R6RS Libraries},
2288 @node rnrs mutable-pairs
2289 @subsubsection rnrs mutable-pairs
2291 The @code{(rnrs mutable-pairs (6))} library provides the @code{set-car!}
2292 and @code{set-cdr!} procedures, which allow the @code{car} and
2293 @code{cdr} fields of a pair to be modified.
2295 These procedures are identical to the ones provide by Guile's core
2296 library. @xref{Pairs}, for documentation. All pairs in Guile are
2297 mutable; consequently, these procedures will never throw the
2298 @code{&assertion} condition described in the R6RS libraries
2301 @node rnrs mutable-strings
2302 @subsubsection rnrs mutable-strings
2304 The @code{(rnrs mutable-strings (6))} library provides the
2305 @code{string-set!} and @code{string-fill!} procedures, which allow the
2306 content of strings to be modified ``in-place.''
2308 These procedures are identical to the ones provided by Guile's core
2309 library. @xref{String Modification}, for documentation. All strings in
2310 Guile are mutable; consequently, these procedures will never throw the
2311 @code{&assertion} condition described in the R6RS libraries
2315 @subsubsection rnrs r5rs
2317 The @code{(rnrs r5rs (6))} library exports bindings for some procedures
2318 present in R5RS but omitted from the R6RS base library specification.
2320 @deffn {Scheme Procedure} exact->inexact z
2321 @deffnx {Scheme Procedure} inexact->exact z
2322 These procedures are identical to the ones provided by Guile's core
2323 library. @xref{Exactness}, for documentation.
2326 @deffn {Scheme Procedure} quotient n1 n2
2327 @deffnx {Scheme Procedure} remainder n1 n2
2328 @deffnx {Scheme Procedure} modulo n1 n2
2329 These procedures are identical to the ones provided by Guile's core
2330 library. @xref{Integer Operations}, for documentation.
2333 @deffn {Scheme Syntax} delay expr
2334 @deffnx {Scheme Procedure} force promise
2335 The @code{delay} form and the @code{force} procedure are identical to
2336 their counterparts in Guile's core library. @xref{Delayed Evaluation},
2340 @deffn {Scheme Procedure} null-environment n
2341 @deffnx {Scheme Procedure} scheme-report-environment n
2342 These procedures are identical to the ones provided by the
2343 @code{(ice-9 r5rs)} Guile module. @xref{Environments}, for
2347 @c r6rs.texi ends here
2350 @c TeX-master: "guile.texi"