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 A @code{set!} to a variable transformer may only expand to an
41 expression, not a definition---even if the original @code{set!}
42 expression was in definition context.
45 @node R6RS Standard Libraries
46 @subsection R6RS Standard Libraries
48 In contrast with earlier versions of the Revised Report, the R6RS
49 organizes the procedures and syntactic forms required of conforming
50 implementations into a set of ``standard libraries'' which can be
51 imported as necessary by user programs and libraries. Here we briefly
52 list the libraries that have been implemented for Guile.
54 We do not attempt to document these libraries fully here, as most of
55 their functionality is already available in Guile itself. The
56 expectation is that most Guile users will use the well-known and
57 well-documented Guile modules. These R6RS libraries are mostly useful
58 to users who want to port their code to other R6RS systems.
60 The documentation in the following sections reproduces some of the
61 content of the library section of the Report, but is mostly intended to
62 provide supplementary information about Guile's implementation of the
63 R6RS standard libraries. For complete documentation, design rationales
64 and further examples, we advise you to consult the ``Standard
65 Libraries'' section of the Report (@pxref{Standard Libraries,
66 R6RS Standard Libraries,, r6rs, The Revised^6 Report on the Algorithmic
70 * Library Usage:: What to know about Guile's library support.
71 * rnrs base:: The base library.
72 * rnrs unicode:: Access to Unicode operations.
73 * rnrs bytevectors:: Functions for working with binary data.
74 * rnrs lists:: List utilities.
75 * rnrs sorting:: Sorting for lists and vectors.
76 * rnrs control:: Additional control structures.
78 * R6RS Records:: A note about R6RS records.
79 * rnrs records syntactic:: Syntactic API for R6RS records.
80 * rnrs records procedural:: Procedural API for R6RS records.
81 * rnrs records inspection:: Reflection on R6RS records.
83 * rnrs exceptions:: Handling exceptional situations.
84 * rnrs conditions:: Data structures for exceptions.
86 * I/O Conditions:: Predefined I/O error types.
87 * rnrs io ports:: Support for port-based I/O.
88 * rnrs io simple:: High-level I/O API.
90 * rnrs files:: Functions for working with files.
91 * rnrs programs:: Functions for working with processes.
92 * rnrs arithmetic fixnums:: Fixed-precision arithmetic operations.
93 * rnrs arithmetic flonums:: Floating-point arithmetic operations.
94 * rnrs arithmetic bitwise:: Exact bitwise arithmetic operations.
95 * rnrs syntax-case:: Support for `syntax-case' macros.
96 * rnrs hashtables:: Hashtables.
97 * rnrs enums:: Enumerations.
98 * rnrs:: The composite library.
99 * rnrs eval:: Support for on-the-fly evaluation.
100 * rnrs mutable-pairs:: Support for mutable pairs.
101 * rnrs mutable-strings:: Support for mutable strings.
102 * rnrs r5rs:: Compatibility layer for R5RS Scheme.
107 @subsubsection Library Usage
109 Guile implements the R6RS `library' form as a transformation to a native
110 Guile module definition. As a consequence of this, all of the libraries
111 described in the following subsections, in addition to being available
112 for use by R6RS libraries and top-level programs, can also be imported
113 as if they were normal Guile modules---via a @code{use-modules} form,
114 say. For example, the R6RS ``composite'' library can be imported by:
121 (use-modules ((rnrs) :version (6)))
124 For more information on Guile's library implementation, see
125 (@pxref{R6RS Libraries}).
128 @subsubsection rnrs base
130 The @code{(rnrs base (6))} library exports the procedures and syntactic
131 forms described in the main section of the Report
132 (@pxref{Base library, R6RS Base library,, r6rs,
133 The Revised^6 Report on the Algorithmic Language Scheme}). They are
134 grouped below by the existing manual sections to which they correspond.
136 @deffn {Scheme Procedure} boolean? obj
137 @deffnx {Scheme Procedure} not x
138 @xref{Booleans}, for documentation.
141 @deffn {Scheme Procedure} symbol? obj
142 @deffnx {Scheme Procedure} symbol->string sym
143 @deffnx {Scheme Procedure} string->symbol str
144 @xref{Symbol Primitives}, for documentation.
147 @deffn {Scheme Procedure} char? obj
148 @deffnx {Scheme Procedure} char=?
149 @deffnx {Scheme Procedure} char<?
150 @deffnx {Scheme Procedure} char>?
151 @deffnx {Scheme Procedure} char<=?
152 @deffnx {Scheme Procedure} char>=?
153 @deffnx {Scheme Procedure} integer->char n
154 @deffnx {Scheme Procedure} char->integer chr
155 @xref{Characters}, for documentation.
158 @deffn {Scheme Procedure} list? x
159 @deffnx {Scheme Procedure} null? x
160 @xref{List Predicates}, for documentation.
163 @deffn {Scheme Procedure} pair? x
164 @deffnx {Scheme Procedure} cons x y
165 @deffnx {Scheme Procedure} car pair
166 @deffnx {Scheme Procedure} cdr pair
167 @deffnx {Scheme Procedure} caar pair
168 @deffnx {Scheme Procedure} cadr pair
169 @deffnx {Scheme Procedure} cdar pair
170 @deffnx {Scheme Procedure} cddr pair
171 @deffnx {Scheme Procedure} caaar pair
172 @deffnx {Scheme Procedure} caadr pair
173 @deffnx {Scheme Procedure} cadar pair
174 @deffnx {Scheme Procedure} cdaar pair
175 @deffnx {Scheme Procedure} caddr pair
176 @deffnx {Scheme Procedure} cdadr pair
177 @deffnx {Scheme Procedure} cddar pair
178 @deffnx {Scheme Procedure} cdddr pair
179 @deffnx {Scheme Procedure} caaaar pair
180 @deffnx {Scheme Procedure} caaadr pair
181 @deffnx {Scheme Procedure} caadar pair
182 @deffnx {Scheme Procedure} cadaar pair
183 @deffnx {Scheme Procedure} cdaaar pair
184 @deffnx {Scheme Procedure} cddaar pair
185 @deffnx {Scheme Procedure} cdadar pair
186 @deffnx {Scheme Procedure} cdaadr pair
187 @deffnx {Scheme Procedure} cadadr pair
188 @deffnx {Scheme Procedure} caaddr pair
189 @deffnx {Scheme Procedure} caddar pair
190 @deffnx {Scheme Procedure} cadddr pair
191 @deffnx {Scheme Procedure} cdaddr pair
192 @deffnx {Scheme Procedure} cddadr pair
193 @deffnx {Scheme Procedure} cdddar pair
194 @deffnx {Scheme Procedure} cddddr pair
195 @xref{Pairs}, for documentation.
198 @deffn {Scheme Procedure} number? obj
199 @xref{Numerical Tower}, for documentation.
202 @deffn {Scheme Procedure} string? obj
203 @xref{String Predicates}, for documentation.
206 @deffn {Scheme Procedure} procedure? obj
207 @xref{Procedure Properties}, for documentation.
210 @deffn {Scheme Syntax} define name value
211 @deffnx {Scheme Syntax} set! variable-name value
212 @xref{Definition}, for documentation.
215 @deffn {Scheme Syntax} define-syntax keyword expression
216 @deffnx {Scheme Syntax} let-syntax ((keyword transformer) ...) exp ...
217 @deffnx {Scheme Syntax} letrec-syntax ((keyword transformer) ...) exp ...
218 @xref{Defining Macros}, for documentation.
221 @deffn {Scheme Syntax} identifier-syntax exp
222 @xref{Identifier Macros}, for documentation.
225 @deffn {Scheme Syntax} syntax-rules literals (pattern template) ...
226 @xref{Syntax Rules}, for documentation.
229 @deffn {Scheme Syntax} lambda formals body
230 @xref{Lambda}, for documentation.
233 @deffn {Scheme Syntax} let bindings body
234 @deffnx {Scheme Syntax} let* bindings body
235 @deffnx {Scheme Syntax} letrec bindings body
236 @xref{Local Bindings}, for documentation.
239 @deffn {Scheme Syntax} let-values bindings body
240 @deffnx {Scheme Syntax} let*-values bindings body
241 @xref{SRFI-11}, for documentation.
244 @deffn {Scheme Syntax} begin expr1 expr2 ...
245 @xref{begin}, for documentation.
248 @deffn {Scheme Syntax} quote expr
249 @deffnx {Scheme Syntax} quasiquote expr
250 @deffnx {Scheme Syntax} unquote expr
251 @deffnx {Scheme Syntax} unquote-splicing expr
252 @xref{Expression Syntax}, for documentation.
255 @deffn {Scheme Syntax} if test consequence [alternate]
256 @deffnx {Scheme Syntax} cond clause1 clause2 ...
257 @deffnx {Scheme Syntax} case key clause1 clause2 ...
258 @xref{if cond case}, for documentation.
261 @deffn {Scheme Syntax} and expr ...
262 @deffnx {Scheme Syntax} or expr ...
263 @xref{and or}, for documentation.
266 @deffn {Scheme Procedure} eq? x y
267 @deffnx {Scheme Procedure} eqv? x y
268 @deffnx {Scheme Procedure} equal? x y
269 @deffnx {Scheme Procedure} symbol=? symbol1 symbol2 ...
270 @xref{Equality}, for documentation.
272 @code{symbol=?} is identical to @code{eq?}.
275 @deffn {Scheme Procedure} complex? z
276 @xref{Complex Numbers}, for documentation.
279 @deffn {Scheme Procedure} real-part z
280 @deffnx {Scheme Procedure} imag-part z
281 @deffnx {Scheme Procedure} make-rectangular real_part imaginary_part
282 @deffnx {Scheme Procedure} make-polar x y
283 @deffnx {Scheme Procedure} magnitude z
284 @deffnx {Scheme Procedure} angle z
285 @xref{Complex}, for documentation.
288 @deffn {Scheme Procedure} sqrt z
289 @deffnx {Scheme Procedure} exp z
290 @deffnx {Scheme Procedure} expt z1 z2
291 @deffnx {Scheme Procedure} log z
292 @deffnx {Scheme Procedure} sin z
293 @deffnx {Scheme Procedure} cos z
294 @deffnx {Scheme Procedure} tan z
295 @deffnx {Scheme Procedure} asin z
296 @deffnx {Scheme Procedure} acos z
297 @deffnx {Scheme Procedure} atan z
298 @xref{Scientific}, for documentation.
301 @deffn {Scheme Procedure} real? x
302 @deffnx {Scheme Procedure} rational? x
303 @deffnx {Scheme Procedure} nan? x
304 @deffnx {Scheme Procedure} numerator x
305 @deffnx {Scheme Procedure} denominator x
306 @deffnx {Scheme Procedure} rationalize x eps
307 @xref{Reals and Rationals}, for documentation.
310 @deffn {Scheme Procedure} exact? x
311 @deffnx {Scheme Procedure} inexact? x
312 @deffnx {Scheme Procedure} exact z
313 @deffnx {Scheme Procedure} inexact z
314 @xref{Exactness}, for documentation. The @code{exact} and
315 @code{inexact} procedures are identical to the @code{inexact->exact} and
316 @code{exact->inexact} procedures provided by Guile's code library.
319 @deffn {Scheme Procedure} integer? x
320 @xref{Integers}, for documentation.
323 @deffn {Scheme Procedure} odd? n
324 @deffnx {Scheme Procedure} even? n
325 @deffnx {Scheme Procedure} gcd x ...
326 @deffnx {Scheme Procedure} lcm x ...
327 @xref{Integer Operations}, for documentation.
330 @deffn {Scheme Procedure} =
331 @deffnx {Scheme Procedure} <
332 @deffnx {Scheme Procedure} >
333 @deffnx {Scheme Procedure} <=
334 @deffnx {Scheme Procedure} >=
335 @deffnx {Scheme Procedure} zero? x
336 @deffnx {Scheme Procedure} positive? x
337 @deffnx {Scheme Procedure} negative? x
338 @xref{Comparison}, for documentation.
341 @deffn {Scheme Procedure} for-each f lst1 lst2 ...
342 @xref{SRFI-1 Fold and Map}, for documentation.
345 @deffn {Scheme Procedure} list elem1 ... elemN
346 @xref{List Constructors}, for documentation.
349 @deffn {Scheme Procedure} length lst
350 @deffnx {Scheme Procedure} list-ref lst k
351 @deffnx {Scheme Procedure} list-tail lst k
352 @xref{List Selection}, for documentation.
355 @deffn {Scheme Procedure} append lst1 ... lstN
356 @deffnx {Scheme Procedure} reverse lst
357 @xref{Append/Reverse}, for documentation.
360 @deffn {Scheme Procedure} number->string n [radix]
361 @deffnx {Scheme Procedure} string->number str [radix]
362 @xref{Conversion}, for documentation.
365 @deffn {Scheme Procedure} string char ...
366 @deffnx {Scheme Procedure} make-string k [chr]
367 @deffnx {Scheme Procedure} list->string lst
368 @xref{String Constructors}, for documentation.
371 @deffn {Scheme Procedure} string->list str [start [end]]
372 @xref{List/String Conversion}, for documentation.
375 @deffn {Scheme Procedure} string-length str
376 @deffnx {Scheme Procedure} string-ref str k
377 @deffnx {Scheme Procedure} string-copy str [start [end]]
378 @deffnx {Scheme Procedure} substring str start [end]
379 @xref{String Selection}, for documentation.
382 @deffn {Scheme Procedure} string=? [s1 [s2 . rest]]
383 @deffnx {Scheme Procedure} string<? [s1 [s2 . rest]]
384 @deffnx {Scheme Procedure} string>? [s1 [s2 . rest]]
385 @deffnx {Scheme Procedure} string<=? [s1 [s2 . rest]]
386 @deffnx {Scheme Procedure} string>=? [s1 [s2 . rest]]
387 @xref{String Comparison}, for documentation.
390 @deffn {Scheme Procedure} string-append . args
391 @xref{Reversing and Appending Strings}, for documentation.
394 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
395 @xref{Mapping Folding and Unfolding}, for documentation.
398 @deffn {Scheme Procedure} + z1 ...
399 @deffnx {Scheme Procedure} - z1 z2 ...
400 @deffnx {Scheme Procedure} * z1 ...
401 @deffnx {Scheme Procedure} / z1 z2 ...
402 @deffnx {Scheme Procedure} max x1 x2 ...
403 @deffnx {Scheme Procedure} min x1 x2 ...
404 @deffnx {Scheme Procedure} abs x
405 @deffnx {Scheme Procedure} truncate x
406 @deffnx {Scheme Procedure} floor x
407 @deffnx {Scheme Procedure} ceiling x
408 @deffnx {Scheme Procedure} round x
409 @xref{Arithmetic}, for documentation.
412 @deffn {Scheme Procedure} div x1 x2
413 @deffnx {Scheme Procedure} mod x1 x2
414 @deffnx {Scheme Procedure} div-and-mod x1 x2
415 These procedures implement number-theoretic division.
417 @code{div-and-mod} returns two values, the respective results of
418 @code{(div x1 x2)} and @code{(mod x1 x2)}.
421 @deffn {Scheme Procedure} div0 x1 x2
422 @deffnx {Scheme Procedure} mod0 x1 x2
423 @deffnx {Scheme Procedure} div0-and-mod0 x1 x2
424 These procedures are similar to @code{div}, @code{mod}, and
425 @code{div-and-mod}, except that @code{mod0} returns values that lie
426 within a half-open interval centered on zero.
429 @deffn {Scheme Procedure} exact-integer-sqrt k
430 This procedure returns two nonnegative integer objects @code{s} and
431 @code{r} such that k = s^2 + r and k < (s + 1)^2.
434 @deffn {Scheme Procedure} real-valued? obj
435 @deffnx {Scheme Procedure} rational-valued? obj
436 @deffnx {Scheme Procedure} integer-valued? obj
437 These procedures return @code{#t} if and only if their arguments can,
438 respectively, be coerced to a real, rational, or integer value without a
439 loss of numerical precision.
441 @code{real-valued?} will return @code{#t} for complex numbers whose
442 imaginary parts are zero.
445 @deffn {Scheme Procedure} finite? x
446 @deffnx {Scheme Procedure} infinite? x
447 @code{infinite?} returns @code{#t} if @var{x} is an infinite value,
448 @code{#f} otherwise. @code{finite?} returns the negation of
452 @deffn {Scheme Syntax} assert expr
453 Raises an @code{&assertion} condition if @var{expr} evaluates to
454 @code{#f}; otherwise evaluates to the value of @var{expr}.
457 @deffn {Scheme Procedure} error who message irritant1 ...
458 @deffnx {Scheme Procedure} assertion-violation who message irritant1 ...
459 These procedures raise compound conditions based on their arguments:
460 If @var{who} is not @code{#f}, the condition will include a @code{&who}
461 condition whose @code{who} field is set to @var{who}; a @code{&message}
462 condition will be included with a @code{message} field equal to
463 @var{message}; an @code{&irritants} condition will be included with its
464 @code{irritants} list given by @code{irritant1 ...}.
466 @code{error} produces a compound condition with the simple conditions
467 described above, as well as an @code{&error} condition;
468 @code{assertion-violation} produces one that includes an
469 @code{&assertion} condition.
472 @deffn {Scheme Procedure} vector-map proc v
473 @deffnx {Scheme Procedure} vector-for-each proc v
474 These procedures implement the @code{map} and @code{for-each} contracts
478 @deffn {Scheme Procedure} vector . l
479 @deffnx {Scheme Procedure} vector? obj
480 @deffnx {Scheme Procedure} make-vector len
481 @deffnx {Scheme Procedure} make-vector len fill
482 @deffnx {Scheme Procedure} list->vector l
483 @deffnx {Scheme Procedure} vector->list v
484 @xref{Vector Creation}, for documentation.
487 @deffn {Scheme Procedure} vector-length vector
488 @deffnx {Scheme Procedure} vector-ref vector k
489 @deffnx {Scheme Procedure} vector-set! vector k obj
490 @deffnx {Scheme Procedure} vector-fill! v fill
491 @xref{Vector Accessors}, for documentation.
494 @deffn {Scheme Procedure} call-with-current-continuation proc
495 @deffnx {Scheme Procedure} call/cc proc
496 @xref{Continuations}, for documentation.
499 @deffn {Scheme Procedure} values arg1 ... argN
500 @deffnx {Scheme Procedure} call-with-values producer consumer
501 @xref{Multiple Values}, for documentation.
504 @deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
505 @xref{Dynamic Wind}, for documentation.
508 @deffn {Scheme Procedure} apply proc arg1 ... argN arglst
509 @xref{Fly Evaluation}, for documentation.
513 @subsubsection rnrs unicode
515 The @code{(rnrs unicode (6))} library provides procedures for
516 manipulating Unicode characters and strings.
518 @deffn {Scheme Procedure} char-upcase char
519 @deffnx {Scheme Procedure} char-downcase char
520 @deffnx {Scheme Procedure} char-titlecase char
521 @deffnx {Scheme Procedure} char-foldcase char
522 These procedures translate their arguments from one Unicode character
523 set to another. @code{char-upcase}, @code{char-downcase}, and
524 @code{char-titlecase} are identical to their counterparts in the
525 Guile core library; @xref{Characters}, for documentation.
527 @code{char-foldcase} returns the result of applying @code{char-upcase}
528 to its argument, followed by @code{char-downcase}---except in the case
529 of the Turkic characters @code{U+0130} and @code{U+0131}, for which the
530 procedure acts as the identity function.
533 @deffn {Scheme Procedure} char-ci=? char1 char2 char3 ...
534 @deffnx {Scheme Procedure} char-ci<? char1 char2 char3 ...
535 @deffnx {Scheme Procedure} char-ci>? char1 char2 char3 ...
536 @deffnx {Scheme Procedure} char-ci<=? char1 char2 char3 ...
537 @deffnx {Scheme Procedure} char-ci>=? char1 char2 char3 ...
538 These procedures facilitate case-insensitive comparison of Unicode
539 characters. They are identical to the procedures provided by Guile's
540 core library. @xref{Characters}, for documentation.
543 @deffn {Scheme Procedure} char-alphabetic? char
544 @deffnx {Scheme Procedure} char-numeric? char
545 @deffnx {Scheme Procedure} char-whitespace? char
546 @deffnx {Scheme Procedure} char-upper-case? char
547 @deffnx {Scheme Procedure} char-lower-case? char
548 @deffnx {Scheme Procedure} char-title-case? char
549 These procedures implement various Unicode character set predicates.
550 They are identical to the procedures provided by Guile's core library.
551 @xref{Characters}, for documentation.
554 @deffn {Scheme Procedure} char-general-category char
555 @xref{Characters}, for documentation.
558 @deffn {Scheme Procedure} string-upcase string
559 @deffnx {Scheme Procedure} string-downcase string
560 @deffnx {Scheme Procedure} string-titlecase string
561 @deffnx {Scheme Procedure} string-foldcase string
562 These procedures perform Unicode case folding operations on their input.
563 @xref{Alphabetic Case Mapping}, for documentation.
566 @deffn {Scheme Procedure} string-ci=? string1 string2 string3 ...
567 @deffnx {Scheme Procedure} string-ci<? string1 string2 string3 ...
568 @deffnx {Scheme Procedure} string-ci>? string1 string2 string3 ...
569 @deffnx {Scheme Procedure} string-ci<=? string1 string2 string3 ...
570 @deffnx {Scheme Procedure} string-ci>=? string1 string2 string3 ...
571 These procedures perform case-insensitive comparison on their input.
572 @xref{String Comparison}, for documentation.
575 @deffn {Scheme Procedure} string-normalize-nfd string
576 @deffnx {Scheme Procedure} string-normalize-nfkd string
577 @deffnx {Scheme Procedure} string-normalize-nfc string
578 @deffnx {Scheme Procedure} string-normalize-nfkc string
579 These procedures perform Unicode string normalization operations on
580 their input. @xref{String Comparison}, for documentation.
583 @node rnrs bytevectors
584 @subsubsection rnrs bytevectors
586 The @code{(rnrs bytevectors (6))} library provides procedures for
587 working with blocks of binary data. This functionality is documented
588 in its own section of the manual; @xref{Bytevectors}.
591 @subsubsection rnrs lists
593 The @code{(rnrs lists (6))} library provides procedures additional
594 procedures for working with lists.
596 @deffn {Scheme Procedure} find proc list
597 This procedure is identical to the one defined in Guile's SRFI-1
598 implementation. @xref{SRFI-1 Searching}, for documentation.
601 @deffn {Scheme Procedure} for-all proc list1 list2 ...
602 @deffnx {Scheme Procedure} exists proc list1 list2 ...
604 The @code{for-all} procedure is identical to the @code{every} procedure
605 defined by SRFI-1; the @code{exists} procedure is identical to SRFI-1's
606 @code{any}. @xref{SRFI-1 Searching}, for documentation.
609 @deffn {Scheme Procedure} filter proc list
610 @deffnx {Scheme Procedure} partition proc list
611 These procedures are identical to the ones provided by SRFI-1.
612 @xref{List Modification}, for a description of @code{filter};
613 @xref{SRFI-1 Filtering and Partitioning}, for @code{partition}.
616 @deffn {Scheme Procedure} fold-left combine nil list1 list2 ... listn
617 @deffnx {Scheme Procedure} fold-right combine nil list1 list2 ... listn
618 These procedures are identical to the @code{fold} and @code{fold-right}
619 procedures provided by SRFI-1. @xref{SRFI-1 Fold and Map}, for
623 @deffn {Scheme Procedure} remp proc list
624 @deffnx {Scheme Procedure} remove obj list
625 @deffnx {Scheme Procedure} remv obj list
626 @deffnx {Scheme Procedure} remq obj list
627 @code{remove}, @code{remv}, and @code{remq} are identical to the
628 @code{delete}, @code{delv}, and @code{delq} procedures provided by
629 Guile's core library, (@pxref{List Modification}). @code{remp} is
630 identical to the alternate @code{remove} procedure provided by SRFI-1;
631 @xref{SRFI-1 Deleting}.
634 @deffn {Scheme Procedure} memp proc list
635 @deffnx {Scheme Procedure} member obj list
636 @deffnx {Scheme Procedure} memv obj list
637 @deffnx {Scheme Procedure} memq obj list
638 @code{member}, @code{memv}, and @code{memq} are identical to the
639 procedures provided by Guile's core library; @xref{List Searching},
640 for their documentation. @code{memp} uses the specified predicate
641 function @code{proc} to test elements of the list @var{list}---it
642 behaves similarly to @code{find}, except that it returns the first
643 sublist of @var{list} whose @code{car} satisfies @var{proc}.
646 @deffn {Scheme Procedure} assp proc alist
647 @deffnx {Scheme Procedure} assoc obj alist
648 @deffnx {Scheme Procedure} assv obj alist
649 @deffnx {Scheme Procedure} assq obj alist
650 @code{assoc}, @code{assv}, and @code{assq} are identical to the
651 procedures provided by Guile's core library;
652 @xref{Alist Key Equality}, for their documentation. @code{assp} uses
653 the specified predicate function @code{proc} to test keys in the
654 association list @var{alist}.
657 @deffn {Scheme Procedure} cons* obj1 ... obj
658 @deffnx {Scheme Procedure} cons* obj
659 This procedure is identical to the one exported by Guile's core
660 library. @xref{List Constructors}, for documentation.
664 @subsubsection rnrs sorting
666 The @code{(rnrs sorting (6))} library provides procedures for sorting
669 @deffn {Scheme Procedure} list-sort proc list
670 @deffnx {Scheme Procedure} vector-sort proc vector
671 These procedures return their input sorted in ascending order, without
672 modifying the original data. @var{proc} must be a procedure that takes
673 two elements from the input list or vector as arguments, and returns a
674 true value if the first is ``less'' than the second, @code{#f}
675 otherwise. @code{list-sort} returns a list; @code{vector-sort} returns
678 Both @code{list-sort} and @code{vector-sort} are implemented in terms of
679 the @code{stable-sort} procedure from Guile's core library.
680 @xref{Sorting}, for a discussion of the behavior of that procedure.
683 @deffn {Scheme Procedure} vector-sort! proc vector
684 Performs a destructive, ``in-place'' sort of @var{vector}, using
685 @var{proc} as described above to determine an ascending ordering of
686 elements. @code{vector-sort!} returns an unspecified value.
688 This procedure is implemented in terms of the @code{sort!} procedure
689 from Guile's core library. @xref{Sorting}, for more information.
693 @subsubsection rnrs control
695 The @code{(rnrs control (6))} library provides syntactic forms useful
696 for constructing conditional expressions and controlling the flow of
699 @deffn {Scheme Syntax} when test expression1 expression2 ...
700 @deffnx {Scheme Syntax} unless test expression1 expression2 ...
701 The @code{when} form is evaluated by evaluating the specified @var{test}
702 expression; if the result is a true value, the @var{expression}s that
703 follow it are evaluated in order, and the value of the final
704 @var{expression} becomes the value of the entire @code{when} expression.
706 The @code{unless} form behaves similarly, with the exception that the
707 specified @var{expression}s are only evaluated if the value of
711 @deffn {Scheme Syntax} do ((variable init step) ...) (test expression ...) command ...
712 This form is identical to the one provided by Guile's core library.
713 @xref{while do}, for documentation.
716 @deffn {Scheme Syntax} case-lambda clause ...
717 This form is identical to the one provided by Guile's core library.
718 @xref{Case-lambda}, for documentation.
722 @subsubsection R6RS Records
724 The manual sections below describe Guile's implementation of R6RS
725 records, which provide support for user-defined data types. The R6RS
726 records API provides a superset of the features provided by Guile's
727 ``native'' records, as well as those of the SRFI-9 records API;
728 @xref{Records}, and @ref{SRFI-9}, for a description of those
731 As with SRFI-9 and Guile's native records, R6RS records are constructed
732 using a record-type descriptor that specifies attributes like the
733 record's name, its fields, and the mutability of those fields.
735 R6RS records extend this framework to support single inheritance via the
736 specification of a ``parent'' type for a record type at definition time.
737 Accessors and mutator procedures for the fields of a parent type may be
738 applied to records of a subtype of this parent. A record type may be
739 @dfn{sealed}, in which case it cannot be used as the parent of another
742 The inheritance mechanism for record types also informs the process of
743 initializing the fields of a record and its parents. Constructor
744 procedures that generate new instances of a record type are obtained
745 from a record constructor descriptor, which encapsulates the record-type
746 descriptor of the record to be constructed along with a @dfn{protocol}
747 procedure that defines how constructors for record subtypes delegate to
748 the constructors of their parent types.
750 A protocol is a procedure used by the record system at construction time
751 to bind arguments to the fields of the record being constructed. The
752 protocol procedure is passed a procedure @var{n} that accepts the
753 arguments required to construct the record's parent type; this
754 procedure, when invoked, will return a procedure @var{p} that accepts
755 the arguments required to construct a new instance of the record type
756 itself and returns a new instance of the record type.
758 The protocol should in turn return a procedure that uses @var{n} and
759 @var{p} to initialize the fields of the record type and its parent
760 type(s). This procedure will be the constructor returned by
762 As a trivial example, consider the hypothetical record type
763 @code{pixel}, which encapsulates an x-y location on a screen, and
764 @code{voxel}, which has @code{pixel} as its parent type and stores an
765 additional coordinate. The following protocol produces a constructor
766 procedure that accepts all three coordinates, uses the first two to
767 initialize the fields of @code{pixel}, and binds the third to the single
768 field of @code{voxel}.
777 It may be helpful to think of protocols as ``constructor factories''
778 that produce chains of delegating constructors glued together by the
779 helper procedure @var{n}.
781 An R6RS record type may be declared to be @dfn{nongenerative} via the
782 use of a unique generated or user-supplied symbol---or
783 @dfn{uid}---such that subsequent record type declarations with the same
784 uid and attributes will return the previously-declared record-type
787 R6RS record types may also be declared to be @dfn{opaque}, in which case
788 the various predicates and introspection procedures defined in
789 @code{(rnrs records introspection)} will behave as if records of this
790 type are not records at all.
792 Note that while the R6RS records API shares much of its namespace with
793 both the SRFI-9 and native Guile records APIs, it is not currently
794 compatible with either.
796 @node rnrs records syntactic
797 @subsubsection rnrs records syntactic
799 The @code{(rnrs records syntactic (6))} library exports the syntactic
800 API for working with R6RS records.
802 @deffn {Scheme Syntax} define-record-type name-spec record-clause*
803 Defines a new record type, introducing bindings for a record-type
804 descriptor, a record constructor descriptor, a constructor procedure,
805 a record predicate, and accessor and mutator procedures for the new
806 record type's fields.
808 @var{name-spec} must either be an identifier or must take the form
809 @code{(record-name constructor-name predicate-name)}, where
810 @var{record-name}, @var{constructor-name}, and @var{predicate-name} are
811 all identifiers and specify the names to which, respectively, the
812 record-type descriptor, constructor, and predicate procedures will be
813 bound. If @var{name-spec} is only an identifier, it specifies the name
814 to which the generated record-type descriptor will be bound.
816 Each @var{record-clause} must be one of the following:
820 @code{(fields field-spec*)}, where each @var{field-spec} specifies a
821 field of the new record type and takes one of the following forms:
824 @code{(immutable field-name accessor-name)}, which specifies an
825 immutable field with the name @var{field-name} and binds an accessor
826 procedure for it to the name given by @var{accessor-name}
828 @code{(mutable field-name accessor-name mutator-name)}, which specifies
829 a mutable field with the name @var{field-name} and binds accessor and
830 mutator procedures to @var{accessor-name} and @var{mutator-name},
833 @code{(immutable field-name)}, which specifies an immutable field with
834 the name @var{field-name}; an accessor procedure for it will be created
835 and named by appending record name and @var{field-name} with a hyphen
838 @code{(mutable field-name}), which specifies a mutable field with the
839 name @var{field-name}; an accessor procedure for it will be created and
840 named as described above; a mutator procedure will also be created and
841 named by appending @code{-set!} to the accessor name
843 @code{field-name}, which specifies an immutable field with the name
844 @var{field-name}; an access procedure for it will be created and named
848 @code{(parent parent-name)}, where @var{parent-name} is a symbol giving
849 the name of the record type to be used as the parent of the new record
852 @code{(protocol expression)}, where @var{expression} evaluates to a
853 protocol procedure which behaves as described above, and is used to
854 create a record constructor descriptor for the new record type
856 @code{(sealed sealed?)}, where @var{sealed?} is a boolean value that
857 specifies whether or not the new record type is sealed
859 @code{(opaque opaque?)}, where @var{opaque?} is a boolean value that
860 specifies whether or not the new record type is opaque
862 @code{(nongenerative [uid])}, which specifies that the record type is
863 nongenerative via the optional uid @var{uid}. If @var{uid} is not
864 specified, a unique uid will be generated at expansion time
866 @code{(parent-rtd parent-rtd parent-cd)}, a more explicit form of the
867 @code{parent} form above; @var{parent-rtd} and @var{parent-cd} should
868 evaluate to a record-type descriptor and a record constructor
869 descriptor, respectively
873 @deffn {Scheme Syntax} record-type-descriptor record-name
874 Evaluates to the record-type descriptor associated with the type
875 specified by @var{record-name}.
878 @deffn {Scheme Syntax} record-constructor-descriptor record-name
879 Evaluates to the record-constructor descriptor associated with the type
880 specified by @var{record-name}.
883 @node rnrs records procedural
884 @subsubsection rnrs records procedural
886 The @code{(rnrs records procedural (6))} library exports the procedural
887 API for working with R6RS records.
889 @deffn {Scheme Procedure} make-record-type-descriptor name parent uid sealed? opaque? fields
890 Returns a new record-type descriptor with the specified characteristics:
891 @var{name} must be a symbol giving the name of the new record type;
892 @var{parent} must be either @code{#f} or a non-sealed record-type
893 descriptor for the returned record type to extend; @var{uid} must be
894 either @code{#f}, indicating that the record type is generative, or
895 a symbol giving the type's nongenerative uid; @var{sealed?} and
896 @var{opaque?} must be boolean values that specify the sealedness and
897 opaqueness of the record type; @var{fields} must be a vector of zero or
898 more field specifiers of the form @code{(mutable name)} or
899 @code{(immutable name)}, where name is a symbol giving a name for the
902 If @var{uid} is not @code{#f}, it must be a symbol
905 @deffn {Scheme Procedure} record-type-descriptor? obj
906 Returns @code{#t} if @var{obj} is a record-type descriptor, @code{#f}
910 @deffn {Scheme Procedure} make-record-constructor-descriptor rtd parent-constructor-descriptor protocol
911 Returns a new record constructor descriptor that can be used to produce
912 constructors for the record type specified by the record-type descriptor
913 @var{rtd} and whose delegation and binding behavior are specified by the
914 protocol procedure @var{protocol}.
916 @var{parent-constructor-descriptor} specifies a record constructor
917 descriptor for the parent type of @var{rtd}, if one exists. If
918 @var{rtd} represents a base type, then
919 @var{parent-constructor-descriptor} must be @code{#f}. If @var{rtd}
920 is an extension of another type, @var{parent-constructor-descriptor} may
921 still be @code{#f}, but protocol must also be @code{#f} in this case.
924 @deffn {Scheme Procedure} record-constructor rcd
925 Returns a record constructor procedure by invoking the protocol
926 defined by the record-constructor descriptor @var{rcd}.
929 @deffn {Scheme Procedure} record-predicate rtd
930 Returns the record predicate procedure for the record-type descriptor
934 @deffn {Scheme Procedure} record-accessor rtd k
935 Returns the record field accessor procedure for the @var{k}th field of
936 the record-type descriptor @var{rtd}.
939 @deffn {Scheme Procedure} record-mutator rtd k
940 Returns the record field mutator procedure for the @var{k}th field of
941 the record-type descriptor @var{rtd}. An @code{&assertion} condition
942 will be raised if this field is not mutable.
945 @node rnrs records inspection
946 @subsubsection rnrs records inspection
948 The @code{(rnrs records inspection (6))} library provides procedures
949 useful for accessing metadata about R6RS records.
951 @deffn {Scheme Procedure} record? obj
952 Return @code{#t} if the specified object is a non-opaque R6RS record,
956 @deffn {Scheme Procedure} record-rtd record
957 Returns the record-type descriptor for @var{record}. An
958 @code{&assertion} is raised if @var{record} is opaque.
961 @deffn {Scheme Procedure} record-type-name rtd
962 Returns the name of the record-type descriptor @var{rtd}.
965 @deffn {Scheme Procedure} record-type-parent rtd
966 Returns the parent of the record-type descriptor @var{rtd}, or @code{#f}
970 @deffn {Scheme Procedure} record-type-uid rtd
971 Returns the uid of the record-type descriptor @var{rtd}, or @code{#f} if
975 @deffn {Scheme Procedure} record-type-generative? rtd
976 Returns @code{#t} if the record-type descriptor @var{rtd} is generative,
980 @deffn {Scheme Procedure} record-type-sealed? rtd
981 Returns @code{#t} if the record-type descriptor @var{rtd} is sealed,
985 @deffn {Scheme Procedure} record-type-opaque? rtd
986 Returns @code{#t} if the record-type descriptor @var{rtd} is opaque,
990 @deffn {Scheme Procedure} record-type-field-names rtd
991 Returns a vector of symbols giving the names of the fields defined by
992 the record-type descriptor @var{rtd} (and not any of its sub- or
996 @deffn {Scheme Procedure} record-field-mutable? rtd k
997 Returns @code{#t} if the field at index @var{k} of the record-type
998 descriptor @var{rtd} (and not any of its sub- or supertypes) is mutable.
1001 @node rnrs exceptions
1002 @subsubsection rnrs exceptions
1004 The @code{(rnrs exceptions (6))} library provides functionality related
1005 to signaling and handling exceptional situations. This functionality is
1006 similar to the exception handling systems provided by Guile's core
1007 library @xref{Exceptions}, and by the SRFI-18 and SRFI-34
1008 modules---@xref{SRFI-18 Exceptions}, and @ref{SRFI-34},
1009 respectively---but there are some key differences in concepts and
1012 A raised exception may be @dfn{continuable} or @dfn{non-continuable}.
1013 When an exception is raised non-continuably, another exception, with the
1014 condition type @code{&non-continuable}, will be raised when the
1015 exception handler returns locally. Raising an exception continuably
1016 captures the current continuation and invokes it after a local return
1017 from the exception handler.
1019 Like SRFI-18 and SRFI-34, R6RS exceptions are implemented on top of
1020 Guile's native @code{throw} and @code{catch} forms, and use custom
1021 ``throw keys'' to identify their exception types. As a consequence,
1022 Guile's @code{catch} form can handle exceptions thrown by these APIs,
1023 but the reverse is not true: Handlers registered by the
1024 @code{with-exception-handler} procedure described below will only be
1025 called on exceptions thrown by the corresponding @code{raise} procedure.
1027 @deffn {Scheme Procedure} with-exception-handler handler thunk
1028 Installs @var{handler}, which must be a procedure taking one argument,
1029 as the current exception handler during the invokation of @var{thunk}, a
1030 procedure taking zero arguments. The handler in place at the time
1031 @code{with-exception-handler} is called is made current again once
1032 either @var{thunk} returns or @var{handler} is invoked after an
1033 exception is thrown from within @var{thunk}.
1035 This procedure is similar to the @code{with-throw-handler} procedure
1036 provided by Guile's code library; (@pxref{Throw Handlers}).
1039 @deffn {Scheme Syntax} guard (variable clause1 clause2 ...) body
1040 Evaluates the expression given by @var{body}, first creating an ad hoc
1041 exception handler that binds a raised exception to @var{variable} and
1042 then evaluates the specified @var{clause}s as if they were part of a
1043 @code{cond} expression, with the value of the first matching clause
1044 becoming the value of the @code{guard} expression
1045 (@pxref{if cond case}). If none of the clause's test expressions
1046 evaluates to @code{#t}, the exception is re-raised, with the exception
1047 handler that was current before the evaluation of the @code{guard} form.
1049 For example, the expression
1052 (guard (ex ((eq? ex 'foo) 'bar) ((eq? ex 'bar) 'baz))
1056 evaluates to @code{baz}.
1059 @deffn {Scheme Procedure} raise obj
1060 Raises a non-continuable exception by invoking the currently-installed
1061 exception handler on @var{obj}. If the handler returns, a
1062 @code{&non-continuable} exception will be raised in the dynamic context
1063 in which the handler was installed.
1066 @deffn {Scheme Procedure} raise-continuable obj
1067 Raises a continuable exception by invoking currently-installed exception
1068 handler on @var{obj}.
1071 @node rnrs conditions
1072 @subsubsection rnrs conditions
1074 The @code{(rnrs condition (6))} library provides forms and procedures
1075 for constructing new condition types, as well as a library of
1076 pre-defined condition types that represent a variety of common
1077 exceptional situations. Conditions are records of a subtype of the
1078 @code{&condition} record type, which is neither sealed nor opaque.
1079 @xref{R6RS Records}.
1081 Conditions may be manipulated singly, as @dfn{simple conditions}, or
1082 when composed with other conditions to form @dfn{compound conditions}.
1083 Compound conditions do not ``nest''---constructing a new compound
1084 condition out of existing compound conditions will ``flatten'' them
1085 into their component simple conditions. For example, making a new
1086 condition out of a @code{&message} condition and a compound condition
1087 that contains an @code{&assertion} condition and another @code{&message}
1088 condition will produce a compound condition that contains two
1089 @code{&message} conditions and one @code{&assertion} condition.
1091 The record type predicates and field accessors described below can
1092 operate on either simple or compound conditions. In the latter case,
1093 the predicate returns @code{#t} if the compound condition contains a
1094 component simple condition of the appropriate type; the field accessors
1095 return the requisite fields from the first component simple condition
1096 found to be of the appropriate type.
1098 This library is quite similar to the SRFI-35 conditions module
1099 (@pxref{SRFI-35}). Among other minor differences, the
1100 @code{(rnrs conditions)} library features slightly different semantics
1101 around condition field accessors, and comes with a larger number of
1102 pre-defined condition types. The two APIs are not currently compatible,
1103 however; the @code{condition?} predicate from one API will return
1104 @code{#f} when applied to a condition object created in the other.
1106 @deffn {Condition Type} &condition
1107 @deffnx {Scheme Procedure} condition? obj
1108 The base record type for conditions.
1111 @deffn {Scheme Procedure} condition condition1 ...
1112 @deffnx {Scheme Procedure} simple-conditions condition
1113 The @code{condition} procedure creates a new compound condition out of
1114 its condition arguments, flattening any specified compound conditions
1115 into their component simple conditions as described above.
1117 @code{simple-conditions} returns a list of the component simple
1118 conditions of the compound condition @code{condition}, in the order in
1119 which they were specified at construction time.
1122 @deffn {Scheme Procedure} condition-predicate rtd
1123 @deffnx {Scheme Procedure} condition-accessor rtd proc
1124 These procedures return condition predicate and accessor procedures for
1125 the specified condition record type @var{rtd}.
1128 @deffn {Scheme Syntax} define-condition-type condition-type supertype constructor predicate field-spec ...
1129 Evaluates to a new record type definition for a condition type with the
1130 name @var{condition-type} that has the condition type @var{supertype} as
1131 its parent. A default constructor, which binds its arguments to the
1132 fields of this type and its parent types, will be bound to the
1133 identifier @var{constructor}; a condition predicate will be bound to
1134 @var{predicate}. The fields of the new type, which are immutable, are
1135 specified by the @var{field-spec}s, each of which must be of the form:
1139 where @var{field} gives the name of the field and @var{accessor} gives
1140 the name for a binding to an accessor procedure created for this field.
1143 @deffn {Condition Type} &message
1144 @deffnx {Scheme Procedure} make-message-condition message
1145 @deffnx {Scheme Procedure} message-condition? obj
1146 @deffnx {Scheme Procedure} condition-message condition
1147 A type that includes a message describing the condition that occurred.
1150 @deffn {Condition Type} &warning
1151 @deffnx {Scheme Procedure} make-warning
1152 @deffnx {Scheme Procedure} warning? obj
1153 A base type for representing non-fatal conditions during execution.
1156 @deffn {Condition Type} &serious
1157 @deffnx {Scheme Procedure} make-serious-condition
1158 @deffnx {Scheme Procedure} serious-condition? obj
1159 A base type for conditions representing errors serious enough that
1163 @deffn {Condition Type} &error
1164 @deffnx {Scheme Procedure} make-error
1165 @deffnx {Scheme Procedure} error? obj
1166 A base type for conditions representing errors.
1169 @deffn {Condition Type} &violation
1170 @deffnx {Scheme Procedure} make-violation
1171 @deffnx {Scheme Procedure} violation?
1172 A subtype of @code{&serious} that can be used to represent violations
1173 of a language or library standard.
1176 @deffn {Condition Type} &assertion
1177 @deffnx {Scheme Procedure} make-assertion-violation
1178 @deffnx {Scheme Procedure} assertion-violation? obj
1179 A subtype of @code{&violation} that indicates an invalid call to a
1183 @deffn {Condition Type} &irritants
1184 @deffnx {Scheme Procedure} make-irritants-condition irritants
1185 @deffnx {Scheme Procedure} irritants-condition? obj
1186 @deffnx {Scheme Procedure} condition-irritants condition
1187 A base type used for storing information about the causes of another
1188 condition in a compound condition.
1191 @deffn {Condition Type} &who
1192 @deffnx {Scheme Procedure} make-who-condition who
1193 @deffnx {Scheme Procedure} who-condition? obj
1194 @deffnx {Scheme Procedure} condiction-who condition
1195 A base type used for storing the identity, a string or symbol, of the
1196 entity responsible for another condition in a compound condition.
1199 @deffn {Condition Type} &non-continuable
1200 @deffnx {Scheme Procedure} make-non-continuable-violation
1201 @deffnx {Scheme Procedure} non-continuable-violation? obj
1202 A subtype of @code{&violation} used to indicate that an exception
1203 handler invoked by @code{raise} has returned locally.
1206 @deffn {Condition Type} &implementation-restriction
1207 @deffnx {Scheme Procedure} make-implementation-restriction-violation
1208 @deffnx {Scheme Procedure} implementation-restriction-violation? obj
1209 A subtype of @code{&violation} used to indicate a violation of an
1210 implementation restriction.
1213 @deffn {Condition Type} &lexical
1214 @deffnx {Scheme Procedure} make-lexical-violation
1215 @deffnx {Scheme Procedure} lexical-violation? obj
1216 A subtype of @code{&violation} used to indicate a syntax violation at
1217 the level of the datum syntax.
1220 @deffn {Condition Type} &syntax
1221 @deffnx {Scheme Procedure} make-syntax-violation form subform
1222 @deffnx {Scheme Procedure} syntax-violation? obj
1223 @deffnx {Scheme Procedure} syntax-violation-form condition
1224 @deffnx {Scheme Procedure} syntax-violation-subform condition
1225 A subtype of @code{&violation} that indicates a syntax violation. The
1226 @var{form} and @var{subform} fields, which must be datum values,
1227 indicate the syntactic form responsible for the condition.
1230 @deffn {Condition Type} &undefined
1231 @deffnx {Scheme Procedure} make-undefined-violation
1232 @deffnx {Scheme Procedure} undefined-violation? obj
1233 A subtype of @code{&violation} that indicates a reference to an unbound
1237 @node I/O Conditions
1238 @subsubsection I/O Conditions
1240 These condition types are exported by both the
1241 @code{(rnrs io ports (6))} and @code{(rnrs io simple (6))} libraries.
1243 @deffn {Condition Type} &i/o
1244 @deffnx {Scheme Procedure} make-i/o-error
1245 @deffnx {Scheme Procedure} i/o-error? obj
1246 A condition supertype for more specific I/O errors.
1249 @deffn {Condition Type} &i/o-read
1250 @deffnx {Scheme Procedure} make-i/o-read-error
1251 @deffnx {Scheme Procedure} i/o-read-error? obj
1252 A subtype of @code{&i/o}; represents read-related I/O errors.
1255 @deffn {Condition Type} &i/o-write
1256 @deffnx {Scheme Procedure} make-i/o-write-error
1257 @deffnx {Scheme Procedure} i/o-write-error? obj
1258 A subtype of @code{&i/o}; represents write-related I/O errors.
1261 @deffn {Condition Type} &i/o-invalid-position
1262 @deffnx {Scheme Procedure} make-i/o-invalid-position-error position
1263 @deffnx {Scheme Procedure} i/o-invalid-position-error? obj
1264 @deffnx {Scheme Procedure} i/o-error-position condition
1265 A subtype of @code{&i/o}; represents an error related to an attempt to
1266 set the file position to an invalid position.
1269 @deffn {Condition Type} &i/o-filename
1270 @deffnx {Scheme Procedure} make-io-filename-error filename
1271 @deffnx {Scheme Procedure} i/o-filename-error? obj
1272 @deffnx {Scheme Procedure} i/o-error-filename condition
1273 A subtype of @code{&i/o}; represents an error related to an operation on
1277 @deffn {Condition Type} &i/o-file-protection
1278 @deffnx {Scheme Procedure} make-i/o-file-protection-error filename
1279 @deffnx {Scheme Procedure} i/o-file-protection-error? obj
1280 A subtype of @code{&i/o-filename}; represents an error resulting from an
1281 attempt to access a named file for which the caller had insufficient
1285 @deffn {Condition Type} &i/o-file-is-read-only
1286 @deffnx {Scheme Procedure} make-i/o-file-is-read-only-error filename
1287 @deffnx {Scheme Procedure} i/o-file-is-read-only-error? obj
1288 A subtype of @code{&i/o-file-protection}; represents an error related to
1289 an attempt to write to a read-only file.
1292 @deffn {Condition Type} &i/o-file-already-exists
1293 @deffnx {Scheme Procedure} make-i/o-file-already-exists-error filename
1294 @deffnx {Scheme Procedure} i/o-file-already-exists-error? obj
1295 A subtype of @code{&i/o-filename}; represents an error related to an
1296 operation on an existing file that was assumed not to exist.
1299 @deffn {Condition Type} &i/o-file-does-not-exist
1300 @deffnx {Scheme Procedure} make-i/o-file-does-not-exist-error
1301 @deffnx {Scheme Procedure} i/o-file-does-not-exist-error? obj
1302 A subtype of @code{&i/o-filename}; represents an error related to an
1303 operation on a non-existent file that was assumed to exist.
1306 @deffn {Condition Type} &i/o-port
1307 @deffnx {Scheme Procedure} make-i/o-port-error port
1308 @deffnx {Scheme Procedure} i/o-port-error? obj
1309 @deffnx {Scheme Procedure} i/o-error-port condition
1310 A subtype of @code{&i/o}; represents an error related to an operation on
1311 the port @var{port}.
1315 @subsubsection rnrs io ports
1317 The @code{(rnrs io ports (6))} library provides various procedures and
1318 syntactic forms for use in writing to and reading from ports. This
1319 functionality is documented in its own section of the manual;
1320 (@pxref{R6RS I/O Ports}).
1322 @node rnrs io simple
1323 @subsubsection rnrs io simple
1325 The @code{(rnrs io simple (6))} library provides convenience functions
1326 for performing textual I/O on ports. This library also exports all of
1327 the condition types and associated procedures described in
1328 (@pxref{I/O Conditions}).
1330 @deffn {Scheme Procedure} eof-object
1331 @deffnx {Scheme Procedure} eof-object? obj
1332 These procedures are identical to the ones provided by the
1333 @code{(rnrs io ports (6))} library. @xref{R6RS I/O Ports}, for
1337 @deffn {Scheme Procedure} input-port? obj
1338 @deffnx {Scheme Procedure} output-port? obj
1339 These procedures are identical to the ones provided by Guile's core
1340 library. @xref{Ports}, for documentation.
1343 @deffn {Scheme Procedure} call-with-input-file filename proc
1344 @deffnx {Scheme Procedure} call-with-output-file filename proc
1345 @deffnx {Scheme Procedure} open-input-file filename
1346 @deffnx {Scheme Procedure} open-output-file filename
1347 @deffnx {Scheme Procedure} with-input-from-file filename thunk
1348 @deffnx {Scheme Procedure} with-output-to-file filename thunk
1349 These procedures are identical to the ones provided by Guile's core
1350 library. @xref{File Ports}, for documentation.
1353 @deffn {Scheme Procedure} close-input-port input-port
1354 @deffnx {Scheme Procedure} close-output-port output-port
1355 These procedures are identical to the ones provided by Guile's core
1356 library. @xref{Closing}, for documentation.
1359 @deffn {Scheme Procedure} peek-char
1360 @deffnx {Scheme Procedure} peek-char textual-input-port
1361 @deffnx {Scheme Procedure} read-char
1362 @deffnx {Scheme Procedure} read-char textual-input-port
1363 These procedures are identical to the ones provided by Guile's core
1364 library. @xref{Reading}, for documentation.
1367 @deffn {Scheme Procedure} read
1368 @deffnx {Scheme Procedure} read textual-input-port
1369 This procedure is identical to the one provided by Guile's core library.
1370 @xref{Scheme Read}, for documentation.
1373 @deffn {Scheme Procedure} display obj
1374 @deffnx {Scheme Procedure} display obj textual-output-port
1375 @deffnx {Scheme Procedure} newline
1376 @deffnx {Scheme Procedure} newline textual-output-port
1377 @deffnx {Scheme Procedure} write obj
1378 @deffnx {Scheme Procedure} write obj textual-output-port
1379 @deffnx {Scheme Procedure} write-char char
1380 @deffnx {Scheme Procedure} write-char char textual-output-port
1381 These procedures are identical to the ones provided by Guile's core
1382 library. @xref{Writing}, for documentation.
1386 @subsubsection rnrs files
1388 The @code{(rnrs files (6))} library provides the @code{file-exists?} and
1389 @code{delete-file} procedures, which test for the existence of a file
1390 and allow the deletion of files from the filesystem, respectively.
1392 These procedures are identical to the ones provided by Guile's core
1393 library. @xref{File System}, for documentation.
1396 @subsubsection rnrs programs
1398 The @code{(rnrs programs (6))} library provides procedures for
1399 process management and introspection.
1401 @deffn {Scheme Procedure} command-line
1402 This procedure is identical to the one provided by Guile's core library.
1403 @xref{Runtime Environment}, for documentation.
1406 @deffn {Scheme Procedure} exit
1407 @deffnx {Scheme Procedure} exit obj
1408 This procedure is identical to the one provided by Guile's core library.
1411 @node rnrs arithmetic fixnums
1412 @subsubsection rnrs arithmetic fixnums
1414 The @code{(rnrs arithmetic fixnums (6))} library provides procedures for
1415 performing arithmetic operations on an implementation-dependent range of
1416 exact integer values, which R6RS refers to as @dfn{fixnums}. In Guile,
1417 the size of a fixnum is determined by the size of the @code{SCM} type; a
1418 single SCM struct is guaranteed to be able to hold an entire fixnum,
1419 making fixnum computations particularly
1420 efficient---(@pxref{The SCM Type}). On 32-bit systems, the most
1421 negative and most positive fixnum values are, respectively, -536870912
1424 Unless otherwise specified, all of the procedures below take fixnums as
1425 arguments, and will raise an @code{&assertion} condition if passed a
1426 non-fixnum argument or an @code{&implementation-restriction} condition
1427 if their result is not itself a fixnum.
1429 @deffn {Scheme Procedure} fixnum? obj
1430 Returns @code{#t} if @var{obj} is a fixnum, @code{#f} otherwise.
1433 @deffn {Scheme Procedure} fixnum-width
1434 @deffnx {Scheme Procedure} least-fixnum
1435 @deffnx {Scheme Procedure} greatest-fixnum
1436 These procedures return, respectively, the maximum number of bits
1437 necessary to represent a fixnum value in Guile, the minimum fixnum
1438 value, and the maximum fixnum value.
1441 @deffn {Scheme Procedure} fx=? fx1 fx2 fx3 ...
1442 @deffnx {Scheme Procedure} fx>? fx1 fx2 fx3 ...
1443 @deffnx {Scheme Procedure} fx<? fx1 fx2 fx3 ...
1444 @deffnx {Scheme Procedure} fx>=? fx1 fx2 fx3 ...
1445 @deffnx {Scheme Procedure} fx<=? fx1 fx2 fx3 ...
1446 These procedures return @code{#t} if their fixnum arguments are
1447 (respectively): equal, monotonically increasing, monotonically
1448 decreasing, monotonically nondecreasing, or monotonically nonincrasing;
1449 @code{#f} otherwise.
1452 @deffn {Scheme Procedure} fxzero? fx
1453 @deffnx {Scheme Procedure} fxpositive? fx
1454 @deffnx {Scheme Procedure} fxnegative? fx
1455 @deffnx {Scheme Procedure} fxodd? fx
1456 @deffnx {Scheme Procedure} fxeven? fx
1457 These numerical predicates return @code{#t} if @var{fx} is,
1458 respectively, zero, greater than zero, less than zero, odd, or even;
1459 @code{#f} otherwise.
1462 @deffn {Scheme Procedure} fxmax fx1 fx2 ...
1463 @deffnx {Scheme Procedure} fxmin fx1 fx2 ...
1464 These procedures return the maximum or minimum of their arguments.
1467 @deffn {Scheme Procedure} fx+ fx1 fx2
1468 @deffnx {Scheme Procedure} fx* fx1 fx2
1469 These procedures return the sum or product of their arguments.
1472 @deffn {Scheme Procedure} fx- fx1 fx2
1473 @deffnx {Scheme Procedure} fx- fx
1474 Returns the difference of @var{fx1} and @var{fx2}, or the negation of
1475 @var{fx}, if called with a single argument.
1477 An @code{&assertion} condition is raised if the result is not itself a
1481 @deffn {Scheme Procedure} fxdiv-and-mod fx1 fx2
1482 @deffnx {Scheme Procedure} fxdiv fx1 fx2
1483 @deffnx {Scheme Procedure} fxmod fx1 fx2
1484 @deffnx {Scheme Procedure} fxdiv0-and-mod0 fx1 fx2
1485 @deffnx {Scheme Procedure} fxdiv0 fx1 fx2
1486 @deffnx {Scheme Procedure} fxmod0 fx1 fx2
1487 These procedures implement number-theoretic division on fixnums;
1488 @xref{(rnrs base)}, for a description of their semantics.
1491 @deffn {Scheme Procedure} fx+/carry fx1 fx2 fx3
1492 Returns the two fixnum results of the following computation:
1494 (let* ((s (+ fx1 fx2 fx3))
1495 (s0 (mod0 s (expt 2 (fixnum-width))))
1496 (s1 (div0 s (expt 2 (fixnum-width)))))
1501 @deffn {Scheme Procedure} fx-/carry fx1 fx2 fx3
1502 Returns the two fixnum results of the following computation:
1504 (let* ((d (- fx1 fx2 fx3))
1505 (d0 (mod0 d (expt 2 (fixnum-width))))
1506 (d1 (div0 d (expt 2 (fixnum-width)))))
1511 @deffn {Scheme Procedure} fx*/carry fx1 fx2 fx3
1513 Returns the two fixnum results of the following computation:
1514 (let* ((s (+ (* fx1 fx2) fx3))
1515 (s0 (mod0 s (expt 2 (fixnum-width))))
1516 (s1 (div0 s (expt 2 (fixnum-width)))))
1521 @deffn {Scheme Procedure} fxnot fx
1522 @deffnx {Scheme Procedure} fxand fx1 ...
1523 @deffnx {Scheme Procedure} fxior fx1 ...
1524 @deffnx {Scheme Procedure} fxxor fx1 ...
1525 These procedures are identical to the @code{lognot}, @code{logand},
1526 @code{logior}, and @code{logxor} procedures provided by Guile's core
1527 library. @xref{Bitwise Operations}, for documentation.
1530 @deffn {Scheme Procedure} fxif fx1 fx2 fx3
1531 Returns the bitwise ``if'' of its fixnum arguments. The bit at position
1532 @code{i} in the return value will be the @code{i}th bit from @var{fx2}
1533 if the @code{i}th bit of @var{fx1} is 1, the @code{i}th bit from
1537 @deffn {Scheme Procedure} fxbit-count fx
1538 Returns the number of 1 bits in the two's complement representation of
1542 @deffn {Scheme Procedure} fxlength fx
1543 Returns the number of bits necessary to represent @var{fx}.
1546 @deffn {Scheme Procedure} fxfirst-bit-set fx
1547 Returns the index of the least significant 1 bit in the two's complement
1548 representation of @var{fx}.
1551 @deffn {Scheme Procedure} fxbit-set? fx1 fx2
1552 Returns @code{#t} if the @var{fx2}th bit in the two's complement
1553 representation of @var{fx1} is 1, @code{#f} otherwise.
1556 @deffn {Scheme Procedure} fxcopy-bit fx1 fx2 fx3
1557 Returns the result of setting the @var{fx2}th bit of @var{fx1} to the
1558 @var{fx2}th bit of @var{fx3}.
1561 @deffn {Scheme Procedure} fxbit-field fx1 fx2 fx3
1562 Returns the integer representation of the contiguous sequence of bits in
1563 @var{fx1} that starts at position @var{fx2} (inclusive) and ends at
1564 position @var{fx3} (exclusive).
1567 @deffn {Scheme Procedure} fxcopy-bit-field fx1 fx2 fx3 fx4
1568 Returns the result of replacing the bit field in @var{fx1} with start
1569 and end positions @var{fx2} and @var{fx3} with the corresponding bit
1570 field from @var{fx4}.
1573 @deffn {Scheme Procedure} fxarithmetic-shift fx1 fx2
1574 @deffnx {Scheme Procedure} fxarithmetic-shift-left fx1 fx2
1575 @deffnx {Scheme Procedure} fxarithmetic-shift-right fx1 fx2
1576 Returns the result of shifting the bits of @var{fx1} right or left by
1577 the @var{fx2} positions. @code{fxarithmetic-shift} is identical
1578 to @code{fxarithmetic-shift-left}.
1581 @deffn {Scheme Procedure} fxrotate-bit-field fx1 fx2 fx3 fx4
1582 Returns the result of cyclically permuting the bit field in @var{fx1}
1583 with start and end positions @var{fx2} and @var{fx3} by @var{fx4} bits
1584 in the direction of more significant bits.
1587 @deffn {Scheme Procedure} fxreverse-bit-field fx1 fx2 fx3
1588 Returns the result of reversing the order of the bits of @var{fx1}
1589 between position @var{fx2} (inclusive) and position @var{fx3}
1593 @node rnrs arithmetic flonums
1594 @subsubsection rnrs arithmetic flonums
1596 The @code{(rnrs arithmetic flonums (6))} library provides procedures for
1597 performing arithmetic operations on inexact representations of real
1598 numbers, which R6RS refers to as @dfn{flonums}.
1600 Unless otherwise specified, all of the procedures below take flonums as
1601 arguments, and will raise an @code{&assertion} condition if passed a
1602 non-flonum argument.
1604 @deffn {Scheme Procedure} flonum? obj
1605 Returns @code{#t} if @var{obj} is a flonum, @code{#f} otherwise.
1608 @deffn {Scheme Procedure} real->flonum x
1609 Returns the flonum that is numerically closest to the real number
1613 @deffn {Scheme Procedure} fl=? fl1 fl2 fl3 ...
1614 @deffnx {Scheme Procedure} fl<? fl1 fl2 fl3 ...
1615 @deffnx {Scheme Procedure} fl<=? fl1 fl2 fl3 ...
1616 @deffnx {Scheme Procedure} fl>? fl1 fl2 fl3 ...
1617 @deffnx {Scheme Procedure} fl>=? fl1 fl2 fl3 ...
1618 These procedures return @code{#t} if their flonum arguments are
1619 (respectively): equal, monotonically increasing, monotonically
1620 decreasing, monotonically nondecreasing, or monotonically nonincrasing;
1621 @code{#f} otherwise.
1624 @deffn {Scheme Procedure} flinteger? fl
1625 @deffnx {Scheme Procedure} flzero? fl
1626 @deffnx {Scheme Procedure} flpositive? fl
1627 @deffnx {Scheme Procedure} flnegative? fl
1628 @deffnx {Scheme Procedure} flodd? fl
1629 @deffnx {Scheme Procedure} fleven? fl
1630 These numerical predicates return @code{#t} if @var{fl} is,
1631 respectively, an integer, zero, greater than zero, less than zero, odd,
1632 even, @code{#f} otherwise. In the case of @code{flodd?} and
1633 @code{fleven?}, @var{fl} must be an integer-valued flonum.
1636 @deffn {Scheme Procedure} flfinite? fl
1637 @deffnx {Scheme Procedure} flinfinite? fl
1638 @deffnx {Scheme Procedure} flnan? fl
1639 These numerical predicates return @code{#t} if @var{fl} is,
1640 respectively, not infinite, infinite, or a @code{NaN} value.
1643 @deffn {Scheme Procedure} flmax fl1 fl2 ...
1644 @deffnx {Scheme Procedure} flmin fl1 fl2 ...
1645 These procedures return the maximum or minimum of their arguments.
1648 @deffn {Scheme Procedure} fl+ fl1 ...
1649 @deffnx {Scheme Procedure} fl* fl ...
1650 These procedures return the sum or product of their arguments.
1653 @deffn {Scheme Procedure} fl- fl1 fl2 ...
1654 @deffnx {Scheme Procedure} fl- fl
1655 @deffnx {Scheme Procedure} fl/ fl1 fl2 ...
1656 @deffnx {Scheme Procedure} fl/ fl
1657 These procedures return, respectively, the difference or quotient of
1658 their arguments when called with two arguments; when called with a
1659 single argument, they return the additive or multiplicative inverse of
1663 @deffn {Scheme Procedure} flabs fl
1664 Returns the absolute value of @var{fl}.
1667 @deffn {Scheme Procedure} fldiv-and-mod fl1 fl2
1668 @deffnx {Scheme Procedure} fldiv fl1 fl2
1669 @deffnx {Scheme Procedure} fldmod fl1 fl2
1670 @deffnx {Scheme Procedure} fldiv0-and-mod0 fl1 fl2
1671 @deffnx {Scheme Procedure} fldiv0 fl1 fl2
1672 @deffnx {Scheme Procedure} flmod0 fl1 fl2
1673 These procedures implement number-theoretic division on flonums;
1674 @xref{(rnrs base)}, for a description for their semantics.
1677 @deffn {Scheme Procedure} flnumerator fl
1678 @deffnx {Scheme Procedure} fldenominator fl
1679 These procedures return the numerator or denominator of @var{fl} as a
1683 @deffn {Scheme Procedure} flfloor fl1
1684 @deffnx {Scheme Procedure} flceiling fl
1685 @deffnx {Scheme Procedure} fltruncate fl
1686 @deffnx {Scheme Procedure} flround fl
1687 These procedures are identical to the @code{floor}, @code{ceiling},
1688 @code{truncate}, and @code{round} procedures provided by Guile's core
1689 library. @xref{Arithmetic}, for documentation.
1692 @deffn {Scheme Procedure} flexp fl
1693 @deffnx {Scheme Procedure} fllog fl
1694 @deffnx {Scheme Procedure} fllog fl1 fl2
1695 @deffnx {Scheme Procedure} flsin fl
1696 @deffnx {Scheme Procedure} flcos fl
1697 @deffnx {Scheme Procedure} fltan fl
1698 @deffnx {Scheme Procedure} flasin fl
1699 @deffnx {Scheme Procedure} flacos fl
1700 @deffnx {Scheme Procedure} flatan fl
1701 @deffnx {Scheme Procedure} flatan fl1 fl2
1702 These procedures, which compute the usual transcendental functions, are
1703 the flonum variants of the procedures provided by the R6RS base library
1704 (@pxref{(rnrs base)}).
1707 @deffn {Scheme Procedure} flsqrt fl
1708 Returns the square root of @var{fl}. If @var{fl} is @code{-0.0},
1709 @var{-0.0} is returned; for other negative values, a @code{NaN} value
1713 @deffn {Scheme Procedure} flexpt fl1 fl2
1714 Returns the value of @var{fl1} raised to the power of @var{fl2}.
1717 The following condition types are provided to allow Scheme
1718 implementations that do not support infinities or @code{NaN} values
1719 to indicate that a computation resulted in such a value. Guile supports
1720 both of these, so these conditions will never be raised by Guile's
1721 standard libraries implementation.
1723 @deffn {Condition Type} &no-infinities
1724 @deffnx {Scheme Procedure} make-no-infinities-violation obj
1725 @deffnx {Scheme Procedure} no-infinities-violation?
1726 A condition type indicating that a computation resulted in an infinite
1727 value on a Scheme implementation incapable of representing infinities.
1730 @deffn {Condition Type} &no-nans
1731 @deffnx {Scheme Procedure} make-no-nans-violation obj
1732 @deffnx {Scheme Procedure} no-nans-violation? obj
1733 A condition type indicating that a computation resulted in a @code{NaN}
1734 value on a Scheme implementation incapable of representing @code{NaN}s.
1737 @deffn {Scheme Procedure} fixnum->flonum fx
1738 Returns the flonum that is numerically closest to the fixnum @var{fx}.
1741 @node rnrs arithmetic bitwise
1742 @subsubsection rnrs arithmetic bitwise
1744 The @code{(rnrs arithmetic bitwise (6))} library provides procedures for
1745 performing bitwise arithmetic operations on the two's complement
1746 representations of fixnums.
1748 This library and the procedures it exports share functionality with
1749 SRFI-60, which provides support for bitwise manipulation of integers
1752 @deffn {Scheme Procedure} bitwise-not ei
1753 @deffnx {Scheme Procedure} bitwise-and ei1 ...
1754 @deffnx {Scheme Procedure} bitwise-ior ei1 ...
1755 @deffnx {Scheme Procedure} bitwise-xor ei1 ...
1756 These procedures are identical to the @code{lognot}, @code{logand},
1757 @code{logior}, and @code{logxor} procedures provided by Guile's core
1758 library. @xref{Bitwise Operations}, for documentation.
1761 @deffn {Scheme Procedure} bitwise-if ei1 ei2 ei3
1762 Returns the bitwise ``if'' of its arguments. The bit at position
1763 @code{i} in the return value will be the @code{i}th bit from @var{ei2}
1764 if the @code{i}th bit of @var{ei1} is 1, the @code{i}th bit from
1768 @deffn {Scheme Procedure} bitwise-bit-count ei
1769 Returns the number of 1 bits in the two's complement representation of
1773 @deffn {Scheme Procedure} bitwise-length ei
1774 Returns the number of bits necessary to represent @var{ei}.
1777 @deffn {Scheme Procedure} bitwise-first-bit-set ei
1778 Returns the index of the least significant 1 bit in the two's complement
1779 representation of @var{ei}.
1782 @deffn {Scheme Procedure} bitwise-bit-set? ei1 ei2
1783 Returns @code{#t} if the @var{ei2}th bit in the two's complement
1784 representation of @var{ei1} is 1, @code{#f} otherwise.
1787 @deffn {Scheme Procedure} bitwise-copy-bit ei1 ei2 ei3
1788 Returns the result of setting the @var{ei2}th bit of @var{ei1} to the
1789 @var{ei2}th bit of @var{ei3}.
1792 @deffn {Scheme Procedure} bitwise-bit-field ei1 ei2 ei3
1793 Returns the integer representation of the contiguous sequence of bits in
1794 @var{ei1} that starts at position @var{ei2} (inclusive) and ends at
1795 position @var{ei3} (exclusive).
1798 @deffn {Scheme Procedure} bitwise-copy-bit-field ei1 ei2 ei3 ei4
1799 Returns the result of replacing the bit field in @var{ei1} with start
1800 and end positions @var{ei2} and @var{ei3} with the corresponding bit
1801 field from @var{ei4}.
1804 @deffn {Scheme Procedure} bitwise-arithmetic-shift ei1 ei2
1805 @deffnx {Scheme Procedure} bitwise-arithmetic-shift-left ei1 ei2
1806 @deffnx {Scheme Procedure} bitwise-arithmetic-shift-right ei1 ei2
1807 Returns the result of shifting the bits of @var{ei1} right or left by
1808 the @var{ei2} positions. @code{bitwise-arithmetic-shift} is identical
1809 to @code{bitwise-arithmetic-shift-left}.
1812 @deffn {Scheme Procedure} bitwise-rotate-bit-field ei1 ei2 ei3 ei4
1813 Returns the result of cyclically permuting the bit field in @var{ei1}
1814 with start and end positions @var{ei2} and @var{ei3} by @var{ei4} bits
1815 in the direction of more significant bits.
1818 @deffn {Scheme Procedure} bitwise-reverse-bit-field ei1 ei2 ei3
1819 Returns the result of reversing the order of the bits of @var{e1}
1820 between position @var{ei2} (inclusive) and position @var{ei3}
1824 @node rnrs syntax-case
1825 @subsubsection rnrs syntax-case
1827 The @code{(rnrs syntax-case (6))} library provides access to the
1828 @code{syntax-case} system for writing hygienic macros. With one
1829 exception, all of the forms and procedures exported by this library
1830 are ``re-exports'' of Guile's native support for @code{syntax-case};
1831 @xref{Syntax Case}, for documentation, examples, and rationale.
1833 @deffn {Scheme Procedure} make-variable-transformer proc
1834 Creates a new variable transformer out of @var{proc}, a procedure that
1835 takes a syntax object as input and returns a syntax object. If an
1836 identifier to which the result of this procedure is bound appears on the
1837 left-hand side of a @code{set!} expression, @var{proc} will be called
1838 with a syntax object representing the entire @code{set!} expression,
1839 and its return value will replace that @code{set!} expression.
1842 @deffn {Scheme Syntax} syntax-case expression (literal ...) clause ...
1843 The @code{syntax-case} pattern matching form.
1846 @deffn {Scheme Syntax} syntax template
1847 @deffnx {Scheme Syntax} quasisyntax template
1848 @deffnx {Scheme Syntax} unsyntax template
1849 @deffnx {Scheme Syntax} unsyntax-splicing template
1850 These forms allow references to be made in the body of a syntax-case
1851 output expression subform to datum and non-datum values. They are
1852 identical to the forms provided by Guile's core library;
1853 @xref{Syntax Case}, for documentation.
1856 @deffn {Scheme Procedure} identifier? obj
1857 @deffnx {Scheme Procedure} bound-identifier=? id1 id2
1858 @deffnx {Scheme Procedure} free-identifier=? id1 id2
1859 These predicate procedures operate on syntax objects representing
1860 Scheme identifiers. @code{identifier?} returns @code{#t} if @var{obj}
1861 represents an identifier, @code{#f} otherwise.
1862 @code{bound-identifier=?} returns @code{#t} if and only if a binding for
1863 @var{id1} would capture a reference to @var{id2} in the transformer's
1864 output, or vice-versa. @code{free-identifier=?} returns @code{#t} if
1865 and only @var{id1} and @var{id2} would refer to the same binding in the
1866 output of the transformer, independent of any bindings introduced by the
1870 @deffn {Scheme Procedure} generate-temporaries l
1871 Returns a list, of the same length as @var{l}, which must be a list or
1872 a syntax object representing a list, of globally unique symbols.
1875 @deffn {Scheme Procedure} syntax->datum syntax-object
1876 @deffnx {Scheme Procedure} datum->syntax template-id datum
1877 These procedures convert wrapped syntax objects to and from Scheme datum
1878 values. The syntax object returned by @code{datum->syntax} shares
1879 contextual information with the syntax object @var{template-id}.
1882 @deffn {Scheme Procedure} syntax-violation whom message form
1883 @deffnx {Scheme Procedure} syntax-violation whom message form subform
1884 Constructs a new compound condition that includes the following
1888 If @var{whom} is not @code{#f}, a @code{&who} condition with the
1889 @var{whom} as its field
1891 A @code{&message} condition with the specified @var{message}
1893 A @code{&syntax} condition with the specified @var{form} and optional
1894 @var{subform} fields
1898 @node rnrs hashtables
1899 @subsubsection rnrs hashtables
1901 The @code{(rnrs hashtables (6))} library provides structures and
1902 procedures for creating and accessing hash tables. The hash tables API
1903 defined by R6RS is substantially similar to both Guile's native hash
1904 tables implementation as well as the one provided by SRFI-69;
1905 @xref{Hash Tables}, and @ref{SRFI-69}, respectively. Note that you can
1906 write portable R6RS library code that manipulates SRFI-69 hash tables
1907 (by importing the @code{(srfi :69)} library); however, hash tables
1908 created by one API cannot be used by another.
1910 Like SRFI-69 hash tables---and unlike Guile's native ones---R6RS hash
1911 tables associate hash and equality functions with a hash table at the
1912 time of its creation. Additionally, R6RS allows for the creation
1913 (via @code{hashtable-copy}; see below) of immutable hash tables.
1915 @deffn {Scheme Procedure} make-eq-hashtable
1916 @deffnx {Scheme Procedure} make-eq-hashtable k
1917 Returns a new hash table that uses @code{eq?} to compare keys and
1918 Guile's @code{hashq} procedure as a hash function. If @var{k} is given,
1919 it specifies the initial capacity of the hash table.
1922 @deffn {Scheme Procedure} make-eqv-hashtable
1923 @deffnx {Scheme Procedure} make-eqv-hashtable k
1924 Returns a new hash table that uses @code{eqv?} to compare keys and
1925 Guile's @code{hashv} procedure as a hash function. If @var{k} is given,
1926 it specifies the initial capacity of the hash table.
1929 @deffn {Scheme Procedure} make-hashtable hash-function equiv
1930 @deffnx {Scheme Procedure} make-hashtable hash-function equiv k
1931 Returns a new hash table that uses @var{equiv} to compare keys and
1932 @var{hash-function} as a hash function. @var{equiv} must be a procedure
1933 that accepts two arguments and returns a true value if they are
1934 equivalent, @code{#f} otherwise; @var{hash-function} must be a procedure
1935 that accepts one argument and returns a non-negative integer.
1937 If @var{k} is given, it specifies the initial capacity of the hash
1941 @deffn {Scheme Procedure} hashtable? obj
1942 Returns @code{#t} if @var{obj} is an R6RS hash table, @code{#f}
1946 @deffn {Scheme Procedure} hashtable-size hashtable
1947 Returns the number of keys currently in the hash table @var{hashtable}.
1950 @deffn {Scheme Procedure} hashtable-ref hashtable key default
1951 Returns the value associated with @var{key} in the hash table
1952 @var{hashtable}, or @var{default} if none is found.
1955 @deffn {Scheme Procedure} hashtable-set! hashtable key obj
1956 Associates the key @var{key} with the value @var{obj} in the hash table
1957 @var{hashtable}, and returns an unspecified value. An @code{&assertion}
1958 condition is raised if @var{hashtable} is immutable.
1961 @deffn {Scheme Procedure} hashtable-delete! hashtable key
1962 Removes any association found for the key @var{key} in the hash table
1963 @var{hashtable}, and returns an unspecified value. An @code{&assertion}
1964 condition is raised if @var{hashtable} is immutable.
1967 @deffn {Scheme Procedure} hashtable-contains? hashtable key
1968 Returns @code{#t} if the hash table @var{hashtable} contains an
1969 association for the key @var{key}, @code{#f} otherwise.
1972 @deffn {Scheme Procedure} hashtable-update! hashtable key proc default
1973 Associates with @var{key} in the hash table @var{hashtable} the result
1974 of calling @var{proc}, which must be a procedure that takes one
1975 argument, on the value currently associated @var{key} in
1976 @var{hashtable}---or on @var{default} if no such association exists.
1977 An @code{&assertion} condition is raised if @var{hashtable} is
1981 @deffn {Scheme Procedure} hashtable-copy hashtable
1982 @deffnx {Scheme Procedure} hashtable-copy hashtable mutable
1983 Returns a copy of the hash table @var{hashtable}. If the optional
1984 argument @var{mutable} is a true value, the new hash table will be
1988 @deffn {Scheme Procedure} hashtable-clear! hashtable
1989 @deffnx {Scheme Procedure} hashtable-clear! hashtable k
1990 Removes all of the associations from the hash table @var{hashtable}.
1991 The optional argument @var{k}, which specifies a new capacity for the
1992 hash table, is accepted by Guile's @code{(rnrs hashtables)}
1993 implementation, but is ignored.
1996 @deffn {Scheme Procedure} hashtable-keys hashtable
1997 Returns a vector of the keys with associations in the hash table
1998 @var{hashtable}, in an unspecified order.
2001 @deffn {Scheme Procedure} hashtable-entries hashtable
2002 Return two values---a vector of the keys with associations in the hash
2003 table @var{hashtable}, and a vector of the values to which these keys
2004 are mapped, in corresponding but unspecified order.
2007 @deffn {Scheme Procedure} hashtable-equivalence-function hashtable
2008 Returns the equivalence predicated use by @var{hashtable}. This
2009 procedure returns @code{eq?} and @code{eqv?}, respectively, for hash
2010 tables created by @code{make-eq-hashtable} and
2011 @code{make-eqv-hashtable}.
2014 @deffn {Scheme Procedure} hashtable-hash-function hashtable
2015 Returns the hash function used by @var{hashtable}. For hash tables
2016 created by @code{make-eq-hashtable} or @code{make-eqv-hashtable},
2017 @code{#f} is returned.
2020 @deffn {Scheme Procedure} hashtable-mutable? hashtable
2021 Returns @code{#t} if @var{hashtable} is mutable, @code{#f} otherwise.
2024 A number of hash functions are provided for convenience:
2026 @deffn {Scheme Procedure} equal-hash obj
2027 Returns an integer hash value for @var{obj}, based on its structure and
2028 current contents. This hash function is suitable for use with
2029 @code{equal?} as an equivalence function.
2032 @deffn {Scheme Procedure} string-hash string
2033 @deffnx {Scheme Procedure} symbol-hash symbol
2034 These procedures are identical to the ones provided by Guile's core
2035 library. @xref{Hash Table Reference}, for documentation.
2038 @deffn {Scheme Procedure} string-ci-hash string
2039 Returns an integer hash value for @var{string} based on its contents,
2040 ignoring case. This hash function is suitable for use with
2041 @code{string-ci=?} as an equivalence function.
2045 @subsubsection rnrs enums
2047 The @code{(rnrs enums (6))} library provides structures and procedures
2048 for working with enumerable sets of symbols. Guile's implementation
2049 defines an @dfn{enum-set} record type that encapsulates a finite set of
2050 distinct symbols, the @dfn{universe}, and a subset of these symbols,
2051 which define the enumeration set.
2053 The SRFI-1 list library provides a number of procedures for performing
2054 set operations on lists; Guile's @code{(rnrs enums)} implementation
2055 makes use of several of them. @xref{SRFI-1 Set Operations}, for
2058 @deffn {Scheme Procedure} make-enumeration symbol-list
2059 Returns a new enum-set whose universe and enumeration set are both equal
2060 to @var{symbol-list}, a list of symbols.
2063 @deffn {Scheme Procedure} enum-set-universe enum-set
2064 Returns an enum-set representing the universe of @var{enum-set},
2068 @deffn {Scheme Procedure} enum-set-indexer enum-set
2069 Returns a procedure that takes a single argument and returns the
2070 zero-indexed position of that argument in the universe of
2071 @var{enum-set}, or @code{#f} if its argument is not a member of that
2075 @deffn {Scheme Procedure} enum-set-constructor enum-set
2076 Returns a procedure that takes a single argument, a list of symbols
2077 from the universe of @var{enum-set}, an enum-set, and returns a new
2078 enum-set with the same universe that represents a subset containing the
2082 @deffn {Scheme Procedure} enum-set->list enum-set
2083 Returns a list containing the symbols of the set represented by
2084 @var{enum-set}, an enum-set, in the order that they appear in the
2085 universe of @var{enum-set}.
2088 @deffn {Scheme Procedure} enum-set-member? symbol enum-set
2089 @deffnx {Scheme Procedure} enum-set-subset? enum-set1 enum-set2
2090 @deffnx {Scheme Procedure} enum-set=? enum-set1 enum-set2
2091 These procedures test for membership of symbols and enum-sets in other
2092 enum-sets. @code{enum-set-member?} returns @code{#t} if and only if
2093 @var{symbol} is a member of the subset specified by @var{enum-set}.
2094 @code{enum-set-subset?} returns @code{#t} if and only if the universe of
2095 @var{enum-set1} is a subset of the universe of @var{enum-set2} and
2096 every symbol in @var{enum-set1} is present in @var{enum-set2}.
2097 @code{enum-set=?} returns @code{#t} if and only if @var{enum-set1} is a
2098 subset, as per @code{enum-set-subset?} of @var{enum-set2} and vice
2102 @deffn {Scheme Procedure} enum-set-union enum-set1 enum-set2
2103 @deffnx {Scheme Procedure} enum-set-intersection enum-set1 enum-set2
2104 @deffnx {Scheme Procedure} enum-set-difference enum-set1 enum-set2
2105 These procedures return, respectively, the union, intersection, and
2106 difference of their enum-set arguments.
2109 @deffn {Scheme Procedure} enum-set-complement enum-set
2110 Returns @var{enum-set}'s complement (an enum-set), with regard to its
2114 @deffn {Scheme Procedure} enum-set-projection enum-set1 enum-set2
2115 Returns the projection of the enum-set @var{enum-set1} onto the universe
2116 of the enum-set @var{enum-set2}.
2119 @deffn {Scheme Syntax} define-enumeration type-name (symbol ...) constructor-syntax
2120 Evaluates to two new definitions: A constructor bound to
2121 @var{constructor-syntax} that behaves similarly to constructors created
2122 by @code{enum-set-constructor}, above, and creates new @var{enum-set}s
2123 in the universe specified by @code{(symbol ...)}; and a ``predicate
2124 macro'' bound to @var{type-name}, which has the following form:
2127 (@var{type-name} sym)
2130 If @var{sym} is a member of the universe specified by the @var{symbol}s
2131 above, this form evaluates to @var{sym}. Otherwise, a @code{&syntax}
2132 condition is raised.
2138 The @code{(rnrs (6))} library is a composite of all of the other R6RS
2139 standard libraries---it imports and re-exports all of their exported
2140 procedures and syntactic forms---with the exception of the following
2144 @item @code{(rnrs eval (6))}
2145 @item @code{(rnrs mutable-pairs (6))}
2146 @item @code{(rnrs mutable-strings (6))}
2147 @item @code{(rnrs r5rs (6))}
2151 @subsubsection rnrs eval
2153 The @code{(rnrs eval (6)} library provides procedures for performing
2154 ``on-the-fly'' evaluation of expressions.
2156 @deffn {Scheme Procedure} eval expression environment
2157 Evaluates @var{expression}, which must be a datum representation of a
2158 valid Scheme expression, in the environment specified by
2159 @var{environment}. This procedure is identical to the one provided by
2160 Guile's code library; @xref{Fly Evaluation}, for documentation.
2163 @deffn {Scheme Procedure} environment import-spec ...
2164 Constructs and returns a new environment based on the specified
2165 @var{import-spec}s, which must be datum representations of the import
2166 specifications used with the @code{import} form. @xref{R6RS Libraries},
2170 @node rnrs mutable-pairs
2171 @subsubsection rnrs mutable-pairs
2173 The @code{(rnrs mutable-pairs (6))} library provides the @code{set-car!}
2174 and @code{set-cdr!} procedures, which allow the @code{car} and
2175 @code{cdr} fields of a pair to be modified.
2177 These procedures are identical to the ones provide by Guile's core
2178 library. @xref{Pairs}, for documentation. All pairs in Guile are
2179 mutable; consequently, these procedures will never throw the
2180 @code{&assertion} condition described in the R6RS libraries
2183 @node rnrs mutable-strings
2184 @subsubsection rnrs mutable-strings
2186 The @code{(rnrs mutable-strings (6))} library provides the
2187 @code{string-set!} and @code{string-fill!} procedures, which allow the
2188 content of strings to be modified ``in-place.''
2190 These procedures are identical to the ones provided by Guile's core
2191 library. @xref{String Modification}, for documentation. All strings in
2192 Guile are mutable; consequently, these procedures will never throw the
2193 @code{&assertion} condition described in the R6RS libraries
2197 @subsubsection rnrs r5rs
2199 The @code{(rnrs r5rs (6))} library exports bindings for some procedures
2200 present in R5RS but omitted from the R6RS base library specification.
2202 @deffn {Scheme Procedure} exact->inexact z
2203 @deffnx {Scheme Procedure} inexact->exact z
2204 These procedures are identical to the ones provided by Guile's core
2205 library. @xref{Exactness}, for documentation.
2208 @deffn {Scheme Procedure} quotient n1 n2
2209 @deffnx {Scheme Procedure} remainder n1 n2
2210 @deffnx {Scheme Procedure} modulo n1 n2
2211 These procedures are identical to the ones provided by Guile's core
2212 library. @xref{Integer Operations}, for documentation.
2215 @deffn {Scheme Syntax} delay expr
2216 @deffnx {Scheme Procedure} force promise
2217 The @code{delay} form and the @code{force} procedure are identical to
2218 their counterparts in Guile's core library. @xref{Delayed Evaluation},
2222 @deffn {Scheme Procedure} null-environment n
2223 @deffnx {Scheme Procedure} scheme-report-environment n
2224 These procedures are identical to the ones provided by the
2225 @code{(ice-9 r5rs)} Guile module. @xref{Environments}, for
2229 @c r6rs.texi ends here
2232 @c TeX-master: "guile.texi"