2 @c This is part of the GNU Guile Reference Manual.
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. R6RS behavior can
42 be turned on via a reader option. @xref{String Syntax}, for more
46 A @code{set!} to a variable transformer may only expand to an
47 expression, not a definition---even if the original @code{set!}
48 expression was in definition context.
51 Instead of using the algorithm detailed in chapter 10 of the R6RS,
52 expansion of toplevel forms happens sequentially.
54 For example, while the expansion of the following set of recursive
55 nested definitions does do the correct thing:
61 (or (= x 0) (odd? (- x 1)))))
64 ((odd? x) (not (even? x)))))
70 The same definitions at the toplevel do not:
76 (or (= x 0) (odd? (- x 1)))))
79 ((odd? x) (not (even? x)))))
81 <unnamed port>:4:18: In procedure even?:
82 <unnamed port>:4:18: Wrong type to apply: #<syntax-transformer odd?>
85 This is because when expanding the right-hand-side of @code{even?}, the
86 reference to @code{odd?} is not yet marked as a syntax transformer, so
87 it is assumed to be a function.
89 While it is likely that we can fix the case of toplevel forms nested in
90 a @code{begin} or a @code{library} form, a fix for toplevel programs
91 seems trickier to implement in a backward-compatible way. Suggestions
92 and/or patches would be appreciated.
95 @node R6RS Standard Libraries
96 @subsection R6RS Standard Libraries
98 In contrast with earlier versions of the Revised Report, the R6RS
99 organizes the procedures and syntactic forms required of conforming
100 implementations into a set of ``standard libraries'' which can be
101 imported as necessary by user programs and libraries. Here we briefly
102 list the libraries that have been implemented for Guile.
104 We do not attempt to document these libraries fully here, as most of
105 their functionality is already available in Guile itself. The
106 expectation is that most Guile users will use the well-known and
107 well-documented Guile modules. These R6RS libraries are mostly useful
108 to users who want to port their code to other R6RS systems.
110 The documentation in the following sections reproduces some of the
111 content of the library section of the Report, but is mostly intended to
112 provide supplementary information about Guile's implementation of the
113 R6RS standard libraries. For complete documentation, design rationales
114 and further examples, we advise you to consult the ``Standard
115 Libraries'' section of the Report (@pxref{Standard Libraries,
116 R6RS Standard Libraries,, r6rs, The Revised^6 Report on the Algorithmic
120 * Library Usage:: What to know about Guile's library support.
121 * rnrs base:: The base library.
122 * rnrs unicode:: Access to Unicode operations.
123 * rnrs bytevectors:: Functions for working with binary data.
124 * rnrs lists:: List utilities.
125 * rnrs sorting:: Sorting for lists and vectors.
126 * rnrs control:: Additional control structures.
128 * R6RS Records:: A note about R6RS records.
129 * rnrs records syntactic:: Syntactic API for R6RS records.
130 * rnrs records procedural:: Procedural API for R6RS records.
131 * rnrs records inspection:: Reflection on R6RS records.
133 * rnrs exceptions:: Handling exceptional situations.
134 * rnrs conditions:: Data structures for exceptions.
136 * I/O Conditions:: Predefined I/O error types.
137 * rnrs io ports:: Support for port-based I/O.
138 * rnrs io simple:: High-level I/O API.
140 * rnrs files:: Functions for working with files.
141 * rnrs programs:: Functions for working with processes.
142 * rnrs arithmetic fixnums:: Fixed-precision arithmetic operations.
143 * rnrs arithmetic flonums:: Floating-point arithmetic operations.
144 * rnrs arithmetic bitwise:: Exact bitwise arithmetic operations.
145 * rnrs syntax-case:: Support for `syntax-case' macros.
146 * rnrs hashtables:: Hashtables.
147 * rnrs enums:: Enumerations.
148 * rnrs:: The composite library.
149 * rnrs eval:: Support for on-the-fly evaluation.
150 * rnrs mutable-pairs:: Support for mutable pairs.
151 * rnrs mutable-strings:: Support for mutable strings.
152 * rnrs r5rs:: Compatibility layer for R5RS Scheme.
157 @subsubsection Library Usage
159 Guile implements the R6RS `library' form as a transformation to a native
160 Guile module definition. As a consequence of this, all of the libraries
161 described in the following subsections, in addition to being available
162 for use by R6RS libraries and top-level programs, can also be imported
163 as if they were normal Guile modules---via a @code{use-modules} form,
164 say. For example, the R6RS ``composite'' library can be imported by:
171 (use-modules ((rnrs) :version (6)))
174 For more information on Guile's library implementation, see
175 (@pxref{R6RS Libraries}).
178 @subsubsection rnrs base
180 The @code{(rnrs base (6))} library exports the procedures and syntactic
181 forms described in the main section of the Report
182 (@pxref{Base library, R6RS Base library,, r6rs,
183 The Revised^6 Report on the Algorithmic Language Scheme}). They are
184 grouped below by the existing manual sections to which they correspond.
186 @deffn {Scheme Procedure} boolean? obj
187 @deffnx {Scheme Procedure} not x
188 @xref{Booleans}, for documentation.
191 @deffn {Scheme Procedure} symbol? obj
192 @deffnx {Scheme Procedure} symbol->string sym
193 @deffnx {Scheme Procedure} string->symbol str
194 @xref{Symbol Primitives}, for documentation.
197 @deffn {Scheme Procedure} char? obj
198 @deffnx {Scheme Procedure} char=?
199 @deffnx {Scheme Procedure} char<?
200 @deffnx {Scheme Procedure} char>?
201 @deffnx {Scheme Procedure} char<=?
202 @deffnx {Scheme Procedure} char>=?
203 @deffnx {Scheme Procedure} integer->char n
204 @deffnx {Scheme Procedure} char->integer chr
205 @xref{Characters}, for documentation.
208 @deffn {Scheme Procedure} list? x
209 @deffnx {Scheme Procedure} null? x
210 @xref{List Predicates}, for documentation.
213 @deffn {Scheme Procedure} pair? x
214 @deffnx {Scheme Procedure} cons x y
215 @deffnx {Scheme Procedure} car pair
216 @deffnx {Scheme Procedure} cdr pair
217 @deffnx {Scheme Procedure} caar pair
218 @deffnx {Scheme Procedure} cadr pair
219 @deffnx {Scheme Procedure} cdar pair
220 @deffnx {Scheme Procedure} cddr pair
221 @deffnx {Scheme Procedure} caaar pair
222 @deffnx {Scheme Procedure} caadr pair
223 @deffnx {Scheme Procedure} cadar pair
224 @deffnx {Scheme Procedure} cdaar pair
225 @deffnx {Scheme Procedure} caddr pair
226 @deffnx {Scheme Procedure} cdadr pair
227 @deffnx {Scheme Procedure} cddar pair
228 @deffnx {Scheme Procedure} cdddr pair
229 @deffnx {Scheme Procedure} caaaar pair
230 @deffnx {Scheme Procedure} caaadr pair
231 @deffnx {Scheme Procedure} caadar pair
232 @deffnx {Scheme Procedure} cadaar pair
233 @deffnx {Scheme Procedure} cdaaar pair
234 @deffnx {Scheme Procedure} cddaar pair
235 @deffnx {Scheme Procedure} cdadar pair
236 @deffnx {Scheme Procedure} cdaadr pair
237 @deffnx {Scheme Procedure} cadadr pair
238 @deffnx {Scheme Procedure} caaddr pair
239 @deffnx {Scheme Procedure} caddar pair
240 @deffnx {Scheme Procedure} cadddr pair
241 @deffnx {Scheme Procedure} cdaddr pair
242 @deffnx {Scheme Procedure} cddadr pair
243 @deffnx {Scheme Procedure} cdddar pair
244 @deffnx {Scheme Procedure} cddddr pair
245 @xref{Pairs}, for documentation.
248 @deffn {Scheme Procedure} number? obj
249 @xref{Numerical Tower}, for documentation.
252 @deffn {Scheme Procedure} string? obj
253 @xref{String Predicates}, for documentation.
256 @deffn {Scheme Procedure} procedure? obj
257 @xref{Procedure Properties}, for documentation.
260 @deffn {Scheme Syntax} define name value
261 @deffnx {Scheme Syntax} set! variable-name value
262 @xref{Definition}, for documentation.
265 @deffn {Scheme Syntax} define-syntax keyword expression
266 @deffnx {Scheme Syntax} let-syntax ((keyword transformer) ...) exp ...
267 @deffnx {Scheme Syntax} letrec-syntax ((keyword transformer) ...) exp ...
268 @xref{Defining Macros}, for documentation.
271 @deffn {Scheme Syntax} identifier-syntax exp
272 @xref{Identifier Macros}, for documentation.
275 @deffn {Scheme Syntax} syntax-rules literals (pattern template) ...
276 @xref{Syntax Rules}, for documentation.
279 @deffn {Scheme Syntax} lambda formals body
280 @xref{Lambda}, for documentation.
283 @deffn {Scheme Syntax} let bindings body
284 @deffnx {Scheme Syntax} let* bindings body
285 @deffnx {Scheme Syntax} letrec bindings body
286 @deffnx {Scheme Syntax} letrec* bindings body
287 @xref{Local Bindings}, for documentation.
290 @deffn {Scheme Syntax} let-values bindings body
291 @deffnx {Scheme Syntax} let*-values bindings body
292 @xref{SRFI-11}, for documentation.
295 @deffn {Scheme Syntax} begin expr1 expr2 ...
296 @xref{begin}, for documentation.
299 @deffn {Scheme Syntax} quote expr
300 @deffnx {Scheme Syntax} quasiquote expr
301 @deffnx {Scheme Syntax} unquote expr
302 @deffnx {Scheme Syntax} unquote-splicing expr
303 @xref{Expression Syntax}, for documentation.
306 @deffn {Scheme Syntax} if test consequence [alternate]
307 @deffnx {Scheme Syntax} cond clause1 clause2 ...
308 @deffnx {Scheme Syntax} case key clause1 clause2 ...
309 @xref{if cond case}, for documentation.
312 @deffn {Scheme Syntax} and expr ...
313 @deffnx {Scheme Syntax} or expr ...
314 @xref{and or}, for documentation.
317 @deffn {Scheme Procedure} eq? x y
318 @deffnx {Scheme Procedure} eqv? x y
319 @deffnx {Scheme Procedure} equal? x y
320 @deffnx {Scheme Procedure} symbol=? symbol1 symbol2 ...
321 @xref{Equality}, for documentation.
323 @code{symbol=?} is identical to @code{eq?}.
326 @deffn {Scheme Procedure} complex? z
327 @xref{Complex Numbers}, for documentation.
330 @deffn {Scheme Procedure} real-part z
331 @deffnx {Scheme Procedure} imag-part z
332 @deffnx {Scheme Procedure} make-rectangular real_part imaginary_part
333 @deffnx {Scheme Procedure} make-polar x y
334 @deffnx {Scheme Procedure} magnitude z
335 @deffnx {Scheme Procedure} angle z
336 @xref{Complex}, for documentation.
339 @deffn {Scheme Procedure} sqrt z
340 @deffnx {Scheme Procedure} exp z
341 @deffnx {Scheme Procedure} expt z1 z2
342 @deffnx {Scheme Procedure} log z
343 @deffnx {Scheme Procedure} sin z
344 @deffnx {Scheme Procedure} cos z
345 @deffnx {Scheme Procedure} tan z
346 @deffnx {Scheme Procedure} asin z
347 @deffnx {Scheme Procedure} acos z
348 @deffnx {Scheme Procedure} atan z
349 @xref{Scientific}, for documentation.
352 @deffn {Scheme Procedure} real? x
353 @deffnx {Scheme Procedure} rational? x
354 @deffnx {Scheme Procedure} nan? x
355 @deffnx {Scheme Procedure} numerator x
356 @deffnx {Scheme Procedure} denominator x
357 @deffnx {Scheme Procedure} rationalize x eps
358 @xref{Reals and Rationals}, for documentation.
361 @deffn {Scheme Procedure} exact? x
362 @deffnx {Scheme Procedure} inexact? x
363 @deffnx {Scheme Procedure} exact z
364 @deffnx {Scheme Procedure} inexact z
365 @xref{Exactness}, for documentation. The @code{exact} and
366 @code{inexact} procedures are identical to the @code{inexact->exact} and
367 @code{exact->inexact} procedures provided by Guile's code library.
370 @deffn {Scheme Procedure} integer? x
371 @xref{Integers}, for documentation.
374 @deffn {Scheme Procedure} odd? n
375 @deffnx {Scheme Procedure} even? n
376 @deffnx {Scheme Procedure} gcd x ...
377 @deffnx {Scheme Procedure} lcm x ...
378 @xref{Integer Operations}, for documentation.
381 @deffn {Scheme Procedure} =
382 @deffnx {Scheme Procedure} <
383 @deffnx {Scheme Procedure} >
384 @deffnx {Scheme Procedure} <=
385 @deffnx {Scheme Procedure} >=
386 @deffnx {Scheme Procedure} zero? x
387 @deffnx {Scheme Procedure} positive? x
388 @deffnx {Scheme Procedure} negative? x
389 @xref{Comparison}, for documentation.
392 @deffn {Scheme Procedure} for-each f lst1 lst2 ...
393 @xref{SRFI-1 Fold and Map}, for documentation.
396 @deffn {Scheme Procedure} list elem1 ... elemN
397 @xref{List Constructors}, for documentation.
400 @deffn {Scheme Procedure} length lst
401 @deffnx {Scheme Procedure} list-ref lst k
402 @deffnx {Scheme Procedure} list-tail lst k
403 @xref{List Selection}, for documentation.
406 @deffn {Scheme Procedure} append lst1 ... lstN
407 @deffnx {Scheme Procedure} reverse lst
408 @xref{Append/Reverse}, for documentation.
411 @deffn {Scheme Procedure} number->string n [radix]
412 @deffnx {Scheme Procedure} string->number str [radix]
413 @xref{Conversion}, for documentation.
416 @deffn {Scheme Procedure} string char ...
417 @deffnx {Scheme Procedure} make-string k [chr]
418 @deffnx {Scheme Procedure} list->string lst
419 @xref{String Constructors}, for documentation.
422 @deffn {Scheme Procedure} string->list str [start [end]]
423 @xref{List/String Conversion}, for documentation.
426 @deffn {Scheme Procedure} string-length str
427 @deffnx {Scheme Procedure} string-ref str k
428 @deffnx {Scheme Procedure} string-copy str [start [end]]
429 @deffnx {Scheme Procedure} substring str start [end]
430 @xref{String Selection}, for documentation.
433 @deffn {Scheme Procedure} string=? [s1 [s2 . rest]]
434 @deffnx {Scheme Procedure} string<? [s1 [s2 . rest]]
435 @deffnx {Scheme Procedure} string>? [s1 [s2 . rest]]
436 @deffnx {Scheme Procedure} string<=? [s1 [s2 . rest]]
437 @deffnx {Scheme Procedure} string>=? [s1 [s2 . rest]]
438 @xref{String Comparison}, for documentation.
441 @deffn {Scheme Procedure} string-append . args
442 @xref{Reversing and Appending Strings}, for documentation.
445 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
446 @xref{Mapping Folding and Unfolding}, for documentation.
449 @deffn {Scheme Procedure} + z1 ...
450 @deffnx {Scheme Procedure} - z1 z2 ...
451 @deffnx {Scheme Procedure} * z1 ...
452 @deffnx {Scheme Procedure} / z1 z2 ...
453 @deffnx {Scheme Procedure} max x1 x2 ...
454 @deffnx {Scheme Procedure} min x1 x2 ...
455 @deffnx {Scheme Procedure} abs x
456 @deffnx {Scheme Procedure} truncate x
457 @deffnx {Scheme Procedure} floor x
458 @deffnx {Scheme Procedure} ceiling x
459 @deffnx {Scheme Procedure} round x
460 @xref{Arithmetic}, for documentation.
463 @deffn {Scheme Procedure} div x1 x2
464 @deffnx {Scheme Procedure} mod x1 x2
465 @deffnx {Scheme Procedure} div-and-mod x1 x2
466 These procedures implement number-theoretic division.
468 @code{div-and-mod} returns two values, the respective results of
469 @code{(div x1 x2)} and @code{(mod x1 x2)}.
472 @deffn {Scheme Procedure} div0 x1 x2
473 @deffnx {Scheme Procedure} mod0 x1 x2
474 @deffnx {Scheme Procedure} div0-and-mod0 x1 x2
475 These procedures are similar to @code{div}, @code{mod}, and
476 @code{div-and-mod}, except that @code{mod0} returns values that lie
477 within a half-open interval centered on zero.
480 @deffn {Scheme Procedure} exact-integer-sqrt k
481 This procedure returns two nonnegative integer objects @code{s} and
482 @code{r} such that k = s^2 + r and k < (s + 1)^2.
485 @deffn {Scheme Procedure} real-valued? obj
486 @deffnx {Scheme Procedure} rational-valued? obj
487 @deffnx {Scheme Procedure} integer-valued? obj
488 These procedures return @code{#t} if and only if their arguments can,
489 respectively, be coerced to a real, rational, or integer value without a
490 loss of numerical precision.
492 @code{real-valued?} will return @code{#t} for complex numbers whose
493 imaginary parts are zero.
496 @deffn {Scheme Procedure} finite? x
497 @deffnx {Scheme Procedure} infinite? x
498 @code{infinite?} returns @code{#t} if @var{x} is an infinite value,
499 @code{#f} otherwise. @code{finite?} returns the negation of
503 @deffn {Scheme Syntax} assert expr
504 Raises an @code{&assertion} condition if @var{expr} evaluates to
505 @code{#f}; otherwise evaluates to the value of @var{expr}.
508 @deffn {Scheme Procedure} error who message irritant1 ...
509 @deffnx {Scheme Procedure} assertion-violation who message irritant1 ...
510 These procedures raise compound conditions based on their arguments:
511 If @var{who} is not @code{#f}, the condition will include a @code{&who}
512 condition whose @code{who} field is set to @var{who}; a @code{&message}
513 condition will be included with a @code{message} field equal to
514 @var{message}; an @code{&irritants} condition will be included with its
515 @code{irritants} list given by @code{irritant1 ...}.
517 @code{error} produces a compound condition with the simple conditions
518 described above, as well as an @code{&error} condition;
519 @code{assertion-violation} produces one that includes an
520 @code{&assertion} condition.
523 @deffn {Scheme Procedure} vector-map proc v
524 @deffnx {Scheme Procedure} vector-for-each proc v
525 These procedures implement the @code{map} and @code{for-each} contracts
529 @deffn {Scheme Procedure} vector . l
530 @deffnx {Scheme Procedure} vector? obj
531 @deffnx {Scheme Procedure} make-vector len
532 @deffnx {Scheme Procedure} make-vector len fill
533 @deffnx {Scheme Procedure} list->vector l
534 @deffnx {Scheme Procedure} vector->list v
535 @xref{Vector Creation}, for documentation.
538 @deffn {Scheme Procedure} vector-length vector
539 @deffnx {Scheme Procedure} vector-ref vector k
540 @deffnx {Scheme Procedure} vector-set! vector k obj
541 @deffnx {Scheme Procedure} vector-fill! v fill
542 @xref{Vector Accessors}, for documentation.
545 @deffn {Scheme Procedure} call-with-current-continuation proc
546 @deffnx {Scheme Procedure} call/cc proc
547 @xref{Continuations}, for documentation.
550 @deffn {Scheme Procedure} values arg1 ... argN
551 @deffnx {Scheme Procedure} call-with-values producer consumer
552 @xref{Multiple Values}, for documentation.
555 @deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
556 @xref{Dynamic Wind}, for documentation.
559 @deffn {Scheme Procedure} apply proc arg1 ... argN arglst
560 @xref{Fly Evaluation}, for documentation.
564 @subsubsection rnrs unicode
566 The @code{(rnrs unicode (6))} library provides procedures for
567 manipulating Unicode characters and strings.
569 @deffn {Scheme Procedure} char-upcase char
570 @deffnx {Scheme Procedure} char-downcase char
571 @deffnx {Scheme Procedure} char-titlecase char
572 @deffnx {Scheme Procedure} char-foldcase char
573 These procedures translate their arguments from one Unicode character
574 set to another. @code{char-upcase}, @code{char-downcase}, and
575 @code{char-titlecase} are identical to their counterparts in the
576 Guile core library; @xref{Characters}, for documentation.
578 @code{char-foldcase} returns the result of applying @code{char-upcase}
579 to its argument, followed by @code{char-downcase}---except in the case
580 of the Turkic characters @code{U+0130} and @code{U+0131}, for which the
581 procedure acts as the identity function.
584 @deffn {Scheme Procedure} char-ci=? char1 char2 char3 ...
585 @deffnx {Scheme Procedure} char-ci<? char1 char2 char3 ...
586 @deffnx {Scheme Procedure} char-ci>? char1 char2 char3 ...
587 @deffnx {Scheme Procedure} char-ci<=? char1 char2 char3 ...
588 @deffnx {Scheme Procedure} char-ci>=? char1 char2 char3 ...
589 These procedures facilitate case-insensitive comparison of Unicode
590 characters. They are identical to the procedures provided by Guile's
591 core library. @xref{Characters}, for documentation.
594 @deffn {Scheme Procedure} char-alphabetic? char
595 @deffnx {Scheme Procedure} char-numeric? char
596 @deffnx {Scheme Procedure} char-whitespace? char
597 @deffnx {Scheme Procedure} char-upper-case? char
598 @deffnx {Scheme Procedure} char-lower-case? char
599 @deffnx {Scheme Procedure} char-title-case? char
600 These procedures implement various Unicode character set predicates.
601 They are identical to the procedures provided by Guile's core library.
602 @xref{Characters}, for documentation.
605 @deffn {Scheme Procedure} char-general-category char
606 @xref{Characters}, for documentation.
609 @deffn {Scheme Procedure} string-upcase string
610 @deffnx {Scheme Procedure} string-downcase string
611 @deffnx {Scheme Procedure} string-titlecase string
612 @deffnx {Scheme Procedure} string-foldcase string
613 These procedures perform Unicode case folding operations on their input.
614 @xref{Alphabetic Case Mapping}, for documentation.
617 @deffn {Scheme Procedure} string-ci=? string1 string2 string3 ...
618 @deffnx {Scheme Procedure} string-ci<? string1 string2 string3 ...
619 @deffnx {Scheme Procedure} string-ci>? string1 string2 string3 ...
620 @deffnx {Scheme Procedure} string-ci<=? string1 string2 string3 ...
621 @deffnx {Scheme Procedure} string-ci>=? string1 string2 string3 ...
622 These procedures perform case-insensitive comparison on their input.
623 @xref{String Comparison}, for documentation.
626 @deffn {Scheme Procedure} string-normalize-nfd string
627 @deffnx {Scheme Procedure} string-normalize-nfkd string
628 @deffnx {Scheme Procedure} string-normalize-nfc string
629 @deffnx {Scheme Procedure} string-normalize-nfkc string
630 These procedures perform Unicode string normalization operations on
631 their input. @xref{String Comparison}, for documentation.
634 @node rnrs bytevectors
635 @subsubsection rnrs bytevectors
637 The @code{(rnrs bytevectors (6))} library provides procedures for
638 working with blocks of binary data. This functionality is documented
639 in its own section of the manual; @xref{Bytevectors}.
642 @subsubsection rnrs lists
644 The @code{(rnrs lists (6))} library provides procedures additional
645 procedures for working with lists.
647 @deffn {Scheme Procedure} find proc list
648 This procedure is identical to the one defined in Guile's SRFI-1
649 implementation. @xref{SRFI-1 Searching}, for documentation.
652 @deffn {Scheme Procedure} for-all proc list1 list2 ...
653 @deffnx {Scheme Procedure} exists proc list1 list2 ...
655 The @code{for-all} procedure is identical to the @code{every} procedure
656 defined by SRFI-1; the @code{exists} procedure is identical to SRFI-1's
657 @code{any}. @xref{SRFI-1 Searching}, for documentation.
660 @deffn {Scheme Procedure} filter proc list
661 @deffnx {Scheme Procedure} partition proc list
662 These procedures are identical to the ones provided by SRFI-1.
663 @xref{List Modification}, for a description of @code{filter};
664 @xref{SRFI-1 Filtering and Partitioning}, for @code{partition}.
667 @deffn {Scheme Procedure} fold-left combine nil list1 list2 ... listn
668 @deffnx {Scheme Procedure} fold-right combine nil list1 list2 ... listn
669 These procedures are identical to the @code{fold} and @code{fold-right}
670 procedures provided by SRFI-1. @xref{SRFI-1 Fold and Map}, for
674 @deffn {Scheme Procedure} remp proc list
675 @deffnx {Scheme Procedure} remove obj list
676 @deffnx {Scheme Procedure} remv obj list
677 @deffnx {Scheme Procedure} remq obj list
678 @code{remove}, @code{remv}, and @code{remq} are identical to the
679 @code{delete}, @code{delv}, and @code{delq} procedures provided by
680 Guile's core library, (@pxref{List Modification}). @code{remp} is
681 identical to the alternate @code{remove} procedure provided by SRFI-1;
682 @xref{SRFI-1 Deleting}.
685 @deffn {Scheme Procedure} memp proc list
686 @deffnx {Scheme Procedure} member obj list
687 @deffnx {Scheme Procedure} memv obj list
688 @deffnx {Scheme Procedure} memq obj list
689 @code{member}, @code{memv}, and @code{memq} are identical to the
690 procedures provided by Guile's core library; @xref{List Searching},
691 for their documentation. @code{memp} uses the specified predicate
692 function @code{proc} to test elements of the list @var{list}---it
693 behaves similarly to @code{find}, except that it returns the first
694 sublist of @var{list} whose @code{car} satisfies @var{proc}.
697 @deffn {Scheme Procedure} assp proc alist
698 @deffnx {Scheme Procedure} assoc obj alist
699 @deffnx {Scheme Procedure} assv obj alist
700 @deffnx {Scheme Procedure} assq obj alist
701 @code{assoc}, @code{assv}, and @code{assq} are identical to the
702 procedures provided by Guile's core library;
703 @xref{Alist Key Equality}, for their documentation. @code{assp} uses
704 the specified predicate function @code{proc} to test keys in the
705 association list @var{alist}.
708 @deffn {Scheme Procedure} cons* obj1 ... obj
709 @deffnx {Scheme Procedure} cons* obj
710 This procedure is identical to the one exported by Guile's core
711 library. @xref{List Constructors}, for documentation.
715 @subsubsection rnrs sorting
717 The @code{(rnrs sorting (6))} library provides procedures for sorting
720 @deffn {Scheme Procedure} list-sort proc list
721 @deffnx {Scheme Procedure} vector-sort proc vector
722 These procedures return their input sorted in ascending order, without
723 modifying the original data. @var{proc} must be a procedure that takes
724 two elements from the input list or vector as arguments, and returns a
725 true value if the first is ``less'' than the second, @code{#f}
726 otherwise. @code{list-sort} returns a list; @code{vector-sort} returns
729 Both @code{list-sort} and @code{vector-sort} are implemented in terms of
730 the @code{stable-sort} procedure from Guile's core library.
731 @xref{Sorting}, for a discussion of the behavior of that procedure.
734 @deffn {Scheme Procedure} vector-sort! proc vector
735 Performs a destructive, ``in-place'' sort of @var{vector}, using
736 @var{proc} as described above to determine an ascending ordering of
737 elements. @code{vector-sort!} returns an unspecified value.
739 This procedure is implemented in terms of the @code{sort!} procedure
740 from Guile's core library. @xref{Sorting}, for more information.
744 @subsubsection rnrs control
746 The @code{(rnrs control (6))} library provides syntactic forms useful
747 for constructing conditional expressions and controlling the flow of
750 @deffn {Scheme Syntax} when test expression1 expression2 ...
751 @deffnx {Scheme Syntax} unless test expression1 expression2 ...
752 The @code{when} form is evaluated by evaluating the specified @var{test}
753 expression; if the result is a true value, the @var{expression}s that
754 follow it are evaluated in order, and the value of the final
755 @var{expression} becomes the value of the entire @code{when} expression.
757 The @code{unless} form behaves similarly, with the exception that the
758 specified @var{expression}s are only evaluated if the value of
762 @deffn {Scheme Syntax} do ((variable init step) ...) (test expression ...) command ...
763 This form is identical to the one provided by Guile's core library.
764 @xref{while do}, for documentation.
767 @deffn {Scheme Syntax} case-lambda clause ...
768 This form is identical to the one provided by Guile's core library.
769 @xref{Case-lambda}, for documentation.
773 @subsubsection R6RS Records
775 The manual sections below describe Guile's implementation of R6RS
776 records, which provide support for user-defined data types. The R6RS
777 records API provides a superset of the features provided by Guile's
778 ``native'' records, as well as those of the SRFI-9 records API;
779 @xref{Records}, and @ref{SRFI-9}, for a description of those
782 As with SRFI-9 and Guile's native records, R6RS records are constructed
783 using a record-type descriptor that specifies attributes like the
784 record's name, its fields, and the mutability of those fields.
786 R6RS records extend this framework to support single inheritance via the
787 specification of a ``parent'' type for a record type at definition time.
788 Accessors and mutator procedures for the fields of a parent type may be
789 applied to records of a subtype of this parent. A record type may be
790 @dfn{sealed}, in which case it cannot be used as the parent of another
793 The inheritance mechanism for record types also informs the process of
794 initializing the fields of a record and its parents. Constructor
795 procedures that generate new instances of a record type are obtained
796 from a record constructor descriptor, which encapsulates the record-type
797 descriptor of the record to be constructed along with a @dfn{protocol}
798 procedure that defines how constructors for record subtypes delegate to
799 the constructors of their parent types.
801 A protocol is a procedure used by the record system at construction time
802 to bind arguments to the fields of the record being constructed. The
803 protocol procedure is passed a procedure @var{n} that accepts the
804 arguments required to construct the record's parent type; this
805 procedure, when invoked, will return a procedure @var{p} that accepts
806 the arguments required to construct a new instance of the record type
807 itself and returns a new instance of the record type.
809 The protocol should in turn return a procedure that uses @var{n} and
810 @var{p} to initialize the fields of the record type and its parent
811 type(s). This procedure will be the constructor returned by
813 As a trivial example, consider the hypothetical record type
814 @code{pixel}, which encapsulates an x-y location on a screen, and
815 @code{voxel}, which has @code{pixel} as its parent type and stores an
816 additional coordinate. The following protocol produces a constructor
817 procedure that accepts all three coordinates, uses the first two to
818 initialize the fields of @code{pixel}, and binds the third to the single
819 field of @code{voxel}.
828 It may be helpful to think of protocols as ``constructor factories''
829 that produce chains of delegating constructors glued together by the
830 helper procedure @var{n}.
832 An R6RS record type may be declared to be @dfn{nongenerative} via the
833 use of a unique generated or user-supplied symbol---or
834 @dfn{uid}---such that subsequent record type declarations with the same
835 uid and attributes will return the previously-declared record-type
838 R6RS record types may also be declared to be @dfn{opaque}, in which case
839 the various predicates and introspection procedures defined in
840 @code{(rnrs records introspection)} will behave as if records of this
841 type are not records at all.
843 Note that while the R6RS records API shares much of its namespace with
844 both the SRFI-9 and native Guile records APIs, it is not currently
845 compatible with either.
847 @node rnrs records syntactic
848 @subsubsection rnrs records syntactic
850 The @code{(rnrs records syntactic (6))} library exports the syntactic
851 API for working with R6RS records.
853 @deffn {Scheme Syntax} define-record-type name-spec record-clause*
854 Defines a new record type, introducing bindings for a record-type
855 descriptor, a record constructor descriptor, a constructor procedure,
856 a record predicate, and accessor and mutator procedures for the new
857 record type's fields.
859 @var{name-spec} must either be an identifier or must take the form
860 @code{(record-name constructor-name predicate-name)}, where
861 @var{record-name}, @var{constructor-name}, and @var{predicate-name} are
862 all identifiers and specify the names to which, respectively, the
863 record-type descriptor, constructor, and predicate procedures will be
864 bound. If @var{name-spec} is only an identifier, it specifies the name
865 to which the generated record-type descriptor will be bound.
867 Each @var{record-clause} must be one of the following:
871 @code{(fields field-spec*)}, where each @var{field-spec} specifies a
872 field of the new record type and takes one of the following forms:
875 @code{(immutable field-name accessor-name)}, which specifies an
876 immutable field with the name @var{field-name} and binds an accessor
877 procedure for it to the name given by @var{accessor-name}
879 @code{(mutable field-name accessor-name mutator-name)}, which specifies
880 a mutable field with the name @var{field-name} and binds accessor and
881 mutator procedures to @var{accessor-name} and @var{mutator-name},
884 @code{(immutable field-name)}, which specifies an immutable field with
885 the name @var{field-name}; an accessor procedure for it will be created
886 and named by appending record name and @var{field-name} with a hyphen
889 @code{(mutable field-name}), which specifies a mutable field with the
890 name @var{field-name}; an accessor procedure for it will be created and
891 named as described above; a mutator procedure will also be created and
892 named by appending @code{-set!} to the accessor name
894 @code{field-name}, which specifies an immutable field with the name
895 @var{field-name}; an access procedure for it will be created and named
899 @code{(parent parent-name)}, where @var{parent-name} is a symbol giving
900 the name of the record type to be used as the parent of the new record
903 @code{(protocol expression)}, where @var{expression} evaluates to a
904 protocol procedure which behaves as described above, and is used to
905 create a record constructor descriptor for the new record type
907 @code{(sealed sealed?)}, where @var{sealed?} is a boolean value that
908 specifies whether or not the new record type is sealed
910 @code{(opaque opaque?)}, where @var{opaque?} is a boolean value that
911 specifies whether or not the new record type is opaque
913 @code{(nongenerative [uid])}, which specifies that the record type is
914 nongenerative via the optional uid @var{uid}. If @var{uid} is not
915 specified, a unique uid will be generated at expansion time
917 @code{(parent-rtd parent-rtd parent-cd)}, a more explicit form of the
918 @code{parent} form above; @var{parent-rtd} and @var{parent-cd} should
919 evaluate to a record-type descriptor and a record constructor
920 descriptor, respectively
924 @deffn {Scheme Syntax} record-type-descriptor record-name
925 Evaluates to the record-type descriptor associated with the type
926 specified by @var{record-name}.
929 @deffn {Scheme Syntax} record-constructor-descriptor record-name
930 Evaluates to the record-constructor descriptor associated with the type
931 specified by @var{record-name}.
934 @node rnrs records procedural
935 @subsubsection rnrs records procedural
937 The @code{(rnrs records procedural (6))} library exports the procedural
938 API for working with R6RS records.
940 @deffn {Scheme Procedure} make-record-type-descriptor name parent uid sealed? opaque? fields
941 Returns a new record-type descriptor with the specified characteristics:
942 @var{name} must be a symbol giving the name of the new record type;
943 @var{parent} must be either @code{#f} or a non-sealed record-type
944 descriptor for the returned record type to extend; @var{uid} must be
945 either @code{#f}, indicating that the record type is generative, or
946 a symbol giving the type's nongenerative uid; @var{sealed?} and
947 @var{opaque?} must be boolean values that specify the sealedness and
948 opaqueness of the record type; @var{fields} must be a vector of zero or
949 more field specifiers of the form @code{(mutable name)} or
950 @code{(immutable name)}, where name is a symbol giving a name for the
953 If @var{uid} is not @code{#f}, it must be a symbol
956 @deffn {Scheme Procedure} record-type-descriptor? obj
957 Returns @code{#t} if @var{obj} is a record-type descriptor, @code{#f}
961 @deffn {Scheme Procedure} make-record-constructor-descriptor rtd parent-constructor-descriptor protocol
962 Returns a new record constructor descriptor that can be used to produce
963 constructors for the record type specified by the record-type descriptor
964 @var{rtd} and whose delegation and binding behavior are specified by the
965 protocol procedure @var{protocol}.
967 @var{parent-constructor-descriptor} specifies a record constructor
968 descriptor for the parent type of @var{rtd}, if one exists. If
969 @var{rtd} represents a base type, then
970 @var{parent-constructor-descriptor} must be @code{#f}. If @var{rtd}
971 is an extension of another type, @var{parent-constructor-descriptor} may
972 still be @code{#f}, but protocol must also be @code{#f} in this case.
975 @deffn {Scheme Procedure} record-constructor rcd
976 Returns a record constructor procedure by invoking the protocol
977 defined by the record-constructor descriptor @var{rcd}.
980 @deffn {Scheme Procedure} record-predicate rtd
981 Returns the record predicate procedure for the record-type descriptor
985 @deffn {Scheme Procedure} record-accessor rtd k
986 Returns the record field accessor procedure for the @var{k}th field of
987 the record-type descriptor @var{rtd}.
990 @deffn {Scheme Procedure} record-mutator rtd k
991 Returns the record field mutator procedure for the @var{k}th field of
992 the record-type descriptor @var{rtd}. An @code{&assertion} condition
993 will be raised if this field is not mutable.
996 @node rnrs records inspection
997 @subsubsection rnrs records inspection
999 The @code{(rnrs records inspection (6))} library provides procedures
1000 useful for accessing metadata about R6RS records.
1002 @deffn {Scheme Procedure} record? obj
1003 Return @code{#t} if the specified object is a non-opaque R6RS record,
1004 @code{#f} otherwise.
1007 @deffn {Scheme Procedure} record-rtd record
1008 Returns the record-type descriptor for @var{record}. An
1009 @code{&assertion} is raised if @var{record} is opaque.
1012 @deffn {Scheme Procedure} record-type-name rtd
1013 Returns the name of the record-type descriptor @var{rtd}.
1016 @deffn {Scheme Procedure} record-type-parent rtd
1017 Returns the parent of the record-type descriptor @var{rtd}, or @code{#f}
1021 @deffn {Scheme Procedure} record-type-uid rtd
1022 Returns the uid of the record-type descriptor @var{rtd}, or @code{#f} if
1026 @deffn {Scheme Procedure} record-type-generative? rtd
1027 Returns @code{#t} if the record-type descriptor @var{rtd} is generative,
1028 @code{#f} otherwise.
1031 @deffn {Scheme Procedure} record-type-sealed? rtd
1032 Returns @code{#t} if the record-type descriptor @var{rtd} is sealed,
1033 @code{#f} otherwise.
1036 @deffn {Scheme Procedure} record-type-opaque? rtd
1037 Returns @code{#t} if the record-type descriptor @var{rtd} is opaque,
1038 @code{#f} otherwise.
1041 @deffn {Scheme Procedure} record-type-field-names rtd
1042 Returns a vector of symbols giving the names of the fields defined by
1043 the record-type descriptor @var{rtd} (and not any of its sub- or
1047 @deffn {Scheme Procedure} record-field-mutable? rtd k
1048 Returns @code{#t} if the field at index @var{k} of the record-type
1049 descriptor @var{rtd} (and not any of its sub- or supertypes) is mutable.
1052 @node rnrs exceptions
1053 @subsubsection rnrs exceptions
1055 The @code{(rnrs exceptions (6))} library provides functionality related
1056 to signaling and handling exceptional situations. This functionality is
1057 similar to the exception handling systems provided by Guile's core
1058 library @xref{Exceptions}, and by the SRFI-18 and SRFI-34
1059 modules---@xref{SRFI-18 Exceptions}, and @ref{SRFI-34},
1060 respectively---but there are some key differences in concepts and
1063 A raised exception may be @dfn{continuable} or @dfn{non-continuable}.
1064 When an exception is raised non-continuably, another exception, with the
1065 condition type @code{&non-continuable}, will be raised when the
1066 exception handler returns locally. Raising an exception continuably
1067 captures the current continuation and invokes it after a local return
1068 from the exception handler.
1070 Like SRFI-18 and SRFI-34, R6RS exceptions are implemented on top of
1071 Guile's native @code{throw} and @code{catch} forms, and use custom
1072 ``throw keys'' to identify their exception types. As a consequence,
1073 Guile's @code{catch} form can handle exceptions thrown by these APIs,
1074 but the reverse is not true: Handlers registered by the
1075 @code{with-exception-handler} procedure described below will only be
1076 called on exceptions thrown by the corresponding @code{raise} procedure.
1078 @deffn {Scheme Procedure} with-exception-handler handler thunk
1079 Installs @var{handler}, which must be a procedure taking one argument,
1080 as the current exception handler during the invokation of @var{thunk}, a
1081 procedure taking zero arguments. The handler in place at the time
1082 @code{with-exception-handler} is called is made current again once
1083 either @var{thunk} returns or @var{handler} is invoked after an
1084 exception is thrown from within @var{thunk}.
1086 This procedure is similar to the @code{with-throw-handler} procedure
1087 provided by Guile's code library; (@pxref{Throw Handlers}).
1090 @deffn {Scheme Syntax} guard (variable clause1 clause2 ...) body
1091 Evaluates the expression given by @var{body}, first creating an ad hoc
1092 exception handler that binds a raised exception to @var{variable} and
1093 then evaluates the specified @var{clause}s as if they were part of a
1094 @code{cond} expression, with the value of the first matching clause
1095 becoming the value of the @code{guard} expression
1096 (@pxref{if cond case}). If none of the clause's test expressions
1097 evaluates to @code{#t}, the exception is re-raised, with the exception
1098 handler that was current before the evaluation of the @code{guard} form.
1100 For example, the expression
1103 (guard (ex ((eq? ex 'foo) 'bar) ((eq? ex 'bar) 'baz))
1107 evaluates to @code{baz}.
1110 @deffn {Scheme Procedure} raise obj
1111 Raises a non-continuable exception by invoking the currently-installed
1112 exception handler on @var{obj}. If the handler returns, a
1113 @code{&non-continuable} exception will be raised in the dynamic context
1114 in which the handler was installed.
1117 @deffn {Scheme Procedure} raise-continuable obj
1118 Raises a continuable exception by invoking currently-installed exception
1119 handler on @var{obj}.
1122 @node rnrs conditions
1123 @subsubsection rnrs conditions
1125 The @code{(rnrs condition (6))} library provides forms and procedures
1126 for constructing new condition types, as well as a library of
1127 pre-defined condition types that represent a variety of common
1128 exceptional situations. Conditions are records of a subtype of the
1129 @code{&condition} record type, which is neither sealed nor opaque.
1130 @xref{R6RS Records}.
1132 Conditions may be manipulated singly, as @dfn{simple conditions}, or
1133 when composed with other conditions to form @dfn{compound conditions}.
1134 Compound conditions do not ``nest''---constructing a new compound
1135 condition out of existing compound conditions will ``flatten'' them
1136 into their component simple conditions. For example, making a new
1137 condition out of a @code{&message} condition and a compound condition
1138 that contains an @code{&assertion} condition and another @code{&message}
1139 condition will produce a compound condition that contains two
1140 @code{&message} conditions and one @code{&assertion} condition.
1142 The record type predicates and field accessors described below can
1143 operate on either simple or compound conditions. In the latter case,
1144 the predicate returns @code{#t} if the compound condition contains a
1145 component simple condition of the appropriate type; the field accessors
1146 return the requisite fields from the first component simple condition
1147 found to be of the appropriate type.
1149 This library is quite similar to the SRFI-35 conditions module
1150 (@pxref{SRFI-35}). Among other minor differences, the
1151 @code{(rnrs conditions)} library features slightly different semantics
1152 around condition field accessors, and comes with a larger number of
1153 pre-defined condition types. The two APIs are not currently compatible,
1154 however; the @code{condition?} predicate from one API will return
1155 @code{#f} when applied to a condition object created in the other.
1157 @deffn {Condition Type} &condition
1158 @deffnx {Scheme Procedure} condition? obj
1159 The base record type for conditions.
1162 @deffn {Scheme Procedure} condition condition1 ...
1163 @deffnx {Scheme Procedure} simple-conditions condition
1164 The @code{condition} procedure creates a new compound condition out of
1165 its condition arguments, flattening any specified compound conditions
1166 into their component simple conditions as described above.
1168 @code{simple-conditions} returns a list of the component simple
1169 conditions of the compound condition @code{condition}, in the order in
1170 which they were specified at construction time.
1173 @deffn {Scheme Procedure} condition-predicate rtd
1174 @deffnx {Scheme Procedure} condition-accessor rtd proc
1175 These procedures return condition predicate and accessor procedures for
1176 the specified condition record type @var{rtd}.
1179 @deffn {Scheme Syntax} define-condition-type condition-type supertype constructor predicate field-spec ...
1180 Evaluates to a new record type definition for a condition type with the
1181 name @var{condition-type} that has the condition type @var{supertype} as
1182 its parent. A default constructor, which binds its arguments to the
1183 fields of this type and its parent types, will be bound to the
1184 identifier @var{constructor}; a condition predicate will be bound to
1185 @var{predicate}. The fields of the new type, which are immutable, are
1186 specified by the @var{field-spec}s, each of which must be of the form:
1190 where @var{field} gives the name of the field and @var{accessor} gives
1191 the name for a binding to an accessor procedure created for this field.
1194 @deffn {Condition Type} &message
1195 @deffnx {Scheme Procedure} make-message-condition message
1196 @deffnx {Scheme Procedure} message-condition? obj
1197 @deffnx {Scheme Procedure} condition-message condition
1198 A type that includes a message describing the condition that occurred.
1201 @deffn {Condition Type} &warning
1202 @deffnx {Scheme Procedure} make-warning
1203 @deffnx {Scheme Procedure} warning? obj
1204 A base type for representing non-fatal conditions during execution.
1207 @deffn {Condition Type} &serious
1208 @deffnx {Scheme Procedure} make-serious-condition
1209 @deffnx {Scheme Procedure} serious-condition? obj
1210 A base type for conditions representing errors serious enough that
1214 @deffn {Condition Type} &error
1215 @deffnx {Scheme Procedure} make-error
1216 @deffnx {Scheme Procedure} error? obj
1217 A base type for conditions representing errors.
1220 @deffn {Condition Type} &violation
1221 @deffnx {Scheme Procedure} make-violation
1222 @deffnx {Scheme Procedure} violation?
1223 A subtype of @code{&serious} that can be used to represent violations
1224 of a language or library standard.
1227 @deffn {Condition Type} &assertion
1228 @deffnx {Scheme Procedure} make-assertion-violation
1229 @deffnx {Scheme Procedure} assertion-violation? obj
1230 A subtype of @code{&violation} that indicates an invalid call to a
1234 @deffn {Condition Type} &irritants
1235 @deffnx {Scheme Procedure} make-irritants-condition irritants
1236 @deffnx {Scheme Procedure} irritants-condition? obj
1237 @deffnx {Scheme Procedure} condition-irritants condition
1238 A base type used for storing information about the causes of another
1239 condition in a compound condition.
1242 @deffn {Condition Type} &who
1243 @deffnx {Scheme Procedure} make-who-condition who
1244 @deffnx {Scheme Procedure} who-condition? obj
1245 @deffnx {Scheme Procedure} condiction-who condition
1246 A base type used for storing the identity, a string or symbol, of the
1247 entity responsible for another condition in a compound condition.
1250 @deffn {Condition Type} &non-continuable
1251 @deffnx {Scheme Procedure} make-non-continuable-violation
1252 @deffnx {Scheme Procedure} non-continuable-violation? obj
1253 A subtype of @code{&violation} used to indicate that an exception
1254 handler invoked by @code{raise} has returned locally.
1257 @deffn {Condition Type} &implementation-restriction
1258 @deffnx {Scheme Procedure} make-implementation-restriction-violation
1259 @deffnx {Scheme Procedure} implementation-restriction-violation? obj
1260 A subtype of @code{&violation} used to indicate a violation of an
1261 implementation restriction.
1264 @deffn {Condition Type} &lexical
1265 @deffnx {Scheme Procedure} make-lexical-violation
1266 @deffnx {Scheme Procedure} lexical-violation? obj
1267 A subtype of @code{&violation} used to indicate a syntax violation at
1268 the level of the datum syntax.
1271 @deffn {Condition Type} &syntax
1272 @deffnx {Scheme Procedure} make-syntax-violation form subform
1273 @deffnx {Scheme Procedure} syntax-violation? obj
1274 @deffnx {Scheme Procedure} syntax-violation-form condition
1275 @deffnx {Scheme Procedure} syntax-violation-subform condition
1276 A subtype of @code{&violation} that indicates a syntax violation. The
1277 @var{form} and @var{subform} fields, which must be datum values,
1278 indicate the syntactic form responsible for the condition.
1281 @deffn {Condition Type} &undefined
1282 @deffnx {Scheme Procedure} make-undefined-violation
1283 @deffnx {Scheme Procedure} undefined-violation? obj
1284 A subtype of @code{&violation} that indicates a reference to an unbound
1288 @node I/O Conditions
1289 @subsubsection I/O Conditions
1291 These condition types are exported by both the
1292 @code{(rnrs io ports (6))} and @code{(rnrs io simple (6))} libraries.
1294 @deffn {Condition Type} &i/o
1295 @deffnx {Scheme Procedure} make-i/o-error
1296 @deffnx {Scheme Procedure} i/o-error? obj
1297 A condition supertype for more specific I/O errors.
1300 @deffn {Condition Type} &i/o-read
1301 @deffnx {Scheme Procedure} make-i/o-read-error
1302 @deffnx {Scheme Procedure} i/o-read-error? obj
1303 A subtype of @code{&i/o}; represents read-related I/O errors.
1306 @deffn {Condition Type} &i/o-write
1307 @deffnx {Scheme Procedure} make-i/o-write-error
1308 @deffnx {Scheme Procedure} i/o-write-error? obj
1309 A subtype of @code{&i/o}; represents write-related I/O errors.
1312 @deffn {Condition Type} &i/o-invalid-position
1313 @deffnx {Scheme Procedure} make-i/o-invalid-position-error position
1314 @deffnx {Scheme Procedure} i/o-invalid-position-error? obj
1315 @deffnx {Scheme Procedure} i/o-error-position condition
1316 A subtype of @code{&i/o}; represents an error related to an attempt to
1317 set the file position to an invalid position.
1320 @deffn {Condition Type} &i/o-filename
1321 @deffnx {Scheme Procedure} make-io-filename-error filename
1322 @deffnx {Scheme Procedure} i/o-filename-error? obj
1323 @deffnx {Scheme Procedure} i/o-error-filename condition
1324 A subtype of @code{&i/o}; represents an error related to an operation on
1328 @deffn {Condition Type} &i/o-file-protection
1329 @deffnx {Scheme Procedure} make-i/o-file-protection-error filename
1330 @deffnx {Scheme Procedure} i/o-file-protection-error? obj
1331 A subtype of @code{&i/o-filename}; represents an error resulting from an
1332 attempt to access a named file for which the caller had insufficient
1336 @deffn {Condition Type} &i/o-file-is-read-only
1337 @deffnx {Scheme Procedure} make-i/o-file-is-read-only-error filename
1338 @deffnx {Scheme Procedure} i/o-file-is-read-only-error? obj
1339 A subtype of @code{&i/o-file-protection}; represents an error related to
1340 an attempt to write to a read-only file.
1343 @deffn {Condition Type} &i/o-file-already-exists
1344 @deffnx {Scheme Procedure} make-i/o-file-already-exists-error filename
1345 @deffnx {Scheme Procedure} i/o-file-already-exists-error? obj
1346 A subtype of @code{&i/o-filename}; represents an error related to an
1347 operation on an existing file that was assumed not to exist.
1350 @deffn {Condition Type} &i/o-file-does-not-exist
1351 @deffnx {Scheme Procedure} make-i/o-file-does-not-exist-error
1352 @deffnx {Scheme Procedure} i/o-file-does-not-exist-error? obj
1353 A subtype of @code{&i/o-filename}; represents an error related to an
1354 operation on a non-existent file that was assumed to exist.
1357 @deffn {Condition Type} &i/o-port
1358 @deffnx {Scheme Procedure} make-i/o-port-error port
1359 @deffnx {Scheme Procedure} i/o-port-error? obj
1360 @deffnx {Scheme Procedure} i/o-error-port condition
1361 A subtype of @code{&i/o}; represents an error related to an operation on
1362 the port @var{port}.
1366 @subsubsection rnrs io ports
1368 The @code{(rnrs io ports (6))} library provides various procedures and
1369 syntactic forms for use in writing to and reading from ports. This
1370 functionality is documented in its own section of the manual;
1371 (@pxref{R6RS I/O Ports}).
1373 @node rnrs io simple
1374 @subsubsection rnrs io simple
1376 The @code{(rnrs io simple (6))} library provides convenience functions
1377 for performing textual I/O on ports. This library also exports all of
1378 the condition types and associated procedures described in
1379 (@pxref{I/O Conditions}).
1381 @deffn {Scheme Procedure} eof-object
1382 @deffnx {Scheme Procedure} eof-object? obj
1383 These procedures are identical to the ones provided by the
1384 @code{(rnrs io ports (6))} library. @xref{R6RS I/O Ports}, for
1388 @deffn {Scheme Procedure} input-port? obj
1389 @deffnx {Scheme Procedure} output-port? obj
1390 These procedures are identical to the ones provided by Guile's core
1391 library. @xref{Ports}, for documentation.
1394 @deffn {Scheme Procedure} call-with-input-file filename proc
1395 @deffnx {Scheme Procedure} call-with-output-file filename proc
1396 @deffnx {Scheme Procedure} open-input-file filename
1397 @deffnx {Scheme Procedure} open-output-file filename
1398 @deffnx {Scheme Procedure} with-input-from-file filename thunk
1399 @deffnx {Scheme Procedure} with-output-to-file filename thunk
1400 These procedures are identical to the ones provided by Guile's core
1401 library. @xref{File Ports}, for documentation.
1404 @deffn {Scheme Procedure} close-input-port input-port
1405 @deffnx {Scheme Procedure} close-output-port output-port
1406 These procedures are identical to the ones provided by Guile's core
1407 library. @xref{Closing}, for documentation.
1410 @deffn {Scheme Procedure} peek-char
1411 @deffnx {Scheme Procedure} peek-char textual-input-port
1412 @deffnx {Scheme Procedure} read-char
1413 @deffnx {Scheme Procedure} read-char textual-input-port
1414 These procedures are identical to the ones provided by Guile's core
1415 library. @xref{Reading}, for documentation.
1418 @deffn {Scheme Procedure} read
1419 @deffnx {Scheme Procedure} read textual-input-port
1420 This procedure is identical to the one provided by Guile's core library.
1421 @xref{Scheme Read}, for documentation.
1424 @deffn {Scheme Procedure} display obj
1425 @deffnx {Scheme Procedure} display obj textual-output-port
1426 @deffnx {Scheme Procedure} newline
1427 @deffnx {Scheme Procedure} newline textual-output-port
1428 @deffnx {Scheme Procedure} write obj
1429 @deffnx {Scheme Procedure} write obj textual-output-port
1430 @deffnx {Scheme Procedure} write-char char
1431 @deffnx {Scheme Procedure} write-char char textual-output-port
1432 These procedures are identical to the ones provided by Guile's core
1433 library. @xref{Writing}, for documentation.
1437 @subsubsection rnrs files
1439 The @code{(rnrs files (6))} library provides the @code{file-exists?} and
1440 @code{delete-file} procedures, which test for the existence of a file
1441 and allow the deletion of files from the filesystem, respectively.
1443 These procedures are identical to the ones provided by Guile's core
1444 library. @xref{File System}, for documentation.
1447 @subsubsection rnrs programs
1449 The @code{(rnrs programs (6))} library provides procedures for
1450 process management and introspection.
1452 @deffn {Scheme Procedure} command-line
1453 This procedure is identical to the one provided by Guile's core library.
1454 @xref{Runtime Environment}, for documentation.
1457 @deffn {Scheme Procedure} exit
1458 @deffnx {Scheme Procedure} exit obj
1459 This procedure is identical to the one provided by Guile's core library.
1462 @node rnrs arithmetic fixnums
1463 @subsubsection rnrs arithmetic fixnums
1465 The @code{(rnrs arithmetic fixnums (6))} library provides procedures for
1466 performing arithmetic operations on an implementation-dependent range of
1467 exact integer values, which R6RS refers to as @dfn{fixnums}. In Guile,
1468 the size of a fixnum is determined by the size of the @code{SCM} type; a
1469 single SCM struct is guaranteed to be able to hold an entire fixnum,
1470 making fixnum computations particularly
1471 efficient---(@pxref{The SCM Type}). On 32-bit systems, the most
1472 negative and most positive fixnum values are, respectively, -536870912
1475 Unless otherwise specified, all of the procedures below take fixnums as
1476 arguments, and will raise an @code{&assertion} condition if passed a
1477 non-fixnum argument or an @code{&implementation-restriction} condition
1478 if their result is not itself a fixnum.
1480 @deffn {Scheme Procedure} fixnum? obj
1481 Returns @code{#t} if @var{obj} is a fixnum, @code{#f} otherwise.
1484 @deffn {Scheme Procedure} fixnum-width
1485 @deffnx {Scheme Procedure} least-fixnum
1486 @deffnx {Scheme Procedure} greatest-fixnum
1487 These procedures return, respectively, the maximum number of bits
1488 necessary to represent a fixnum value in Guile, the minimum fixnum
1489 value, and the maximum fixnum value.
1492 @deffn {Scheme Procedure} fx=? fx1 fx2 fx3 ...
1493 @deffnx {Scheme Procedure} fx>? fx1 fx2 fx3 ...
1494 @deffnx {Scheme Procedure} fx<? fx1 fx2 fx3 ...
1495 @deffnx {Scheme Procedure} fx>=? fx1 fx2 fx3 ...
1496 @deffnx {Scheme Procedure} fx<=? fx1 fx2 fx3 ...
1497 These procedures return @code{#t} if their fixnum arguments are
1498 (respectively): equal, monotonically increasing, monotonically
1499 decreasing, monotonically nondecreasing, or monotonically nonincrasing;
1500 @code{#f} otherwise.
1503 @deffn {Scheme Procedure} fxzero? fx
1504 @deffnx {Scheme Procedure} fxpositive? fx
1505 @deffnx {Scheme Procedure} fxnegative? fx
1506 @deffnx {Scheme Procedure} fxodd? fx
1507 @deffnx {Scheme Procedure} fxeven? fx
1508 These numerical predicates return @code{#t} if @var{fx} is,
1509 respectively, zero, greater than zero, less than zero, odd, or even;
1510 @code{#f} otherwise.
1513 @deffn {Scheme Procedure} fxmax fx1 fx2 ...
1514 @deffnx {Scheme Procedure} fxmin fx1 fx2 ...
1515 These procedures return the maximum or minimum of their arguments.
1518 @deffn {Scheme Procedure} fx+ fx1 fx2
1519 @deffnx {Scheme Procedure} fx* fx1 fx2
1520 These procedures return the sum or product of their arguments.
1523 @deffn {Scheme Procedure} fx- fx1 fx2
1524 @deffnx {Scheme Procedure} fx- fx
1525 Returns the difference of @var{fx1} and @var{fx2}, or the negation of
1526 @var{fx}, if called with a single argument.
1528 An @code{&assertion} condition is raised if the result is not itself a
1532 @deffn {Scheme Procedure} fxdiv-and-mod fx1 fx2
1533 @deffnx {Scheme Procedure} fxdiv fx1 fx2
1534 @deffnx {Scheme Procedure} fxmod fx1 fx2
1535 @deffnx {Scheme Procedure} fxdiv0-and-mod0 fx1 fx2
1536 @deffnx {Scheme Procedure} fxdiv0 fx1 fx2
1537 @deffnx {Scheme Procedure} fxmod0 fx1 fx2
1538 These procedures implement number-theoretic division on fixnums;
1539 @xref{(rnrs base)}, for a description of their semantics.
1542 @deffn {Scheme Procedure} fx+/carry fx1 fx2 fx3
1543 Returns the two fixnum results of the following computation:
1545 (let* ((s (+ fx1 fx2 fx3))
1546 (s0 (mod0 s (expt 2 (fixnum-width))))
1547 (s1 (div0 s (expt 2 (fixnum-width)))))
1552 @deffn {Scheme Procedure} fx-/carry fx1 fx2 fx3
1553 Returns the two fixnum results of the following computation:
1555 (let* ((d (- fx1 fx2 fx3))
1556 (d0 (mod0 d (expt 2 (fixnum-width))))
1557 (d1 (div0 d (expt 2 (fixnum-width)))))
1562 @deffn {Scheme Procedure} fx*/carry fx1 fx2 fx3
1564 Returns the two fixnum results of the following computation:
1565 (let* ((s (+ (* fx1 fx2) fx3))
1566 (s0 (mod0 s (expt 2 (fixnum-width))))
1567 (s1 (div0 s (expt 2 (fixnum-width)))))
1572 @deffn {Scheme Procedure} fxnot fx
1573 @deffnx {Scheme Procedure} fxand fx1 ...
1574 @deffnx {Scheme Procedure} fxior fx1 ...
1575 @deffnx {Scheme Procedure} fxxor fx1 ...
1576 These procedures are identical to the @code{lognot}, @code{logand},
1577 @code{logior}, and @code{logxor} procedures provided by Guile's core
1578 library. @xref{Bitwise Operations}, for documentation.
1581 @deffn {Scheme Procedure} fxif fx1 fx2 fx3
1582 Returns the bitwise ``if'' of its fixnum arguments. The bit at position
1583 @code{i} in the return value will be the @code{i}th bit from @var{fx2}
1584 if the @code{i}th bit of @var{fx1} is 1, the @code{i}th bit from
1588 @deffn {Scheme Procedure} fxbit-count fx
1589 Returns the number of 1 bits in the two's complement representation of
1593 @deffn {Scheme Procedure} fxlength fx
1594 Returns the number of bits necessary to represent @var{fx}.
1597 @deffn {Scheme Procedure} fxfirst-bit-set fx
1598 Returns the index of the least significant 1 bit in the two's complement
1599 representation of @var{fx}.
1602 @deffn {Scheme Procedure} fxbit-set? fx1 fx2
1603 Returns @code{#t} if the @var{fx2}th bit in the two's complement
1604 representation of @var{fx1} is 1, @code{#f} otherwise.
1607 @deffn {Scheme Procedure} fxcopy-bit fx1 fx2 fx3
1608 Returns the result of setting the @var{fx2}th bit of @var{fx1} to the
1609 @var{fx2}th bit of @var{fx3}.
1612 @deffn {Scheme Procedure} fxbit-field fx1 fx2 fx3
1613 Returns the integer representation of the contiguous sequence of bits in
1614 @var{fx1} that starts at position @var{fx2} (inclusive) and ends at
1615 position @var{fx3} (exclusive).
1618 @deffn {Scheme Procedure} fxcopy-bit-field fx1 fx2 fx3 fx4
1619 Returns the result of replacing the bit field in @var{fx1} with start
1620 and end positions @var{fx2} and @var{fx3} with the corresponding bit
1621 field from @var{fx4}.
1624 @deffn {Scheme Procedure} fxarithmetic-shift fx1 fx2
1625 @deffnx {Scheme Procedure} fxarithmetic-shift-left fx1 fx2
1626 @deffnx {Scheme Procedure} fxarithmetic-shift-right fx1 fx2
1627 Returns the result of shifting the bits of @var{fx1} right or left by
1628 the @var{fx2} positions. @code{fxarithmetic-shift} is identical
1629 to @code{fxarithmetic-shift-left}.
1632 @deffn {Scheme Procedure} fxrotate-bit-field fx1 fx2 fx3 fx4
1633 Returns the result of cyclically permuting the bit field in @var{fx1}
1634 with start and end positions @var{fx2} and @var{fx3} by @var{fx4} bits
1635 in the direction of more significant bits.
1638 @deffn {Scheme Procedure} fxreverse-bit-field fx1 fx2 fx3
1639 Returns the result of reversing the order of the bits of @var{fx1}
1640 between position @var{fx2} (inclusive) and position @var{fx3}
1644 @node rnrs arithmetic flonums
1645 @subsubsection rnrs arithmetic flonums
1647 The @code{(rnrs arithmetic flonums (6))} library provides procedures for
1648 performing arithmetic operations on inexact representations of real
1649 numbers, which R6RS refers to as @dfn{flonums}.
1651 Unless otherwise specified, all of the procedures below take flonums as
1652 arguments, and will raise an @code{&assertion} condition if passed a
1653 non-flonum argument.
1655 @deffn {Scheme Procedure} flonum? obj
1656 Returns @code{#t} if @var{obj} is a flonum, @code{#f} otherwise.
1659 @deffn {Scheme Procedure} real->flonum x
1660 Returns the flonum that is numerically closest to the real number
1664 @deffn {Scheme Procedure} fl=? fl1 fl2 fl3 ...
1665 @deffnx {Scheme Procedure} fl<? fl1 fl2 fl3 ...
1666 @deffnx {Scheme Procedure} fl<=? fl1 fl2 fl3 ...
1667 @deffnx {Scheme Procedure} fl>? fl1 fl2 fl3 ...
1668 @deffnx {Scheme Procedure} fl>=? fl1 fl2 fl3 ...
1669 These procedures return @code{#t} if their flonum arguments are
1670 (respectively): equal, monotonically increasing, monotonically
1671 decreasing, monotonically nondecreasing, or monotonically nonincrasing;
1672 @code{#f} otherwise.
1675 @deffn {Scheme Procedure} flinteger? fl
1676 @deffnx {Scheme Procedure} flzero? fl
1677 @deffnx {Scheme Procedure} flpositive? fl
1678 @deffnx {Scheme Procedure} flnegative? fl
1679 @deffnx {Scheme Procedure} flodd? fl
1680 @deffnx {Scheme Procedure} fleven? fl
1681 These numerical predicates return @code{#t} if @var{fl} is,
1682 respectively, an integer, zero, greater than zero, less than zero, odd,
1683 even, @code{#f} otherwise. In the case of @code{flodd?} and
1684 @code{fleven?}, @var{fl} must be an integer-valued flonum.
1687 @deffn {Scheme Procedure} flfinite? fl
1688 @deffnx {Scheme Procedure} flinfinite? fl
1689 @deffnx {Scheme Procedure} flnan? fl
1690 These numerical predicates return @code{#t} if @var{fl} is,
1691 respectively, not infinite, infinite, or a @code{NaN} value.
1694 @deffn {Scheme Procedure} flmax fl1 fl2 ...
1695 @deffnx {Scheme Procedure} flmin fl1 fl2 ...
1696 These procedures return the maximum or minimum of their arguments.
1699 @deffn {Scheme Procedure} fl+ fl1 ...
1700 @deffnx {Scheme Procedure} fl* fl ...
1701 These procedures return the sum or product of their arguments.
1704 @deffn {Scheme Procedure} fl- fl1 fl2 ...
1705 @deffnx {Scheme Procedure} fl- fl
1706 @deffnx {Scheme Procedure} fl/ fl1 fl2 ...
1707 @deffnx {Scheme Procedure} fl/ fl
1708 These procedures return, respectively, the difference or quotient of
1709 their arguments when called with two arguments; when called with a
1710 single argument, they return the additive or multiplicative inverse of
1714 @deffn {Scheme Procedure} flabs fl
1715 Returns the absolute value of @var{fl}.
1718 @deffn {Scheme Procedure} fldiv-and-mod fl1 fl2
1719 @deffnx {Scheme Procedure} fldiv fl1 fl2
1720 @deffnx {Scheme Procedure} fldmod fl1 fl2
1721 @deffnx {Scheme Procedure} fldiv0-and-mod0 fl1 fl2
1722 @deffnx {Scheme Procedure} fldiv0 fl1 fl2
1723 @deffnx {Scheme Procedure} flmod0 fl1 fl2
1724 These procedures implement number-theoretic division on flonums;
1725 @xref{(rnrs base)}, for a description for their semantics.
1728 @deffn {Scheme Procedure} flnumerator fl
1729 @deffnx {Scheme Procedure} fldenominator fl
1730 These procedures return the numerator or denominator of @var{fl} as a
1734 @deffn {Scheme Procedure} flfloor fl1
1735 @deffnx {Scheme Procedure} flceiling fl
1736 @deffnx {Scheme Procedure} fltruncate fl
1737 @deffnx {Scheme Procedure} flround fl
1738 These procedures are identical to the @code{floor}, @code{ceiling},
1739 @code{truncate}, and @code{round} procedures provided by Guile's core
1740 library. @xref{Arithmetic}, for documentation.
1743 @deffn {Scheme Procedure} flexp fl
1744 @deffnx {Scheme Procedure} fllog fl
1745 @deffnx {Scheme Procedure} fllog fl1 fl2
1746 @deffnx {Scheme Procedure} flsin fl
1747 @deffnx {Scheme Procedure} flcos fl
1748 @deffnx {Scheme Procedure} fltan fl
1749 @deffnx {Scheme Procedure} flasin fl
1750 @deffnx {Scheme Procedure} flacos fl
1751 @deffnx {Scheme Procedure} flatan fl
1752 @deffnx {Scheme Procedure} flatan fl1 fl2
1753 These procedures, which compute the usual transcendental functions, are
1754 the flonum variants of the procedures provided by the R6RS base library
1755 (@pxref{(rnrs base)}).
1758 @deffn {Scheme Procedure} flsqrt fl
1759 Returns the square root of @var{fl}. If @var{fl} is @code{-0.0},
1760 @var{-0.0} is returned; for other negative values, a @code{NaN} value
1764 @deffn {Scheme Procedure} flexpt fl1 fl2
1765 Returns the value of @var{fl1} raised to the power of @var{fl2}.
1768 The following condition types are provided to allow Scheme
1769 implementations that do not support infinities or @code{NaN} values
1770 to indicate that a computation resulted in such a value. Guile supports
1771 both of these, so these conditions will never be raised by Guile's
1772 standard libraries implementation.
1774 @deffn {Condition Type} &no-infinities
1775 @deffnx {Scheme Procedure} make-no-infinities-violation obj
1776 @deffnx {Scheme Procedure} no-infinities-violation?
1777 A condition type indicating that a computation resulted in an infinite
1778 value on a Scheme implementation incapable of representing infinities.
1781 @deffn {Condition Type} &no-nans
1782 @deffnx {Scheme Procedure} make-no-nans-violation obj
1783 @deffnx {Scheme Procedure} no-nans-violation? obj
1784 A condition type indicating that a computation resulted in a @code{NaN}
1785 value on a Scheme implementation incapable of representing @code{NaN}s.
1788 @deffn {Scheme Procedure} fixnum->flonum fx
1789 Returns the flonum that is numerically closest to the fixnum @var{fx}.
1792 @node rnrs arithmetic bitwise
1793 @subsubsection rnrs arithmetic bitwise
1795 The @code{(rnrs arithmetic bitwise (6))} library provides procedures for
1796 performing bitwise arithmetic operations on the two's complement
1797 representations of fixnums.
1799 This library and the procedures it exports share functionality with
1800 SRFI-60, which provides support for bitwise manipulation of integers
1803 @deffn {Scheme Procedure} bitwise-not ei
1804 @deffnx {Scheme Procedure} bitwise-and ei1 ...
1805 @deffnx {Scheme Procedure} bitwise-ior ei1 ...
1806 @deffnx {Scheme Procedure} bitwise-xor ei1 ...
1807 These procedures are identical to the @code{lognot}, @code{logand},
1808 @code{logior}, and @code{logxor} procedures provided by Guile's core
1809 library. @xref{Bitwise Operations}, for documentation.
1812 @deffn {Scheme Procedure} bitwise-if ei1 ei2 ei3
1813 Returns the bitwise ``if'' of its arguments. The bit at position
1814 @code{i} in the return value will be the @code{i}th bit from @var{ei2}
1815 if the @code{i}th bit of @var{ei1} is 1, the @code{i}th bit from
1819 @deffn {Scheme Procedure} bitwise-bit-count ei
1820 Returns the number of 1 bits in the two's complement representation of
1824 @deffn {Scheme Procedure} bitwise-length ei
1825 Returns the number of bits necessary to represent @var{ei}.
1828 @deffn {Scheme Procedure} bitwise-first-bit-set ei
1829 Returns the index of the least significant 1 bit in the two's complement
1830 representation of @var{ei}.
1833 @deffn {Scheme Procedure} bitwise-bit-set? ei1 ei2
1834 Returns @code{#t} if the @var{ei2}th bit in the two's complement
1835 representation of @var{ei1} is 1, @code{#f} otherwise.
1838 @deffn {Scheme Procedure} bitwise-copy-bit ei1 ei2 ei3
1839 Returns the result of setting the @var{ei2}th bit of @var{ei1} to the
1840 @var{ei2}th bit of @var{ei3}.
1843 @deffn {Scheme Procedure} bitwise-bit-field ei1 ei2 ei3
1844 Returns the integer representation of the contiguous sequence of bits in
1845 @var{ei1} that starts at position @var{ei2} (inclusive) and ends at
1846 position @var{ei3} (exclusive).
1849 @deffn {Scheme Procedure} bitwise-copy-bit-field ei1 ei2 ei3 ei4
1850 Returns the result of replacing the bit field in @var{ei1} with start
1851 and end positions @var{ei2} and @var{ei3} with the corresponding bit
1852 field from @var{ei4}.
1855 @deffn {Scheme Procedure} bitwise-arithmetic-shift ei1 ei2
1856 @deffnx {Scheme Procedure} bitwise-arithmetic-shift-left ei1 ei2
1857 @deffnx {Scheme Procedure} bitwise-arithmetic-shift-right ei1 ei2
1858 Returns the result of shifting the bits of @var{ei1} right or left by
1859 the @var{ei2} positions. @code{bitwise-arithmetic-shift} is identical
1860 to @code{bitwise-arithmetic-shift-left}.
1863 @deffn {Scheme Procedure} bitwise-rotate-bit-field ei1 ei2 ei3 ei4
1864 Returns the result of cyclically permuting the bit field in @var{ei1}
1865 with start and end positions @var{ei2} and @var{ei3} by @var{ei4} bits
1866 in the direction of more significant bits.
1869 @deffn {Scheme Procedure} bitwise-reverse-bit-field ei1 ei2 ei3
1870 Returns the result of reversing the order of the bits of @var{e1}
1871 between position @var{ei2} (inclusive) and position @var{ei3}
1875 @node rnrs syntax-case
1876 @subsubsection rnrs syntax-case
1878 The @code{(rnrs syntax-case (6))} library provides access to the
1879 @code{syntax-case} system for writing hygienic macros. With one
1880 exception, all of the forms and procedures exported by this library
1881 are ``re-exports'' of Guile's native support for @code{syntax-case};
1882 @xref{Syntax Case}, for documentation, examples, and rationale.
1884 @deffn {Scheme Procedure} make-variable-transformer proc
1885 Creates a new variable transformer out of @var{proc}, a procedure that
1886 takes a syntax object as input and returns a syntax object. If an
1887 identifier to which the result of this procedure is bound appears on the
1888 left-hand side of a @code{set!} expression, @var{proc} will be called
1889 with a syntax object representing the entire @code{set!} expression,
1890 and its return value will replace that @code{set!} expression.
1893 @deffn {Scheme Syntax} syntax-case expression (literal ...) clause ...
1894 The @code{syntax-case} pattern matching form.
1897 @deffn {Scheme Syntax} syntax template
1898 @deffnx {Scheme Syntax} quasisyntax template
1899 @deffnx {Scheme Syntax} unsyntax template
1900 @deffnx {Scheme Syntax} unsyntax-splicing template
1901 These forms allow references to be made in the body of a syntax-case
1902 output expression subform to datum and non-datum values. They are
1903 identical to the forms provided by Guile's core library;
1904 @xref{Syntax Case}, for documentation.
1907 @deffn {Scheme Procedure} identifier? obj
1908 @deffnx {Scheme Procedure} bound-identifier=? id1 id2
1909 @deffnx {Scheme Procedure} free-identifier=? id1 id2
1910 These predicate procedures operate on syntax objects representing
1911 Scheme identifiers. @code{identifier?} returns @code{#t} if @var{obj}
1912 represents an identifier, @code{#f} otherwise.
1913 @code{bound-identifier=?} returns @code{#t} if and only if a binding for
1914 @var{id1} would capture a reference to @var{id2} in the transformer's
1915 output, or vice-versa. @code{free-identifier=?} returns @code{#t} if
1916 and only @var{id1} and @var{id2} would refer to the same binding in the
1917 output of the transformer, independent of any bindings introduced by the
1921 @deffn {Scheme Procedure} generate-temporaries l
1922 Returns a list, of the same length as @var{l}, which must be a list or
1923 a syntax object representing a list, of globally unique symbols.
1926 @deffn {Scheme Procedure} syntax->datum syntax-object
1927 @deffnx {Scheme Procedure} datum->syntax template-id datum
1928 These procedures convert wrapped syntax objects to and from Scheme datum
1929 values. The syntax object returned by @code{datum->syntax} shares
1930 contextual information with the syntax object @var{template-id}.
1933 @deffn {Scheme Procedure} syntax-violation whom message form
1934 @deffnx {Scheme Procedure} syntax-violation whom message form subform
1935 Constructs a new compound condition that includes the following
1939 If @var{whom} is not @code{#f}, a @code{&who} condition with the
1940 @var{whom} as its field
1942 A @code{&message} condition with the specified @var{message}
1944 A @code{&syntax} condition with the specified @var{form} and optional
1945 @var{subform} fields
1949 @node rnrs hashtables
1950 @subsubsection rnrs hashtables
1952 The @code{(rnrs hashtables (6))} library provides structures and
1953 procedures for creating and accessing hash tables. The hash tables API
1954 defined by R6RS is substantially similar to both Guile's native hash
1955 tables implementation as well as the one provided by SRFI-69;
1956 @xref{Hash Tables}, and @ref{SRFI-69}, respectively. Note that you can
1957 write portable R6RS library code that manipulates SRFI-69 hash tables
1958 (by importing the @code{(srfi :69)} library); however, hash tables
1959 created by one API cannot be used by another.
1961 Like SRFI-69 hash tables---and unlike Guile's native ones---R6RS hash
1962 tables associate hash and equality functions with a hash table at the
1963 time of its creation. Additionally, R6RS allows for the creation
1964 (via @code{hashtable-copy}; see below) of immutable hash tables.
1966 @deffn {Scheme Procedure} make-eq-hashtable
1967 @deffnx {Scheme Procedure} make-eq-hashtable k
1968 Returns a new hash table that uses @code{eq?} to compare keys and
1969 Guile's @code{hashq} procedure as a hash function. If @var{k} is given,
1970 it specifies the initial capacity of the hash table.
1973 @deffn {Scheme Procedure} make-eqv-hashtable
1974 @deffnx {Scheme Procedure} make-eqv-hashtable k
1975 Returns a new hash table that uses @code{eqv?} to compare keys and
1976 Guile's @code{hashv} procedure as a hash function. If @var{k} is given,
1977 it specifies the initial capacity of the hash table.
1980 @deffn {Scheme Procedure} make-hashtable hash-function equiv
1981 @deffnx {Scheme Procedure} make-hashtable hash-function equiv k
1982 Returns a new hash table that uses @var{equiv} to compare keys and
1983 @var{hash-function} as a hash function. @var{equiv} must be a procedure
1984 that accepts two arguments and returns a true value if they are
1985 equivalent, @code{#f} otherwise; @var{hash-function} must be a procedure
1986 that accepts one argument and returns a non-negative integer.
1988 If @var{k} is given, it specifies the initial capacity of the hash
1992 @deffn {Scheme Procedure} hashtable? obj
1993 Returns @code{#t} if @var{obj} is an R6RS hash table, @code{#f}
1997 @deffn {Scheme Procedure} hashtable-size hashtable
1998 Returns the number of keys currently in the hash table @var{hashtable}.
2001 @deffn {Scheme Procedure} hashtable-ref hashtable key default
2002 Returns the value associated with @var{key} in the hash table
2003 @var{hashtable}, or @var{default} if none is found.
2006 @deffn {Scheme Procedure} hashtable-set! hashtable key obj
2007 Associates the key @var{key} with the value @var{obj} in the hash table
2008 @var{hashtable}, and returns an unspecified value. An @code{&assertion}
2009 condition is raised if @var{hashtable} is immutable.
2012 @deffn {Scheme Procedure} hashtable-delete! hashtable key
2013 Removes any association found for the key @var{key} in the hash table
2014 @var{hashtable}, and returns an unspecified value. An @code{&assertion}
2015 condition is raised if @var{hashtable} is immutable.
2018 @deffn {Scheme Procedure} hashtable-contains? hashtable key
2019 Returns @code{#t} if the hash table @var{hashtable} contains an
2020 association for the key @var{key}, @code{#f} otherwise.
2023 @deffn {Scheme Procedure} hashtable-update! hashtable key proc default
2024 Associates with @var{key} in the hash table @var{hashtable} the result
2025 of calling @var{proc}, which must be a procedure that takes one
2026 argument, on the value currently associated @var{key} in
2027 @var{hashtable}---or on @var{default} if no such association exists.
2028 An @code{&assertion} condition is raised if @var{hashtable} is
2032 @deffn {Scheme Procedure} hashtable-copy hashtable
2033 @deffnx {Scheme Procedure} hashtable-copy hashtable mutable
2034 Returns a copy of the hash table @var{hashtable}. If the optional
2035 argument @var{mutable} is a true value, the new hash table will be
2039 @deffn {Scheme Procedure} hashtable-clear! hashtable
2040 @deffnx {Scheme Procedure} hashtable-clear! hashtable k
2041 Removes all of the associations from the hash table @var{hashtable}.
2042 The optional argument @var{k}, which specifies a new capacity for the
2043 hash table, is accepted by Guile's @code{(rnrs hashtables)}
2044 implementation, but is ignored.
2047 @deffn {Scheme Procedure} hashtable-keys hashtable
2048 Returns a vector of the keys with associations in the hash table
2049 @var{hashtable}, in an unspecified order.
2052 @deffn {Scheme Procedure} hashtable-entries hashtable
2053 Return two values---a vector of the keys with associations in the hash
2054 table @var{hashtable}, and a vector of the values to which these keys
2055 are mapped, in corresponding but unspecified order.
2058 @deffn {Scheme Procedure} hashtable-equivalence-function hashtable
2059 Returns the equivalence predicated use by @var{hashtable}. This
2060 procedure returns @code{eq?} and @code{eqv?}, respectively, for hash
2061 tables created by @code{make-eq-hashtable} and
2062 @code{make-eqv-hashtable}.
2065 @deffn {Scheme Procedure} hashtable-hash-function hashtable
2066 Returns the hash function used by @var{hashtable}. For hash tables
2067 created by @code{make-eq-hashtable} or @code{make-eqv-hashtable},
2068 @code{#f} is returned.
2071 @deffn {Scheme Procedure} hashtable-mutable? hashtable
2072 Returns @code{#t} if @var{hashtable} is mutable, @code{#f} otherwise.
2075 A number of hash functions are provided for convenience:
2077 @deffn {Scheme Procedure} equal-hash obj
2078 Returns an integer hash value for @var{obj}, based on its structure and
2079 current contents. This hash function is suitable for use with
2080 @code{equal?} as an equivalence function.
2083 @deffn {Scheme Procedure} string-hash string
2084 @deffnx {Scheme Procedure} symbol-hash symbol
2085 These procedures are identical to the ones provided by Guile's core
2086 library. @xref{Hash Table Reference}, for documentation.
2089 @deffn {Scheme Procedure} string-ci-hash string
2090 Returns an integer hash value for @var{string} based on its contents,
2091 ignoring case. This hash function is suitable for use with
2092 @code{string-ci=?} as an equivalence function.
2096 @subsubsection rnrs enums
2098 The @code{(rnrs enums (6))} library provides structures and procedures
2099 for working with enumerable sets of symbols. Guile's implementation
2100 defines an @dfn{enum-set} record type that encapsulates a finite set of
2101 distinct symbols, the @dfn{universe}, and a subset of these symbols,
2102 which define the enumeration set.
2104 The SRFI-1 list library provides a number of procedures for performing
2105 set operations on lists; Guile's @code{(rnrs enums)} implementation
2106 makes use of several of them. @xref{SRFI-1 Set Operations}, for
2109 @deffn {Scheme Procedure} make-enumeration symbol-list
2110 Returns a new enum-set whose universe and enumeration set are both equal
2111 to @var{symbol-list}, a list of symbols.
2114 @deffn {Scheme Procedure} enum-set-universe enum-set
2115 Returns an enum-set representing the universe of @var{enum-set},
2119 @deffn {Scheme Procedure} enum-set-indexer enum-set
2120 Returns a procedure that takes a single argument and returns the
2121 zero-indexed position of that argument in the universe of
2122 @var{enum-set}, or @code{#f} if its argument is not a member of that
2126 @deffn {Scheme Procedure} enum-set-constructor enum-set
2127 Returns a procedure that takes a single argument, a list of symbols
2128 from the universe of @var{enum-set}, an enum-set, and returns a new
2129 enum-set with the same universe that represents a subset containing the
2133 @deffn {Scheme Procedure} enum-set->list enum-set
2134 Returns a list containing the symbols of the set represented by
2135 @var{enum-set}, an enum-set, in the order that they appear in the
2136 universe of @var{enum-set}.
2139 @deffn {Scheme Procedure} enum-set-member? symbol enum-set
2140 @deffnx {Scheme Procedure} enum-set-subset? enum-set1 enum-set2
2141 @deffnx {Scheme Procedure} enum-set=? enum-set1 enum-set2
2142 These procedures test for membership of symbols and enum-sets in other
2143 enum-sets. @code{enum-set-member?} returns @code{#t} if and only if
2144 @var{symbol} is a member of the subset specified by @var{enum-set}.
2145 @code{enum-set-subset?} returns @code{#t} if and only if the universe of
2146 @var{enum-set1} is a subset of the universe of @var{enum-set2} and
2147 every symbol in @var{enum-set1} is present in @var{enum-set2}.
2148 @code{enum-set=?} returns @code{#t} if and only if @var{enum-set1} is a
2149 subset, as per @code{enum-set-subset?} of @var{enum-set2} and vice
2153 @deffn {Scheme Procedure} enum-set-union enum-set1 enum-set2
2154 @deffnx {Scheme Procedure} enum-set-intersection enum-set1 enum-set2
2155 @deffnx {Scheme Procedure} enum-set-difference enum-set1 enum-set2
2156 These procedures return, respectively, the union, intersection, and
2157 difference of their enum-set arguments.
2160 @deffn {Scheme Procedure} enum-set-complement enum-set
2161 Returns @var{enum-set}'s complement (an enum-set), with regard to its
2165 @deffn {Scheme Procedure} enum-set-projection enum-set1 enum-set2
2166 Returns the projection of the enum-set @var{enum-set1} onto the universe
2167 of the enum-set @var{enum-set2}.
2170 @deffn {Scheme Syntax} define-enumeration type-name (symbol ...) constructor-syntax
2171 Evaluates to two new definitions: A constructor bound to
2172 @var{constructor-syntax} that behaves similarly to constructors created
2173 by @code{enum-set-constructor}, above, and creates new @var{enum-set}s
2174 in the universe specified by @code{(symbol ...)}; and a ``predicate
2175 macro'' bound to @var{type-name}, which has the following form:
2178 (@var{type-name} sym)
2181 If @var{sym} is a member of the universe specified by the @var{symbol}s
2182 above, this form evaluates to @var{sym}. Otherwise, a @code{&syntax}
2183 condition is raised.
2189 The @code{(rnrs (6))} library is a composite of all of the other R6RS
2190 standard libraries---it imports and re-exports all of their exported
2191 procedures and syntactic forms---with the exception of the following
2195 @item @code{(rnrs eval (6))}
2196 @item @code{(rnrs mutable-pairs (6))}
2197 @item @code{(rnrs mutable-strings (6))}
2198 @item @code{(rnrs r5rs (6))}
2202 @subsubsection rnrs eval
2204 The @code{(rnrs eval (6)} library provides procedures for performing
2205 ``on-the-fly'' evaluation of expressions.
2207 @deffn {Scheme Procedure} eval expression environment
2208 Evaluates @var{expression}, which must be a datum representation of a
2209 valid Scheme expression, in the environment specified by
2210 @var{environment}. This procedure is identical to the one provided by
2211 Guile's code library; @xref{Fly Evaluation}, for documentation.
2214 @deffn {Scheme Procedure} environment import-spec ...
2215 Constructs and returns a new environment based on the specified
2216 @var{import-spec}s, which must be datum representations of the import
2217 specifications used with the @code{import} form. @xref{R6RS Libraries},
2221 @node rnrs mutable-pairs
2222 @subsubsection rnrs mutable-pairs
2224 The @code{(rnrs mutable-pairs (6))} library provides the @code{set-car!}
2225 and @code{set-cdr!} procedures, which allow the @code{car} and
2226 @code{cdr} fields of a pair to be modified.
2228 These procedures are identical to the ones provide by Guile's core
2229 library. @xref{Pairs}, for documentation. All pairs in Guile are
2230 mutable; consequently, these procedures will never throw the
2231 @code{&assertion} condition described in the R6RS libraries
2234 @node rnrs mutable-strings
2235 @subsubsection rnrs mutable-strings
2237 The @code{(rnrs mutable-strings (6))} library provides the
2238 @code{string-set!} and @code{string-fill!} procedures, which allow the
2239 content of strings to be modified ``in-place.''
2241 These procedures are identical to the ones provided by Guile's core
2242 library. @xref{String Modification}, for documentation. All strings in
2243 Guile are mutable; consequently, these procedures will never throw the
2244 @code{&assertion} condition described in the R6RS libraries
2248 @subsubsection rnrs r5rs
2250 The @code{(rnrs r5rs (6))} library exports bindings for some procedures
2251 present in R5RS but omitted from the R6RS base library specification.
2253 @deffn {Scheme Procedure} exact->inexact z
2254 @deffnx {Scheme Procedure} inexact->exact z
2255 These procedures are identical to the ones provided by Guile's core
2256 library. @xref{Exactness}, for documentation.
2259 @deffn {Scheme Procedure} quotient n1 n2
2260 @deffnx {Scheme Procedure} remainder n1 n2
2261 @deffnx {Scheme Procedure} modulo n1 n2
2262 These procedures are identical to the ones provided by Guile's core
2263 library. @xref{Integer Operations}, for documentation.
2266 @deffn {Scheme Syntax} delay expr
2267 @deffnx {Scheme Procedure} force promise
2268 The @code{delay} form and the @code{force} procedure are identical to
2269 their counterparts in Guile's core library. @xref{Delayed Evaluation},
2273 @deffn {Scheme Procedure} null-environment n
2274 @deffnx {Scheme Procedure} scheme-report-environment n
2275 These procedures are identical to the ones provided by the
2276 @code{(ice-9 r5rs)} Guile module. @xref{Environments}, for
2280 @c r6rs.texi ends here
2283 @c TeX-master: "guile.texi"